react-material-expressive 1.0.0

package/docs/components/Loading.md

@@ -0,0 +1,67 @@
+# Loading
+
+Icon-sized circular **indeterminate** spinner, colored with currentColor
+(defaults to primary). M3 sizing: **40px** diameter (the non-wavy
+`CircularProgressIndicatorTokens.Size`; 48 is only the wavy baseline), 4px
+stroke. The animation is an SVG arc with round caps that grows ~10°↔270°
+while it spins — the **same `_Spinner` `Circle` renders when
+indeterminate**.
+
+`Loading` is not a separate Material component: visually it **is**
+`<Circle indeterminate />`, kept as a convenience that inherits
+`currentColor` and uses `role="status"` so it drops cleanly inside buttons,
+text and tight inline contexts. For the distinct shape-morphing M3
+Expressive component (SoftBurst → … → Oval) see
+[LoadingIndicator](LoadingIndicator.md); for determinate/labelled progress
+use [Circle](Progress.md).
+
+## `Loading` vs `<Circle indeterminate />`
+
+They render the **same spinner** (shared `_Spinner`, identical animation
+and 40px default), so pick by intent, not by looks:
+
+|          | `Loading`                                  | `Circle indeterminate`                                                |
+| -------- | ------------------------------------------ | --------------------------------------------------------------------- |
+| ARIA     | `role="status"` (live region — "loading…") | `role="progressbar"` (busy, no value)                                 |
+| Color    | `currentColor` — recolor via `className`   | fixed `primary` (the progress color)                                  |
+| Lives in | `elements` (inline spinner)                | `components`, with `Progress` (`value`, `wavy`, track, center label…) |
+
+Reach for `Loading` as an **inline "busy" spinner** you drop in a button or
+a sentence and tint with `currentColor`; reach for [`Circle`](Progress.md)
+`indeterminate` when it is a **progress indicator** — same component family
+as the determinate / wavy / labelled progress.
+
+## Import
+
+```tsx
+import {Loading} from "react-material-expressive";
+```
+
+## API
+
+```ts
+interface LoadingProps {
+  className?: string; // e.g. "text-tertiary"
+  labels?: LoadingLabels; // accessible names
+  size?: number; // px, default 40 (M3 non-wavy circular Size)
+  strokeWidth?: number; // px, default 4
+}
+
+interface LoadingLabels {
+  label?: string; // aria-label (default "Loading")
+}
+```
+
+## Examples
+
+```tsx
+<Loading />
+<Loading className="text-on-surface-variant" size={24} />
+```
+
+## Gotchas
+
+- `role="status"` announces it; pass a contextual `labels.label`
+  ("Loading messages").
+- For determinate progress use [Progress / Circle](Progress.md).
+- **BREAKING:** the `label` prop was replaced by `labels={{label}}`.

package/docs/components/LoadingIndicator.md

@@ -0,0 +1,64 @@
+# LoadingIndicator
+
+M3 Expressive loading indicator: a 38dp shape morphing through the
+Compose sequence (SoftBurst → Cookie9Sided → Pentagon → Pill → Sunny →
+Cookie4Sided → Oval) on 650ms ticks that replay the Compose morph spring
+(through the target at speed, 14% overshoot at the brake — the visible size pulse — settle and dwell; damping 0.6/stiffness 200), plus a
++90° rotation kick per morph on top of the 4666ms global rotation,
+inside a 48dp container. The default paints only the `primary` shape;
+`contained` adds the fully-round `primary-container` circle with an
+`on-primary-container` indicator (`md.comp.loading-indicator` tokens).
+The shape morph runs via SVG/SMIL — no JavaScript, works in every
+engine. Indeterminate by design: for determinate progress use
+`Progress`/`Circle`.
+
+## Import
+
+```tsx
+import {LoadingIndicator} from "react-material-expressive";
+```
+
+## API
+
+```ts
+interface LoadingIndicatorProps {
+  className?: string;
+  contained?: boolean; // 48dp primary-container circle
+  labels?: LoadingIndicatorLabels; // accessible names
+}
+
+interface LoadingIndicatorLabels {
+  label?: string; // aria-label (default "Loading")
+}
+```
+
+## Example
+
+```tsx
+{
+  isLoading ? <LoadingIndicator /> : <Results items={items} />;
+}
+{
+  isSyncing ? <LoadingIndicator contained labels={{label: "Syncing"}} /> : null;
+}
+```
+
+## Gotchas
+
+- Use it for short waits (per spec); longer or measurable processes
+  should use the progress indicators instead.
+- **BREAKING:** the `aria-label` prop was replaced by `labels={{label}}`.
+- Colors resolve through `--md-sys-color-*`, so themes apply
+  automatically.
+- Motion and shapes are ported 1:1 from the Compose LoadingIndicator
+  source and `androidx.graphics.shapes`: the keyframe paths are the
+  **exact** MaterialShapes polygons (`RoundedPolygon` corner-rounding +
+  `Morph` feature-matching), generated by the dev-only
+  `scripts/gen-loading-indicator.mjs` into `_loadingIndicatorShapes.ts`
+  (the only artifact shipped). Regenerate with the script — never
+  hand-edit the data file (it is in `.prettierignore` so the generator
+  stays the single source of truth).
+- The `<svg>` is the 48dp container (the Compose draw surface), not the
+  38dp active size: the shapes scale to the 38dp nominal but the spring
+  overshoot pulses them larger (~46px peak), and a 38px box would clip
+  the pulse since an `<svg>` defaults to `overflow:hidden`.

