@instruments/materia-ui 0.1.0

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

@@ -0,0 +1,58 @@
+import type { VariantProps } from "class-variance-authority";
+import type { LucideIcon } from "lucide-react";
+import type * as React from "react";
+import type { ResponsiveValue } from "../../tokens/responsive.js";
+import type { Tone } from "../../tokens/tone.js";
+import type { PillEmphasis, PillSize, PillTone, pillVariants } from "../pill/pill-variants.js";
+/** Tag tone - aliased from shared PillTone */
+export type TagTone = PillTone;
+export type TagSize = PillSize;
+export type TagEmphasis = PillEmphasis;
+export declare const TAG_TONES: TagTone[];
+export declare const TAG_SIZES: TagSize[];
+export interface TagProps extends Omit<React.HTMLAttributes<HTMLElement>, "children">, Omit<VariantProps<typeof pillVariants>, "disabled" | "size"> {
+    children?: React.ReactNode;
+    /** Disabled state */
+    disabled?: boolean;
+    /**
+     * Tag size - a single token or a per-breakpoint object like
+     * `{ base: "sm", md: "lg" }`. Forwarded to the underlying Pill. @default "base"
+     */
+    size?: ResponsiveValue<PillSize>;
+    /** Custom dismiss icon (defaults to X) */
+    dismissIcon?: React.ReactNode;
+    /** Leading status dot: `true` for a neutral dot, or a {@link Tone} to tint it. */
+    dot?: boolean | Tone;
+    /** Hide dismiss button even when onDismiss is provided */
+    hideDismiss?: boolean;
+    /** Leading icon */
+    icon?: LucideIcon | React.ComponentType<React.SVGProps<SVGSVGElement>>;
+    /** Leading circular thumbnail image */
+    imageUrl?: string;
+    /** Show loading spinner (replaces leading visual) */
+    loading?: boolean;
+    /** Selection handler; renders a separate button when removal is also shown. */
+    onClick?: React.MouseEventHandler<HTMLButtonElement>;
+    /** Dismiss handler - shows dismiss button */
+    onDismiss?: (event: React.MouseEvent | React.KeyboardEvent) => void;
+}
+/**
+ * Tag - An interactive pill component for selection, filtering, and multi-select scenarios.
+ *
+ * Uses shared pill styling (identical to Badge) with interactive capabilities:
+ * dismissibility, click handling, and keyboard support.
+ *
+ * The outer element is polymorphic based on interactivity:
+ * - `onClick` provided: `<button>`
+ * - `onDismiss` only: `<div>` with dismiss `<button>`
+ * - Both: `<div>` with separate selection and dismiss `<button>` elements
+ * - Neither: `<span>` (presentational)
+ *
+ * @bestPractice Choose `Tag` when the chip is interactive (selection/filter/dismiss); for a display-only status label or count use `Badge`, and for a bare colour dot use `Dot`.
+ * @bestPractice Pass `onClick` for selection and `onDismiss` for removal. When both are provided they render as sibling buttons inside one visual chip; don't wrap Tag in another button.
+ * @bestPractice With both actions, HTML attributes (including the accessible name and selected state) apply to the selection button; `className` and `style` style the outer chip.
+ * @bestPractice Set at most one leading visual - `loading` > `imageUrl` > `dot` > `icon` (in that precedence); pass a Lucide component to `icon` (not `<Icon/>`), and `imageUrl` renders a circular `<img alt="">`, so keep it decorative.
+ * @bestPractice When `onDismiss` is set, Backspace/Delete also removes the tag while it's focused - don't bind your own conflicting key handler.
+ * @category data
+ */
+export declare const Tag: ({ className, style, tone, size, emphasis, asInput, radius, disabled, children, icon, dot, imageUrl, loading, onClick, onDismiss, dismissIcon, hideDismiss, ...props }: TagProps) => React.JSX.Element;

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

