react-material-expressive 1.0.0

package/docs/components/Divider.md

@@ -0,0 +1,48 @@
+# Divider
+
+M3 divider: a 1px rule in `outline-variant` (decorative — per M3 never use
+`outline` for dividers).
+
+## Import
+
+```tsx
+import {Divider} from "react-material-expressive";
+```
+
+## API
+
+```ts
+interface DividerProps extends ComponentProps<"hr"> {
+  // M3 inset dividers (16dp). Omit for a full-width rule.
+  inset?: "start" | "middle" | "end";
+}
+```
+
+`inset` mirrors the M3 spec's named insets:
+
+| Value      | M3 name      | Leading / trailing          |
+| ---------- | ------------ | --------------------------- |
+| (omitted)  | full-width   | 0 / 0 (100%)                |
+| `"start"`  | inset        | 16dp / 0 (the list divider) |
+| `"middle"` | middle-inset | 16dp / 16dp                 |
+| `"end"`    | —            | 0 / 16dp (RTL-symmetric)    |
+
+Margins are logical (`ms`/`me`), so the inset follows the writing
+direction.
+
+## Examples
+
+```tsx
+<Divider />
+<Divider inset="start" />        // list divider (leading 16dp)
+<Divider inset="middle" />       // middle-inset (16dp both)
+<Divider className="my-2" />     // tighter spacing
+```
+
+## Gotchas
+
+- Renders an `<hr>` (1px `outline-variant`); default vertical margin is
+  16dp (`my-4`) — override with `className` for context-specific spacing.
+- Horizontal only. M3's web spec and @material/web don't define a vertical
+  divider (it exists only in Compose as `VerticalDivider`); for a vertical
+  rule use a `1px`-wide `bg-outline-variant` element directly.

package/docs/components/Dropdown.md

@@ -0,0 +1,79 @@
+# Dropdown
+
+Trigger + anchor for the shared M3E vertical [Menu](Menu.md): it positions
+the menu below the trigger and owns the open state (toggles on trigger
+click, closes on outside click, item activation or Escape, and returns
+focus to the trigger). All the menu visuals and keyboard come from `Menu`,
+so `Dropdown.Item` is an alias of `Menu.Item` and you can also use
+`Menu.Label` / `Menu.Divider` and the `selected` / `badge` item props.
+Standard (surface-based) by default or `vibrant` (tertiary-based).
+
+## Import
+
+```tsx
+import {Dropdown} from "react-material-expressive";
+```
+
+## API
+
+```ts
+interface DropdownProps {
+  apart?: boolean; // detach the menu with a 4dp gap
+  children: ReactNode; // trigger
+  className?: string;
+  menu?: ReactNode; // Dropdown.Item list
+  menuClassName?: string;
+  vibrant?: boolean; // tertiary-based scheme instead of standard
+}
+
+interface DropdownItemProps {
+  children?;
+  className?;
+  disabled?: boolean;
+  label?: ReactNode;
+  leftElement?: ReactNode; // 20px box (use icon size 20)
+  onClick?: MouseEventHandler<HTMLButtonElement>;
+  rightElement?: ReactNode; // trailing meta (body-small)
+}
+```
+
+## Example
+
+```tsx
+<Dropdown
+  menu={
+    <>
+      <Dropdown.Item
+        label="Profile"
+        leftElement={<MaterialSymbol name="person" size={20} />}
+      />
+      <Dropdown.Item
+        label="Settings"
+        rightElement="⌘S"
+        onClick={openSettings}
+      />
+    </>
+  }>
+  <Button iconRight={<MaterialSymbol name="expand_more" size={18} />}>
+    Open
+  </Button>
+</Dropdown>
+```
+
+## Gotchas
+
+- The whole wrapper toggles on click, so clicking an item also closes the
+  menu (select-like behavior).
+- The menu is content-width, clamped to the M3 spec's 112–280dp range
+  (`w-max min-w-[112px] max-w-[280px]`); use `apart` for a detached look.
+- Icons are 20dp in the vertical menu — pass `size={20}` to `MaterialSymbol`
+  so the glyph fills its box (the default is 24).
+- The first and last items round their outer corners (top / bottom) to
+  corner-medium so they sit concentric with the menu's corner-large and
+  don't read as a square cut against the rounded container; the inner
+  corners stay extra-small.
+- The expressive shape-morph (corners growing on the active state) only
+  applies to submenu parents; this flat menu keeps the extra-small corner
+  and shows hover/focus/pressed through the state layer.
+- For corner positioning use `OverflowMenu` instead (still the baseline
+  square menu — not yet migrated to the vertical menu).

