@instruments/materia-ui 0.1.0

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

@@ -0,0 +1,66 @@
+import { Tooltip as TooltipPrimitive } from "@base-ui/react/tooltip";
+/**
+ * Shares tooltip timing across all descendant tooltips (hover delay plus
+ * skip-delay grouping so adjacent tooltips open instantly). `delay`
+ * defaults to 0 for instant show; `closeDelay` and `timeout` (the skip-delay
+ * window) are Base UI's. `Tooltip` wraps one of these automatically,
+ * so it's only needed directly to configure timing for a group of tooltips.
+ */
+declare const TooltipProvider: ({ delay, ...props }: TooltipPrimitive.Provider.Props) => import("react").JSX.Element;
+/**
+ * Root component for a tooltip. Wraps TooltipProvider automatically.
+ *
+ * @param props - The tooltip props
+ * @param props.open - Controlled open state. Use with onOpenChange.
+ * @param props.defaultOpen - Uncontrolled default open state.
+ * @param props.onOpenChange - Callback `(open, eventDetails)` when open state changes.
+ * @param props.delay - Delay before showing tooltip in ms. Defaults to 0.
+ * @param props... - All other Base UI Tooltip.Root props.
+ *
+ * @example
+ * ```tsx
+ * <Tooltip>
+ *   <TooltipTrigger>Hover me</TooltipTrigger>
+ *   <TooltipContent>Tooltip text</TooltipContent>
+ * </Tooltip>
+ * ```
+ *
+ * @bestPractice Keep `TooltipContent` a short, non-interactive label - no buttons or links inside; for rich or actionable hover content use `HoverCard`.
+ * @bestPractice The trigger must be focusable (a button / link, or `render` onto one) or keyboard and AT users never see the tip.
+ * @bestPractice Share one `TooltipProvider` to tune `delay` / skip-delay for a group; `Tooltip` wraps its own provider, so you only need it for grouping.
+ * @category overlays
+ */
+declare const Tooltip: <Payload>({ delay, ...props }: TooltipPrimitive.Root.Props<Payload> & {
+    /** Delay before showing tooltip in ms. Defaults to 0. */
+    delay?: number;
+}) => import("react").JSX.Element;
+/**
+ * Element that triggers the tooltip on hover or focus.
+ *
+ * @param props - The tooltip trigger props
+ * @param props... - All Base UI Tooltip.Trigger props.
+ */
+declare const TooltipTrigger: ({ ...props }: TooltipPrimitive.Trigger.Props) => import("react").JSX.Element;
+type TooltipPositionerProps = Pick<TooltipPrimitive.Positioner.Props, "align" | "alignOffset" | "anchor" | "arrowPadding" | "collisionAvoidance" | "collisionBoundary" | "collisionPadding" | "positionMethod" | "side" | "sideOffset" | "sticky">;
+/**
+ * Content displayed in the tooltip. Includes arrow pointer.
+ *
+ * @param props - The tooltip content props
+ * @param props.side - Side relative to trigger. Options: "top", "right", "bottom", "left".
+ * @param props.sideOffset - Distance from trigger in pixels. Defaults to 0.
+ * @param props.align - Alignment relative to trigger. Options: "start", "center", "end".
+ * @param props.className - Additional CSS classes to apply.
+ * @param props.children - Tooltip text content.
+ * @param props... - All other Base UI Tooltip.Popup props.
+ *
+ * @example
+ * ```tsx
+ * <TooltipContent side="top" sideOffset={4}>
+ *   Tooltip text
+ * </TooltipContent>
+ * ```
+ */
+declare const TooltipContent: ({ className, sideOffset, children, side, align, alignOffset, anchor, arrowPadding, collisionAvoidance, collisionBoundary, collisionPadding, positionMethod, sticky, ...props }: Omit<TooltipPrimitive.Popup.Props, "className"> & TooltipPositionerProps & {
+    className?: string;
+}) => import("react").JSX.Element;
+export { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger };

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