@@ -0,0 +1,211 @@
+"use client";
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { cn } from "@instruments/materia-ui/utils/cn";
+import { X } from "lucide-react";
+import { focusRing } from "../../tokens/focus-ring.js";
+import { resolveResponsiveBase } from "../../tokens/responsive.js";
+import { isString, hasText, isPresent } from "../../utils/type-guards.js";
+import { Dot } from "../dot.js";
+import { Icon } from "../icon.js";
+import { Pill } from "../pill/pill-root.js";
+import { PILL_ICON_SIZE_MAP } from "../pill/pill-variants.js";
+import { Spinner } from "../spinner.js";
+export const TAG_TONES = [
+    "neutral",
+    "brand",
+    "success",
+    "warning",
+    "info",
+    "danger",
+];
+export const TAG_SIZES = [
+    "2xs",
+    "xs",
+    "sm",
+    "base",
+    "lg",
+    "xl",
+    "2xl",
+    "3xl",
+];
+/** Circular thumbnail image sizes + negative margin to sit at pill edge */
+const TAG_IMAGE_SIZES = {
+    "2xl": "-ml-2.5 size-8",
+    "2xs": "size-2.5",
+    "3xl": "-ml-3.5 size-10",
+    base: "-ml-1.5 size-5",
+    lg: "-ml-1.5 size-5",
+    sm: "-ml-1 size-4",
+    xl: "-ml-2 size-6",
+    xs: "-ml-0.5 size-3",
+};
+/** Dismiss button sizing per tag size */
+const TAG_DISMISS_SIZES = {
+    "2xl": "-mr-1 size-5 [&_svg]:size-4",
+    "2xs": "-mr-px size-2.5 [&_svg]:size-2",
+    "3xl": "-mr-1.5 size-6 [&_svg]:size-5",
+    base: "-mr-0.5 size-4 [&_svg]:size-3",
+    lg: "-mr-0.5 size-4 [&_svg]:size-3.5",
+    sm: "-mr-0.5 size-3.5 [&_svg]:size-3",
+    xl: "-mr-1 size-5 [&_svg]:size-4",
+    xs: "-mr-0.5 size-3 [&_svg]:size-2.5",
+};
+/** Dot colour on solid pills - matches text contrast direction */
+const SOLID_DOT_COLORS = {
+    brand: "var(--color-black-alpha-30)",
+    danger: "var(--color-alpha-70)",
+    info: "var(--color-alpha-70)",
+    neutral: "var(--color-alpha-70)",
+    success: "var(--color-alpha-70)",
+    warning: "var(--color-black-alpha-30)",
+};
+/** Dot sizing per tag size */
+const TAG_DOT_SIZES = {
+    "2xl": "lg",
+    "2xs": "2xs",
+    "3xl": "xl",
+    base: "sm",
+    lg: "sm",
+    sm: "xs",
+    xl: "base",
+    xs: "xs",
+};
+/** Pick the polymorphic outer element based on interactivity. */
+const getTagElement = (isClickable, isDismissible) => {
+    if (isClickable && isDismissible) {
+        return "div";
+    }
+    if (isClickable) {
+        return "button";
+    }
+    if (isDismissible) {
+        return "div";
+    }
+    return "span";
+};
+/** Build the leading visual: spinner, image, dot, icon, or nothing. */
+const renderLeadingVisual = ({ emphasis, dot, dotSize, icon, iconSize, imageUrl, loading, resolvedSize, tone, }) => {
+    if (loading) {
+        return _jsx(Spinner, { size: iconSize });
+    }
+    if (hasText(imageUrl)) {
+        return (_jsx("img", { alt: "", className: cn("shrink-0 rounded-full object-cover ring-1 ring-black/10 ring-inset", TAG_IMAGE_SIZES[resolvedSize]), height: 24, src: imageUrl, width: 24 }));
+    }
+    if (dot !== false && dot !== undefined) {
+        const isSolid = !emphasis || emphasis === "solid";
+        const resolvedTone = tone ?? "neutral";
+        return isSolid ? (_jsx(Dot, { color: SOLID_DOT_COLORS[resolvedTone], size: dotSize })) : (_jsx(Dot, { size: dotSize, tone: isString(dot) ? dot : undefined }));
+    }
+    if (icon) {
+        return _jsx(Icon, { icon: icon, size: iconSize });
+    }
+    return null;
+};
+/** Outer pill classes: pointer cursor when clickable, room for a dot beside no dismiss control. */
+const getTagClassName = ({ className, dot, isClickable, isDismissible, }) => cn(isClickable && "cursor-pointer", dot !== false && dot !== undefined && !isDismissible && "pr-tag-dot", className);
+/**
+ * An invisible 44px square starting at the dismiss control's left edge, so it
+ * is a full touch target however small the glyph is drawn, without reaching
+ * back over the label of a clickable tag.
+ */
+const DISMISS_HIT_AREA = "relative after:absolute after:top-1/2 after:left-0 after:size-11 after:-translate-y-1/2";
+/**
+ * Removal is a native button, beside the selection button when both exist.
+ */
+const TagDismiss = ({ dismissIcon, disabled, label, onClick, resolvedSize, }) => (_jsx("button", { "aria-label": label, className: cn("inline-flex shrink-0 cursor-pointer items-center justify-center rounded-sm opacity-60 hover:opacity-100 focus-visible:opacity-100", focusRing(), DISMISS_HIT_AREA, TAG_DISMISS_SIZES[resolvedSize], "transition-opacity"), "data-slot": "tag-dismiss", disabled: disabled, onClick: onClick, type: "button", children: dismissIcon ?? _jsx(Icon, { icon: X }) }));
+const getTagDismissHandler = (onDismiss, disabled) => (event) => {
+    event.stopPropagation();
+    if (disabled !== true) {
+        onDismiss?.(event);
+    }
+};
+const getTagKeyDownHandler = ({ disabled, onDismiss, onKeyDown, }) => (event) => {
+    if (disabled !== true &&
+        onDismiss &&
+        (event.key === "Backspace" || event.key === "Delete")) {
+        event.preventDefault();
+        onDismiss(event);
+    }
+    onKeyDown?.(event);
+};
+const getTagAppearanceProps = ({ emphasis, asInput, disabled, radius, }) => {
+    const appearance = {};
+    if (emphasis !== undefined) {
+        appearance.emphasis = emphasis;
+    }
+    if (asInput !== undefined) {
+        appearance.asInput = asInput;
+    }
+    if (disabled !== undefined) {
+        appearance.disabled = disabled;
+    }
+    if (radius !== undefined) {
+        appearance.radius = radius;
+    }
+    return appearance;
+};
+/**
+ * Tag - An interactive pill component for selection, filtering, and multi-select scenarios.
+ *
+ * Uses shared pill styling (identical to Badge) with interactive capabilities:
+ * dismissibility, click handling, and keyboard support.
+ *
+ * The outer element is polymorphic based on interactivity:
+ * - `onClick` provided: `<button>`
+ * - `onDismiss` only: `<div>` with dismiss `<button>`
+ * - Both: `<div>` with separate selection and dismiss `<button>` elements
+ * - Neither: `<span>` (presentational)
+ *
+ * @bestPractice Choose `Tag` when the chip is interactive (selection/filter/dismiss); for a display-only status label or count use `Badge`, and for a bare colour dot use `Dot`.
+ * @bestPractice Pass `onClick` for selection and `onDismiss` for removal. When both are provided they render as sibling buttons inside one visual chip; don't wrap Tag in another button.
+ * @bestPractice With both actions, HTML attributes (including the accessible name and selected state) apply to the selection button; `className` and `style` style the outer chip.
+ * @bestPractice Set at most one leading visual - `loading` > `imageUrl` > `dot` > `icon` (in that precedence); pass a Lucide component to `icon` (not `<Icon/>`), and `imageUrl` renders a circular `<img alt="">`, so keep it decorative.
+ * @bestPractice When `onDismiss` is set, Backspace/Delete also removes the tag while it's focused - don't bind your own conflicting key handler.
+ * @category data
+ */
+export const Tag = ({ className, style, tone, size = "base", emphasis, asInput, radius, disabled, children, icon, dot, imageUrl, loading = false, onClick, onDismiss, dismissIcon, hideDismiss = false, ...props }) => {
+    // Single-token base for the icon/dot/image/dismiss size lookups below; the
+    // Pill receives the full responsive `size` and layers `md:*` overrides.
+    const resolvedSize = resolveResponsiveBase(size, "base");
+    const isClickable = !!onClick;
+    const isDismissible = !!onDismiss && !hideDismiss;
+    const hasSeparateActions = isClickable && isDismissible;
+    const Element = getTagElement(isClickable, isDismissible);
+    const iconSize = PILL_ICON_SIZE_MAP[resolvedSize];
+    const dotSize = TAG_DOT_SIZES[resolvedSize];
+    const leadingVisual = renderLeadingVisual({
+        dot,
+        dotSize,
+        emphasis,
+        icon,
+        iconSize,
+        imageUrl,
+        loading,
+        resolvedSize,
+        tone,
+    });
+    const handleDismissClick = getTagDismissHandler(onDismiss, disabled);
+    const handleKeyDown = getTagKeyDownHandler({
+        disabled,
+        onDismiss,
+        onKeyDown: props.onKeyDown,
+    });
+    const label = props["aria-label"] ?? (isString(children) ? children : undefined);
+    const dismissElement = isDismissible ? (_jsx(TagDismiss, { dismissIcon: dismissIcon, disabled: disabled, label: hasText(label) ? `Remove ${label}` : "Remove", onClick: handleDismissClick, resolvedSize: resolvedSize })) : null;
+    // Filter undefined values from remaining props for exactOptionalPropertyTypes compatibility
+    const definedProps = Object.fromEntries(Object.entries(props).filter(([key, value]) => key !== "onKeyDown" && value !== undefined));
+    const content = (_jsxs(_Fragment, { children: [leadingVisual, isPresent(children) && _jsx("span", { className: "truncate", children: children })] }));
+    const selectionElement = hasSeparateActions ? (_jsx("button", { ...definedProps, className: cn("inline-flex min-w-0 items-center self-stretch rounded-sm", focusRing()), "data-slot": "tag-select", disabled: disabled, onClick: onClick, style: { gap: "inherit" }, type: "button", children: content })) : (content);
+    return (_jsxs(Pill, { ...getTagAppearanceProps({ emphasis, asInput, disabled, radius }), as: Element, className: getTagClassName({
+            className,
+            dot,
+            isClickable,
+            isDismissible,
+        }), "data-component": "tag", "data-slot": "tag", size: size, style: style, tone: tone, ...(isClickable && !hasSeparateActions
+            ? {
+                onClick,
+                type: "button",
+                render: (_jsx("button", { disabled: disabled, type: "button", children: content })),
+            }
+            : {}), ...(hasSeparateActions ? {} : definedProps), onKeyDown: handleKeyDown, children: [selectionElement, dismissElement] }));
+};