package/docs/components/FAB.md

@@ -0,0 +1,63 @@
+# FAB / ExtendedFAB
+
+M3 floating action buttons. FAB sizes 56/80/96 with shapes
+large/large-increased/extra-large and icons 24/28/36 (80 is the default
+M3 Expressive medium FAB); Extended FAB comes in the M3 Expressive sizes
+small 56 (large shape, title-medium, icon 24, padding 16, gap 8), medium
+80 (large-increased, title-large, icon 28, padding 26, gap 12) and large
+96 (extra-large, headline-small, icon 36, padding 28, gap 16). Both rest
+at elevation level 3 and raise to 4 on hover.
+
+## Import
+
+```tsx
+import {ExtendedFAB, FAB} from "react-material-expressive";
+```
+
+## API
+
+```ts
+interface FABProps extends ComponentProps<"button"> {
+  icon?: ReactNode;
+  size?: "fab" | "fabMedium" | "fabLarge"; // 56 / 80 / 96, default "fabMedium"
+  variant?: "primary" | "secondary" | "tertiary"; // default "primary"
+}
+
+interface ExtendedFABProps extends ComponentProps<"button"> {
+  icon?: ReactNode; // optional leading icon (24/28/36px box per size)
+  size?: "small" | "medium" | "large"; // 56 / 80 / 96, default "small"
+  text?: string; // label fallback when no children
+  variant?: "primary" | "secondary" | "tertiary"; // default "primary"
+}
+```
+
+## Variants
+
+- `primary` — primary-container (the M3 Expressive default color style).
+- `secondary` — secondary-container.
+- `tertiary` — tertiary-container.
+
+The small FAB (40) and the `surface` color style were removed — both are no
+longer recommended in M3 Expressive.
+
+## Examples
+
+```tsx
+<FAB aria-label="Create" icon={<MaterialSymbol name="add" />} />
+<FAB aria-label="Edit" size="fabLarge" variant="tertiary"
+     icon={<MaterialSymbol name="edit" size={36} />} />
+<ExtendedFAB icon={<MaterialSymbol name="edit" />}>Compose</ExtendedFAB>
+<ExtendedFAB size="medium" variant="secondary"
+     icon={<MaterialSymbol name="edit" size={28} />}>Compose</ExtendedFAB>
+```
+
+## Gotchas
+
+- FAB is icon-only: pass `aria-label`.
+- Use one FAB per screen (M3); prefer `secondary`/`tertiary` containers on
+  busy surfaces.
+- Inside a DockedToolbar the FAB is flattened
+  automatically — no extra class needed.
+- The spec's solid color styles (primary & on-primary, etc.) aren't
+  built-in variants; recolor via `className` (e.g.
+  `"bg-primary text-on-primary"`).

package/docs/components/FABMenu.md

@@ -0,0 +1,76 @@
+# FABMenu
+
+M3 Expressive FAB menu: a 56dp FAB that morphs into a fully-round close
+button — radius, container color (container → solid set color) and the
+icon crossfade ride one fast-spatial spring, like Compose's
+`ToggleFloatingActionButton` — revealing up to six menu-item pills above
+it, right-aligned and staggered bottom-up (8dp gap to the FAB, 4dp
+between items). Each pill reveals by width from its trailing edge
+(fast-spatial spring) while fading in on a quicker track, and closing
+runs the same springs in reverse, top-down — the Compose
+`FloatingActionButtonMenu` choreography. Items use the medium button
+metrics (height 56, `title-medium`, icon 24, paddings 24, level 3
+shadow) on the set's container color (`md.comp.fab-menu` tokens).
+
+## Import
+
+```tsx
+import {FABMenu} from "react-material-expressive";
+```
+
+## API
+
+```ts
+interface FABMenuProps {
+  children?: ReactNode; // FABMenu.Item list (2–6 items per spec)
+  className?: string;
+  icon?: ReactNode; // FAB icon while closed (24px box)
+  labels?: FABMenuLabels; // trigger aria-labels
+  variant?: "primary" | "secondary" | "tertiary"; // color set
+}
+
+interface FABMenuLabels {
+  open?: string; // trigger aria-label while closed (default "Open menu")
+  close?: string; // trigger aria-label while open (default "Close menu")
+}
+
+interface FABMenuItemProps {
+  className?: string;
+  icon?: ReactNode; // 24px box
+  label?: ReactNode;
+  onClick?: MouseEventHandler;
+}
+```
+
+## Example
+
+```tsx
+<FABMenu
+  icon={<MaterialSymbol name="add" size={24} />}
+  labels={{open: "Create"}}>
+  <FABMenu.Item
+    icon={<MaterialSymbol name="edit" size={24} />}
+    label="Compose"
+    onClick={compose}
+  />
+  <FABMenu.Item
+    icon={<MaterialSymbol name="group" size={24} />}
+    label="New group"
+    onClick={newGroup}
+  />
+</FABMenu>
+```
+
+## Gotchas
+
+- Position the wrapper yourself — per spec the FAB sits with 16dp margins
+  (e.g. `className="fixed right-4 bottom-4"`); the menu opens upward from
+  the FAB's top trailing edge.
+- Item clicks close the menu (so do Escape and outside clicks); run your
+  action in the item `onClick`.
+- The spec recommends 2–6 items.
+- Colors resolve through the `--md-sys-color-*` tokens of the chosen set,
+  so themes apply automatically.
+- **BREAKING:** the `label` prop was replaced by `labels={{open, close}}`
+  (the open-state aria-label, previously hardcoded "Close menu", is now
+  `labels.close`).