package/docs/components/MaterialSymbol.md

@@ -0,0 +1,48 @@
+# MaterialSymbol
+
+Zero-dependency Material Symbols glyph: renders a ligature `<span>` with
+`font-variation-settings`. It only displays if the consumer loaded the
+corresponding Material Symbols variable font — the library bundles no
+font.
+
+## Import
+
+```tsx
+import {MaterialSymbol} from "react-material-expressive";
+```
+
+Load the font (once, in your app):
+
+```html
+<link
+  href="https://fonts.googleapis.com/css2?family=Material+Symbols+Rounded:opsz,wght,FILL,GRAD@20..48,100..700,0..1,-50..200&display=block"
+  rel="stylesheet" />
+```
+
+## API
+
+```ts
+interface MaterialSymbolProps extends Omit<ComponentProps<"span">, "children"> {
+  fill?: boolean; // FILL axis
+  grade?: number; // GRAD (-25..200)
+  name: string; // ligature, e.g. "favorite"
+  opticalSize?: number; // opsz (defaults to size)
+  size?: number; // px, default 24
+  variant?: "rounded" | "outlined" | "sharp"; // must match the loaded font
+  weight?: number; // wght (100..700)
+}
+```
+
+## Examples
+
+```tsx
+<MaterialSymbol name="favorite" />
+<MaterialSymbol fill name="favorite" className="text-error" />
+<MaterialSymbol name="settings" size={18} weight={500} />
+```
+
+## Gotchas
+
+- `aria-hidden` by default — give the parent control an `aria-label`.
+- Components accept ANY ReactNode icon; this helper is just the
+  recommended zero-dep path.

package/docs/components/MediaFrame.md

@@ -0,0 +1,46 @@
+# MediaFrame
+
+Presentational frame for media: size/aspect/radius/overflow plus an
+optional placeholder, on a surface-container-highest backdrop. Renders no
+image of its own — pair it with `Img`, `Video` or any media node.
+
+## Import
+
+```tsx
+import {MediaFrame} from "react-material-expressive";
+```
+
+## API
+
+```ts
+interface MediaFrameProps {
+  aspect?: number | string;
+  children?: ReactNode; // the media
+  className?: string;
+  height?: number | string;
+  width?: number | string;
+  onClick?: MouseEventHandler<HTMLDivElement>;
+  overflow?: boolean; // clip to shape (default true)
+  placeholder?: ReactNode; // centered fallback
+  radius?: number | string;
+  size?: number | string;
+  style?: CSSProperties;
+}
+```
+
+## Example
+
+```tsx
+<MediaFrame
+  aspect={16 / 9}
+  radius={16}
+  width={320}
+  placeholder={<MaterialSymbol name="movie" size={32} />}>
+  <Video className="absolute inset-0 size-full" src="/clip.mp4" />
+</MediaFrame>
+```
+
+## Gotchas
+
+- Children should usually be absolutely positioned (`absolute inset-0
+size-full`) to fill the frame.

package/docs/components/Menu.md