package/dist/components/tag.d.ts

@@ -0,0 +1,2 @@
+export type { TagEmphasis, TagProps, TagSize, TagTone } from "./tag/tag-root.js";
+export { TAG_SIZES, TAG_TONES, Tag } from "./tag/tag-root.js";

package/dist/components/tag.js

@@ -0,0 +1 @@
+export { TAG_SIZES, TAG_TONES, Tag } from "./tag/tag-root.js";

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

@@ -0,0 +1,61 @@
+import { useRender } from "@base-ui/react/use-render";
+import type { TextElement } from "../../tokens/element.js";
+import type { ResponsiveValue } from "../../tokens/responsive.js";
+/** The type roles Text renders at, smallest first: body copy up to a small heading. */
+export declare const TEXT_SIZES: readonly ["caption", "paragraph-sm", "paragraph", "paragraph-lg", "subheading", "subheading-lg", "heading-sm"];
+/** A type role Text renders at; see {@link TEXT_SIZES}. */
+export type TextSize = (typeof TEXT_SIZES)[number];
+/**
+ * Maps each {@link TextSize} to its role class; exported as `textSizeClasses`.
+ * The role owns the font-size, line-height and letter-spacing.
+ */
+declare const SIZE_CLASSES: Record<TextSize, string>;
+declare const VARIANT_CLASSES: {
+    readonly accent: "text-accent-foreground";
+    readonly default: "";
+    readonly muted: "text-muted-foreground";
+};
+declare const WEIGHT_CLASSES: {
+    readonly medium: "font-medium";
+    readonly normal: "font-normal";
+    readonly semibold: "font-semibold";
+};
+type TextVariant = keyof typeof VARIANT_CLASSES;
+type TextWeight = keyof typeof WEIGHT_CLASSES;
+type TextProps = Omit<useRender.ComponentProps<"p">, "size"> & {
+    /**
+     * Render as a different host element from the closed text vocabulary
+     * ({@link TextElement}). The set is deliberately closed and text-only:
+     * `as="div"` and `as="label"` are type errors (use Box for decorative
+     * wrappers, Label for form labels). Ref and event-handler types remain the
+     * default element's (HTMLParagraphElement).
+     *
+     * `as` and `render` are mutually exclusive; if both are passed, `render`
+     * wins (a dev-only warning fires).
+     * @example <Text as="span" />
+     */
+    as?: TextElement;
+    /**
+     * Type role - a single role or a responsive object like
+     * `{ base: "paragraph-sm", md: "paragraph-lg" }`.
+     * @default "paragraph-sm"
+     */
+    size?: ResponsiveValue<TextSize>;
+    /** Text colour variant */
+    variant?: TextVariant;
+    /** Font weight */
+    weight?: TextWeight;
+};
+/**
+ * The typography primitive for body copy - renders a `<p>` (or any element via
+ * `as` or `render`). Ships without a line-length cap; add `max-w-prose` at the call
+ * site for long-form prose. `size` names a type role, defaults to
+ * `paragraph-sm` and accepts responsive values:
+ * `size={{ base: "paragraph-sm", md: "paragraph-lg" }}`.
+ *
+ * @bestPractice `as` is a closed text-only vocabulary - use `as="span"` for inline copy; `as="div"`/`as="label"` are type errors (use `Box` for wrappers, `Label` for form labels).
+ * @bestPractice `as` and `render` are mutually exclusive (`render` wins, dev-warned); Text ships without a line-length cap - add `max-w-prose` at the call site for long-form prose.
+ * @category typography
+ */
+declare const Text: ({ as, size, variant, weight, className, ref, render, ...props }: TextProps) => import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>>;
+export { SIZE_CLASSES as textSizeClasses, Text };

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

