react-material-expressive 1.0.0

package/docs/components/Badge.md

@@ -0,0 +1,50 @@
+# Badge / DotBadge / OnIconBadge
+
+M3 badges: full shape on the error container. `Badge` is the large badge
+(min 16px, `label-small` count), `DotBadge` the 6px small badge,
+`OnIconBadge` a count badge pre-positioned on an icon's top-right corner.
+
+## Import
+
+```tsx
+import {Badge, DotBadge, OnIconBadge} from "react-material-expressive";
+```
+
+## API
+
+```ts
+interface BadgeProps extends ComponentProps<"div"> {
+  icon?: ReactNode;
+  iconLeft?: ReactNode;
+  iconRight?: ReactNode; // 12px boxes
+  text?: ReactNode; // content fallback when no children
+}
+type DotBadgeProps = ComponentProps<"div">;
+interface OnIconBadgeProps extends ComponentProps<"div"> {
+  count?: ReactNode;
+}
+```
+
+## Examples
+
+```tsx
+<Badge text="3" />
+<Badge className="bg-tertiary text-on-tertiary" text="new" /> // recolor via className
+
+<span className="relative inline-flex">
+    <MaterialSymbol name="notifications" size={32} />
+    <OnIconBadge count="12" />
+</span>
+```
+
+## Gotchas
+
+- `OnIconBadge` positions absolutely — the icon wrapper needs
+  `position: relative`.
+- `OnIconBadge` follows the M3 placement spec (14×12dp from the icon's
+  top-trailing corner): top −2, leading edge fixed 12px from the trailing
+  edge, growing outward (trailing) with the count.
+- Keep counts short ("999+" — the spec caps the badge at 4 characters /
+  16×34dp); the badge grows with content.
+- Dot on an icon goes flush in the corner (`top-0 right-0`), per the
+  spec's 6×6dp corner measurement.

package/docs/components/Blob.md

@@ -0,0 +1,44 @@
+# Blob
+
+Decorative blurred blob with organic border-radius morphing
+(`animate-blob`, 10s loop). Token-colored (`bg-primary/10` by default) and
+non-interactive.
+
+## Import
+
+```tsx
+import {Blob} from "react-material-expressive";
+```
+
+## API
+
+```ts
+interface BlobProps {
+  children?: ReactNode;
+  className?: string;
+  color?: string; // background class, e.g. "bg-tertiary/15"
+  delay?: number; // ms phase offset into the loop, stagger multiple blobs
+  height?: number; // default 300
+  position?: string; // position classes (default centered)
+  width?: number; // default 300
+}
+```
+
+## Example
+
+```tsx
+<section className="relative overflow-hidden">
+  <Blob color="bg-primary/15" position="top-10 left-1/4" />
+  <Blob color="bg-tertiary/15" delay={3000} width={220} height={220} />
+  <h1 className="relative z-10 text-display-small">Hero</h1>
+</section>
+```
+
+## Gotchas
+
+- Absolutely positioned: the parent needs `position: relative` and usually
+  `overflow-hidden`.
+- It's `aria-hidden` and `pointer-events-none` by design.
+- `delay` is applied as a **negative** `animation-delay` (phase offset):
+  staggered blobs morph from the first frame instead of sitting frozen as
+  perfect circles until the delay elapses.

package/docs/components/Button.md

