Make contributing easy

[OliverO2]

For a possible document or section on how to contribute effectively, here are some initial thoughts I have collected so far (preliminary, does not account for Sass):

Basics

• Explain style guide.
• Explain how to configure IDE.
• Explain pull request workflow.

How to create a Kmdc wrapper

MDC component refers to the material.io Web framework component. A Kmdc component is a Kotlin wrapper component for an MDC component.

Prerequisite:

• Familiarity with Compose for Web and Kotlin/JS.

Let's go:

1. Read about MDC Architecture and Integrating MDC Web into Frameworks. Kmdc uses "The Simple Approach: Wrapping MDC Web vanilla components".

2. Pick an MDC component to wrap, familiarize yourself with its interface.

   • Read the MDC component's README (example: mdc-checkbox).
   • Check out the MDC component's Typescript/JavaScript interface.

3. Create the Kmdc wrapper component. See MDCCheckbox.kt for an example.

   • A trick first:
     • These two lines import the @material stylesheet (@JsModule translates to require):

       @JsModule("@material/checkbox/dist/mdc.checkbox.css")
       external val MDCCheckboxStyle: dynamic

     • In addition, the style variable must be referenced in a function (TODO: where exactly?) to avoid the stylesheet being dropped by DCE.
   • Then declare the Typescript/JavaScript MDC component in Kotlin. See the example code on how to create a module object, declare the component's class, and put static functions into a companion object.
   • Each Kmdc component has
     • the usual Compose for Web attributes (attr),
     • Kmdc component options (opts),
     • other parameters as required.
   • Kmdc component options feature the same builder-style design as attributes.
   • Most MDC components require proper initialization and teardown, which is accomplished via a ref initialization lambda as part of the attrs. Its almost minimal form is shown below. If the MDC component has no destroy() function, provide an empty lambda for onDispose.

      ref {
        it.mdc = MDCCheckboxModule.MDCCheckbox.attachTo(it)
        // more stuff as required
        onDispose {
          it.mdc<MDCCheckboxModule.MDCCheckbox> { destroy() }
        }
      }