@@ -0,0 +1,64 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Tooltip as TooltipPrimitive } from "@base-ui/react/tooltip";
+import { cn } from "@instruments/materia-ui/utils/cn";
+import { POPOVER_CONTENT_ANIMATION } from "../../tokens/overlay-styles.js";
+/**
+ * Shares tooltip timing across all descendant tooltips (hover delay plus
+ * skip-delay grouping so adjacent tooltips open instantly). `delay`
+ * defaults to 0 for instant show; `closeDelay` and `timeout` (the skip-delay
+ * window) are Base UI's. `Tooltip` wraps one of these automatically,
+ * so it's only needed directly to configure timing for a group of tooltips.
+ */
+const TooltipProvider = ({ delay = 0, ...props }) => (_jsx(TooltipPrimitive.Provider, { "data-component": "tooltip-provider", "data-slot": "tooltip-provider", delay: delay, ...props }));
+/**
+ * Root component for a tooltip. Wraps TooltipProvider automatically.
+ *
+ * @param props - The tooltip props
+ * @param props.open - Controlled open state. Use with onOpenChange.
+ * @param props.defaultOpen - Uncontrolled default open state.
+ * @param props.onOpenChange - Callback `(open, eventDetails)` when open state changes.
+ * @param props.delay - Delay before showing tooltip in ms. Defaults to 0.
+ * @param props... - All other Base UI Tooltip.Root props.
+ *
+ * @example
+ * ```tsx
+ * <Tooltip>
+ *   <TooltipTrigger>Hover me</TooltipTrigger>
+ *   <TooltipContent>Tooltip text</TooltipContent>
+ * </Tooltip>
+ * ```
+ *
+ * @bestPractice Keep `TooltipContent` a short, non-interactive label - no buttons or links inside; for rich or actionable hover content use `HoverCard`.
+ * @bestPractice The trigger must be focusable (a button / link, or `render` onto one) or keyboard and AT users never see the tip.
+ * @bestPractice Share one `TooltipProvider` to tune `delay` / skip-delay for a group; `Tooltip` wraps its own provider, so you only need it for grouping.
+ * @category overlays
+ */
+const Tooltip = ({ delay, ...props }) => (_jsx(TooltipProvider, { ...(delay === undefined ? {} : { delay }), children: _jsx(TooltipPrimitive.Root, { "data-component": "tooltip", "data-slot": "tooltip", ...props }) }));
+/**
+ * Element that triggers the tooltip on hover or focus.
+ *
+ * @param props - The tooltip trigger props
+ * @param props... - All Base UI Tooltip.Trigger props.
+ */
+const TooltipTrigger = ({ ...props }) => (_jsx(TooltipPrimitive.Trigger, { "data-component": "tooltip-trigger", "data-slot": "tooltip-trigger", ...props }));
+/**
+ * Content displayed in the tooltip. Includes arrow pointer.
+ *
+ * @param props - The tooltip content props
+ * @param props.side - Side relative to trigger. Options: "top", "right", "bottom", "left".
+ * @param props.sideOffset - Distance from trigger in pixels. Defaults to 0.
+ * @param props.align - Alignment relative to trigger. Options: "start", "center", "end".
+ * @param props.className - Additional CSS classes to apply.
+ * @param props.children - Tooltip text content.
+ * @param props... - All other Base UI Tooltip.Popup props.
+ *
+ * @example
+ * ```tsx
+ * <TooltipContent side="top" sideOffset={4}>
+ *   Tooltip text
+ * </TooltipContent>
+ * ```
+ */
+const TooltipContent = ({ className, sideOffset = 0, children, side, align, alignOffset, anchor, arrowPadding, collisionAvoidance, collisionBoundary, collisionPadding, positionMethod, sticky, ...props }) => (_jsx(TooltipPrimitive.Portal, { children: _jsx(TooltipPrimitive.Positioner, { align: align, alignOffset: alignOffset, anchor: anchor, arrowPadding: arrowPadding, className: "z-50", collisionAvoidance: collisionAvoidance, collisionBoundary: collisionBoundary, collisionPadding: collisionPadding, positionMethod: positionMethod, side: side, sideOffset: sideOffset, sticky: sticky, children: _jsxs(TooltipPrimitive.Popup, { className: cn(`${POPOVER_CONTENT_ANIMATION} bg-foreground text-background text-caption w-fit origin-(--transform-origin) rounded-full px-3 py-1.5 text-balance`, className), "data-component": "tooltip-content", "data-slot": "tooltip-content", ...props, children: [children, _jsx(TooltipPrimitive.Arrow, { className: "bg-foreground z-50 size-2.5 rotate-45 rounded-xs data-[side=bottom]:-top-0.75 data-[side=left]:-right-0.75 data-[side=right]:-left-0.75 data-[side=top]:-bottom-0.75" })] }) }) }));
+export { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger };

package/dist/components/tooltip.d.ts

@@ -0,0 +1 @@
+export { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger, } from "./tooltip/tooltip-root.js";

package/dist/components/tooltip.js

@@ -0,0 +1 @@
+export { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger, } from "./tooltip/tooltip-root.js";

package/dist/components/verge/verge-anatomy.d.ts

@@ -0,0 +1,5 @@
+/**
+ * vergeAnatomy helper for Verge.
+ * Import from "@instruments/materia-ui/components/verge".
+ */
+export declare const vergeAnatomy: import("../../tokens/anatomy.js").ComponentAnatomy;

package/dist/components/verge/verge-anatomy.js

@@ -0,0 +1,17 @@
+import { defineAnatomy } from "../../tokens/anatomy.js";
+/**
+ * vergeAnatomy helper for Verge.
+ * Import from "@instruments/materia-ui/components/verge".
+ */
+export const vergeAnatomy = defineAnatomy({
+    children: [
+        {
+            description: "Reserved space whose controls reveal on hover, focus and touch",
+            label: "VergeSlot",
+            slot: "verge-slot",
+        },
+    ],
+    description: "Row or card the slot listens to for hover and focus",
+    label: "VergeRoot",
+    slot: "verge-root",
+});

package/dist/components/verge/verge-context.d.ts

@@ -0,0 +1,5 @@
+/** Provided by `VergeRoot` so a `VergeSlot` can tell whether a root is listening. */
+declare const VergeProvider: import("react").Provider<boolean>;
+/** True when the slot sits inside a `VergeRoot`. */
+declare const useInsideVerge: () => boolean;
+export { VergeProvider, useInsideVerge };

package/dist/components/verge/verge-context.js

@@ -0,0 +1,8 @@
+"use client";
+import { createContext, useContext } from "react";
+const VergeContext = createContext(false);
+/** Provided by `VergeRoot` so a `VergeSlot` can tell whether a root is listening. */
+const VergeProvider = VergeContext.Provider;
+/** True when the slot sits inside a `VergeRoot`. */
+const useInsideVerge = () => useContext(VergeContext);
+export { VergeProvider, useInsideVerge };

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

@@ -0,0 +1,38 @@
+import { useRender } from "@base-ui/react/use-render";
+import type { LayoutElement } from "../../tokens/element.js";
+export interface VergeRootProps extends useRender.ComponentProps<"div"> {
+    /**
+     * Render as a different host element from the closed layout vocabulary
+     * ({@link LayoutElement}). A row inside a real list must be an `li`.
+     *
+     * `as` and `render` are mutually exclusive; if both are passed, `render`
+     * wins (a dev-only warning fires).
+     * @example <VergeRoot as="li" />
+     */
+    as?: LayoutElement;
+}
+/**
+ * The container a `VergeSlot` listens to: a row, a card, a list item. It has no
+ * appearance of its own, only the hover and focus state its slots read. Wrap
+ * the whole row, not just the controls, so the reveal answers to the user
+ * pointing at the row.
+ *
+ * Adapted from @patternmode/verge.
+ *
+ * @example
+ * ```tsx
+ * <VergeRoot as="li" className="flex items-center gap-2">
+ *   <Text as="span">Carrara marble</Text>
+ *   <VergeSlot slots={2}>
+ *     <Button aria-label="Edit" emphasis="ghost" icon={Pencil} size="icon-xs" />
+ *     <Button aria-label="More" emphasis="ghost" icon={Ellipsis} size="icon-xs" />
+ *   </VergeSlot>
+ * </VergeRoot>
+ * ```
+ *
+ * @bestPractice Wrap the whole row in `VergeRoot`, not just the controls, so hovering or tabbing anywhere in the row reveals them.
+ * @bestPractice A nested `VergeRoot` does not isolate its slots: hovering an outer row also reveals an inner row's controls.
+ * @bestPractice `as` and `render` are mutually exclusive (`render` wins, dev-warned); use `as="li"` inside a real list.
+ * @category layout
+ */
+export declare const VergeRoot: ({ as, children, className, ref, render, ...props }: VergeRootProps) => import("react").JSX.Element;

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