@@ -0,0 +1,79 @@
+# Button
+
+M3 Expressive button. `size` defaults to `s` (small): height 40,
+`label-large`, full shape, 20px icons with 8px icon-label gap and
+symmetric 16dp padding. Five sizes (`xs`/`s`/`m`/`l`/`xl`), `shape`
+(round/square + pressed morph) and a `selected` toggle.
+
+## Import
+
+```tsx
+import {Button} from "react-material-expressive";
+```
+
+## API
+
+```ts
+interface ButtonProps extends ComponentProps<"button"> {
+  iconLeft?: ReactNode; // 20/20/24/32/40px box per size
+  iconRight?: ReactNode;
+  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"
+  text?: string; // label fallback when no children
+  variant?: "filled" | "tonal" | "outlined" | "elevated" | "text"; // default "filled"
+}
+```
+
+## Variants
+
+- `filled` — primary/on-primary, highest emphasis.
+- `tonal` — secondary-container/on-secondary-container.
+- `elevated` — surface-container-low + level 1 shadow (level 2 on hover).
+- `outlined` — outline border, primary label.
+- `text` — lowest emphasis, primary label, no container.
+
+## Expressive sizes and shapes
+
+All five sizes (`xs`/`s`/`m`/`l`/`xl`, default `s`) use symmetric padding
+12/16/24/48/64, icons 20/20/24/32/40, labels label-large → title-medium →
+headline-small → headline-large, and per-size square radii (12/12/16/28/28).
+Pressing morphs both shapes to the per-size pressed radius (8/8/12/16/16,
+the DSDB PressedContainerShape tokens; border-radius transition,
+emphasized). The asymmetric 24dp padding of the old common button is no
+longer recommended in M3E.
+
+## Toggle
+
+With `selected` the button becomes a toggle: colors follow the M3
+Expressive toggle tokens per variant (elevated: surface-container-low ↔
+primary; filled: surface-container ↔ primary; tonal: secondary-container
+↔ secondary; outlined: outline ↔ inverse-surface — the text variant has
+no toggle) and the shape follows the selection (unselected round,
+selected square). Emits `aria-pressed`, so it works inside
+`ButtonGroupConnected` out of the box.
+
+## States
+
+Hover/focus/pressed use M3 state layers (8/12/12% currentColor); the
+press ripple grows from the pointer like @material/web. Filled/tonal gain
+a level 1 shadow on hover. `disabled` renders container `on-surface/12` +
+label `on-surface/38` (outlined: 12% border; no container on text), and
+removes elevation.
+
+## Examples
+
+```tsx
+<Button>Accept</Button>
+<Button variant="tonal" iconLeft={<MaterialSymbol name="add" size={18} />}>
+    New item
+</Button>
+<Button size="xl" shape="square">Get started</Button>
+<Button variant="text" onClick={close}>Cancel</Button>
+```
+
+## Gotchas
+
+- `type` defaults to `"button"` (no accidental form submits).
+- Icons are `ReactNode`; size them at 18px for spec fidelity (or at the
+  per-size icon box when using `size`).

package/docs/components/ButtonGroup.md

@@ -0,0 +1,46 @@
+# ButtonGroup
+
+M3 Expressive standard button group: an invisible container that spaces
+its buttons per size (18/12/8/8/8dp — wider on small sizes to preserve
+48dp touch targets) and adds the press interaction between them: the
+pressed button widens while its direct neighbors compress, animated by
+the shared 200ms emphasized morph (web approximation of the Compose
+~15% width spring).
+
+## Import
+
+```tsx
+import {ButtonGroup} from "react-material-expressive";
+```
+
+## API
+
+```ts
+interface ButtonGroupProps {
+  children?: ReactNode; // Buttons / IconButtons with the same `size`
+  className?: string;
+  label?: string; // aria-label for the group
+  size?: "xs" | "s" | "m" | "l" | "xl"; // default "s"
+}
+```
+
+## Example
+
+```tsx
+<ButtonGroup label="Playback controls" size="s">
+  <Button size="s" text="Back" variant="tonal" />
+  <Button size="s" text="Pause" variant="filled" />
+  <Button size="s" text="Next" variant="tonal" />
+</ButtonGroup>
+```
+
+## Gotchas
+
+- Pass the same `size` to the group and every button inside — the press
+  width-morph assumes the size's symmetric padding.
+- Per spec, avoid text buttons and standard icon buttons inside groups
+  (they have no container treatment). Use filled/tonal/outlined/elevated.
+- The width morph applies to label `Button`s (padding-driven width); icon
+  buttons keep their fixed square size.
+- The group has no colors of its own — theming comes entirely from the
+  buttons' tokens.

