@aphrody/m3-react

Typed React components for every md-* element of @aphrody/material-web, generated with @lit/react createComponent.

bun add @aphrody/m3-react @aphrody/material-web react react-dom

import {
  MdCheckbox,
  MdFilledButton,
  MdOutlinedTextField,
} from "@aphrody/m3-react";

export function SignIn() {
  return (
    <form>
      <MdOutlinedTextField
        label="Email"
        onInput={e => console.log((e.target as HTMLInputElement).value)}
      />
      <MdCheckbox
        onChange={e => console.log((e.target as HTMLInputElement).checked)}
      />
      <MdFilledButton type="submit">Sign in</MdFilledButton>
    </form>
  );
}

License: Apache-2.0 (LICENSE). Install guide: docs/material/m3/INSTALL.md.

One wrapper per tag (PascalCase of the tag name), with the element's real native events mapped to React props. Importing a wrapper registers its custom element as a side effect (the wrapper imports the @aphrody/material-web module that calls customElements.define); no other import is needed. The elements are Lit web components, so they render on the client; see FRAMEWORKS.md for SSR and RSC setups.

Controlled inputs read e.target.value / e.target.checked; the handler receives the DOM event, not (event, value).

Slots and icons

Sub-parts are slotted content:

import {
  MdDialog,
  MdFilledButton,
  MdIcon,
  MdTextButton,
} from "@aphrody/m3-react";

<MdDialog
  open
  onClosed={e => console.log((e.target as HTMLDialogElement).returnValue)}
>
  <div slot="headline">Delete?</div>
  <form slot="content" method="dialog">
    This cannot be undone.
  </form>
  <div slot="actions">
    <MdTextButton value="cancel">Cancel</MdTextButton>
    <MdFilledButton value="delete">
      <MdIcon slot="icon">delete</MdIcon>
      Delete
    </MdFilledButton>
  </div>
</MdDialog>;

MdIcon needs the Material Symbols font, which the library does not load. Load it once at startup:

import { ensureMaterialSymbols } from "@aphrody/material-web/icon/material-symbols.js";
ensureMaterialSymbols(); // or { iconNames: ["delete", "search"] } to subset

The child text is the glyph name (Material Symbols snake_case). Variable axes are tokens: --md-icon-fill (0..1), --md-icon-wght (100..700), --md-icon-grad, --md-icon-opsz.

Layout

• src/index.ts: re-exports every wrapper (one export * per group).

• src/wrappers/<group>.ts: one file per material-web source folder (button.ts, select.ts, labs.ts, ...). Each export:

  export const MdFilledButton = createComponent({
    react: React,
    tagName: "md-filled-button",
    elementClass: MdFilledButtonElement, // from @aphrody/material-web/button/filled-button.js
    events: {}, // real native events (see the table below)
  });
  

• generate.ts: reads md-elements.txt, scans a material-web source checkout (--source <dir>) to resolve each tag to its entry file and exported class (@customElement('md-x') export class Foo), applies the verified event table and writes src/wrappers/, src/index.ts, .manifest.json and the last section of this README. It prefers the canonical path (bundled by all.ts, aphrody-components.ts or aphrody-labs.ts), then non-labs/gb, then labs/gb (the only home of md-button, md-card, md-menu-group and md-split-button, whose classes are re-aliased to Md*).

• src/material-web-shims.d.ts: ambient *.cssresult.js and *.css modules, see below.

Mapped events (verified in the Lit sources)

Event names come from @fires and new (Custom)?Event('...') in material-web/<dir>/internal/*.ts. Upstream components use plain names (input, change, opening, ...); fork components namespace theirs (paginator:page, table:sort, side-sheet:opening, tree:select, ...).

Presentational elements (md-icon, md-divider, md-elevation, md-ripple, md-focus-ring, assist/filter/suggestion chips, cards, fab, buttons, md-item, md-toolbar, md-carousel, md-accordion, md-loading-indicator, panes and scaffold) emit no documented event: events: {}.

Type checking

bun check --noEmit checks the wrappers and the material-web sources they import. The package tsconfig.json sets:

1. experimentalDecorators: true and useDefineForClassFields: false: the fork's Lit elements use legacy decorators.
2. src/material-web-shims.d.ts: declares *.cssresult.js and *.css as ambient modules. They are Sass build artifacts absent from a source checkout; the wrappers never touch them, so they are typed any (which also avoids the nominal clash between material-web's nested lit@2 and this package's lit@3).
3. moduleResolution: bundler: resolves bare @aphrody/material-web/x/y.js imports.

Against a built material-web (with *.cssresult.js and *.css present) the shims are unnecessary. All 119 tags of md-elements.txt resolve to a real entry file with an exported class.

All wrappers (119)

Regenerated by generate.ts (.manifest.json). 0 unresolved.