@@ -0,0 +1,48 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useRender } from "@base-ui/react/use-render";
+import { cn } from "@instruments/materia-ui/utils/cn";
+import { reportDevIssue } from "../../utils/dev-issue.js";
+import { VergeProvider } from "./verge-context.js";
+/**
+ * The container a `VergeSlot` listens to: a row, a card, a list item. It has no
+ * appearance of its own, only the hover and focus state its slots read. Wrap
+ * the whole row, not just the controls, so the reveal answers to the user
+ * pointing at the row.
+ *
+ * Adapted from @patternmode/verge.
+ *
+ * @example
+ * ```tsx
+ * <VergeRoot as="li" className="flex items-center gap-2">
+ *   <Text as="span">Carrara marble</Text>
+ *   <VergeSlot slots={2}>
+ *     <Button aria-label="Edit" emphasis="ghost" icon={Pencil} size="icon-xs" />
+ *     <Button aria-label="More" emphasis="ghost" icon={Ellipsis} size="icon-xs" />
+ *   </VergeSlot>
+ * </VergeRoot>
+ * ```
+ *
+ * @bestPractice Wrap the whole row in `VergeRoot`, not just the controls, so hovering or tabbing anywhere in the row reveals them.
+ * @bestPractice A nested `VergeRoot` does not isolate its slots: hovering an outer row also reveals an inner row's controls.
+ * @bestPractice `as` and `render` are mutually exclusive (`render` wins, dev-warned); use `as="li"` inside a real list.
+ * @category layout
+ */
+export const VergeRoot = ({ as, children, className, ref, render, ...props }) => {
+    if (render !== undefined && as !== undefined) {
+        reportDevIssue("VergeRoot: `as` and `render` are mutually exclusive; `render` wins and `as` is ignored.");
+    }
+    const element = useRender({
+        defaultTagName: as ?? "div",
+        props: {
+            className: cn("group/verge relative", className),
+            "data-component": "verge-root",
+            "data-slot": "verge-root",
+            ...props,
+            children,
+        },
+        ref,
+        render,
+    });
+    return _jsx(VergeProvider, { value: true, children: element });
+};

package/dist/components/verge/verge-slot.d.ts

@@ -0,0 +1,55 @@
+import { useRender } from "@base-ui/react/use-render";
+import type { LayoutElement } from "../../tokens/element.js";
+/** How many controls' worth of width a slot may reserve. */
+export type VergeSlots = 1 | 2 | 3 | 4 | 5 | 6;
+export interface VergeSlotProps extends useRender.ComponentProps<"div"> {
+    /**
+     * Render as a different host element from the closed layout vocabulary
+     * ({@link LayoutElement}).
+     *
+     * `as` and `render` are mutually exclusive; if both are passed, `render`
+     * wins (a dev-only warning fires).
+     * @example <VergeSlot as="span" />
+     */
+    as?: LayoutElement;
+    /**
+     * How many controls' worth of width to hold open. Children reserve their own
+     * width already, so this is only for controls that must align into a column
+     * across rows carrying different numbers of them.
+     */
+    slots?: VergeSlots;
+    /**
+     * Keep the slot revealed regardless of pointer or focus: a row whose action
+     * is mid-flight, or a documentation example showing the revealed state.
+     * @default false
+     */
+    visible?: boolean;
+}
+/**
+ * A reserved slot whose controls rest hidden and reveal on hover, on focus
+ * within the row, and always on touch (`pointer: coarse`). The slot holds its
+ * space throughout, so nothing shifts.
+ *
+ * The slot hides with opacity, never `display: none` or `visibility: hidden`,
+ * so its controls stay in the tab order: focus arriving on one is what reveals
+ * it. `pointer-events` is off at rest so the mouse cannot click a control it
+ * cannot see. An open menu or popover inside the slot holds it revealed.
+ *
+ * Used outside a `VergeRoot` it renders permanently visible rather than
+ * permanently hidden, because an unreachable control is the worse failure.
+ *
+ * Adapted from @patternmode/verge.
+ *
+ * @example
+ * ```tsx
+ * <VergeSlot slots={2}>
+ *   <Button aria-label="Edit" emphasis="ghost" icon={Pencil} size="icon-xs" />
+ * </VergeSlot>
+ * ```
+ *
+ * @bestPractice Keep controls visually small and give them a 44 by 44 pixel hit area on coarse pointers; the slot reserves space but does not own the controls' hit area.
+ * @bestPractice Use `slots` only to align controls into a column across rows with different counts; otherwise let the children size the slot.
+ * @bestPractice Do not use `visible` to say a row matters more; a control drawn on every row at rest is furniture.
+ * @category layout
+ */
+export declare const VergeSlot: ({ as, className, ref, render, slots, visible, ...props }: VergeSlotProps) => import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>>;