package/docs/components/ButtonGroupConnected.md

@@ -0,0 +1,62 @@
+# ButtonGroupConnected
+
+M3 Expressive connected button group: buttons joined by 2dp gaps where
+the group controls the corners. Outer edges keep the group shape — full
+(round) or the per-size square value (4/8/8/16/20dp) — while inner
+corners stay small (8/8/8/16/20dp), sharpen while pressed (4/4/4/12/16dp)
+and round to full when a toggle button is selected. Unlike the standard
+`ButtonGroup` there is no interaction between neighbors. It is the
+M3 Expressive successor of the segmented buttons.
+
+## Import
+
+```tsx
+import {ButtonGroupConnected} from "react-material-expressive";
+```
+
+## API
+
+```ts
+interface ButtonGroupConnectedProps {
+  children?: ReactNode; // Buttons / IconButtons with the same `size`
+  className?: string;
+  label?: string; // aria-label for the group
+  shape?: "round" | "square"; // outer corners (default "round")
+  size?: "xs" | "s" | "m" | "l" | "xl"; // default "s"
+}
+```
+
+## Selection
+
+The group reads selection from the children's `aria-pressed` — toggle
+`IconButton`s (`selected`) work out of the box; manage single or
+multi-select state in your app. The selected button rounds to full and
+its colors follow the button toggle specs.
+
+## Example
+
+```tsx
+const [active, setActive] = useState(0);
+
+<ButtonGroupConnected label="Transport mode">
+  {modes.map((mode, index) => (
+    <IconButton
+      icon={<MaterialSymbol name={mode.icon} size={24} />}
+      key={mode.id}
+      onClick={() => setActive(index)}
+      selected={active === index}
+      size="s"
+      variant="tonal"
+    />
+  ))}
+</ButtonGroupConnected>;
+```
+
+## Gotchas
+
+- Pass the same `size` to the group and every button inside.
+- The group corner system overrides the children's own shape (including
+  their standalone pressed morphs) on purpose — it must, per spec.
+- XS/S groups enforce a 48dp minimum button width for touch targets.
+- The group has no colors of its own — theming comes entirely from the
+  buttons' tokens.

package/docs/components/Card.md

@@ -0,0 +1,52 @@
+# Card
+
+M3 card (shape medium, 16dp padding) with composable sub-parts:
+`Card.Header`, `Card.Body`, `Card.Footer`.
+
+## Import
+
+```tsx
+import {Card} from "react-material-expressive";
+```
+
+## API
+
+```ts
+interface CardProps extends ComponentProps<"div"> {
+  variant?: "elevated" | "filled" | "outlined"; // default "filled"
+}
+// Card.Header / Card.Body / Card.Footer: ComponentProps<"div">
+```
+
+## Variants (M3 spec)
+
+- `elevated` — surface-container-low + elevation level 1.
+- `filled` — surface-container-highest.
+- `outlined` — surface + outline-variant border.
+
+## Example
+
+```tsx
+<Card variant="elevated" className="max-w-sm">
+  <Card.Header>
+    <Avatar name="MX" />
+    <TextElement title="Headline" body="Subhead" />
+  </Card.Header>
+  <Card.Body>
+    <p className="text-body-medium text-on-surface-variant">Content…</p>
+  </Card.Body>
+  <Card.Footer className="justify-end">
+    <Button variant="text">Dismiss</Button>
+    <Button>Action</Button>
+  </Card.Footer>
+</Card>
+```
+
+## Gotchas
+
+- For edge-to-edge media use `className="p-0"` and pad inner content
+  manually (see the WithMedia story).
+- Cards are non-interactive by default; wrap with `LinkContainer` for a
+  clickable card. The hover/pressed/dragged tokens in the M3 card sets
+  apply only to actionable cards, so the base component ships none.
+- Spec guidance: keep at most 8dp between sibling cards.

package/docs/components/Checkbox.md

