README.md

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 [email protected] 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.

Additionally, you need to enable SCSS support.

plugins {
    kotlin("multiplatform")
    id("org.jetbrains.compose")
}
kotlin {
    js {
        browser {
            commonWebpackConfig {
                cssSupport { enabled.set(true) }
                scssSupport { enabled.set(true) }
            }
        }
    }
    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) for the top-level component and UpperCamelCaseLogicalName for all subcomponents. Most of the components also follow the same argument order schema:

1. ...requiredMdcOptions - MDC-specific options with no default values
2. ...optionalMdcOptions - MDC-specific options with default values 3.attrs: (AttrsBuilder<out HTMLElement>.() -> Unit)? = null - compose attributes builder for the underlying HTML element 4.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 showcases can be found in the sandbox)

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

    MDCFormField { // Using implicit `content` argument to wrap MDCCheckbox inside MDCFormField UI as recommended by the MDC docs
        MDCCheckbox(
            checked = checked,
            label = "Yes/No",
            attrs = { // Overriding underlying HTMLInput element attributes
                onInput { checked = !checked }
            }
        ) // MDCCheckbox doesn't allow for additional inner content
    }
}

Progress

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

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

Other libraries and extensions:

• kmdc-icons

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

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 Showcases file 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

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

Thanks to all the people who contributed to kmdc so far!