package/docs/components/Gallery.md

@@ -0,0 +1,35 @@
+# Gallery
+
+Stacked media gallery with 8dp gaps; compose rows with `Gallery.Row` and
+size each media by width fractions.
+
+## Import
+
+```tsx
+import {Gallery} from "react-material-expressive";
+```
+
+## API
+
+```ts
+type GalleryProps = ComponentProps<"div">;
+type ImageRowProps = ComponentProps<"div">; // Gallery.Row
+```
+
+## Example
+
+```tsx
+<Gallery>
+  <Gallery.Row>
+    <Img alt="" aspect={21 / 9} className="w-full" radius={16} src={hero} />
+  </Gallery.Row>
+  <Gallery.Row>
+    <Img alt="" aspect={1} className="w-1/2" radius={16} src={a} />
+    <Img alt="" aspect={1} className="w-1/2" radius={16} src={b} />
+  </Gallery.Row>
+</Gallery>
+```
+
+## Gotchas
+
+- Layout-only: pair with `Img`/`Video` or any media node.

package/docs/components/Icon.md

@@ -0,0 +1,36 @@
+# Icon
+
+Icon slot helper: wraps each provided node in a fixed square box (default
+24px, `shrink-0`, centered, `leading-none`) so arbitrary icons align with
+adjacent text. Used internally by buttons/menus; useful for custom rows.
+
+## Import
+
+```tsx
+import {Icon} from "react-material-expressive";
+```
+
+## API
+
+```ts
+interface IconProps {
+  className?: string;
+  icon?: ReactNode; // standalone slot
+  iconLeft?: ReactNode; // leading slot
+  iconRight?: ReactNode; // trailing slot
+  size?: number; // box px, default 24
+}
+```
+
+## Example
+
+```tsx
+<span className="flex items-center gap-2 text-body-large">
+  <Icon iconLeft={<MaterialSymbol name="event" />} />
+  Aligned with text
+</span>
+```
+
+## Gotchas
+
+- The box fixes ALIGNMENT; size the glyph itself via the icon you pass.

package/docs/components/IconButton.md