@@ -0,0 +1,45 @@
+# Checkbox
+
+M3 checkbox: custom-rendered 18×18 box (2dp shape, 2dp outline, checkmark
+in currentColor) with a 40px circular state layer. The native input is the
+source of truth — controlled (`checked` + `onChange`) and uncontrolled
+(`defaultChecked`) both keep platform semantics.
+
+## Import
+
+```tsx
+import {Checkbox} from "react-material-expressive";
+```
+
+## API
+
+```ts
+interface CheckboxProps extends Omit<
+  ComponentProps<"input">,
+  "type" | "size" | "children"
+> {
+  className?: string; // wrapping <label>
+  inputClassName?: string; // visual box
+  label?: ReactNode;
+}
+```
+
+## States
+
+Unchecked (on-surface-variant outline) / checked (primary container,
+on-primary check) / disabled (38% outline; selected disabled: 38%
+container). Hover/focus/pressed show the 40px state layer (on-surface
+unchecked, primary checked).
+
+## Examples
+
+```tsx
+<Checkbox label="Accept terms" onChange={(e) => setOk(e.target.checked)} />
+<Checkbox checked={value} onChange={(e) => setValue(e.target.checked)} label="Controlled" />
+<Checkbox defaultChecked disabled label="Locked" />
+```
+
+## Gotchas
+
+- The label is part of the clickable area (wrapped in `<label>`).
+- For groups just repeat with a shared `name`.

package/docs/components/Chips.md

@@ -0,0 +1,77 @@
+# Chips
+
+M3 chip: height 32, small shape (8), `label-large`, 18px icons. Padding is
+16dp, reduced to 8dp on the icon/remove side automatically.
+
+## Import
+
+```tsx
+import {Chips} from "react-material-expressive";
+```
+
+## API
+
+```ts
+interface ChipsProps extends ComponentProps<"button"> {
+  avatar?: boolean; // input chips: 24dp leading avatar (4dp edge padding)
+  elevated?: boolean; // surface-container-low + level 1 instead of outline
+  labels?: ChipsLabels; // accessible names
+  leftElement?: ReactNode; // 18px box
+  onRemove?: (e) => void; // input chips: trailing remove affordance
+  rightElement?: ReactNode; // 18px box
+  selected?: boolean; // filter/input visual state (controlled by you)
+  text?: string; // label fallback when no children
+  variant?: "assist" | "filter" | "input" | "suggestion"; // default "assist"
+}
+
+interface ChipsLabels {
+  remove?: string; // trailing remove affordance aria-label (default "Remove")
+}
+```
+
+## Variants
+
+- `assist` — on-surface label; leading icon tinted primary.
+- `suggestion` — on-surface-variant label; leading icon tinted primary.
+- `filter` / `input` — on-surface-variant label; when `selected`, the chip
+  turns secondary-container without border. Both expose `aria-pressed`.
+  The leading icon tints primary on unselected filter chips and on
+  selected input chips (per the M3 chip token sets). Selected filter
+  chips grow a leading checkmark (the chip widens ~150ms while the check
+  draws in); a custom `leftElement` crossfades with the check instead.
+- `elevated` — swaps the outline for `surface-container-low` at elevation
+  1 (2 on hover, 1 pressed). Not available on input chips (ignored), like
+  `@material/web`.
+
+The flat outline is `outline-variant` (current M3 tokens) and darkens on
+keyboard focus (on-surface for assist, on-surface-variant otherwise).
+
+## States
+
+State layer on hover/focus/pressed. A selected flat filter chip raises to
+elevation 1 on hover (snap, like every chip elevation). `disabled`: border
+`on-surface/12`, label `on-surface/38` (selected or elevated disabled:
+container `on-surface/12`, no shadow). The input remove affordance carries
+a 48dp-tall touch target that bleeds past the 32dp container (spec: min
+48dp for the close icon).
+
+## Examples
+
+```tsx
+<Chips leftElement={<MaterialSymbol name="event" size={18} />} text="Add to calendar" />
+<Chips variant="filter" selected={active} onClick={toggle} text="Vegan" />
+<Chips variant="input" text="ada@example.com" onRemove={() => remove(id)} />
+<Chips
+    avatar
+    leftElement={<Avatar height={24} name="AL" width={24} />}
+    onRemove={() => remove(id)}
+    text="Ada Lovelace"
+    variant="input"
+/>
+```
+
+## Gotchas
+
+- `selected` is a display prop — manage the selection set in your app
+  (chips are presentational).
+- `onRemove` stops propagation, so chip `onClick` doesn't fire on remove.