@@ -0,0 +1,149 @@
+# Menu
+
+The M3 Expressive **vertical menu** surface and behaviour, used as the
+shared primitive behind the anchored menus (`Dropdown`, and — as they
+migrate — `OverflowMenu` / `ToggleThemeMenu`). It is **anchorless**: the
+host positions and mounts it; `Menu` owns the surface, the reveal
+animation and the WAI-ARIA menu keyboard.
+
+Backs `Dropdown`, `OverflowMenu`, `ToggleThemeMenu` and the `SplitButton`
+menu (thin trigger/anchor adapters over this primitive).
+
+Covered: surface, items (`selected`, `badge`, leading/trailing slots),
+group surfaces (`Menu.Group` — the "with gap" grouping), section labels
+(`Menu.Label`), dividers (`Menu.Divider`), **submenus (`Menu.Sub`)**, the
+standard + vibrant schemes and the full menu keyboard. Accepted gap: a
+2-line supporting-text item (not a kit building block — use the item
+content).
+
+## Import
+
+```tsx
+import {Menu} from "react-material-expressive";
+```
+
+## API
+
+```ts
+interface MenuProps {
+  children?: ReactNode; // Menu.Item list
+  className?: string; // host positioning
+  exiting?: boolean; // true while the close animation plays
+  onClose?: () => void; // items call it on activation; Escape/Tab too
+  up?: boolean; // reveal upward (anchored above the trigger)
+  vibrant?: boolean; // tertiary-based scheme instead of standard
+}
+
+interface MenuItemProps {
+  badge?: boolean | string; // trailing error badge (string = count/label)
+  children?: ReactNode;
+  className?: string;
+  disabled?: boolean;
+  keepOpen?: boolean; // don't close the menu on activation
+  label?: ReactNode;
+  leftElement?: ReactNode; // 20px leading box (use icon size 20)
+  onClick?: MouseEventHandler<HTMLButtonElement>;
+  rightElement?: ReactNode; // trailing shortcut text (label-large) or 20px icon
+  selected?: boolean; // tertiary-container fill + corner-medium
+}
+
+interface MenuGroupProps {
+  children?: ReactNode; // Menu.Item list (and nested Menu.Sub)
+  className?: string;
+}
+
+interface MenuLabelProps {
+  children?: ReactNode; // section label text (label-large)
+  className?: string;
+  leftElement?: ReactNode; // optional 20px leading icon
+}
+
+interface MenuDividerProps {
+  className?: string;
+}
+
+interface MenuSubProps {
+  children?: ReactNode; // submenu content (Menu.Item / nested Menu.Sub)
+  className?: string;
+  disabled?: boolean;
+  label?: ReactNode;
+  leftElement?: ReactNode; // 20px leading box
+}
+```
+
+`Menu.Sub` opens a nested menu to the side (rendered in a portal so it
+escapes the surface clip): on hover, Right/Enter, or click; closes on
+Left/Escape (focus returns to the trigger). A leaf activation anywhere
+dismisses the whole chain. The trigger keeps the on-surface state layer
+while open (the M3E active state) and shows a trailing chevron.
+
+Group items two ways — the M3 menu anatomy lists both "Gap" and "Divider"
+as optional parts:
+
+- **With a gap** — wrap each cluster in `Menu.Group`. Each group renders as
+  its own surface (corner-large, its own elevation) and the menu stacks them
+  with a 2dp gap. First/last items round against their own group's corner.
+- **With a divider / label** — interleave `Menu.Divider` (1px
+  `outline-variant`, inset) and `Menu.Label` (section header, 32 tall,
+  `on-surface-variant` / `on-tertiary-container`) as flat children of
+  `Menu`, separating groups within a single surface.
+
+Either way the keyboard treats the whole menu as one list (arrows move
+across groups).
+
+## Anatomy & behaviour
+
+- Container: corner-large (16), `surface-container-low` (standard) or
+  `tertiary-container` (`vibrant`), elevation 3, width clamped 112–280dp.
+  With `Menu.Group` children the container is instead a transparent stack:
+  each group is its own surface (same tokens) and they sit 2dp apart.
+- Item: 48 tall, inset state layer (corner extra-small) with `label-large`,
+  20dp leading/trailing icons, 12dp padding. First/last items round their
+  outer corner to corner-medium (concentric with the container); `selected`
+  morphs the state layer to corner-medium with a tertiary fill.
+- Keyboard (WAI-ARIA menu): on open the menu **surface** is focused, so no
+  item is pre-highlighted and the first ArrowDown/ArrowUp lands on the
+  first/last item; thereafter ArrowUp/Down move between enabled items
+  (wrapping, across groups), Home/End jump, printable keys typeahead
+  (matched against the item's **label** only — leading icons and trailing
+  shortcuts are ignored), Escape closes. (A submenu opened by keyboard
+  instead focuses its first item, per the WAI-ARIA submenu pattern.) Items
+  are `role="menuitem"` with roving `tabindex`, so they are **not** in the
+  Tab order on purpose — Tab moves focus out of the menu; use the arrow keys
+  to move between items.
+
+## Example
+
+```tsx
+<Menu onClose={close}>
+  <Menu.Item
+    label="Profile"
+    leftElement={<MaterialSymbol name="person" size={20} />}
+  />
+  <Menu.Item label="Settings" selected onClick={openSettings} />
+  <Menu.Item disabled label="Workspace" />
+</Menu>
+```
+
+Grouped with a gap (separate surfaces):
+
+```tsx
+<Menu onClose={close}>
+  <Menu.Group>
+    <Menu.Item label="Italic" />
+    <Menu.Item label="Bold" selected />
+    <Menu.Item label="Underline" />
+  </Menu.Group>
+  <Menu.Group>
+    <Menu.Item label="Cut" rightElement="⌘X" />
+    <Menu.Item label="Copy" rightElement="⌘C" />
+  </Menu.Group>
+</Menu>
+```
+
+## Gotchas
+
+- Anchorless: wrap it in a positioned element and control mount/unmount
+  (e.g. via `useDismissable`) yourself, or use `Dropdown` which does this.
+- `selected` is visual; for single-selection semantics in a picker, the
+  consumer still owns the selected value.

