react-material-expressive 1.0.0

package/docs/components/Progress.md

@@ -0,0 +1,83 @@
+# Progress / Circle
+
+M3 Expressive progress indicators. `Progress` is linear (primary
+indicator over a secondary-container track with a 4px gap and a stop
+indicator; optional `wavy` sine variant); `Circle` is circular (4px
+stroke, 4px track gap, optional center content). Both support determinate
+(`value` 0–100) and `indeterminate` modes with proper `progressbar`
+semantics; the linear indeterminate is the @material/web two-bar (a primary +
+secondary bar translate/scale across; `wavy` runs the same choreography with
+each segment drawn as a traveling sine), and the circular indeterminate is an
+SVG arc with round caps that grows ~10°↔270° while it spins (`wavy` ripples
+that spinning arc).
+
+## Import
+
+```tsx
+import {Circle, Progress} from "react-material-expressive";
+```
+
+## API
+
+```ts
+interface ProgressProps {
+  className?: string;
+  indeterminate?: boolean;
+  labels?: ProgressLabels; // accessible names
+  value?: number; // 0–100
+  wavy?: boolean; // M3 Expressive sine active indicator (indeterminate: two sine segments sweep across)
+}
+
+interface ProgressLabels {
+  label?: string; // aria-label (default "Progress")
+}
+
+interface CircleProps {
+  children?: ReactNode; // center content (e.g. "60%")
+  className?: string;
+  indeterminate?: boolean;
+  labels?: CircleLabels; // accessible names
+  size?: number; // px, defaults: 40 flat / 48 wavy (M3E baselines)
+  strokeWidth?: number; // px, default 4 (the spec's configurable thickness)
+  value?: number; // 0–100
+  wavy?: boolean; // rippled active arc — determinate (flat outside 10-95% like Compose) and the indeterminate spinner
+}
+
+interface CircleLabels {
+  label?: string; // aria-label (default "Progress")
+}
+```
+
+## Examples
+
+```tsx
+<Progress value={60} />
+<Progress value={60} wavy />
+<Progress indeterminate />
+<Circle value={60}>60%</Circle>
+<Circle value={60} wavy />
+<Circle indeterminate size={32} />
+```
+
+## Gotchas
+
+- Determinate values transition like @material/web (linear 250ms,
+  circular stroke 500ms).
+- The linear indeterminate runs @material/web's two-bar choreography (a
+  primary + secondary bar translate/scale, 2s). The flat variant draws solid
+  bars; `wavy` reuses that exact timing — two primary segments sweep sideways
+  (their head/tail `clip-path` is derived from the flat translate/scale) and
+  each shows the same traveling sine as the determinate active indicator
+  (wavelength 40), 10px tall (the flat bar is 4px). The circular indeterminate
+  is an SVG arc with round caps that grows ~10°↔270° while it spins (flat
+  reuses `_Spinner`); `wavy` keeps that spin + grow/shrink dash but draws a
+  rippled ring (amplitude 1.6, wavelength 15) whose wave travels.
+- The flat `Circle indeterminate` and [`Loading`](Loading.md) render the
+  **same** spinner (`_Spinner`) — pick by intent: `Circle` is the **progress
+  indicator**
+  (`role="progressbar"`, fixed `primary`, can hold a center label);
+  `Loading` is the inline **status** spinner (`role="status"`, recolorable
+  via `currentColor`, lives in `elements`) for a busy indicator inside a
+  button or text.
+- **BREAKING:** the `aria-label` prop was replaced by `labels={{label}}` on
+  `Progress`, `Circle` and [`LoadingIndicator`](LoadingIndicator.md).

package/docs/components/Radio.md