@@ -0,0 +1,66 @@
+import { useRender } from "@base-ui/react/use-render";
+import { cn } from "@instruments/materia-ui/utils/cn";
+import { getResponsiveSizeClasses } from "../../tokens/responsive.js";
+import { reportDevIssue } from "../../utils/dev-issue.js";
+/** The type roles Text renders at, smallest first: body copy up to a small heading. */
+export const TEXT_SIZES = [
+    "caption",
+    "paragraph-sm",
+    "paragraph",
+    "paragraph-lg",
+    "subheading",
+    "subheading-lg",
+    "heading-sm",
+];
+/**
+ * Maps each {@link TextSize} to its role class; exported as `textSizeClasses`.
+ * The role owns the font-size, line-height and letter-spacing.
+ */
+const SIZE_CLASSES = {
+    caption: "text-caption",
+    "paragraph-sm": "text-paragraph-sm",
+    paragraph: "text-paragraph",
+    "paragraph-lg": "text-paragraph-lg",
+    subheading: "text-subheading",
+    "subheading-lg": "text-subheading-lg",
+    "heading-sm": "text-heading-sm",
+};
+const VARIANT_CLASSES = {
+    accent: "text-accent-foreground",
+    default: "",
+    muted: "text-muted-foreground",
+};
+const WEIGHT_CLASSES = {
+    medium: "font-medium",
+    normal: "font-normal",
+    semibold: "font-semibold",
+};
+/**
+ * The typography primitive for body copy - renders a `<p>` (or any element via
+ * `as` or `render`). Ships without a line-length cap; add `max-w-prose` at the call
+ * site for long-form prose. `size` names a type role, defaults to
+ * `paragraph-sm` and accepts responsive values:
+ * `size={{ base: "paragraph-sm", md: "paragraph-lg" }}`.
+ *
+ * @bestPractice `as` is a closed text-only vocabulary - use `as="span"` for inline copy; `as="div"`/`as="label"` are type errors (use `Box` for wrappers, `Label` for form labels).
+ * @bestPractice `as` and `render` are mutually exclusive (`render` wins, dev-warned); Text ships without a line-length cap - add `max-w-prose` at the call site for long-form prose.
+ * @category typography
+ */
+const Text = ({ as, size, variant = "default", weight = "normal", className, ref, render, ...props }) => {
+    if (render !== undefined && as !== undefined) {
+        reportDevIssue("Text: `as` and `render` are mutually exclusive; `render` wins and `as` is ignored.");
+    }
+    const sizeClasses = getResponsiveSizeClasses(size, SIZE_CLASSES, "paragraph-sm");
+    return useRender({
+        defaultTagName: as ?? "p",
+        props: {
+            className: cn("trim-both text-pretty", sizeClasses, VARIANT_CLASSES[variant], WEIGHT_CLASSES[weight], className),
+            "data-component": "text",
+            "data-slot": "text",
+            ...props,
+        },
+        ref,
+        render,
+    });
+};
+export { SIZE_CLASSES as textSizeClasses, Text };