@@ -0,0 +1,69 @@
+# IconButton
+
+M3 icon button: 40×40 visual container with a 48×48 touch target, 24px
+icon, full shape. M3 Expressive sizes, widths, shapes and the toggle
+(`selected`) variant are available.
+
+## Import
+
+```tsx
+import {IconButton} from "react-material-expressive";
+```
+
+## API
+
+```ts
+interface IconButtonProps extends ComponentProps<"button"> {
+  icon?: ReactNode; // 24px box; children work as a fallback slot
+  selected?: boolean; // M3 Expressive toggle (adds aria-pressed)
+  shape?: "round" | "square"; // M3 Expressive; default "round"
+  size?: "xs" | "s" | "m" | "l" | "xl"; // M3 Expressive: 32/40/56/96/136, default "s"
+  variant?: "filled" | "tonal" | "outlined" | "standard"; // default "filled"
+  width?: "narrow" | "default" | "wide"; // M3 Expressive
+}
+```
+
+## Variants
+
+- `filled` — primary container.
+- `tonal` — secondary-container.
+- `outlined` — outline border, on-surface-variant icon.
+- `standard` — no container, on-surface-variant icon.
+
+## Expressive sizes, widths and toggle
+
+Sizes use icons 20/24/24/32/40; `width` narrows or widens the container
+per size. Pressing morphs both shapes to the per-size pressed radius
+(8/8/12/16/16, the DSDB PressedContainerShape tokens). With `selected` the button becomes a toggle: colors follow the
+M3 Expressive toggle tokens per variant (filled: surface-container ↔
+primary; tonal: secondary-container ↔ secondary; outlined selected:
+inverse-surface; standard: on-surface-variant ↔ primary) and the shape
+flips with the selection (unselected round, selected square) unless
+`shape` is set explicitly.
+
+## States
+
+State layers on hover/focus/pressed (the press ripple grows from the
+pointer); `disabled` = container `on-surface/12` + icon `on-surface/38`
+(standard/outlined keep no fill).
+
+## Examples
+
+```tsx
+<IconButton
+    aria-label="Settings"
+    icon={<MaterialSymbol name="settings" />}
+    variant="standard"
+/>
+<IconButton
+    aria-label="Favorite"
+    icon={<MaterialSymbol name="favorite" />}
+    selected={isFavorite}
+    onClick={() => setIsFavorite((value) => !value)}
+/>
+```
+
+## Gotchas
+
+- Icon-only: always pass `aria-label`.
+- The 48×48 touch target is a child span on the sub-48 sizes (`xs`/`s`).

package/docs/components/Img.md

@@ -0,0 +1,52 @@
+# Img
+
+MediaFrame + image: renders a native `<img>` (object-fit, hides on error
+so the placeholder shows) or your injected media. Accepts
+`string | StaticImageData` sources.
+
+## Import
+
+```tsx
+import {Img} from "react-material-expressive";
+```
+
+## API
+
+```ts
+interface ImgProps extends MediaInjectionProps {
+  // children | image | render
+  alt?: string;
+  aspect?: number | string; // e.g. 16/9
+  className?: string;
+  height?: number | string;
+  width?: number | string;
+  objectFit?: "fill" | "contain" | "cover" | "none" | "scale-down"; // default cover
+  onClick?: MouseEventHandler<HTMLDivElement>;
+  placeholder?: ReactNode; // shown with no media or on error
+  radius?: number | string; // px or CSS value
+  size?: number | string; // width = height shorthand
+  src?: string | StaticImageData;
+  style?: CSSProperties;
+}
+```
+
+Injection priority: `render({src, alt, className, style})` > `image` >
+`children` > native `<img>`.
+
+## Examples
+
+```tsx
+<Img alt="Cover" aspect={16 / 9} radius={16} src="/cover.jpg" width={320} />
+<Img alt="Broken" placeholder={<MaterialSymbol name="broken_image" />} size={140} src={maybeUrl} />
+
+// Next.js injection
+<Img aspect={1} size={140} src={photo} render={({src, alt, className, style}) => (
+    <Image alt={alt} className={className} fill src={src!} style={style} />
+)} />
+```
+
+## Gotchas
+
+- The frame paints `surface-container-highest` behind the media — visible
+  while loading and on error.
+- `radius` accepts CSS strings (e.g. `"var(--md-sys-shape-corner-large)"`).

package/docs/components/Layers.md

@@ -0,0 +1,43 @@
+# Layers — Container / Section
+
+Layout helpers. `Container` is a dotted showcase panel (token-based dot
+grid, large shape) for presenting content over a neutral, theme-aware
+background. `Section` is a responsive content band: column on small
+screens, row on `lg+`.
+
+## Import
+
+```tsx
+import {Container, Section} from "react-material-expressive";
+```
+
+## API
+
+```ts
+interface ContainerProps {
+  children?: ReactNode;
+  className?: string;
+  padding?: string; // padding class override (default p-6)
+}
+
+interface SectionProps {
+  children: ReactNode;
+  className?: string;
+}
+```
+
+## Example
+
+```tsx
+<Section>
+  <Card>…</Card>
+  <Container className="mx-0">
+    <Button>Showcased</Button>
+  </Container>
+</Section>
+```
+
+## Gotchas
+
+- The dot grid uses `--md-sys-color-outline-variant`, so it adapts to the
+  active theme.

package/docs/components/Link.md