@@ -0,0 +1,39 @@
+# Radio
+
+M3 radio button: custom-rendered 20px ring + 10px dot with a 40px circular
+state layer. The native input is the source of truth, so uncontrolled
+groups (shared `name`) keep native semantics; pass `checked` + `onChange`
+for controlled usage.
+
+## Import
+
+```tsx
+import {Radio} from "react-material-expressive";
+```
+
+## API
+
+```ts
+interface RadioProps extends Omit<
+  ComponentProps<"input">,
+  "type" | "size" | "children"
+> {
+  className?: string; // wrapping <label>
+  label?: ReactNode;
+}
+```
+
+## Example
+
+```tsx
+<div role="radiogroup" aria-label="Size">
+  <Radio defaultChecked label="Small" name="size" value="s" />
+  <Radio label="Medium" name="size" value="m" />
+  <Radio disabled label="Large" name="size" value="l" />
+</div>
+```
+
+## Gotchas
+
+- Group radios with the same `name` inside a `role="radiogroup"` container.
+- Disabled follows M3 (38% ring/dot/label).

package/docs/components/Search.md

@@ -0,0 +1,100 @@
+# Search / SearchInput / SearchItem
+
+M3 search bar + docked search view. Default = the M3 Expressive **contained**
+style: a persistent full-pill bar on `surface-container-high` that, on
+click/focus, opens a **separate** suggestions card below — `corner-medium`
+(12) all around, a 2dp gap, no divider, elevation 3. The bar leading icon is
+`on-surface` (primary affordance), the trailing icon/avatar `on-surface-variant`.
+Items are 56dp `body-large` rows. Closes on outside click or Escape.
+
+> **M3 Expressive note:** the legacy **divided** style (`divided`) joins the
+> bar and results with an `outline` divider and squares off the bar's bottom
+> corners (extra-large). M3 Expressive marks it _"not recommended — use
+> contained"_; it stays for baseline parity.
+
+## Import
+
+```tsx
+import {Search, SearchInput} from "react-material-expressive";
+```
+
+## API
+
+```ts
+interface SearchProps {
+  children: ReactNode; // the bar content (SearchInput)
+  className?: string;
+  divided?: boolean; // baseline joined-with-divider style (legacy)
+  result?: ReactNode; // Search.Item list shown while open
+  resultClassName?: string;
+}
+
+interface SearchInputProps extends Omit<
+  ComponentProps<"input">,
+  "placeholder" | "size"
+> {
+  className?: string;
+  inputClassName?: string;
+  labels?: SearchInputLabels; // accessible names
+  leftElement?: ReactNode; // 56px slot (search icon / back)
+  rightElement?: ReactNode; // 56px slot (avatar / mic)
+}
+
+interface SearchInputLabels {
+  placeholder?: string; // input placeholder (default "Search")
+}
+
+interface SearchItemProps {
+  children?;
+  className?;
+  label?: ReactNode;
+  leftElement?: ReactNode; // 24px box
+  onClick?: MouseEventHandler<HTMLButtonElement>;
+  rightElement?: ReactNode;
+}
+```
+
+`Search.Input` and `Search.Item` are also exposed as statics.
+
+## Example
+
+```tsx
+<Search
+  result={
+    <>
+      <Search.Item
+        label="Recent query"
+        leftElement={<MaterialSymbol name="history" />}
+        onClick={pick}
+      />
+      <Search.Item
+        label="Trending"
+        leftElement={<MaterialSymbol name="trending_up" />}
+      />
+    </>
+  }>
+  <SearchInput
+    labels={{placeholder: "Search"}}
+    leftElement={<MaterialSymbol name="search" />}
+    onChange={onQuery}
+  />
+</Search>
+```
+
+## Gotchas
+
+- `SearchInput` is transparent — the `Search` wrapper owns the container
+  color/shape. Standalone bars: wrap in `Search` without `result`.
+- Search bars don't float labels (M3); the placeholder stays visible.
+- The suggestions card opens with the menu choreography (500ms emphasized
+  clip reveal with staggered items, 150ms accelerate exit). In the default
+  **contained** style the bar keeps its 28px pill shape and the card floats
+  2dp below (corner-medium, level-3 shadow). With `divided` the bar's bottom
+  corners square off in step with the reveal (real 28px pill — half the 56dp
+  bar) and the card joins it via the `outline` divider.
+- The bar is flat at rest (tonal-first, matching Compose's `Level0` default);
+  the search-bar token nominally specifies elevation 3.
+- Like the lib's menus, the docked card is an inline overlay (no full-page
+  scrim).
+- **BREAKING:** the native `placeholder` prop was replaced by
+  `labels={{placeholder}}`.

