@instruments/materia-ui 0.1.0 → 0.2.0

package/agent-docs.md

@@ -1259,10 +1259,11 @@ The component renders only the field stack - no card, heading, or CTA chrome. Co
 
 `@instruments/materia-ui/components/progress`
 
-Linear progress bar showing completion from 0 to 100; pass `value={null}` for an indeterminate (empty) track. Built on Base UI Progress for accessible semantics.
+Linear progress bar showing completion from 0 to 100. Pass `value={null}` when the amount of work is unknown: a short bar slides across the track on a loop, and under reduced motion it holds still in the middle. Built on Base UI Progress for accessible semantics.
 
-- Use `Progress` for determinate 0–100 completion (`value={null}` for an indeterminate track); position in a stepped flow is `ProgressDots`.
+- Use `Progress` for determinate 0–100 completion and `value={null}` when the total is unknown; position in a stepped flow is `ProgressDots`.
 - For a ring instead of a bar use `ProgressCircle` - it needs an explicit `label` for its native `<progress>` accessible name.
+- Mount `ReducedMotionProvider` at the app root - the indeterminate bar slides via `m.*` (LazyMotion).
 
 ## ProgressDots
 
@@ -1945,7 +1946,7 @@ The typography primitive for body copy - renders a `<p>` (or any element via `as
 Renders a textarea element for multi-line text input (Base UI `Field.Control` rendering a `<textarea>`). Inside a Field it is the field's control: the FieldLabel targets it, FieldDescription/FieldError describe it, and it inherits the field's invalid state.
 
 - Inside a `Field`, let invalid state cascade like `Input` - omit `hasError`; pass it only to force error styling on a standalone `Textarea`.
-- It auto-grows with content (`field-sizing-content`); set `rows` for an initial height rather than pinning height via CSS.
+- It auto-grows with content (`field-sizing-content`); set `rows` for a minimum height in lines rather than pinning height via CSS.
 - Give it a label - inside a `Field` a `FieldLabel` targets it with no ids to wire; standalone, point a `Label`'s `htmlFor` at its `id`. A placeholder is not an accessible name.
 
 ## ThinkingLoader

package/dist/components/button/button-variants.js

@@ -114,18 +114,37 @@ const NEUTRAL_SOFT = "border-border bg-secondary text-secondary-foreground";
 const NEUTRAL_SOFT_GRADIENT = "before:bg-sheen-bright hover:before:bg-sheen-hover active:before:bg-none disabled:before:bg-none data-disabled:before:bg-none data-[hovered=true]:before:bg-sheen-hover data-[pressed=true]:before:bg-none dark:before:bg-sheen-dark";
 const NEUTRAL_OUTLINE = "border-border bg-background text-foreground hover:bg-muted hover:text-accent-foreground data-[hovered=true]:bg-muted data-[hovered=true]:text-accent-foreground";
 const NEUTRAL_GHOST = "border-transparent bg-transparent text-foreground shadow-none hover:bg-muted hover:text-accent-foreground data-[hovered=true]:bg-muted data-[hovered=true]:text-accent-foreground";
-const NEUTRAL_LINK = "border-transparent bg-transparent text-foreground underline-offset-4 shadow-none hover:underline data-[hovered=true]:underline";
-const NEUTRAL_LINK_FLAT = "shadow-none before:hidden active:scale-100 active:underline-offset-5 data-[pressed=true]:scale-100 data-[pressed=true]:underline-offset-5";
+/* ── Link, shared by every tone: no fill at rest or on hover, so each tone
+ * only picks a text colour that reads on the page. ─────────────────── */
+const LINK = "border-transparent bg-transparent underline-offset-4 shadow-none hover:bg-transparent hover:underline data-[hovered=true]:bg-transparent data-[hovered=true]:underline";
+const LINK_FLAT = "shadow-none before:hidden active:scale-100 active:underline-offset-5 data-[pressed=true]:scale-100 data-[pressed=true]:underline-offset-5";
+const NEUTRAL_LINK = `${LINK} text-foreground`;
 const NEUTRAL_TRANSPARENT = "transform-gpu border-transparent bg-primary/50 backdrop-blur-md will-change-[filter,background-color] hover:bg-primary/60 data-[hovered=true]:bg-primary/60";
 /* ── Danger tone (was `variant="destructive"`) modifiers ────────────── */
+// Built like neutral soft. The hover pins the fill, since the danger tone
+// darkens its solid fill on hover.
+const DANGER_SOFT = "border-error-border bg-error-soft text-error-foreground hover:bg-error-soft data-[hovered=true]:bg-error-soft";
 const DANGER_OUTLINE = "border-destructive text-destructive hover:bg-destructive/5 data-[hovered=true]:bg-destructive/5";
 const DANGER_GHOST = "text-destructive hover:bg-destructive/10 hover:text-destructive data-[hovered=true]:bg-destructive/10 data-[hovered=true]:text-destructive";
-const DANGER_TRANSPARENT = "transform-gpu border-transparent bg-destructive/50 backdrop-blur-md will-change-[filter,background-color] hover:bg-destructive/60 data-[hovered=true]:bg-destructive/60";
+const DANGER_LINK = `${LINK} text-destructive`;
+// Half the danger fill over a light page is a pale red, so light mode takes
+// dark text; over graphite it is mid-toned, so dark mode takes white, as
+// Pill's status tones do.
+const DANGER_TRANSPARENT = "transform-gpu border-transparent bg-destructive/50 text-foreground backdrop-blur-md will-change-[filter,background-color] hover:bg-destructive/60 data-[hovered=true]:bg-destructive/60 dark:text-white/90";
 /* ── Brand tone (was `variant="brand"`) modifiers ───────────────────── */
 const BRAND_SOLID_GRADIENT = "shadow-button-sheen before:bg-sheen-strong hover:before:bg-sheen-hover active:shadow-none active:before:bg-none disabled:shadow-none disabled:before:bg-none data-disabled:shadow-none data-disabled:before:bg-none data-[hovered=true]:before:bg-sheen-hover data-[pressed=true]:shadow-none data-[pressed=true]:before:bg-none";
-const BRAND_OUTLINE = "border-brand text-brand hover:bg-brand/5 data-[hovered=true]:bg-brand/5";
-const BRAND_GHOST = "text-brand hover:bg-brand/10 hover:text-brand data-[hovered=true]:bg-brand/10 data-[hovered=true]:text-brand";
-const BRAND_TRANSPARENT = "transform-gpu border-transparent bg-brand/50 backdrop-blur-md will-change-[filter,background-color] hover:bg-brand/60 data-[hovered=true]:bg-brand/60";
+// Built like neutral soft, with Pill's brand soft colours. Dark brand soft is
+// graphite, so the text there takes the brand accent.
+const BRAND_SOFT = "bg-brand-soft text-brand-foreground dark:text-brand-accent";
+// Without a fill, brand yellow is unreadable on the page, so the text takes
+// `brand-strong`; the outline border can stay yellow.
+const BRAND_OUTLINE = "border-brand text-brand-strong hover:bg-brand/5 data-[hovered=true]:bg-brand/5";
+const BRAND_GHOST = "text-brand-strong hover:bg-brand/10 hover:text-brand-strong data-[hovered=true]:bg-brand/10 data-[hovered=true]:text-brand-strong";
+const BRAND_LINK = `${LINK} text-brand-strong`;
+// Over graphite, half the brand fill turns olive and the brand foreground
+// stops reading, so dark mode thickens the fill rather than swapping the text,
+// which keeps the brand and its foreground overridable as a pair.
+const BRAND_TRANSPARENT = "transform-gpu border-transparent bg-brand/50 backdrop-blur-md will-change-[filter,background-color] hover:bg-brand/60 data-[hovered=true]:bg-brand/60 dark:bg-brand/70 dark:hover:bg-brand/80 dark:data-[hovered=true]:bg-brand/80";
 /**
  * buttonVariants - CVA helper for Button styling.
  *
@@ -191,7 +210,7 @@ const buttonVariants = cva([
         },
         {
             asInput: false,
-            class: `${NEUTRAL_LINK} ${SOLID_SURFACE} ${NEUTRAL_LINK_FLAT}`,
+            class: `${NEUTRAL_LINK} ${SOLID_SURFACE} ${LINK_FLAT}`,
             emphasis: "link",
             tone: "neutral",
         },
@@ -208,6 +227,12 @@ const buttonVariants = cva([
             emphasis: "solid",
             tone: "danger",
         },
+        {
+            asInput: false,
+            class: `${DANGER_SOFT} ${SOLID_SURFACE} ${SOLID_SHADOW} ${NEUTRAL_SOFT_GRADIENT}`,
+            emphasis: "soft",
+            tone: "danger",
+        },
         {
             asInput: false,
             class: `${SOLID_SHADOW} ${DANGER_OUTLINE}`,
@@ -226,6 +251,12 @@ const buttonVariants = cva([
             emphasis: "transparent",
             tone: "danger",
         },
+        {
+            asInput: false,
+            class: `${DANGER_LINK} ${LINK_FLAT}`,
+            emphasis: "link",
+            tone: "danger",
+        },
         /* ── Brand tone (base colours from variants.tone) ─────── */
         {
             asInput: false,
@@ -233,6 +264,12 @@ const buttonVariants = cva([
             emphasis: "solid",
             tone: "brand",
         },
+        {
+            asInput: false,
+            class: `${BRAND_SOFT} ${SOLID_SURFACE} ${SOLID_SHADOW} ${NEUTRAL_SOFT_GRADIENT}`,
+            emphasis: "soft",
+            tone: "brand",
+        },
         {
             asInput: false,
             class: `${SOLID_SHADOW} ${BRAND_OUTLINE}`,
@@ -251,6 +288,12 @@ const buttonVariants = cva([
             emphasis: "transparent",
             tone: "brand",
         },
+        {
+            asInput: false,
+            class: `${BRAND_LINK} ${LINK_FLAT}`,
+            emphasis: "link",
+            tone: "brand",
+        },
         // Input chips carry the solid drop-shadow (was `variant="default"`).
         // asInput replaces every tone/emphasis surface (gated `asInput: false`).
         { asInput: true, class: SOLID_SHADOW },
@@ -281,10 +324,12 @@ const buttonVariants = cva([
         // brand|danger>, emphasis is the full Emphasis plus Button's `link`
         // extension. The `satisfies Record<…>` fails to compile if these keys
         // drift from ButtonTone/ButtonEmphasis (declared below).
+        // Danger fades only to /95 on hover: a lighter red under the light
+        // foreground and the sheen drops below 4.5:1 at /90.
         tone: {
             neutral: "",
             brand: "border-brand-accent/40 bg-brand text-brand-foreground focus-visible:ring-brand/25 data-[focused=true]:ring-brand/25",
-            danger: "border-destructive bg-destructive text-destructive-foreground hover:bg-destructive/90 data-[hovered=true]:bg-destructive/90 focus-visible:ring-red-400/50 data-[focused=true]:ring-red-400/50",
+            danger: "border-destructive bg-destructive text-destructive-foreground hover:bg-destructive/95 data-[hovered=true]:bg-destructive/95 focus-visible:ring-red-400/50 data-[focused=true]:ring-red-400/50",
         },
         emphasis: {
             solid: "",

package/dist/components/button-group/button-group-root.js

@@ -40,16 +40,18 @@ const buttonGroupVariants = cva("flex w-fit items-stretch *:focus-visible:relati
             dividers: false,
             variant: "segmented",
         },
-        // Remove overlapping borders when dividers are disabled (joined variant behaviour)
+        // A joined group keeps each child's own border and drops every trailing
+        // edge but the last, so neighbours share one line and an outline group
+        // reads as one continuous outline. Dividers recolour that shared edge.
         {
-            class: "[&>[data-slot=button]]:border-0",
-            dividers: false,
+            class: "[&>*:not(:last-child)]:border-r-0",
             orientation: "horizontal",
+            variant: "joined",
         },
         {
-            class: "[&>[data-slot=button]]:border-0",
-            dividers: false,
+            class: "[&>*:not(:last-child)]:border-b-0",
             orientation: "vertical",
+            variant: "joined",
         },
         // Optional radius overrides (applies to non-separator items)
         {
@@ -90,7 +92,7 @@ const buttonGroupVariants = cva("flex w-fit items-stretch *:focus-visible:relati
         variant: {
             /**
              * Default "joined" behaviour - relies on each child for borders/background,
-             * and simply removes overlapping borders + inner radii.
+             * and collapses the borders and inner radii where neighbours meet.
              */
             joined: "",
             /**

package/dist/components/calendar/calendar-root.js

@@ -2,16 +2,42 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { cn } from "@instruments/materia-ui/utils/cn";
 import { ChevronLeft, ChevronRight } from "lucide-react";
-import { DayButton, DayPicker } from "react-day-picker";
+import { Day, DayButton, DayPicker } from "react-day-picker";
 import { buttonVariants } from "../button.js";
 import { Icon } from "../icon.js";
 const CalendarChevron = ({ orientation }) => (_jsx(Icon, { icon: orientation === "left" ? ChevronLeft : ChevronRight, size: "xs" }));
 /**
- * DayPicker marks selection on the grid cell, not the button inside it, so the
- * button carries its own copy to paint the filled day. A range's middle days
- * are selected too, but sit on the cell's accent band instead of a fill.
+ * The accent band behind a selected range, painted on the grid cell because
+ * only the cells meet edge to edge. Middle days fill their cell, rounded where
+ * a week starts or ends; the first and last days fill the half that faces the
+ * range, so the band runs into their filled button. A range of one day has no
+ * band.
  */
-const CalendarDayButton = ({ modifiers, ...props }) => (_jsx(DayButton, { "data-selected": modifiers.selected === true && modifiers.range_middle !== true, modifiers: modifiers, ...props }));
+const rangeBandClasses = (modifiers) => {
+    const start = modifiers.range_start === true;
+    const end = modifiers.range_end === true;
+    if (modifiers.range_middle === true) {
+        return "bg-accent text-accent-foreground first:rounded-l-md last:rounded-r-md";
+    }
+    if (start && !end) {
+        return "bg-linear-to-r from-transparent from-50% to-accent to-50% last:rounded-r-md";
+    }
+    if (end && !start) {
+        return "bg-linear-to-l from-transparent from-50% to-accent to-50% first:rounded-l-md";
+    }
+    return undefined;
+};
+const CalendarDay = ({ className, modifiers, ...props }) => (_jsx(Day, { className: cn(className, rangeBandClasses(modifiers)), modifiers: modifiers, ...props }));
+/**
+ * DayPicker marks state on the grid cell, not the button inside it, so the
+ * button carries its own copy to paint the day. A range's middle days are
+ * selected too, but sit on the cell's band instead of a fill; today is tinted
+ * unless it is filled.
+ */
+const CalendarDayButton = ({ modifiers, ...props }) => {
+    const filled = modifiers.selected === true && modifiers.range_middle !== true;
+    return (_jsx(DayButton, { "data-selected": filled, "data-today": modifiers.today === true && !filled, modifiers: modifiers, ...props }));
+};
 /**
  * Date picker built on react-day-picker, styled with the shared button variants;
  * supports `single`, `multiple`, and `range` selection via the `mode` prop.
@@ -26,9 +52,8 @@ const Calendar = ({ className, classNames, showOutsideDays = true, ...props }) =
         button_next: cn(buttonVariants({ emphasis: "ghost", tone: "neutral" }), "text-muted-foreground hover:bg-accent hover:text-foreground size-8 p-0"),
         button_previous: cn(buttonVariants({ emphasis: "ghost", tone: "neutral" }), "text-muted-foreground hover:bg-accent hover:text-foreground size-8 p-0"),
         caption_label: "text-paragraph-sm font-medium",
-        day: cn("text-paragraph-sm relative w-9 p-0 text-center focus-within:relative focus-within:z-20", props.mode === "range" &&
-            "[&:has([aria-selected])]:bg-accent [&:has([aria-selected].day-outside)]:bg-accent/50 [&:has(>.day-range-end)]:rounded-r-md [&:has(>.day-range-start)]:rounded-l-md first:[&:has([aria-selected])]:rounded-l-md last:[&:has([aria-selected])]:rounded-r-md [&:has([aria-selected].day-range-end)]:rounded-r-md"),
-        day_button: cn(buttonVariants({ emphasis: "ghost" }), "data-[selected=true]:bg-primary data-[selected=true]:text-primary-foreground data-[selected=true]:hover:bg-primary data-[selected=true]:hover:text-primary-foreground size-8 rounded-md p-0 font-normal"),
+        day: "text-paragraph-sm relative w-9 p-0 text-center focus-within:relative focus-within:z-20",
+        day_button: cn(buttonVariants({ emphasis: "ghost" }), "data-[today=true]:bg-accent data-[today=true]:text-accent-foreground data-[selected=true]:bg-primary data-[selected=true]:text-primary-foreground data-[selected=true]:hover:bg-primary data-[selected=true]:hover:text-primary-foreground size-8 rounded-md p-0 font-normal"),
         disabled: "text-muted-foreground opacity-50",
         hidden: "invisible",
         month: "flex flex-col gap-4",
@@ -36,18 +61,19 @@ const Calendar = ({ className, classNames, showOutsideDays = true, ...props }) =
         month_grid: "w-full border-collapse space-y-1",
         months: "relative flex flex-col gap-2 sm:flex-row",
         nav: "absolute inset-x-0 top-0 z-10 flex h-9 items-center justify-between px-1",
-        outside: "day-outside text-muted-foreground opacity-50 aria-selected:bg-accent/50 aria-selected:text-muted-foreground aria-selected:opacity-30",
-        range_end: "day-range-end",
-        range_middle: "aria-selected:bg-accent aria-selected:text-accent-foreground",
-        range_start: "day-range-start",
+        outside: "text-muted-foreground opacity-50 aria-selected:bg-accent/50 aria-selected:text-muted-foreground aria-selected:opacity-30",
+        range_end: "",
+        range_middle: "",
+        range_start: "",
         selected: "",
-        today: "bg-accent text-accent-foreground",
+        today: "",
         week: "mt-2 flex w-full",
         weekday: "w-9 rounded-md text-calendar font-normal text-muted-foreground",
         weekdays: "flex",
         ...classNames,
     }, components: {
         Chevron: CalendarChevron,
+        Day: CalendarDay,
         DayButton: CalendarDayButton,
     }, showOutsideDays: showOutsideDays, ...props }));
 Calendar.displayName = "Calendar";

package/dist/components/chart/chart-tooltip.js

@@ -4,14 +4,13 @@ import { cn } from "@instruments/materia-ui/utils/cn";
 import { isNumber, isString } from "../../utils/type-guards.js";
 import { Flex } from "../flex.js";
 import { Grid } from "../grid.js";
-import { getPayloadConfigFromPayload, readDatumStringField, resolveConfigKey, useChart, } from "./chart-context.js";
+import { getPayloadConfigFromPayload, readDatumStringField, resolveConfigKey, resolveEntryKey, useChart, } from "./chart-context.js";
 /** recharts `Tooltip` - pair it with {@link ChartTooltipContent} via `content`. */
 export { Tooltip as ChartTooltip } from "recharts";
 /** One value cell inside the tooltip: swatch (or config icon) + label + value. */
-const TooltipRow = ({ item, indicator, hideIndicator, nestLabel, nestedLabel, color, }) => {
+const TooltipRow = ({ item, indicator, hideIndicator, nestLabel, nestedLabel, color, configKey, }) => {
     const { config } = useChart();
-    const key = resolveConfigKey(item.name, item.dataKey);
-    const itemConfig = getPayloadConfigFromPayload(config, item, key);
+    const itemConfig = getPayloadConfigFromPayload(config, item, configKey);
     const swatchColor = color ?? readDatumStringField(item, "fill") ?? item.color;
     const swatchStyle = {
         "--color-bg": swatchColor,
@@ -58,5 +57,8 @@ export const ChartTooltipContent = ({ active, payload, className, indicator = "d
     const items = payload.filter((item) => item.type !== "none");
     const tooltipLabel = hideLabel ? null : (_jsx(TooltipLabel, { config: config, label: label, labelClassName: labelClassName, labelFormatter: labelFormatter, labelKey: labelKey, payload: payload }));
     const nestLabel = items.length === 1 && indicator !== "dot";
-    return (_jsxs(Grid, { className: cn("bg-popover text-popover-foreground text-caption min-w-32 items-start gap-1.5 rounded-xl border px-2.5 py-1.5 shadow-md dark:shadow-none", className), columns: "none", "data-component": "chart-tooltip-content", "data-slot": "chart-tooltip-content", gap: "none", children: [nestLabel ? null : tooltipLabel, _jsx(Grid, { className: "gap-1.5", columns: "none", gap: "none", children: items.map((item) => (_jsx(TooltipRow, { color: color, hideIndicator: hideIndicator, indicator: indicator, item: item, nestedLabel: tooltipLabel, nestLabel: nestLabel }, resolveConfigKey(nameKey, item.name, item.dataKey)))) })] }));
+    return (_jsxs(Grid, { className: cn("bg-popover text-popover-foreground text-caption min-w-32 items-start gap-1.5 rounded-xl border px-2.5 py-1.5 shadow-md dark:shadow-none", className), columns: "none", "data-component": "chart-tooltip-content", "data-slot": "chart-tooltip-content", gap: "none", children: [nestLabel ? null : tooltipLabel, _jsx(Grid, { className: "gap-1.5", columns: "none", gap: "none", children: items.map((item) => {
+                    const key = resolveConfigKey(nameKey, item.name, item.dataKey);
+                    return (_jsx(TooltipRow, { color: color, configKey: key, hideIndicator: hideIndicator, indicator: indicator, item: item, nestedLabel: tooltipLabel, nestLabel: nestLabel }, resolveEntryKey(item, key)));
+                }) })] }));
 };

package/dist/components/empty/empty-media.js

@@ -16,17 +16,17 @@ const SIZE_MEDIA_MB = {
     sm: "mb-1",
 };
 /**
- * Tone → text colour for the bare (plain) icon. `brand` uses the DS
- * brand-on-plain pairing (`text-brand-accent`, per Pill's ghost-brand
- * treatment) - raw `text-brand` yellow fails contrast on light surfaces.
+ * Tone → text colour for the bare (plain) icon, each at least 3:1 on the page.
+ * Brand and warning hues are too light on a light page, so they take
+ * `brand-strong` and the warning foreground.
  */
 const PLAIN_ICON_TONE = {
-    brand: "text-brand-accent",
+    brand: "text-brand-strong",
     danger: "text-destructive",
     info: "text-info-accent",
     neutral: "text-muted-foreground",
     success: "text-affirmative-accent",
-    warning: "text-amber-500",
+    warning: "text-warning-foreground",
 };
 /** Bare-icon size (one step up from the boxed icon so it reads on its own). */
 const PLAIN_ICON_SIZE = {

package/dist/components/input-group/input-group-textarea.d.ts

@@ -7,7 +7,8 @@ export type InputGroupTextareaProps = Omit<React.ComponentProps<"textarea">, "si
  * Textarea element for use inside InputGroup (Base UI `Field.Control`
  * rendering a `<textarea>`). Inherits disabled state from InputGroup context;
  * inside a Field it is the field's control, and it carries `aria-invalid`
- * when the group has an error.
+ * when the group has an error. It grows with its text, and `rows` sets its
+ * minimum height in lines.
  *
  * @example
  * ```tsx
@@ -19,4 +20,4 @@ export type InputGroupTextareaProps = Omit<React.ComponentProps<"textarea">, "si
  * </InputGroup>
  * ```
  */
-export declare const InputGroupTextarea: ({ className, testId, disabled: disabledProp, id, name, ...props }: InputGroupTextareaProps) => React.JSX.Element;
+export declare const InputGroupTextarea: ({ className, testId, disabled: disabledProp, id, name, rows, style, ...props }: InputGroupTextareaProps) => React.JSX.Element;

package/dist/components/input-group/input-group-textarea.js

@@ -4,11 +4,13 @@ import { Field as FieldPrimitive } from "@base-ui/react/field";
 import { cn } from "@instruments/materia-ui/utils/cn";
 import { INPUT_CONTROL_RESET } from "../../tokens/input-shell.js";
 import { useInputGroup } from "../input-group/input-group-context.js";
+import { useTextareaRows } from "../textarea/use-textarea-rows.js";
 /**
  * Textarea element for use inside InputGroup (Base UI `Field.Control`
  * rendering a `<textarea>`). Inherits disabled state from InputGroup context;
  * inside a Field it is the field's control, and it carries `aria-invalid`
- * when the group has an error.
+ * when the group has an error. It grows with its text, and `rows` sets its
+ * minimum height in lines.
  *
  * @example
  * ```tsx
@@ -20,10 +22,12 @@ import { useInputGroup } from "../input-group/input-group-context.js";
  * </InputGroup>
  * ```
  */
-export const InputGroupTextarea = ({ className, testId, disabled: disabledProp, id, name, ...props }) => {
+export const InputGroupTextarea = ({ className, testId, disabled: disabledProp, id, name, rows, style, ...props }) => {
     const { disabled: contextDisabled, hasError } = useInputGroup();
     const disabled = disabledProp ?? contextDisabled;
+    const { className: sizingClassName, ref: sizingRef, style: sizingStyle, } = useTextareaRows(rows);
     // The control owns id/name/disabled so Field can label and validate it;
-    // textarea-only props ride on the rendered element.
-    return (_jsx(FieldPrimitive.Control, { disabled: disabled, render: _jsx("textarea", { className: cn(INPUT_CONTROL_RESET, "text-paragraph flex field-sizing-content min-h-16 resize-none px-0 py-2", className), "data-component": "input-group-textarea", "data-slot": "input-group-control", ...(hasError ? { "aria-invalid": true } : {}), ...(testId === undefined ? {} : { "data-testid": testId }), ...props }), ...(id === undefined ? {} : { id }), ...(name === undefined ? {} : { name }) }));
+    // textarea-only props ride on the rendered element. The sizing ref sits on
+    // the control so a caller's own `ref` on the textarea still lands.
+    return (_jsx(FieldPrimitive.Control, { disabled: disabled, ref: sizingRef, render: _jsx("textarea", { className: cn(INPUT_CONTROL_RESET, "text-paragraph flex resize-none px-0 py-2", sizingClassName, className), "data-component": "input-group-textarea", "data-slot": "input-group-control", rows: rows, style: { ...sizingStyle, ...style }, ...(hasError ? { "aria-invalid": true } : {}), ...(testId === undefined ? {} : { "data-testid": testId }), ...props }), ...(id === undefined ? {} : { id }), ...(name === undefined ? {} : { name }) }));
 };

package/dist/components/pill/pill-variants.js

@@ -60,15 +60,19 @@ export const pillVariants = cva(cn("inline-flex items-center justify-center bord
             emphasis: "solid",
             tone: "success",
         },
+        // The soft token is pale in light and graphite in dark, the reverse of
+        // the accent fill, so one class reads on it in both themes.
         {
-            className: "text-white/90",
+            className: "text-info-soft",
             emphasis: "solid",
             tone: "info",
         },
+        // Dark mode gives the warning foreground the accent's own colour, as text
+        // on graphite, so the solid takes the graphite soft token instead.
         {
-            className: "text-white/90",
+            className: "dark:text-warning-soft",
             emphasis: "solid",
-            tone: "danger",
+            tone: "warning",
         },
         /* ── Soft (was `light`) ───────────────────────────── */
         /* neutral+soft reproduces the old secondary/solid render */
@@ -152,8 +156,10 @@ export const pillVariants = cva(cn("inline-flex items-center justify-center bord
             emphasis: "ghost",
             tone: "success",
         },
+        // Amber is too light to read on a light page, so light mode takes the
+        // warning foreground.
         {
-            className: "text-warning-accent dark:text-warning-accent",
+            className: "text-warning-foreground dark:text-warning-accent",
             emphasis: "ghost",
             tone: "warning",
         },
@@ -167,8 +173,9 @@ export const pillVariants = cva(cn("inline-flex items-center justify-center bord
             emphasis: "ghost",
             tone: "danger",
         },
+        // Brand accent fails on a light page; graphite keeps the accent.
         {
-            className: "text-brand-accent dark:text-brand-accent",
+            className: "text-brand-strong dark:text-brand-accent",
             emphasis: "ghost",
             tone: "brand",
         },
@@ -178,28 +185,32 @@ export const pillVariants = cva(cn("inline-flex items-center justify-center bord
             emphasis: "transparent",
             tone: "neutral",
         },
+        // A half status fill is pale over a light page and mid-toned over
+        // graphite, so status tones take dark text in light and white in dark.
         {
-            className: "bg-affirmative-accent/50 transform-gpu border-transparent text-white/90 backdrop-blur-md will-change-[filter,background-color]",
+            className: "bg-affirmative-accent/50 text-foreground transform-gpu border-transparent backdrop-blur-md will-change-[filter,background-color] dark:text-white/90",
             emphasis: "transparent",
             tone: "success",
         },
         {
-            className: "bg-warning-accent/50 transform-gpu border-transparent backdrop-blur-md will-change-[filter,background-color]",
+            className: "bg-warning-accent/50 transform-gpu border-transparent backdrop-blur-md will-change-[filter,background-color] dark:text-white/90",
             emphasis: "transparent",
             tone: "warning",
         },
         {
-            className: "bg-info-accent/50 transform-gpu border-transparent text-white/90 backdrop-blur-md will-change-[filter,background-color]",
+            className: "bg-info-accent/50 text-foreground transform-gpu border-transparent backdrop-blur-md will-change-[filter,background-color] dark:text-white/90",
             emphasis: "transparent",
             tone: "info",
         },
         {
-            className: "bg-destructive/50 transform-gpu border-transparent text-white/90 backdrop-blur-md will-change-[filter,background-color]",
+            className: "bg-destructive/50 text-foreground transform-gpu border-transparent backdrop-blur-md will-change-[filter,background-color] dark:text-white/90",
             emphasis: "transparent",
             tone: "danger",
         },
+        // Over graphite a half brand fill turns olive, so dark mode thickens it
+        // and keeps the brand foreground.
         {
-            className: "bg-brand/50 transform-gpu border-transparent backdrop-blur-md will-change-[filter,background-color]",
+            className: "bg-brand/50 dark:bg-brand/70 transform-gpu border-transparent backdrop-blur-md will-change-[filter,background-color]",
             emphasis: "transparent",
             tone: "brand",
         },

package/dist/components/progress/progress-root.d.ts

@@ -21,15 +21,17 @@ interface ProgressCircleProps {
     valueFormatter?: (value: number, max: number) => string;
 }
 /**
- * Linear progress bar showing completion from 0 to 100; pass `value={null}`
- * for an indeterminate (empty) track. Built on Base UI Progress for accessible
- * semantics.
+ * Linear progress bar showing completion from 0 to 100. Pass `value={null}`
+ * when the amount of work is unknown: a short bar slides across the track on a
+ * loop, and under reduced motion it holds still in the middle. Built on Base
+ * UI Progress for accessible semantics.
  *
- * @bestPractice Use `Progress` for determinate 0–100 completion (`value={null}` for an indeterminate track); position in a stepped flow is `ProgressDots`.
+ * @bestPractice Use `Progress` for determinate 0–100 completion and `value={null}` when the total is unknown; position in a stepped flow is `ProgressDots`.
  * @bestPractice For a ring instead of a bar use `ProgressCircle` - it needs an explicit `label` for its native `<progress>` accessible name.
+ * @bestPractice Mount `ReducedMotionProvider` at the app root - the indeterminate bar slides via `m.*` (LazyMotion).
  * @category feedback
  */
-declare const Progress: ({ className, ...props }: ProgressProps) => React.JSX.Element;
+declare const Progress: ({ className, value, ...props }: ProgressProps) => React.JSX.Element;
 /**
  * Circular progress ring with an optional centred content slot; the value is
  * clamped to `0..max` and exposed through a visually hidden native `<progress>`.

package/dist/components/progress/progress-root.js

@@ -2,17 +2,38 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { Progress as ProgressPrimitive } from "@base-ui/react/progress";
 import { Center } from "@instruments/materia-ui/components/center";
+import { durations } from "@instruments/materia-ui/tokens/motion";
 import { cn } from "@instruments/materia-ui/utils/cn";
+import { useReducedMotion } from "motion/react";
+import * as m from "motion/react-m";
+// The indeterminate bar is a third of the track, so translating it by its own
+// width runs it from just off the left edge (-100%) to just off the right
+// (300%).
+const SLIDE = { x: ["-100%", "300%"] };
+const SLIDE_TRANSITION = {
+    duration: durations.slow,
+    ease: "linear",
+    repeat: Number.POSITIVE_INFINITY,
+};
 /**
- * Linear progress bar showing completion from 0 to 100; pass `value={null}`
- * for an indeterminate (empty) track. Built on Base UI Progress for accessible
- * semantics.
+ * Linear progress bar showing completion from 0 to 100. Pass `value={null}`
+ * when the amount of work is unknown: a short bar slides across the track on a
+ * loop, and under reduced motion it holds still in the middle. Built on Base
+ * UI Progress for accessible semantics.
  *
- * @bestPractice Use `Progress` for determinate 0–100 completion (`value={null}` for an indeterminate track); position in a stepped flow is `ProgressDots`.
+ * @bestPractice Use `Progress` for determinate 0–100 completion and `value={null}` when the total is unknown; position in a stepped flow is `ProgressDots`.
  * @bestPractice For a ring instead of a bar use `ProgressCircle` - it needs an explicit `label` for its native `<progress>` accessible name.
+ * @bestPractice Mount `ReducedMotionProvider` at the app root - the indeterminate bar slides via `m.*` (LazyMotion).
  * @category feedback
  */
-const Progress = ({ className, ...props }) => (_jsx(ProgressPrimitive.Root, { className: cn("bg-muted relative block h-2 w-full overflow-hidden rounded-full", className), "data-component": "progress", "data-slot": "progress", ...props, children: _jsx(ProgressPrimitive.Track, { className: "block size-full", "data-component": "progress-track", "data-slot": "progress-track", children: _jsx(ProgressPrimitive.Indicator, { className: "bg-primary transition-width block h-full data-indeterminate:hidden", "data-component": "progress-indicator", "data-slot": "progress-indicator" }) }) }));
+const Progress = ({ className, value, ...props }) => {
+    // Gate on the preference directly: MotionConfig's reduced mode would jump
+    // the slide to its last keyframe, which leaves the bar off the track.
+    const reducedMotion = useReducedMotion() === true;
+    const indeterminate = value === null;
+    const sliding = indeterminate && !reducedMotion;
+    return (_jsx(ProgressPrimitive.Root, { className: cn("bg-muted relative block h-2 w-full overflow-hidden rounded-full", className), "data-component": "progress", "data-slot": "progress", value: value, ...props, children: _jsx(ProgressPrimitive.Track, { className: "block size-full", "data-component": "progress-track", "data-slot": "progress-track", children: _jsx(ProgressPrimitive.Indicator, { className: cn("bg-primary transition-width block h-full", indeterminate && "w-1/3 rounded-full", indeterminate && !sliding && "translate-x-full"), "data-component": "progress-indicator", "data-slot": "progress-indicator", render: sliding ? (_jsx(m.div, { animate: SLIDE, transition: SLIDE_TRANSITION })) : (_jsx("div", {})) }) }) }));
+};
 const clamp = (value, min, max) => {
     if (Number.isNaN(value)) {
         return min;

package/dist/components/radio-group/radio-group-root.d.ts

@@ -30,13 +30,17 @@ declare const RadioGroup: ({ className, ...props }: RadioGroupPrimitive.Props) =
 export type RadioGroupItemProps = RadioProps & {
     /** Label text for the radio option */
     children: React.ReactNode;
+    /** Optional helper text below the label; wired to the radio via `aria-describedby`. */
+    description?: React.ReactNode;
 };
 /**
- * A radio option with an associated label. Combines Radio and Label for convenience.
+ * A radio option with an associated label and optional description. Combines
+ * Radio, Label and muted helper text, laid out like `CheckboxField`.
  *
  * @param props - The radio group item props
  * @param props.value - Unique value for this radio option (required).
  * @param props.children - Label text content.
+ * @param props.description - Helper text below the label, linked to the radio via `aria-describedby`.
  * @param props.size - Size using shared ComponentSize scale. Defaults to "sm".
  * @param props.disabled - Disable this radio option. Defaults to false.
  * @param props.className - Additional CSS classes for the radio input.
@@ -46,9 +50,9 @@ export type RadioGroupItemProps = RadioProps & {
  * ```tsx
  * <RadioGroup>
  *   <RadioGroupItem value="a">Option A</RadioGroupItem>
- *   <RadioGroupItem value="b" disabled>Option B</RadioGroupItem>
+ *   <RadioGroupItem value="b" description="Arrives tomorrow" disabled>Option B</RadioGroupItem>
  * </RadioGroup>
  * ```
  */
-declare const RadioGroupItem: ({ children, className, id: providedId, disabled, ...props }: RadioGroupItemProps) => React.JSX.Element;
+declare const RadioGroupItem: ({ children, description, className, id: providedId, disabled, "aria-describedby": ariaDescribedBy, ...props }: RadioGroupItemProps) => React.JSX.Element;
 export { RadioGroup, RadioGroupItem };

package/dist/components/radio-group/radio-group-root.js

@@ -5,8 +5,10 @@ import { cn } from "@instruments/materia-ui/utils/cn";
 import { useId } from "react";
 import { CONTROL_LINE_CLASSES } from "../../tokens/control-line.js";
 import { Flex } from "../flex.js";
+import { Grid } from "../grid.js";
 import { Label } from "../label.js";
 import { Radio } from "../radio.js";
+import { Text } from "../text.js";
 /**
  * Container for a group of radio buttons. Manages single selection state.
  *
@@ -34,11 +36,13 @@ import { Radio } from "../radio.js";
  */
 const RadioGroup = ({ className, ...props }) => (_jsx(RadioGroupPrimitive, { className: cn("grid gap-3", className), "data-component": "radio-group", "data-slot": "radio-group", ...props }));
 /**
- * A radio option with an associated label. Combines Radio and Label for convenience.
+ * A radio option with an associated label and optional description. Combines
+ * Radio, Label and muted helper text, laid out like `CheckboxField`.
  *
  * @param props - The radio group item props
  * @param props.value - Unique value for this radio option (required).
  * @param props.children - Label text content.
+ * @param props.description - Helper text below the label, linked to the radio via `aria-describedby`.
  * @param props.size - Size using shared ComponentSize scale. Defaults to "sm".
  * @param props.disabled - Disable this radio option. Defaults to false.
  * @param props.className - Additional CSS classes for the radio input.
@@ -48,13 +52,19 @@ const RadioGroup = ({ className, ...props }) => (_jsx(RadioGroupPrimitive, { cla
  * ```tsx
  * <RadioGroup>
  *   <RadioGroupItem value="a">Option A</RadioGroupItem>
- *   <RadioGroupItem value="b" disabled>Option B</RadioGroupItem>
+ *   <RadioGroupItem value="b" description="Arrives tomorrow" disabled>Option B</RadioGroupItem>
  * </RadioGroup>
  * ```
  */
-const RadioGroupItem = ({ children, className, id: providedId, disabled, ...props }) => {
+const RadioGroupItem = ({ children, description, className, id: providedId, disabled, "aria-describedby": ariaDescribedBy, ...props }) => {
     const generatedId = useId();
+    const descriptionId = useId();
     const id = providedId ?? generatedId;
-    return (_jsxs(Flex, { align: "flex-start", "data-component": "radio-group-item", "data-disabled": disabled, "data-slot": "radio-group-item", gap: "xs", children: [_jsx("span", { className: cn(CONTROL_LINE_CLASSES, "text-paragraph-sm"), children: _jsx(Radio, { className: className, disabled: disabled, id: id, ...props }) }), _jsx(Label, { htmlFor: id, children: children })] }));
+    const hasDescription = description !== undefined && description !== null;
+    // Keep any ids the caller passed, and add the description's own.
+    const describedBy = hasDescription
+        ? [ariaDescribedBy, descriptionId].join(" ").trim()
+        : ariaDescribedBy;
+    return (_jsxs(Flex, { align: "flex-start", "data-component": "radio-group-item", "data-disabled": disabled, "data-slot": "radio-group-item", gap: "sm", children: [_jsx("span", { className: cn(CONTROL_LINE_CLASSES, "text-paragraph-sm"), children: _jsx(Radio, { "aria-describedby": describedBy, className: className, disabled: disabled, id: id, ...props }) }), _jsxs(Grid, { columns: "none", gap: "2xs", children: [_jsx(Label, { className: cn("cursor-pointer", disabled === true ? "cursor-not-allowed opacity-60" : null), htmlFor: id, children: children }), hasDescription ? (_jsx(Text, { id: descriptionId, size: "paragraph-sm", variant: "muted", children: description })) : null] })] }));
 };
 export { RadioGroup, RadioGroupItem };

package/dist/components/textarea/textarea-root.d.ts

@@ -24,7 +24,7 @@ interface TextareaProps extends WithTestId<React.ComponentProps<"textarea">> {
  * ```
  *
  * @bestPractice Inside a `Field`, let invalid state cascade like `Input` - omit `hasError`; pass it only to force error styling on a standalone `Textarea`.
- * @bestPractice It auto-grows with content (`field-sizing-content`); set `rows` for an initial height rather than pinning height via CSS.
+ * @bestPractice It auto-grows with content (`field-sizing-content`); set `rows` for a minimum height in lines rather than pinning height via CSS.
  * @bestPractice Give it a label - inside a `Field` a `FieldLabel` targets it with no ids to wire; standalone, point a `Label`'s `htmlFor` at its `id`. A placeholder is not an accessible name.
  * @category forms
  */