package/dist/components/text/text.test-d.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Type-level surface guards for Text's closed `as` vocabulary (plan M1a).
+ *
+ * Evaluated by `tsc --noEmit` (the `typecheck` gate), not by vitest or the
+ * Playwright story smoke - a `.test-d.ts` name matches neither runner's globs.
+ *
+ * Text draws from {@link TextElement} - a text-only vocabulary distinct from the
+ * layout one. `as="span"` is accepted, but `as="label"` is a type error (labels
+ * need `htmlFor`; the DS answer is Label) and `as="div"` is a type error
+ * (decorative wrappers are Box's job, not Text's). `as="button"` is likewise
+ * rejected. If the union widens, the rejection guards stop satisfying
+ * `extends true`.
+ */
+import type { ComponentProps } from "react";
+import type { Text } from "./text-root.js";
+/** Passes only when `T` is exactly `true`. */
+type Expect<T extends true> = T;
+/** Boolean negation at the type level. */
+type Not<B extends boolean> = B extends true ? false : true;
+/** `true` iff a value of type `V` is accepted as Text props. */
+type Accepts<V> = V extends ComponentProps<typeof Text> ? true : false;
+export type SpanAccepted = Expect<Accepts<{
+    as: "span";
+}>>;
+export type LabelRejected = Expect<Not<Accepts<{
+    as: "label";
+}>>>;
+export type DivRejected = Expect<Not<Accepts<{
+    as: "div";
+}>>>;
+export type ButtonRejected = Expect<Not<Accepts<{
+    as: "button";
+}>>>;
+export type SizeContainerKeyAccepted = Expect<Accepts<{
+    size: {
+        base: "paragraph-sm";
+        md: "paragraph";
+        "@md": "paragraph-lg";
+    };
+}>>;
+export type RoleSizeAccepted = Expect<Accepts<{
+    size: "caption";
+}>>;
+export type TShirtSizeRejected = Expect<Not<Accepts<{
+    size: "sm";
+}>>>;
+export {};

