RotBolt / kmdc

Kompose wrappers for material-components-web

Kompose Material Design Components (KMDC)

The library is currently very experimental with no API stability guarantees. Breaking changes are being introduced each release.

A set of Kotlin wrappers over material-components-web@13.0.0 library providing Jetbrains Compose DSL for building beautiful WEB UIs. The API surface is identical to JS version, except for few places where slight adjustments are made to make it more fluid for compose.

Setup

KMDC wraps each MDC module 1:1 and as such allows you to pick and choose which exact components you'd like to use. This is recommended approach as it helps in reducing bundle size. However, for the lazy ones out there, a "shortcut" module is also available, which brings in all KMDC modules as transitive dependencies under a single dependency.

Either approach can be installed by declaring relevant dependencies in your jsMain sourceSet.

plugins {
  kotlin("multiplatform")
  id("org.jetbrains.compose")
}
kotlin {
  sourceSets {
    named("jsMain") {
      dependencies {
        // Be lazy and use the shortcut
        implementation("dev.petuska:kmdc:_")
        implementation("dev.petuska:kmdcx:_")

        // Do some work and see dem gains
        implementation("dev.petuska:kmdc-button:_")
        implementation("dev.petuska:kmdc-radio:_")
        implementation("dev.petuska:kmdcx-icons:_")
      }
    }
  }
}

Usage

Most of the API maps closely to MDC JS API, making all examples there semi-valid. KMDC components follow a specific naming convention to make its components more discoverable as well. The convention is MDC[UpperCamelCaseMDCComponentName] (e.g. MDCTopAppBar). Most of the components also follow the same argument order schema:

1. opts: (MDCComponentOpts.() -> Unit)? = null - MDC-specific options overrides
2. attrs: (AttrsBuilder<out HTMLElement>.() -> Unit)? = null - compose attributes builder for the underlying HTML element
3. content: (ComposableBuilder<out HTMLElement>.() -> Unit)? = null - compose inner content builder for the underlying HTML element

Here's a quick peek how these things come together (more samples can be found in the sandbox)

@Composable
fun Sample() {
  var checked by remember { mutableStateOf(false) } // Declaring controlled state

  MDCFormField { // Using implicit `content` argument to wrap MDCCheckbox inside MDCFormField component as recommended by MDC docs
    MDCCheckbox(
      checked = checked, // MDCCheckbox breaks regular args schema in favour of more convenient usage
      label = "MDCCheckbox",
      attrs = { onClick { checked = !checked } } // Overriding underlying HTMLInput element attributes
    ) // MDCCheckbox doesn't allow for additional inner content
  }
}

Progress

Here's a tracker list of currently completed material-components-web modules:

• mdc-animation (SASS)
• mdc-auto-init (won't wrap)
• mdc-banner
• mdc-base (won't wrap)
• mdc-button
• mdc-card
• mdc-checkbox
• mdc-chips
• mdc-circular-progress
• mdc-data-table
• mdc-density (won't wrap)
• mdc-dialog
• mdc-dom (won't wrap)
• mdc-drawer
• mdc-elevation
• mdc-fab
• mdc-feature-targeting (won't wrap)
• mdc-floating-label
• mdc-form-field
• mdc-icon-button
• mdc-image-list
• mdc-layout-grid
• mdc-line-ripple
• mdc-linear-progress
• mdc-list
• mdc-menu-surface
• mdc-menu
• mdc-notched-outline
• mdc-progress-indicator (won't wrap)
• mdc-radio
• mdc-ripple
• mdc-rtl (SASS)
• mdc-segmented-button
• mdc-select
• mdc-shape (SASS)
• mdc-slider
• mdc-snackbar
• mdc-switch
• mdc-tab-bar
• mdc-tab-indicator
• mdc-tab-scroller
• mdc-tab
• mdc-textfield
• mdc-theme (SASS)
• mdc-tokens (won't wrap)
• mdc-tooltip
• mdc-top-app-bar
• mdc-touch-target
• mdc-typography

Other libraries and extensions:

• material-icons

Contributing

All contributions are welcome. Have a look for a good first issue in the issue tracker, or open your own issue if you have some ideas. If you want to chat, either start a discussion or ping me on slack.

Further details can be found in Contributing Guidelines

Module Structure

KMDC project modules can be categorised into three groups:

• Core MDC wrappers - grouped under ./kmdc meta-module
• Extensions of core wrappers or relevant non-kmdc wrappers - grouped under ./kmdcx meta-module
• Local testing utilities - grouped under ./test meta-module

Developer Setup

• Install JDK 11+
• Run ./gradlew assemble to build js binaries
• Use ./sandbox/ to render components in browser (needs to be linked separately in IDEA)
  • ./gradlew jsBrowserRun -t to start development server
  • Visit http://localhost:3000 to see your content
  • If you're adding a new component, render it by creating Samples property for it
  • Thanks to gradle continuous mode, any change in kmdc modules will trigger automatic refresh of sandbox and the browser. It takes a few seconds after you save your changes, so be patient.

Further details can be found in Contributing Guidelines