package/dist/components/verge/verge-slot.js

@@ -0,0 +1,61 @@
+"use client";
+import { useRender } from "@base-ui/react/use-render";
+import { cn } from "@instruments/materia-ui/utils/cn";
+import { reportDevIssue } from "../../utils/dev-issue.js";
+import { useInsideVerge } from "./verge-context.js";
+/** One control is a 28px (`size-7`) icon button wide. */
+const RESERVED_WIDTH = {
+    1: "min-w-7",
+    2: "min-w-14",
+    3: "min-w-21",
+    4: "min-w-28",
+    5: "min-w-35",
+    6: "min-w-42",
+};
+/**
+ * A reserved slot whose controls rest hidden and reveal on hover, on focus
+ * within the row, and always on touch (`pointer: coarse`). The slot holds its
+ * space throughout, so nothing shifts.
+ *
+ * The slot hides with opacity, never `display: none` or `visibility: hidden`,
+ * so its controls stay in the tab order: focus arriving on one is what reveals
+ * it. `pointer-events` is off at rest so the mouse cannot click a control it
+ * cannot see. An open menu or popover inside the slot holds it revealed.
+ *
+ * Used outside a `VergeRoot` it renders permanently visible rather than
+ * permanently hidden, because an unreachable control is the worse failure.
+ *
+ * Adapted from @patternmode/verge.
+ *
+ * @example
+ * ```tsx
+ * <VergeSlot slots={2}>
+ *   <Button aria-label="Edit" emphasis="ghost" icon={Pencil} size="icon-xs" />
+ * </VergeSlot>
+ * ```
+ *
+ * @bestPractice Keep controls visually small and give them a 44 by 44 pixel hit area on coarse pointers; the slot reserves space but does not own the controls' hit area.
+ * @bestPractice Use `slots` only to align controls into a column across rows with different counts; otherwise let the children size the slot.
+ * @bestPractice Do not use `visible` to say a row matters more; a control drawn on every row at rest is furniture.
+ * @category layout
+ */
+export const VergeSlot = ({ as, className, ref, render, slots, visible = false, ...props }) => {
+    const insideRoot = useInsideVerge();
+    if (render !== undefined && as !== undefined) {
+        reportDevIssue("VergeSlot: `as` and `render` are mutually exclusive; `render` wins and `as` is ignored.");
+    }
+    return useRender({
+        defaultTagName: as ?? "div",
+        props: {
+            className: cn("flex shrink-0 items-center justify-end gap-0.5 pointer-coarse:gap-2", "duration-quick transition-opacity ease-out motion-reduce:transition-none", insideRoot
+                ? "pointer-events-none opacity-0 group-focus-within/verge:pointer-events-auto group-focus-within/verge:opacity-100 group-hover/verge:pointer-events-auto group-hover/verge:opacity-100 has-aria-expanded:pointer-events-auto has-aria-expanded:opacity-100 has-data-popup-open:pointer-events-auto has-data-popup-open:opacity-100 data-visible:pointer-events-auto data-visible:opacity-100 pointer-coarse:pointer-events-auto pointer-coarse:opacity-100"
+                : "", slots === undefined ? "" : RESERVED_WIDTH[slots], className),
+            "data-component": "verge-slot",
+            "data-slot": "verge-slot",
+            "data-visible": visible ? "" : undefined,
+            ...props,
+        },
+        ref,
+        render,
+    });
+};

package/dist/components/verge.d.ts

@@ -0,0 +1,3 @@
+export { vergeAnatomy } from "./verge/verge-anatomy.js";
+export { VergeRoot, type VergeRootProps } from "./verge/verge-root.js";
+export { VergeSlot, type VergeSlotProps, type VergeSlots, } from "./verge/verge-slot.js";

package/dist/components/verge.js

@@ -0,0 +1,3 @@
+export { vergeAnatomy } from "./verge/verge-anatomy.js";
+export { VergeRoot } from "./verge/verge-root.js";
+export { VergeSlot, } from "./verge/verge-slot.js";