package/dist/components/text/text.test-d.js

@@ -0,0 +1 @@
+export {};

package/dist/components/text.d.ts

@@ -0,0 +1 @@
+export { TEXT_SIZES, Text, type TextSize, textSizeClasses, } from "./text/text-root.js";

package/dist/components/text.js

@@ -0,0 +1 @@
+export { TEXT_SIZES, Text, textSizeClasses, } from "./text/text-root.js";

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

@@ -0,0 +1,32 @@
+import type * as React from "react";
+import type { WithTestId } from "../../utils/with-test-id.js";
+interface TextareaProps extends WithTestId<React.ComponentProps<"textarea">> {
+    /** Force error styling and `aria-invalid`; otherwise inherits an ancestor Field's invalid state. */
+    hasError?: boolean;
+}
+/**
+ * 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.
+ *
+ * @param props - The textarea props
+ * @param props.className - Additional CSS classes to apply.
+ * @param props.testId - Test ID for testing purposes.
+ * @param props.hasError - Force error styling and `aria-invalid`.
+ * @param props... - All other standard HTML textarea element props (e.g., value, onChange, placeholder, rows, disabled, etc.).
+ *
+ * @example
+ * ```tsx
+ * <Textarea placeholder="Enter description…" rows={4} />
+ * <Textarea value={value} onChange={(e) => setValue(e.target.value)} />
+ * <Textarea hasError placeholder="Invalid input" />
+ * ```
+ *
+ * @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 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
+ */
+declare const Textarea: ({ className, testId, hasError, id, name, disabled, rows, style, ...props }: TextareaProps) => React.JSX.Element;
+export { Textarea };

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