package/docs/components/DatePicker.md

@@ -0,0 +1,112 @@
+# DatePicker
+
+M3 date pickers built over the library's `Dialog` / `InputOutlined`
+primitives, controllable and presentational (native `Date`, no date
+dependency, locale via `Intl`). Three forms:
+
+- **`DatePicker`** — modal calendar (360×568 dialog, surface-container-high,
+  level 3, extra-large 28) with a 120dp headline header, month/year
+  navigation, a year grid, and a keyboard-input toggle. Selection is drafted
+  and committed on **OK**.
+- **`DatePicker.Docked`** — an outlined field with a calendar icon that
+  opens a dropdown calendar; selection commits immediately.
+- **`DateRangePicker`** — modal range picker (first tap sets the start, the
+  next the end; the days between highlight in secondary-container).
+
+## Import
+
+```tsx
+import {DatePicker, DateRangePicker} from "react-material-expressive";
+```
+
+## API
+
+```ts
+interface DatePickerProps {
+  input?: boolean; // start in keyboard-input mode
+  isVisible: boolean;
+  labels?: DatePickerLabels; // every user-facing string (see below)
+  locale?: string; // Intl locale; default system
+  max?: Date | null;
+  min?: Date | null;
+  onClose: () => void;
+  onConfirm?: (date: Date | null) => void; // OK
+  value?: Date | null;
+  weekStartsOn?: number; // 0 = Sunday … 6 = Saturday (default 0)
+}
+
+// All text lives in `labels` — each key optional, English defaults shown.
+interface DatePickerLabels {
+  supporting?: ReactNode; // "Select date"
+  cancel?: ReactNode; // "Cancel"
+  confirm?: ReactNode; // "OK"
+  inputLabel?: string; // "Date"
+  inputPlaceholder?: string; // "mm/dd/yyyy"
+  switchToCalendar?: string; // aria (input→calendar toggle)
+  switchToInput?: string; // aria (calendar→input toggle)
+  previousMonth?: string; // aria "Previous month"
+  nextMonth?: string; // aria "Next month"
+  selectYear?: string; // aria "Select year"
+}
+
+interface DatePickerDockedProps {
+  className?: string;
+  labels?: DatePickerDockedLabels; // { field, openCalendar, previousMonth, nextMonth, selectYear }
+  locale?: string;
+  max?: Date | null;
+  min?: Date | null;
+  onChange?: (date: Date | null) => void;
+  value?: Date | null;
+  weekStartsOn?: number;
+}
+
+type DateRange = [Date | null, Date | null];
+interface DateRangePickerProps {
+  isVisible: boolean;
+  // labels: { supporting, cancel, confirm, start, end, previousMonth, nextMonth, selectYear }
+  labels?: DateRangePickerLabels;
+  locale?: string;
+  max?: Date | null;
+  min?: Date | null;
+  onClose: () => void;
+  onConfirm?: (range: DateRange) => void;
+  value?: DateRange;
+  weekStartsOn?: number;
+}
+```
+
+## Example
+
+```tsx
+const [open, setOpen] = useState(false);
+const [date, setDate] = useState<Date | null>(null);
+
+<Button onClick={() => setOpen(true)}>Pick a date</Button>
+<DatePicker
+    isVisible={open}
+    onClose={() => setOpen(false)}
+    onConfirm={setDate}
+    value={date}
+/>;
+
+// Docked
+<DatePicker.Docked value={date} onChange={setDate} />;
+```
+
+## Gotchas
+
+- The modal drafts the selection internally and only calls `onConfirm` on
+  **OK** — Cancel/scrim discards. The docked variant commits on click.
+- Weekday labels and the headline are localized via `Intl`; set `locale`
+  for a fixed locale, `weekStartsOn` for the first column.
+- Every user-facing string (visible text **and** the control aria-labels)
+  is in `labels`, e.g. `labels={{cancel: "Cancelar", confirm: "Aceptar"}}`;
+  unset keys keep the English defaults.
+- `min`/`max` disable out-of-range days.
+
+## Accepted gaps (criterion)
+
+- The range picker uses the standard navigable calendar with in-range
+  highlighting rather than the Android full-screen scrolling-months layout.
+- Day-grid arrow-key navigation is not implemented (days are buttons; Tab
+  reaches them). The input mode covers fast keyboard entry.