package/docs/components/Select.md

@@ -0,0 +1,76 @@
+# Select
+
+M3 selects: the text field anatomy (height 56, floating label, supporting
+text, error states — filled or outlined) opening a 48dp-item options menu
+with the @material/web animation (500ms emphasized reveal, 150ms
+accelerate close). The caret cross-fades to an up arrow while open (75ms
+linear delayed 75ms, like `md-select`). Keyboard navigation
+(arrows/Home/End/Enter/Esc) and 200ms typeahead like `md-select`; the
+selected option uses secondary-container. Designed to sit next to the text fields in forms —
+same metrics, label behavior and supporting text.
+
+## Import
+
+```tsx
+import {SelectFilled, SelectOutlined} from "react-material-expressive";
+```
+
+## API
+
+```ts
+interface SelectOption {
+  disabled?: boolean;
+  label?: ReactNode; // display content; defaults to the value
+  value: string;
+}
+
+interface SelectFilledProps {
+  className?: string;
+  defaultValue?: string;
+  disabled?: boolean;
+  error?: boolean;
+  errorText?: ReactNode;
+  id?: string;
+  label?: string; // floating label
+  leftElement?: ReactNode; // leading icon (24px box)
+  name?: string; // posts the value via a hidden input
+  onChange?: (value: string) => void;
+  options: SelectOption[];
+  supportingText?: ReactNode;
+  value?: string; // controlled
+}
+// SelectOutlinedProps is identical.
+```
+
+## Examples
+
+```tsx
+<SelectFilled
+    label="Fruit"
+    options={[
+        {label: "Apple", value: "apple"},
+        {label: "Banana", value: "banana"},
+    ]}
+    onChange={setFruit}
+/>
+<SelectOutlined label="Quantity" name="qty" options={options} />
+```
+
+## Keyboard
+
+Closed: `ArrowDown`/`ArrowUp`/`Enter`/`Space` open the menu (highlighting
+the selected option); typing selects the first match directly. Open:
+arrows move the highlight (skipping disabled options, wrapping),
+`Home`/`End` jump, `Enter`/`Space` select, `Escape`/`Tab` close, typing
+highlights by prefix (200ms buffer).
+
+## Gotchas
+
+- Trigger is a `role="combobox"` button with `aria-activedescendant`
+  (focus never leaves the trigger) over a `role="listbox"` menu.
+- `name` renders a hidden input so the value posts in native forms;
+  native `required` validation is not wired — validate in `onSubmit`.
+- The menu matches the field width and clips after ~280px with scroll.
+- The label float shares the text fields' animation: a transform-only
+  tween between two label copies (@material/web technique) — font-size
+  never interpolates.

package/docs/components/Sheets.md

@@ -0,0 +1,62 @@
+# BottomSheet / SideSheet
+
+M3 modal sheets over a 32% scrim, on surface-container-low at elevation 1.
+Both stay mounted during their exit animation (slide down / slide right)
+and lock body scroll while open.
+
+## Import
+
+```tsx
+import {BottomSheet, SideSheet} from "react-material-expressive";
+```
+
+## API
+
+```ts
+interface BottomSheetProps {
+  children?: ReactNode;
+  className?: string;
+  dragHandle?: boolean; // M3 32x4 handle (default true; clicking it closes)
+  isVisible?: boolean;
+  onClose?: () => void;
+}
+
+interface SideSheetProps {
+  children?: ReactNode;
+  className?: string;
+  closeButton?: boolean | ReactNode; // true = default X icon button
+  isVisible?: boolean;
+  labels?: SideSheetLabels; // accessible names
+  onClose?: () => void;
+  title?: ReactNode; // title-large header
+}
+
+interface SideSheetLabels {
+  close?: string; // default close button aria-label (default "Close")
+}
+```
+
+- BottomSheet: extra-large top corners, max width 640, 72dp top margin,
+  slides from the bottom. The 32×4 drag handle is `on-surface-variant`
+  (full opacity, per token) with 22dp padding above/below.
+- SideSheet: docked right, 360px (400 on ≥sm; max-width 400), large start
+  corners, slides from the right. The `title` headline is `on-surface-variant`
+  (M3 side-sheet color role), not on-surface.
+
+## Example
+
+```tsx
+<BottomSheet isVisible={open} onClose={() => setOpen(false)}>
+    <List>…</List>
+</BottomSheet>
+
+<SideSheet closeButton isVisible={open} onClose={close} title="Filters">
+    …
+</SideSheet>
+```
+
+## Gotchas
+
+- Controlled-only (`isVisible` + `onClose`); Escape and scrim click close.
+- Content scrolls inside the sheet; the bottom sheet caps at
+  `100vh − 72px`.