package/dist/components/visually-hidden/visually-hidden-root.d.ts

@@ -0,0 +1,11 @@
+import type * as React from "react";
+export type VisuallyHiddenProps = React.ComponentProps<"span">;
+/**
+ * Hides content visually while keeping it in the accessibility tree - for
+ * screen-reader-only labels and captions that must not take up layout space.
+ * RSC-safe.
+ * @bestPractice Use for screen-reader-only text (e.g. a link's full context) - for icon-only `Button`s prefer the `aria-label` prop the component already requires.
+ * @bestPractice Never hide interactive or focusable content inside it - sighted keyboard users would tab into something they cannot see.
+ * @category typography
+ */
+export declare const VisuallyHidden: ({ className, ...props }: VisuallyHiddenProps) => React.JSX.Element;

package/dist/components/visually-hidden/visually-hidden-root.js

@@ -0,0 +1,11 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { cn } from "../../utils/cn.js";
+/**
+ * Hides content visually while keeping it in the accessibility tree - for
+ * screen-reader-only labels and captions that must not take up layout space.
+ * RSC-safe.
+ * @bestPractice Use for screen-reader-only text (e.g. a link's full context) - for icon-only `Button`s prefer the `aria-label` prop the component already requires.
+ * @bestPractice Never hide interactive or focusable content inside it - sighted keyboard users would tab into something they cannot see.
+ * @category typography
+ */
+export const VisuallyHidden = ({ className, ...props }) => (_jsx("span", { className: cn("sr-only", className), "data-component": "visually-hidden", ...props }));

package/dist/components/visually-hidden.d.ts

@@ -0,0 +1 @@
+export { VisuallyHidden, type VisuallyHiddenProps, } from "./visually-hidden/visually-hidden-root.js";

package/dist/components/visually-hidden.js

@@ -0,0 +1 @@
+export { VisuallyHidden, } from "./visually-hidden/visually-hidden-root.js";

package/dist/components/voice/live-waveform.d.ts

@@ -0,0 +1,19 @@
+export interface LiveWaveformProps {
+    /** Live RMS level, `0..1`. Drives the bar heights while `active`. */
+    level: number;
+    /** When `false`, bars sit at the idle floor/undulation instead of tracking `level`. */
+    active?: boolean;
+    /** Number of bars to render, `5..7`. @default 6 */
+    barCount?: number;
+    className?: string;
+}
+/**
+ * A dumb, props-driven voice waveform: a row of bars whose heights track a live
+ * `level` through a spring, animated with `transform: scaleY()` only (never
+ * height, so it stays on the compositor). When `active` is `false` - or the
+ * user prefers reduced motion - the bars drop to a floor with a slow, phase-
+ * offset idle undulation instead of tracking the input.
+ *
+ * @category motion
+ */
+export declare const LiveWaveform: ({ level, active, barCount, className, }: LiveWaveformProps) => import("react").JSX.Element;

package/dist/components/voice/live-waveform.js