@@ -0,0 +1,43 @@
+# LinkBox / LinkContainer
+
+Native `<a>` links — no router coupling. `LinkBox` is a **text link** that
+reads as a link: primary color, **underlined at rest** (the underline is not
+color-only on purpose — an inline link must be distinguishable from body text
+without relying on color, WCAG 1.4.1, since `primary` vs text is only
+2.64:1 light / 1.31:1 dark). The current page (`active`) gets a heavier
+underline (no color change) + `aria-current="page"`. `LinkContainer` is a
+block-level link that wraps arbitrary content (cards, media) without adding
+text styling.
+
+## Import
+
+```tsx
+import {LinkBox, LinkContainer} from "react-material-expressive";
+```
+
+## API
+
+```ts
+interface LinkBoxProps extends ComponentProps<"a"> {
+  active?: boolean; // explicit current-page (heavier underline); else derived
+  currentPath?: string; // pathname from YOUR router
+}
+type LinkContainerProps = ComponentProps<"a">;
+```
+
+## Examples
+
+```tsx
+<p>Read the <LinkBox href="/guidelines">guidelines</LinkBox>.</p>
+<LinkBox currentPath={pathname} href="/docs">Docs</LinkBox>
+
+<LinkContainer aria-label="Open article" href="/post/42">
+    <Card variant="outlined">…</Card>
+</LinkContainer>
+```
+
+## Gotchas
+
+- Client-side routing: intercept `onClick` (preventDefault + router.push)
+  or wrap with your framework's Link passing these as children styles.
+- `LinkBox` inherits font size; set type scale via `className`.

package/docs/components/List.md

@@ -0,0 +1,87 @@
+# List
+
+M3 list: transparent container (inherits the surface it sits on) with
+8dp vertical padding; item height follows the text-row count — **56dp**
+one-line, **72dp** two-line, **88dp** three-line (overline + headline +
+supporting; three-line items top-align their leading + text, the trailing
+element stays centered). 16dp leading/trailing space, 12dp between elements.
+Compose with `List.Item`. `variant` defaults to `"expressive"` (filled
+`surface-container` tiles separated by a 2dp gap, with a container shape that
+morphs on interaction (4 → 12 → 16dp) and 20px icons — recommended for new
+designs); pass `variant="plain"` for the transparent, rectangular list with
+24px icons, which M3E keeps available.
+
+## Import
+
+```tsx
+import {List} from "react-material-expressive";
+```
+
+## API
+
+```ts
+interface ListProps extends ComponentProps<"ul"> {
+  variant?: "expressive" | "plain"; // default "expressive"
+}
+
+interface ListItemProps {
+  body?: ReactNode; // supporting text → 72dp item
+  children?: ReactNode; // custom content replacing the text block
+  className?: string;
+  disabled?: boolean;
+  headline?: ReactNode; // body-large
+  href?: string; // renders a native <a>
+  label?: ReactNode; // overline (label-small)
+  leftElement?: ReactNode; // 24px min box, on-surface-variant
+  onClick?: MouseEventHandler<HTMLElement>;
+  rightElement?: ReactNode;
+  selected?: boolean; // secondary-container fill + on-secondary-container (visual)
+  target?: string;
+}
+```
+
+Interactive items (`href`/`onClick`) render `<a>`/`<button>` with an M3
+state layer; static items render a plain row. `selected` is visual only
+(secondary-container) — the consumer owns selection semantics, as with
+`Menu.Item`.
+
+## Example
+
+```tsx
+<List>
+    <List.Item
+        headline="Inbox"
+        leftElement={<MaterialSymbol name="inbox" />}
+        onClick={openInbox}
+        rightElement={<span>24</span>}
+    />
+    <List.Item
+        headline="Profile"
+        body="Account settings"
+        href="/profile"
+        leftElement={<Avatar name="A" size={40} />}
+    />
+</List>
+
+// Plain (transparent, rectangular) variant.
+<List variant="plain">
+    <List.Item
+        headline="Inbox"
+        leftElement={<MaterialSymbol name="inbox" />}
+        onClick={openInbox}
+    />
+</List>
+```
+
+## Gotchas
+
+- The container is transparent on purpose (M3) — it picks up the sheet,
+  card or surface behind it.
+- For dividers between items use `<Divider className="my-0" inset />`.
+- The default is the **Expressive** variant (`variant="expressive"`): filled
+  `surface-container` tiles with a shape that morphs on interaction
+  (extra-small → medium → large) and 20px icons. The filled tiles read against
+  a plain `surface` background; inside a `surface-container` set a different
+  container via `className`. Pass `variant="plain"` for the M3 **plain** list
+  (transparent, rectangular items, 24px icons), which M3E keeps fully
+  supported.