package/docs/components/Slider.md

@@ -0,0 +1,89 @@
+# Slider / SliderDual
+
+M3 Expressive sliders: 16px inset track (primary active /
+secondary-container inactive, full outer corners, 2px inner), 4×44 pill
+handle with a 6px gap on each side (narrows to 2px while pressed),
+`on-secondary-container` stop indicator dots (4dp, 6dp from the end) and a
+44×48 `inverse-surface` value indicator (`label-large`, 12dp above the
+handle) on hover/drag. `size` selects the M3E track scale — `xs` (16dp,
+default), `s` (24), `m` (40), `l` (56), `xl` (96), with handle heights
+44/44/52/68/108 and corners 8/8/12/16/28; the thick sizes (`m`/`l`/`xl`)
+host an optional inset `icon` at the leading edge of the track, two-toned
+to follow it (`on-primary` over the active track, `on-secondary-container`
+over the inactive).
+Built over native `input[type=range]` — keyboard and a11y come for free.
+
+## Import
+
+```tsx
+import {Slider, SliderDual} from "react-material-expressive";
+```
+
+## API
+
+```ts
+interface SliderProps {
+  className?: string;
+  defaultValue?: number;
+  disabled?: boolean;
+  icon?: ReactNode; // inset leading icon (m/l/xl), two-toned by track
+  labels?: SliderLabels; // accessible names
+  max?: number;
+  min?: number;
+  size?: "xs" | "s" | "m" | "l" | "xl"; // M3E track scale (xs default)
+  step?: number; // 100 / 0 / browser default
+  onChange?: (value: number) => void;
+  showLabel?: boolean; // value indicator (default true)
+  tooltipChildren?: ReactNode; // suffix inside the indicator (e.g. "%")
+  value?: number; // controlled
+}
+
+interface SliderLabels {
+  label?: string; // aria-label (default "Slider")
+}
+
+interface SliderDualValue {
+  max: number;
+  min: number;
+}
+interface SliderDualProps {
+  // same options (incl. `size`, no `icon`), with:
+  defaultValue?: SliderDualValue;
+  labels?: SliderDualLabels; // accessible names
+  onChange?: (value: SliderDualValue) => void;
+  value?: SliderDualValue;
+}
+
+interface SliderDualLabels {
+  label?: string; // base aria-label (default "Range slider")
+  minimum?: string; // min handle suffix (default "minimum")
+  maximum?: string; // max handle suffix (default "maximum")
+  // each handle's aria-label = `${label} ${minimum|maximum}`
+}
+```
+
+## Examples
+
+```tsx
+<Slider defaultValue={40} onChange={setVolume} />
+<Slider min={0} max={100} step={10} tooltipChildren="%" />
+<SliderDual value={range} onChange={setRange} />
+```
+
+## Gotchas
+
+- `Slider.onChange` receives a plain number; `SliderDual.onChange` a
+  `{min, max}` pair (handles clamp to ±1 step of each other).
+- Range click-to-jump works on `Slider`; on `SliderDual` only the handles
+  are draggable.
+- Sizes `xs`–`xl` are supported on both `Slider` and `SliderDual`; the
+  inset `icon` is single-`Slider` only (the range's active segment sits
+  between the handles, so there's no fixed leading edge for it).
+- The inset `icon` is two-toned like the stop indicators — `on-primary`
+  over the active track, `on-secondary-container` over the inactive one —
+  so it changes colour (rather than vanishing) as the handle crosses it.
+- The M3E "discrete/stops" rendering (a 4dp stop indicator at every step,
+  on-primary over the active track / on-secondary-container over the
+  inactive one) is not drawn — `step` still snaps the value.
+- **BREAKING:** the `aria-label` prop was replaced by `labels={{label}}`
+  (`SliderDual` handle suffixes are `labels.minimum`/`labels.maximum`).

package/docs/components/Snackbar.md

@@ -0,0 +1,73 @@
+# Snackbar / SnackbarWrapper
+
+M3 snackbar: shape extra-small (4), inverse-surface, min height 48, width
+344–600, `body-medium` text. Action and close render as real M3 buttons
+recolored to inverse roles. `SnackbarWrapper` is the fixed bottom-centered
+stacking area.
+
+## Import
+
+```tsx
+import {Snackbar, SnackbarWrapper} from "react-material-expressive";
+```
+
+## API
+
+```ts
+interface SnackbarProps {
+  actionLabel?: string; // optional text action
+  autoHideDuration?: number; // ms; auto-calls onClose, pauses on hover/focus
+  button?: ReactNode; // extra trailing content
+  className?: string;
+  closeIcon?: ReactNode; // custom X
+  isVisible: boolean;
+  labels?: SnackbarLabels; // accessible names
+  onAction?: () => void;
+  onClose?: () => void;
+  showClose?: boolean; // optional close icon button
+  text?: ReactNode;
+}
+
+interface SnackbarLabels {
+  dismiss?: string; // close button aria-label (default "Dismiss")
+}
+
+interface SnackbarWrapperProps {
+  children: ReactNode;
+  className?: string;
+}
+```
+
+Everything but `isVisible` is optional — a message-only snackbar is valid.
+
+## Example
+
+```tsx
+<SnackbarWrapper>
+  <Snackbar
+    actionLabel="Undo"
+    autoHideDuration={4000}
+    isVisible={open}
+    onAction={undo}
+    onClose={() => setOpen(false)}
+    showClose
+    text="Photo archived"
+  />
+</SnackbarWrapper>
+```
+
+## Gotchas
+
+- Auto-hide pauses while hovered or focused (M3 a11y) and resumes with a
+  full interval on leave.
+- Enter/exit are a fade + scale (0.8↔1) — the M3 Expressive snackbar motion
+  (Compose `FadeInFadeOutWithScale`), not a slide; the component unmounts
+  ~200ms after `isVisible` goes false.
+- Single-line is 48dp, two-line 68dp; elevation level 3.
+- `role="status"` announces politely to screen readers.
+- The dismiss button aria-label is customizable via `labels.dismiss`
+  (default "Dismiss").
+- `SnackbarWrapper` portals to `document.body`, so it always paints above app
+  content no matter where it is mounted — a positioned, z-indexed ancestor
+  can't trap it in a lower stacking context. It renders only on the client
+  (SSR-safe).

package/docs/components/SplitButton.md

@@ -0,0 +1,75 @@
+# SplitButton
+
+M3 Expressive split button: a leading action button plus a trailing menu
+button separated by a 2dp gap. Outer corners are full; the inner corners
+morph on hover/focus/press (4/4/4/8/12dp at rest → 8/12/12/20/20dp per
+size). While the menu is open the trailing button rounds to full, centers
+its caret (rotated 180°) and keeps a pressed-opacity state layer — the
+container colors never change on selection (spec). Colors, state layers,
+elevation and disabled states are the standard button ones, so themes
+apply via the same tokens.
+
+## Import
+
+```tsx
+import {SplitButton} from "react-material-expressive";
+```
+
+## API
+
+```ts
+interface SplitButtonProps {
+  children?: ReactNode; // leading button label
+  className?: string;
+  disabled?: boolean; // disables both buttons
+  iconLeft?: ReactNode; // leading icon (sized per size like Button)
+  labels?: SplitButtonLabels; // trailing menu aria-label
+  menu?: ReactNode; // SplitButton.Item list (anchored bottom right)
+  menuClassName?: string;
+  onClick?: MouseEventHandler; // leading button action
+  size?: "xs" | "s" | "m" | "l" | "xl"; // default "s" (40dp)
+  text?: string; // label fallback when no children
+  variant?: "elevated" | "filled" | "tonal" | "outlined"; // default "filled"
+}
+
+interface SplitButtonLabels {
+  menu?: string; // trailing button aria-label (default "More options")
+}
+```
+
+The menu is the shared M3E vertical [`Menu`](Menu.md) (corner-large surface,
+`surface-container-low`, elevation 3) anchored to the trailing button's
+bottom-right; focus returns to that button when it closes. `SplitButton.Item`
+is the shared `Menu.Item` (same as `OverflowMenu.Item`).
+
+## Sizes
+
+Heights match the Expressive button sizes (32/40/56/96/136). The trailing
+button uses the spec menu icon (22/22/26/38/50dp) with the optical offset
+(−1/−1/−2/−3/−6dp) that disappears when open. Both buttons keep the
+Compose 48dp minimum width — it only shows on an icon-only XS leading
+button (which would otherwise be 42dp wide).
+
+## Example
+
+```tsx
+<SplitButton
+  iconLeft={<MaterialSymbol name="send" size={20} />}
+  onClick={send}
+  text="Send"
+  menu={
+    <>
+      <SplitButton.Item label="Schedule send" onClick={schedule} />
+      <SplitButton.Item label="Save draft" onClick={saveDraft} />
+    </>
+  }
+/>
+```
+
+## Gotchas
+
+- The leading button never opens the menu — only the trailing one does
+  (clicks on items close it; Escape and outside clicks too).
+- There is no `text` color variant: the spec only defines elevated,
+  filled, tonal and outlined.
+- **BREAKING:** `menuLabel` was replaced by `labels={{menu}}`.

package/docs/components/Stories.md

@@ -0,0 +1,71 @@
+# Stories
+
+Horizontal scrollable story strip with two item types: `Stories.User`
+(circular, ring/badges/live, name below) and `Stories.Business` (rounded
+media with primary ring and start-aligned label). Media is injectable.
+
+## Import
+
+```tsx
+import {Stories} from "react-material-expressive";
+```
+
+## API
+
+```ts
+interface StoriesProps {
+  children: ReactNode;
+  className?: string;
+}
+
+interface UserItemProps extends MediaInjectionProps {
+  alt?: string;
+  badge?: boolean;
+  badgeColor?: string;
+  badgeIcon?: ReactNode;
+  badgeText?: string;
+  className?: string;
+  live?: boolean;
+  liveColor?: string;
+  liveIcon?: ReactNode;
+  liveText?: string; // default "LIVE"
+  name?: string;
+  onClick?: MouseEventHandler<HTMLDivElement>;
+  radius?: number;
+  size?: number; // default 64
+  ring?: boolean; // animated token-gradient ring
+  src?: string | StaticImageData;
+}
+
+interface BusinessItemProps extends MediaInjectionProps {
+  alt?: string;
+  className?: string;
+  height?: number;
+  width?: number; // default 64
+  onClick?: MouseEventHandler<HTMLDivElement>;
+  radius?: number;
+  ring?: boolean; // static primary ring
+  src?: string | StaticImageData;
+  text?: string;
+}
+```
+
+## Example
+
+```tsx
+<Stories>
+  <Stories.User name="Ada" ring src="/ada.jpg" />
+  <Stories.User live name="Grace" src="/grace.jpg" />
+  <Stories.Business src="/brand.png" text="Coffee & Co" />
+</Stories>
+```
+
+## Gotchas
+
+- Pure presentation: wire `onClick` for your story viewer. `onClick` lands
+  on a `<div>` (no button semantics) — wrap in a `<button>` for keyboard
+  users, like `Avatar`.
+- All imagery falls back per the media-injection contract (render > image
+  > children > native `<img>`).
+- `Stories.User`'s animated ring stops under `prefers-reduced-motion`;
+  `Stories.Business`'s ring is static.