@@ -0,0 +1,65 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { easings } from "@instruments/materia-ui/tokens/motion";
+import { cn } from "@instruments/materia-ui/utils/cn";
+import { useMotionValue, useReducedMotion, useSpring, useTransform, } from "motion/react";
+import * as m from "motion/react-m";
+import { useEffect, useMemo } from "react";
+import { Flex } from "../flex.js";
+/** Bars never fully collapse - a dead-flat waveform reads as a crashed mic. */
+const FLOOR = 0.15;
+/** Spring that smooths the raw `level` before it reaches the bars. */
+const WAVEFORM_SPRING = { stiffness: 300, damping: 24 };
+/** Amplitude of the slow idle undulation played when silent. */
+const IDLE_AMPLITUDE = 0.12;
+const clamp01 = (value) => Math.min(1, Math.max(0, value));
+const clampBarCount = (value) => Math.min(7, Math.max(5, value));
+/**
+ * Deterministic per-bar loudness weight - a symmetric bell so centre bars read
+ * taller than the edges. Pure function of index, never `Math.random`, so SSR
+ * and client agree and the profile is stable across renders.
+ */
+const barWeight = (index, count) => 0.55 + 0.45 * Math.sin((Math.PI * (index + 0.5)) / count);
+const Bar = ({ smoothed, weight, index, live, reduced }) => {
+    // Hook is called unconditionally; only bound to the element in live mode.
+    const scaleY = useTransform(smoothed, (value) => Math.min(1, FLOOR + (1 - FLOOR) * value * weight));
+    if (live) {
+        return (_jsx(m.span, { "aria-hidden": true, className: "h-full w-0.75 origin-bottom rounded-full bg-current", style: { scaleY } }));
+    }
+    // Reduced motion: a static floor bar, no undulation.
+    if (reduced) {
+        return (_jsx("span", { "aria-hidden": true, className: "h-full w-0.75 origin-bottom rounded-full bg-current", style: { transform: `scaleY(${FLOOR})` } }));
+    }
+    return (_jsx(m.span, { "aria-hidden": true, animate: { scaleY: [FLOOR, FLOOR + IDLE_AMPLITUDE, FLOOR] }, className: "h-full w-0.75 origin-bottom rounded-full bg-current", style: { scaleY: FLOOR }, transition: {
+            delay: index * 0.18,
+            duration: 1.6,
+            ease: easings.inOut,
+            repeat: Number.POSITIVE_INFINITY,
+            repeatType: "mirror",
+        } }));
+};
+/**
+ * A dumb, props-driven voice waveform: a row of bars whose heights track a live
+ * `level` through a spring, animated with `transform: scaleY()` only (never
+ * height, so it stays on the compositor). When `active` is `false` - or the
+ * user prefers reduced motion - the bars drop to a floor with a slow, phase-
+ * offset idle undulation instead of tracking the input.
+ *
+ * @category motion
+ */
+export const LiveWaveform = ({ level, active = true, barCount = 6, className, }) => {
+    const reduced = useReducedMotion() ?? false;
+    const count = clampBarCount(barCount);
+    const live = active && !reduced;
+    const target = useMotionValue(0);
+    const smoothed = useSpring(target, WAVEFORM_SPRING);
+    useEffect(() => {
+        target.set(live ? clamp01(level) : 0);
+    }, [live, level, target]);
+    const bars = useMemo(() => Array.from({ length: count }, (_bar, index) => ({
+        key: `waveform-bar-${index}`,
+        index,
+        weight: barWeight(index, count),
+    })), [count]);
+    return (_jsx(Flex, { align: "flex-end", "aria-hidden": true, as: "span", className: cn("h-3.5 gap-0.75", className), children: bars.map((bar) => (_jsx(Bar, { index: bar.index, live: live, reduced: reduced, smoothed: smoothed, weight: bar.weight }, bar.key))) }));
+};

package/dist/components/voice/voice-error-popover.d.ts

@@ -0,0 +1,29 @@
+import type { ReactNode } from "react";
+export interface VoiceErrorPopoverProps {
+    /** Controlled visibility. The parent owns error state and dismissal. */
+    open: boolean;
+    /** The error message to surface. */
+    message: string;
+    /** When set, renders an action button (e.g. `"Retry"`) that calls `onAction`. */
+    actionLabel?: string;
+    onAction?: () => void;
+    onDismiss?: () => void;
+    /** Accessible label for the dismiss button. @default "Dismiss" */
+    dismissLabel?: string;
+    /** The anchor - the pill. The popover is positioned above it. */
+    children: ReactNode;
+    className?: string;
+}
+/**
+ * A dumb, controlled error popover anchored above its `children` (the pill).
+ * Not built on the Base UI `Popover` primitive: this atom is fully `open`-driven
+ * with no trigger, portal, or focus-trap to own - the parent owns error state -
+ * so a lightweight anchored container keeps it self-contained and predictable.
+ *
+ * Entry is origin-aware: it scales up from `scale(0.97)` + fades in over ≤200ms
+ * with `transform-origin` at the bottom (the pill edge), so it reads as growing
+ * out of the control rather than appearing over it.
+ *
+ * @category feedback
+ */
+export declare const VoiceErrorPopover: ({ open, message, actionLabel, onAction, onDismiss, dismissLabel, children, className, }: VoiceErrorPopoverProps) => import("react").JSX.Element;

package/dist/components/voice/voice-error-popover.js