@@ -0,0 +1,46 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Field as FieldPrimitive } from "@base-ui/react/field";
+import { focusInput } from "@instruments/materia-ui/tokens/focus-input";
+import { cn } from "@instruments/materia-ui/utils/cn";
+import { hasErrorInput } from "../../tokens/has-error-input.js";
+import { INPUT_SHELL } from "../../tokens/input-shell.js";
+import { useFieldContext } from "../field/field-context.js";
+/**
+ * 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.
+ *
+ * @param props - The textarea props
+ * @param props.className - Additional CSS classes to apply.
+ * @param props.testId - Test ID for testing purposes.
+ * @param props.hasError - Force error styling and `aria-invalid`.
+ * @param props... - All other standard HTML textarea element props (e.g., value, onChange, placeholder, rows, disabled, etc.).
+ *
+ * @example
+ * ```tsx
+ * <Textarea placeholder="Enter description…" rows={4} />
+ * <Textarea value={value} onChange={(e) => setValue(e.target.value)} />
+ * <Textarea hasError placeholder="Invalid input" />
+ * ```
+ *
+ * @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 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
+ */
+const Textarea = ({ className, testId, hasError, id, name, disabled, rows, style, ...props }) => {
+    const field = useFieldContext();
+    const resolvedError = hasError ?? field?.invalid ?? false;
+    // `field-sizing-content` sizes the box to its text and ignores `rows`, so
+    // `rows` sets the starting height instead: that many lines plus the py-2
+    // padding and the 1px border, before the box grows with its content.
+    const sizedStyle = rows === undefined
+        ? style
+        : { minHeight: `calc(${rows}lh + 1rem + 2px)`, ...style };
+    // 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, { render: _jsx("textarea", { className: cn(focusInput(), `flex field-sizing-content min-h-16 w-full ${INPUT_SHELL} placeholder:text-muted-foreground transition-color-shadow text-paragraph md:text-paragraph-sm px-3 py-2 shadow-xs disabled:cursor-not-allowed disabled:opacity-50`, hasErrorInput, className), "data-component": "textarea", "data-slot": "textarea", rows: rows, style: sizedStyle, ...(hasError === true ? { "aria-invalid": true } : {}), ...(resolvedError ? { "data-error": true } : {}), ...(testId === undefined ? {} : { "data-testid": testId }), ...props }), ...(disabled === undefined ? {} : { disabled }), ...(id === undefined ? {} : { id }), ...(name === undefined ? {} : { name }) }));
+};
+export { Textarea };

package/dist/components/textarea.d.ts

@@ -0,0 +1 @@
+export { Textarea } from "./textarea/textarea-root.js";

package/dist/components/textarea.js

@@ -0,0 +1 @@
+export { Textarea } from "./textarea/textarea-root.js";

package/dist/components/thinking-loader/thinking-loader-counter.d.ts

@@ -0,0 +1,12 @@
+interface ThinkingLoaderCounterProps {
+    className?: string;
+    current: number;
+    total: number;
+}
+/**
+ * Counter displaying "X/Y" progress with animated number transitions.
+ * Uses the shared AnimatedNumber component for smooth digit changes.
+ * Colour is inherited from parent via currentColor.
+ */
+export declare const ThinkingLoaderCounter: ({ current, total, className, }: ThinkingLoaderCounterProps) => import("react").JSX.Element;
+export {};