package/docs/components/Dialog.md

@@ -0,0 +1,83 @@
+# Dialog
+
+M3 modal dialog: shape extra-large (28), 280–560dp wide,
+surface-container-high container, 32% scrim, elevation 3. Mounts/unmounts
+with fade enter/exit animations and locks body scroll while open.
+
+## Import
+
+```tsx
+import {Dialog} from "react-material-expressive";
+```
+
+## API
+
+```ts
+interface DialogProps {
+    children?: ReactNode;
+    className?: string;
+    dismissable?: boolean;   // scrim click + Escape close (default true)
+    isVisible: boolean;
+    onClose: () => void;
+}
+
+// Sub-parts
+Dialog.Header: {headline?: ReactNode; icon?: ReactNode; text?: ReactNode; className?}
+Dialog.Body:   ComponentProps<"div">  // body-medium, on-surface-variant
+Dialog.Footer: ComponentProps<"div">  // right-aligned action row
+```
+
+`Dialog.Header` renders an optional 24px hero icon (secondary color, which
+centers the header per M3), an `headline-small` headline and
+`body-medium` supporting text. The headline also gives the dialog its
+accessible name: `Dialog` wires `aria-labelledby` to the `Dialog.Header`
+headline through an internal context.
+
+## Accessibility & keyboard
+
+The panel is a `div` (not the native `<dialog>`), so it replicates
+`showModal()` behaviour manually:
+
+- `role="dialog"` + `aria-modal="true"`, named by the `Dialog.Header`
+  headline via `aria-labelledby`. Provide a headline for an accessible
+  name; if you compose a custom header instead, name it yourself.
+- On open, focus moves into the dialog — to a child carrying the
+  `autofocus` attribute if present, otherwise the panel itself — and is
+  restored to the previously focused element on close.
+- `Tab` / `Shift+Tab` are trapped inside the panel and wrap around.
+- `Escape` closes the dialog when `dismissable` (default), same as a
+  scrim click.
+
+## Example
+
+```tsx
+const [open, setOpen] = useState(false);
+
+<Dialog isVisible={open} onClose={() => setOpen(false)}>
+  <Dialog.Header
+    headline="Reset settings?"
+    icon={<MaterialSymbol name="restart_alt" />}
+    text="This cannot be undone."
+  />
+  <Dialog.Footer>
+    <Button variant="text" onClick={() => setOpen(false)}>
+      Cancel
+    </Button>
+    <Button variant="text" onClick={confirm}>
+      Accept
+    </Button>
+  </Dialog.Footer>
+</Dialog>;
+```
+
+## Gotchas
+
+- Controlled-only: there is no internal open state.
+- The exit animation runs 150ms after `isVisible` goes false; the
+  component stays mounted until it finishes (`useDismissable`).
+- Long content scrolls inside the panel as a whole (max-height
+  100vh − 48). This is the only modeled variant: there are no per-section
+  scroll dividers, no full-screen dialog and no `alertdialog` type — the
+  M3 spec lists those as optional/separate, and the basic dialog is
+  faithful to it value-for-value (verified 2026-06-12 against
+  m3.material.io and @material/web).