package/docs/components/NavigationBar.md

@@ -0,0 +1,78 @@
+# NavigationBar
+
+M3 Expressive flexible navigation bar: height 64,
+surface-container, 3–5 destinations. Vertical items (default) carry a
+32×56 indicator pill over the 24px icon with `label-medium` below;
+`horizontal` switches to the medium-window configuration — fixed-width
+40dp pills holding icon + label, centered in the bar. On selection the
+indicator springs its width and alpha from the center (one axis,
+default-spatial spring) while the icon swaps to its filled variant, and
+the press ripple runs inside the pill. Active colors: indicator
+`secondary-container`, icon `on-secondary-container`, label `secondary`
+when vertical (below the pill) but `on-secondary-container` when
+`horizontal` (inside the pill, on the indicator, matching the icon);
+inactive `on-surface-variant`.
+
+## Import
+
+```tsx
+import {NavigationBar} from "react-material-expressive";
+```
+
+## API
+
+```ts
+interface NavigationBarProps extends ComponentProps<"nav"> {
+  horizontal?: boolean; // 40dp icon+label pills (medium windows)
+}
+
+interface NavBarItemProps {
+  active?: boolean; // explicit; otherwise derived from href+currentPath
+  activeIcon?: ReactNode; // e.g. the filled glyph
+  badge?: boolean;
+  badgeColor?: string;
+  badgeText?: string;
+  className?: string;
+  currentPath?: string; // pathname from YOUR router
+  dotBadge?: boolean;
+  href?: string; // renders a native <a>
+  icon?: ReactNode;
+  label?: ReactNode;
+  onClick?: MouseEventHandler<HTMLElement>;
+  target?: string;
+}
+```
+
+## Example
+
+```tsx
+<NavigationBar>
+  <NavigationBar.Item
+    activeIcon={<MaterialSymbol fill name="home" />}
+    currentPath={pathname}
+    href="/home"
+    icon={<MaterialSymbol name="home" />}
+    label="Home"
+  />
+  <NavigationBar.Item
+    badge
+    badgeText="3"
+    href="/inbox"
+    currentPath={pathname}
+    icon={<MaterialSymbol name="inbox" />}
+    label="Inbox"
+  />
+</NavigationBar>
+```
+
+## Gotchas
+
+- Router-agnostic: pass `currentPath` (or control `active` yourself) and
+  intercept `onClick` for client-side routing.
+- Items without `href` render `<button>`.
+- Active items set `aria-current="page"`.
+- Per spec: always pass `label` (don't remove them), use the filled icon
+  as `activeIcon`, bottom of the window only, compact/medium sizes —
+  desktop layouts should use a navigation rail.
+- Vertical items split the bar width equally; horizontal items are
+  fixed-width and centered (the bar adds the outer margins).

package/docs/components/NavigationRail.md

@@ -0,0 +1,105 @@
+# NavigationRail
+
+M3 Expressive navigation rail. Collapsed: 96dp wide (80 with `narrow`)
+on `surface`, 44dp top spacing, vertical items (32×56 indicator pill,
+`label-medium` below, 4dp apart). `expanded` morphs it into the 220dp
+rail that replaces the navigation drawer: the springing width
+(default-spatial; fast-spatial when `modal`) drives a continuous morph —
+each item is a single row pill stretched open by its label slot into a
+content-hugging 56dp row (`label-large` — larger than the collapsed
+`label-medium` below-label, leading icon, anchored at the 20dp side
+padding — the pill wraps icon + label, it is not full width), the
+below-label collapses while the side-label reveals inside the growing
+pill (the active expanded label sits on the indicator, so it takes
+`on-secondary-container` to match the icon — the collapsed below-label
+stays `secondary` on the surface), and the rail FAB extends with its
+label. The menu button (rendered when `onMenuClick` is set) toggles the
+morph; the library draws its default M3 icon, swapping `menu` → `menu_open`
+with `expanded` (override either glyph via `menuIcon`/`menuOpenIcon`). `modal` overlays
+the expansion as a full-window drawer (fixed, spanning the available
+height like the 32% scrim; surface-container, level 2, large end corners)
+instead of pushing content; the overlay surface eases out in lockstep with the
+width as the rail collapses, deflating smoothly into the resting rail. The selection animation matches the bar:
+indicator expands from the center with the press ripple inside the pill.
+
+## Import
+
+```tsx
+import {NavigationRail} from "react-material-expressive";
+```
+
+## API
+
+```ts
+interface NavigationRailProps {
+  bottom?: ReactNode; // bottom-aligned slot
+  children?: ReactNode; // NavigationRail.Item list
+  className?: string;
+  expanded?: boolean; // 220dp morph (drive from the menu button)
+  fabIcon?: ReactNode; // rail FAB (extends with fabLabel when expanded)
+  fabLabel?: ReactNode;
+  labels?: NavigationRailLabels; // menu button aria-label (expand/collapse)
+  menuIcon?: ReactNode; // override the collapsed glyph (default M3 menu)
+  menuOpenIcon?: ReactNode; // override the expanded glyph (default M3 menu_open)
+  modal?: boolean; // expansion overlays content with a scrim
+  narrow?: boolean; // 80dp collapsed width
+  onFabClick?: MouseEventHandler<HTMLButtonElement>;
+  onClose?: () => void; // modal dismiss (scrim click / Escape)
+  onMenuClick?: MouseEventHandler<HTMLButtonElement>; // renders the menu button (lib draws menu/menu_open)
+}
+interface NavigationRailLabels {
+  expand?: string; // menu aria-label while collapsed. Default "Expand"
+  collapse?: string; // menu aria-label while expanded. Default "Collapse"
+}
+// NavigationRail.Item: same props as NavigationBar.Item
+```
+
+## Example
+
+```tsx
+const [expanded, setExpanded] = useState(false);
+
+<NavigationRail
+  expanded={expanded}
+  fabIcon={<MaterialSymbol name="edit" />}
+  fabLabel="Compose"
+  onFabClick={compose}
+  onMenuClick={() => setExpanded((value) => !value)}>
+  <NavigationRail.Item
+    activeIcon={<MaterialSymbol fill name="inbox" />}
+    currentPath={pathname}
+    href="/inbox"
+    icon={<MaterialSymbol name="inbox" />}
+    label="Inbox"
+  />
+  <NavigationRail.Item
+    currentPath={pathname}
+    href="/sent"
+    icon={<MaterialSymbol name="send" />}
+    label="Sent"
+  />
+</NavigationRail>;
+```
+
+## Gotchas
+
+- The rail is `h-full` — give its parent (or the rail via `className`) a
+  height. The expanded width can be tuned with the
+  `--rail-expanded-width` custom property (spec range 220–360).
+- `expanded` is plain-controlled; provide `onMenuClick` to render the menu
+  button. The library draws the default `menu` ↔ `menu_open` glyph itself
+  (override either with `menuIcon`/`menuOpenIcon`), sets `aria-expanded`,
+  and uses `labels.expand`/`labels.collapse` for the aria-label. Wire
+  `onMenuClick` to flip `expanded`. (Breaking: the old `menu` slot was
+  removed in favor of `onMenuClick`.)
+- With `modal`, the collapsed footprint stays in the layout while the
+  expansion overlays the content as a full-window drawer (it spans the
+  whole window height, like the scrim — give the page that height) — wire
+  `onClose` for scrim/Escape.
+- The rail FAB is coplanar (no shadow) and defaults to
+  `primary-container`; recolor via `className` if needed.
+- Each item renders one pill (no duplicated layouts): the side-label is
+  `aria-hidden` and the accessible name comes from the below-label.
+- Per spec: 3–7 destinations, vertical rails sit opposite the content
+  edge with ≥24dp margins on large screens, and the rail stays fixed
+  while content scrolls vertically.

package/docs/components/OverflowMenu.md

@@ -0,0 +1,65 @@
+# OverflowMenu
+
+M3 contextual menu anchored to a corner of its trigger (default
+bottom-right): shape extra-small (4), surface-container, elevation 2, 48dp items
+with optional badges.
+
+## Import
+
+```tsx
+import {OverflowMenu} from "react-material-expressive";
+```
+
+## API
+
+```ts
+interface OverflowMenuProps {
+  bottomLeft?: boolean;
+  bottomRight?: boolean;
+  topLeft?: boolean;
+  topRight?: boolean;
+  children?: ReactNode; // trigger (usually an IconButton)
+  className?: string;
+  menu?: ReactNode; // OverflowMenu.Item list
+  menuClassName?: string;
+}
+
+interface OverflowMenuItemProps {
+  badge?: boolean;
+  badgeText?: string;
+  children?;
+  className?;
+  disabled?: boolean;
+  label?: ReactNode;
+  leftElement?: ReactNode;
+  onClick?: MouseEventHandler<HTMLButtonElement>;
+  rightElement?: ReactNode;
+}
+```
+
+## Example
+
+```tsx
+<OverflowMenu
+  bottomRight
+  menu={
+    <>
+      <OverflowMenu.Item
+        label="Share"
+        leftElement={<MaterialSymbol name="share" />}
+      />
+      <OverflowMenu.Item badge badgeText="2" label="Comments" />
+    </>
+  }>
+  <IconButton
+    aria-label="More"
+    icon={<MaterialSymbol name="more_vert" />}
+    variant="standard"
+  />
+</OverflowMenu>
+```
+
+## Gotchas
+
+- Position flags are booleans; with none set it falls back to bottomRight.
+- Closes on outside click, item click and Escape.

package/docs/components/Perspective.md

@@ -0,0 +1,45 @@
+# PerspectiveImage / PerspectiveCard
+
+3D tilt showcases. `PerspectiveImage` follows the cursor anywhere on the
+page (hero/parallax); `PerspectiveCard` tilts only while hovered and
+resets on leave. Pointer-only — static on touch devices, and the tilt is
+suppressed under `prefers-reduced-motion` (the effect is purely
+decorative).
+
+## Import
+
+```tsx
+import {
+  PerspectiveCard,
+  PerspectiveImage,
+} from "react-material-expressive";
+```
+
+## API
+
+```ts
+interface PerspectiveImageProps {
+  children?: ReactNode;
+  className?: string;
+  intensity?: number; // deg per cursor px (default 0.03)
+  perspective?: number; // px (default 800)
+}
+// PerspectiveCardProps: same (intensity default 0.025)
+```
+
+## Example
+
+```tsx
+<PerspectiveCard>
+    <Card variant="elevated">…</Card>
+</PerspectiveCard>
+
+<PerspectiveImage intensity={0.02}>
+    <div className="w-fit"><Img alt="" size={280} src={art} /></div>
+</PerspectiveImage>
+```
+
+## Gotchas
+
+- The transform applies to the wrapper — keep it `w-fit` so the rotation
+  pivots on the content, not a full-width row.