package/dist/components/thinking-loader/thinking-loader-counter.js

@@ -0,0 +1,10 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { AnimatedNumber } from "@instruments/materia-ui/components/animated-number";
+import { cn } from "@instruments/materia-ui/utils/cn";
+/**
+ * Counter displaying "X/Y" progress with animated number transitions.
+ * Uses the shared AnimatedNumber component for smooth digit changes.
+ * Colour is inherited from parent via currentColor.
+ */
+export const ThinkingLoaderCounter = ({ current, total, className, }) => (_jsx(AnimatedNumber, { className: cn("text-caption font-mono opacity-70", className), suffix: `/${total}`, value: current }));

package/dist/components/thinking-loader/thinking-loader-icon.d.ts

@@ -0,0 +1,13 @@
+import type { LucideIcon } from "lucide-react";
+interface ThinkingLoaderIconProps {
+    icon: LucideIcon | undefined;
+    stepId: string;
+}
+/**
+ * Morphing icon that crossfades between icons while staying in place.
+ * Uses the shared IconMorph component for blur-crossfade animations.
+ * Timing is aligned with ThinkingLoaderStep for cohesive feel.
+ * Colour is inherited from parent via currentColor.
+ */
+export declare const ThinkingLoaderIcon: ({ icon: Icon, stepId, }: ThinkingLoaderIconProps) => import("react").JSX.Element | null;
+export {};

package/dist/components/thinking-loader/thinking-loader-icon.js

@@ -0,0 +1,16 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { IconMorph } from "../icon-morph/icon-morph-root.js";
+import { ANIMATION_TIMING } from "../thinking-loader/thinking-loader-step.js";
+/**
+ * Morphing icon that crossfades between icons while staying in place.
+ * Uses the shared IconMorph component for blur-crossfade animations.
+ * Timing is aligned with ThinkingLoaderStep for cohesive feel.
+ * Colour is inherited from parent via currentColor.
+ */
+export const ThinkingLoaderIcon = ({ icon: Icon, stepId, }) => {
+    if (!Icon) {
+        return null;
+    }
+    return (_jsx(IconMorph, { enterDuration: ANIMATION_TIMING.enter, enterEasing: "out", exitDuration: ANIMATION_TIMING.exit, exitEasing: "out", icon: Icon, morphKey: stepId, size: "xs" }));
+};

package/dist/components/thinking-loader/thinking-loader-root.d.ts

@@ -0,0 +1,24 @@
+import type { ThinkingLoaderProps } from "../thinking-loader/types.js";
+/**
+ * LLM-style "labor illusion" loader with blur conveyor animations and shimmer text effect.
+ *
+ * Supports both controlled mode (parent drives `currentStep`) and uncontrolled mode
+ * (auto-cycles through steps based on `interval`).
+ *
+ * @example
+ * ```tsx
+ * // Uncontrolled - auto-cycles
+ * <ThinkingLoader steps={IMPORT_STEPS} showCounter />
+ *
+ * // Controlled - parent drives progression
+ * <ThinkingLoader steps={MATCH_STEPS} currentStep={step} />
+ *
+ * // Inline orb summary (tray headers, agent chrome)
+ * <ThinkingLoader orb="working" shimmer={false} steps={[{ id: "summary", label: "2 things in progress" }]} />
+ * ```
+ *
+ * @bestPractice Drive `ThinkingLoader` with `currentStep` (controlled) to reflect real progress, or omit it to auto-cycle `steps` on `interval` for a labor-illusion loader.
+ * @bestPractice It already renders an `aria-live="polite"` region announcing each step - don't wrap it in another status role. Mount `ReducedMotionProvider` since it animates via `m.*`.
+ * @category feedback
+ */
+export declare const ThinkingLoader: ({ steps, currentStep, interval, showCounter, shimmer, shimmerVariant, morphIcons, loader, orb, className, onStepChange, }: ThinkingLoaderProps) => import("react").JSX.Element | null;