@@ -0,0 +1,24 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { easings } from "@instruments/materia-ui/tokens/motion";
+import { cn } from "@instruments/materia-ui/utils/cn";
+import { X } from "lucide-react";
+import { AnimatePresence } from "motion/react";
+import * as m from "motion/react-m";
+import { Button } from "../button.js";
+import { Flex } from "../flex.js";
+/** Entry runs in ≤200ms, ease-out, scaling up from the pill edge. */
+const ENTRY_DURATION = 0.18;
+/**
+ * A dumb, controlled error popover anchored above its `children` (the pill).
+ * Not built on the Base UI `Popover` primitive: this atom is fully `open`-driven
+ * with no trigger, portal, or focus-trap to own - the parent owns error state -
+ * so a lightweight anchored container keeps it self-contained and predictable.
+ *
+ * Entry is origin-aware: it scales up from `scale(0.97)` + fades in over ≤200ms
+ * with `transform-origin` at the bottom (the pill edge), so it reads as growing
+ * out of the control rather than appearing over it.
+ *
+ * @category feedback
+ */
+export const VoiceErrorPopover = ({ open, message, actionLabel, onAction, onDismiss, dismissLabel = "Dismiss", children, className, }) => (_jsxs(Flex, { className: cn("relative", className), inline: true, children: [children, _jsx(AnimatePresence, { children: open ? (_jsx(m.div, { animate: { opacity: 1, scale: 1 }, className: "absolute bottom-full left-1/2 z-50 mb-2 w-max max-w-xs origin-bottom -translate-x-1/2", exit: { opacity: 0, scale: 0.97 }, initial: { opacity: 0, scale: 0.97 }, role: "alert", transition: { duration: ENTRY_DURATION, ease: easings.out }, children: _jsxs(Flex, { align: "flex-start", className: "border-border bg-popover text-popover-foreground rounded-xl border p-3 shadow-md dark:shadow-none", gap: "xs", children: [_jsx("p", { className: "text-paragraph-sm flex-1", children: message }), actionLabel !== undefined && actionLabel !== "" ? (_jsx(Button, { onClick: onAction, size: "sm", type: "button", children: actionLabel })) : null, _jsx(Button, { "aria-label": dismissLabel, emphasis: "soft", icon: X, onClick: onDismiss, size: "icon-sm", square: true, tone: "neutral", type: "button" })] }) })) : null })] }));

package/dist/components/voice/voice-pill.d.ts

@@ -0,0 +1,34 @@
+export type VoicePillState = "idle" | "typing" | "arming" | "listening" | "finalizing" | "error";
+export interface VoicePillProps {
+    /** Current visual state. The parent owns all transitions between states. */
+    state: VoicePillState;
+    /** Live RMS level `0..1`, used while `listening`/`finalizing`. @default 0 */
+    level?: number;
+    /** Elapsed capture time in ms, shown as an `mm:ss` timer while recording. @default 0 */
+    elapsedMs?: number;
+    onClick?: () => void;
+    disabled?: boolean;
+    /** Accessible label. The parent chooses copy per state - never hardcoded here. */
+    label: string;
+    /** Maps to `aria-pressed` (e.g. `true` while listening). */
+    pressed?: boolean;
+    className?: string;
+}
+/**
+ * The composer's send/voice control, morphing across a single `<button>`. A
+ * dumb, fully props-driven atom: it owns no timers, audio, or permissions - a
+ * parent drives every transition through `state`, `level`, and `elapsedMs`.
+ *
+ * States: `idle` shows the `Mic` (empty-composer control); `typing` swaps
+ * instantly to `ArrowUp`; `arming` gives a brief pre-listen pulse; `listening`
+ * widens the pill and crossfades (with a masking blur) to a live waveform plus
+ * a `tabular-nums` timer; `finalizing` freezes the bars and contracts faster
+ * than it expanded; `error` shakes once (or, under reduced motion, pulses a
+ * destructive tint). Carries a glass sheen so `idle` reads as a plain primary pill.
+ *
+ * @bestPractice Keep this dumb - drive every transition from the parent through `state`/`level`/`elapsedMs`; it owns no timers, audio, or permissions.
+ * @bestPractice Pass `label` per state (the parent decides the copy, e.g. "Voice input" vs "Stop dictation") so screen readers announce the current action; never hardcode it here.
+ * @bestPractice Feed `level` from a real RMS meter while `listening` - a dead-flat waveform reads as a crashed mic; the atom floors and undulates the bars, but only live level makes it look alive.
+ * @category motion
+ */
+export declare const VoicePill: ({ state, level, elapsedMs, onClick, disabled, label, pressed, className, }: VoicePillProps) => import("react").JSX.Element;