@instruments/materia-ui 0.1.0

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

@@ -0,0 +1,37 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { focusRing } from "@instruments/materia-ui/tokens/focus-ring";
+import { cn } from "@instruments/materia-ui/utils/cn";
+import { cva } from "class-variance-authority";
+import { Minus, Plus } from "lucide-react";
+import { DISABLED, INPUT_SHELL } from "../../tokens/input-shell.js";
+import { SQUARE_CONTROL_SIZE_CLASSES } from "../../tokens/square-control.js";
+const expandButtonVariants = cva(cn(focusRing(), `group inline-flex shrink-0 items-center justify-center ${INPUT_SHELL} text-foreground ring-offset-background hover:bg-foreground-wash shadow-xs transition-colors ${DISABLED}`), {
+    defaultVariants: {
+        size: "sm",
+    },
+    variants: {
+        size: SQUARE_CONTROL_SIZE_CLASSES,
+    },
+});
+/**
+ * Small square toggle button for expand/collapse actions; shows Plus when
+ * collapsed and Minus when expanded, and reflects state via `aria-expanded`.
+ * Import from "@instruments/materia-ui/components/expand-button".
+ *
+ * This is an icon-only control, so pass an `aria-label` (or `aria-labelledby`)
+ * describing the action (e.g. "Expand row") - without it screen readers
+ * announce an unlabelled button.
+ *
+ * @example
+ * <ExpandButton aria-label="Expand row" expanded={open} onClick={toggle} />
+ *
+ * @bestPractice Always pass an `aria-label` (e.g. "Expand row") - it's icon-only, so without one screen readers announce an unlabelled button.
+ * @bestPractice Drive the icon and `aria-expanded` with the `expanded` prop; set `expandedIcon`/`collapsedIcon` only to override the default Minus/Plus pair.
+ * @category actions
+ */
+const ExpandButton = ({ className, expanded = false, expandedIcon: ExpandedIcon = Minus, collapsedIcon: CollapsedIcon = Plus, size, ...props }) => {
+    const Icon = expanded ? ExpandedIcon : CollapsedIcon;
+    return (_jsx("button", { "aria-expanded": expanded, className: cn(expandButtonVariants({ size }), className), type: "button", ...props, children: _jsx(Icon, { "aria-hidden": "true" }) }));
+};
+export { ExpandButton };

package/dist/components/expand-button/plus-minus-morph-icon.d.ts

@@ -0,0 +1,21 @@
+import type { ComponentType, SVGProps } from "react";
+type MorphIcon = ComponentType<SVGProps<SVGSVGElement>>;
+export type PlusMinusMorphIconProps = SVGProps<SVGSVGElement> & {
+    /** Whether the control shows its expanded (Minus) state. @default false */
+    expanded?: boolean;
+    /** Icon shown while expanded. @default Minus */
+    expandedIcon?: MorphIcon;
+    /** Icon shown while collapsed. @default Plus */
+    collapsedIcon?: MorphIcon;
+};
+/**
+ * Plus↔Minus quarter-turn morph. Expanding spins clockwise (+90°) into Minus;
+ * collapsing reverses (-90°) back into Plus - the outgoing icon exits towards
+ * that angle while the incoming icon enters from the opposite side, reading
+ * as one continuous turn rather than two independent fades.
+ *
+ * Accepts standard SVG props (e.g. `className` from {@link Icon}) and forwards
+ * them onto the active Lucide glyph so size/stroke tokens still apply.
+ */
+export declare const PlusMinusMorphIcon: ({ expanded, expandedIcon: ExpandedIcon, collapsedIcon: CollapsedIcon, className, ...props }: PlusMinusMorphIconProps) => import("react").JSX.Element;
+export {};

package/dist/components/expand-button/plus-minus-morph-icon.js

@@ -0,0 +1,35 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { durations, easings } from "@instruments/materia-ui/tokens/motion";
+import { Minus, Plus } from "lucide-react";
+import { AnimatePresence } from "motion/react";
+import * as m from "motion/react-m";
+/** Enter transition - deceleration only, per the design system's "never
+ * ease-out on enter" rule. Snappy: crisp but readable. */
+const ICON_ENTER_TRANSITION = {
+    duration: durations.normal,
+    ease: easings.out,
+};
+/** Exit is quicker and may ease in - the icon is leaving, not arriving. */
+const ICON_EXIT_TRANSITION = {
+    duration: durations.quick,
+    ease: easings.out,
+};
+/**
+ * Plus↔Minus quarter-turn morph. Expanding spins clockwise (+90°) into Minus;
+ * collapsing reverses (-90°) back into Plus - the outgoing icon exits towards
+ * that angle while the incoming icon enters from the opposite side, reading
+ * as one continuous turn rather than two independent fades.
+ *
+ * Accepts standard SVG props (e.g. `className` from {@link Icon}) and forwards
+ * them onto the active Lucide glyph so size/stroke tokens still apply.
+ */
+export const PlusMinusMorphIcon = ({ expanded = false, expandedIcon: ExpandedIcon = Minus, collapsedIcon: CollapsedIcon = Plus, className, ...props }) => {
+    const Icon = expanded ? ExpandedIcon : CollapsedIcon;
+    const rotation = expanded ? 90 : -90;
+    return (_jsx(AnimatePresence, { initial: false, mode: "popLayout", children: _jsx(m.span, { animate: { opacity: 1, rotate: 0 }, className: "inline-flex items-center justify-center", exit: {
+                opacity: 0,
+                rotate: rotation,
+                transition: ICON_EXIT_TRANSITION,
+            }, initial: { opacity: 0, rotate: -rotation }, transition: ICON_ENTER_TRANSITION, children: _jsx(Icon, { "aria-hidden": "true", className: className, ...props }) }, expanded ? "expanded" : "collapsed") }));
+};

package/dist/components/expand-button.d.ts

@@ -0,0 +1,4 @@
+export type { ExpandButtonProps } from "./expand-button/expand-button-root.js";
+export { ExpandButton } from "./expand-button/expand-button-root.js";
+export type { PlusMinusMorphIconProps } from "./expand-button/plus-minus-morph-icon.js";
+export { PlusMinusMorphIcon } from "./expand-button/plus-minus-morph-icon.js";

package/dist/components/expand-button.js

@@ -0,0 +1,2 @@
+export { ExpandButton } from "./expand-button/expand-button-root.js";
+export { PlusMinusMorphIcon } from "./expand-button/plus-minus-morph-icon.js";

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

@@ -0,0 +1,25 @@
+interface ExpandableTextProps {
+    /** Content to render inside the expandable area. */
+    children: React.ReactNode;
+    /** Additional className for the outer container. */
+    className?: string;
+    /**
+     * Collapsed height in rem units.
+     * @default 2.5 (2 lines of sm text)
+     */
+    collapsedHeight?: number;
+}
+declare const ExpandableTextBase: ({ children, className, collapsedHeight, }: ExpandableTextProps) => import("react").JSX.Element;
+/**
+ * Long copy clamped to a fixed height that fades out at the cut, with a
+ * More/Less toggle that animates it open. The toggle only appears when the
+ * content actually overflows.
+ *
+ * @bestPractice Use it for secondary prose such as a product description or a review; keep headings and anything the reader must see outside it.
+ * @bestPractice Set `collapsedHeight` in rem to a whole number of lines at the text's line height, so the cut lands between lines.
+ * @bestPractice Reach for `Collapsible` when the hidden part is separate content behind a labelled trigger rather than the rest of one passage.
+ * @category data
+ */
+declare const ExpandableText: import("react").MemoExoticComponent<typeof ExpandableTextBase>;
+export type { ExpandableTextProps };
+export { ExpandableText };

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

@@ -0,0 +1,49 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { durations, easings } from "@instruments/materia-ui/tokens/motion";
+import { cn } from "@instruments/materia-ui/utils/cn";
+import { AnimatePresence } from "motion/react";
+import * as m from "motion/react-m";
+import { memo, useCallback, useState } from "react";
+const DEFAULT_COLLAPSED_HEIGHT = 2.5;
+const transition = {
+    duration: durations.normal,
+    ease: easings.out,
+};
+const ExpandableTextBase = ({ children, className, collapsedHeight = DEFAULT_COLLAPSED_HEIGHT, }) => {
+    const [isExpanded, setIsExpanded] = useState(false);
+    const [isClamped, setIsClamped] = useState(false);
+    // isClamped is measured from the live DOM (scrollHeight vs collapsed px) -
+    // it cannot be derived during render, only after layout. A ref callback
+    // measures when the content mounts or `collapsedHeight` changes.
+    const measureContent = useCallback((el) => {
+        if (el !== null) {
+            // The computed root font size is always in px, e.g. "16px".
+            const fontSize = Number(getComputedStyle(document.documentElement).fontSize.replace("px", ""));
+            setIsClamped(el.scrollHeight > collapsedHeight * fontSize);
+        }
+    }, [collapsedHeight]);
+    const toggleExpanded = useCallback(() => {
+        setIsExpanded((prev) => !prev);
+    }, []);
+    const heightValue = `${collapsedHeight}rem`;
+    return (_jsxs("div", { className: cn(className), children: [_jsx(m.div
+            // oxlint-disable-next-line react-doctor/no-layout-property-animation -- the height change has to move the content below it
+            , { 
+                // oxlint-disable-next-line react-doctor/no-layout-property-animation -- the height change has to move the content below it
+                animate: { height: isExpanded ? "auto" : heightValue }, className: cn(!isExpanded &&
+                    isClamped &&
+                    "[mask-image:linear-gradient(to_bottom,#000_calc(100%-0.75rem),transparent)]"), initial: false, style: { overflow: "hidden" }, transition: transition, children: _jsx("div", { ref: measureContent, children: children }) }), _jsx(AnimatePresence, { mode: "wait", children: isClamped && (_jsx(m.button, { animate: { opacity: 1 }, className: "text-muted-foreground text-paragraph-sm mt-1 block underline underline-offset-2", exit: { opacity: 0 }, initial: { opacity: 0 }, onClick: toggleExpanded, transition: transition, type: "button", children: isExpanded ? "Less" : "More" }, isExpanded ? "less" : "more")) })] }));
+};
+/**
+ * Long copy clamped to a fixed height that fades out at the cut, with a
+ * More/Less toggle that animates it open. The toggle only appears when the
+ * content actually overflows.
+ *
+ * @bestPractice Use it for secondary prose such as a product description or a review; keep headings and anything the reader must see outside it.
+ * @bestPractice Set `collapsedHeight` in rem to a whole number of lines at the text's line height, so the cut lands between lines.
+ * @bestPractice Reach for `Collapsible` when the hidden part is separate content behind a labelled trigger rather than the rest of one passage.
+ * @category data
+ */
+const ExpandableText = memo(ExpandableTextBase);
+export { ExpandableText };

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

@@ -0,0 +1 @@
+export { ExpandableText } from "./expandable-text/expandable-text-root.js";

package/dist/components/expandable-text.js

@@ -0,0 +1 @@
+export { ExpandableText } from "./expandable-text/expandable-text-root.js";

package/dist/components/fade-overlay/fade-overlay-root.d.ts

@@ -0,0 +1,33 @@
+import type { ReactNode } from "react";
+export interface FadeOverlayProps {
+    /** Drives the fade in/out of the overlay. */
+    visible: boolean;
+    /** Border radius of the fade container. */
+    radius: number | string;
+    /** The decorative overlay content (border beam, shine sweep, …). */
+    overlay: ReactNode;
+    /** Positional overrides forwarded to the fade container. */
+    className?: string | undefined;
+    /**
+     * Optional wrapped content. When provided, the overlay wraps it in a
+     * `relative` box; when omitted, the overlay assumes its nearest ancestor is
+     * already `position: relative`.
+     */
+    children?: ReactNode | undefined;
+}
+/**
+ * Fades a decorative overlay (a border beam, a shine sweep, …) in and out with
+ * `visible`, keeping it MOUNTED through its fade-out exit so the overlay's
+ * animation rAF loop survives until the fade completes - then unmounts it.
+ * Honours `prefers-reduced-motion` by rendering nothing but `children` (a
+ * static decorative band would read louder than the animation it replaces).
+ *
+ * Use as a wrapper (pass `children`) or a bare overlay (omit them). This is the
+ * shared exit-animation lifecycle that backs `BorderBeam` and `Shine`.
+ *
+ * @bestPractice Reach for `FadeOverlay` to fade a decorative overlay in/out - it keeps the overlay mounted through its fade-out so the animation's rAF loop survives, then unmounts it; don't hand-roll that lifecycle.
+ * @bestPractice It's the shared engine behind `BorderBeam` and `Shine` - prefer those named components for their specific looks; drop to `FadeOverlay` directly only for a new overlay effect.
+ * @bestPractice Needs `ReducedMotionProvider`; under reduced motion it renders only `children` (a static band would read louder than the animation), so the overlay doesn't appear.
+ * @category motion
+ */
+export declare const FadeOverlay: ({ visible, radius, overlay, className, children, }: FadeOverlayProps) => ReactNode;

package/dist/components/fade-overlay/fade-overlay-root.js

@@ -0,0 +1,48 @@
+"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 { useReducedMotion } from "motion/react";
+import * as m from "motion/react-m";
+import { useState } from "react";
+/** Fade-in/out duration for decorative overlays (seconds). */
+const FADE_DURATION_SECONDS = 0.45;
+/**
+ * Fades a decorative overlay (a border beam, a shine sweep, …) in and out with
+ * `visible`, keeping it MOUNTED through its fade-out exit so the overlay's
+ * animation rAF loop survives until the fade completes - then unmounts it.
+ * Honours `prefers-reduced-motion` by rendering nothing but `children` (a
+ * static decorative band would read louder than the animation it replaces).
+ *
+ * Use as a wrapper (pass `children`) or a bare overlay (omit them). This is the
+ * shared exit-animation lifecycle that backs `BorderBeam` and `Shine`.
+ *
+ * @bestPractice Reach for `FadeOverlay` to fade a decorative overlay in/out - it keeps the overlay mounted through its fade-out so the animation's rAF loop survives, then unmounts it; don't hand-roll that lifecycle.
+ * @bestPractice It's the shared engine behind `BorderBeam` and `Shine` - prefer those named components for their specific looks; drop to `FadeOverlay` directly only for a new overlay effect.
+ * @bestPractice Needs `ReducedMotionProvider`; under reduced motion it renders only `children` (a static band would read louder than the animation), so the overlay doesn't appear.
+ * @category motion
+ */
+export const FadeOverlay = ({ visible, radius, overlay, className, children, }) => {
+    const shouldReduceMotion = useReducedMotion();
+    // `mounted` is an exit-animation gate, NOT derived state: it lags `visible`,
+    // staying true after visible flips to false so the overlay can fade out, then
+    // unmounting via onAnimationComplete (which stops its rAF loop). Deriving it
+    // would unmount instantly and skip the fade-out. It is raised again during
+    // render when `visible` returns.
+    const [mounted, setMounted] = useState(visible);
+    if (visible && !mounted) {
+        setMounted(true);
+    }
+    if (shouldReduceMotion === true) {
+        return children ?? null;
+    }
+    const faded = mounted ? (_jsx(m.div, { animate: { opacity: visible ? 1 : 0 }, "aria-hidden": true, className: cn("pointer-events-none absolute inset-0", className), initial: { opacity: 0 }, onAnimationComplete: () => {
+            if (!visible) {
+                setMounted(false);
+            }
+        }, style: { borderRadius: radius }, transition: { duration: FADE_DURATION_SECONDS, ease: easings.out }, children: overlay })) : null;
+    if (children === undefined) {
+        return faded;
+    }
+    return (_jsxs("div", { className: "relative", children: [children, faded] }));
+};

package/dist/components/fade-overlay.d.ts

@@ -0,0 +1 @@
+export { FadeOverlay, type FadeOverlayProps, } from "./fade-overlay/fade-overlay-root.js";

package/dist/components/fade-overlay.js

@@ -0,0 +1 @@
+export { FadeOverlay, } from "./fade-overlay/fade-overlay-root.js";

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

@@ -0,0 +1,10 @@
+/**
+ * Field component anatomy.
+ * Documents the composition structure for form fields with labels, inputs, and feedback.
+ */
+export declare const fieldAnatomy: import("../../tokens/anatomy.js").ComponentAnatomy;
+/**
+ * FieldGroup component anatomy.
+ * Documents the composition structure for grouping multiple fields.
+ */
+export declare const fieldGroupAnatomy: import("../../tokens/anatomy.js").ComponentAnatomy;

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

@@ -0,0 +1,50 @@
+import { defineAnatomy } from "../../tokens/anatomy.js";
+/**
+ * Field component anatomy.
+ * Documents the composition structure for form fields with labels, inputs, and feedback.
+ */
+export const fieldAnatomy = defineAnatomy({
+    children: [
+        {
+            description: "Accessible label for the field",
+            label: "FieldLabel",
+            slot: "field-label",
+        },
+        {
+            children: [
+                {
+                    description: "Helper text or instructions",
+                    label: "FieldDescription",
+                    slot: "field-description",
+                },
+                {
+                    description: "Validation error messages",
+                    label: "FieldError",
+                    slot: "field-error",
+                },
+            ],
+            description: "Container for input and messages",
+            label: "FieldContent",
+            slot: "field-content",
+        },
+    ],
+    description: "Form field container with label, input, and feedback",
+    label: "Field",
+    slot: "field",
+});
+/**
+ * FieldGroup component anatomy.
+ * Documents the composition structure for grouping multiple fields.
+ */
+export const fieldGroupAnatomy = defineAnatomy({
+    children: [
+        {
+            description: "Individual form field",
+            label: "Field",
+            slot: "field",
+        },
+    ],
+    description: "Container for grouping multiple fields",
+    label: "FieldGroup",
+    slot: "field-group",
+});

package/dist/components/field/field-content.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Container for field input/control and associated description/error messages.
+ *
+ * @param props - The field content props
+ * @param props.className - Additional CSS classes to apply.
+ * @param props.children - Form control and FieldDescription/FieldError components.
+ * @param props... - All other standard HTML div element props.
+ *
+ * @example
+ * ```tsx
+ * <FieldContent>
+ *   <Input />
+ *   <FieldDescription>Helper text</FieldDescription>
+ *   <FieldError />
+ * </FieldContent>
+ * ```
+ */
+export declare const FieldContent: ({ className, ...props }: React.ComponentProps<"div">) => import("react").JSX.Element;

package/dist/components/field/field-content.js

@@ -0,0 +1,21 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { cn } from "@instruments/materia-ui/utils/cn";
+import { Flex } from "../flex.js";
+/**
+ * Container for field input/control and associated description/error messages.
+ *
+ * @param props - The field content props
+ * @param props.className - Additional CSS classes to apply.
+ * @param props.children - Form control and FieldDescription/FieldError components.
+ * @param props... - All other standard HTML div element props.
+ *
+ * @example
+ * ```tsx
+ * <FieldContent>
+ *   <Input />
+ *   <FieldDescription>Helper text</FieldDescription>
+ *   <FieldError />
+ * </FieldContent>
+ * ```
+ */
+export const FieldContent = ({ className, ...props }) => (_jsx(Flex, { className: cn("group/field-content flex-1 gap-1.5", className), "data-component": "field-content", "data-slot": "field-content", direction: "column", ...props }));

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

@@ -0,0 +1,22 @@
+interface FieldContextValue {
+    fieldId: string;
+    /** Whether the field is in an invalid state; drives the destructive styling of its parts. */
+    invalid: boolean;
+}
+/**
+ * Carries the field's id and invalid flag to its parts (FieldDescription,
+ * FieldError, FieldLabel) and to descendant Input/InputGroup/Textarea
+ * controls for their error styling. Label, description and `aria-invalid`
+ * wiring itself comes from Base UI's Field. Used internally by Field.
+ */
+export declare const FieldProvider: ({ id, invalid, children, }: {
+    id?: string | undefined;
+    invalid?: boolean | undefined;
+    children: React.ReactNode;
+}) => import("react").JSX.Element;
+/**
+ * Read field context from the nearest Field ancestor.
+ * Returns null when used outside a Field.
+ */
+export declare const useFieldContext: () => FieldContextValue | null;
+export {};

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

@@ -0,0 +1,21 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { createContext, use, useId, useMemo } from "react";
+const FieldContext = createContext(null);
+/**
+ * Carries the field's id and invalid flag to its parts (FieldDescription,
+ * FieldError, FieldLabel) and to descendant Input/InputGroup/Textarea
+ * controls for their error styling. Label, description and `aria-invalid`
+ * wiring itself comes from Base UI's Field. Used internally by Field.
+ */
+export const FieldProvider = ({ id, invalid = false, children, }) => {
+    const generatedId = useId();
+    const fieldId = id ?? generatedId;
+    const value = useMemo(() => ({ fieldId, invalid }), [fieldId, invalid]);
+    return (_jsx(FieldContext.Provider, { value: value, children: children }));
+};
+/**
+ * Read field context from the nearest Field ancestor.
+ * Returns null when used outside a Field.
+ */
+export const useFieldContext = () => use(FieldContext);

package/dist/components/field/field-description.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Helper text or description displayed below a field label or above the
+ * control (Base UI `Field.Description`). Inside a `<Field>` it joins the
+ * control's `aria-describedby` automatically.
+ *
+ * @param props - The field description props
+ * @param props.className - Additional CSS classes to apply.
+ * @param props.children - Description text content (supports links).
+ * @param props... - All other standard HTML paragraph element props.
+ *
+ * @example
+ * ```tsx
+ * <FieldDescription>Enter your full name as it appears on your ID.</FieldDescription>
+ * ```
+ */
+export declare const FieldDescription: ({ className, id, ...props }: React.ComponentProps<"p">) => import("react").JSX.Element;

package/dist/components/field/field-description.js

@@ -0,0 +1,25 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Field as FieldPrimitive } from "@base-ui/react/field";
+import { cn } from "@instruments/materia-ui/utils/cn";
+import { useFieldContext } from "../field/field-context.js";
+/**
+ * Helper text or description displayed below a field label or above the
+ * control (Base UI `Field.Description`). Inside a `<Field>` it joins the
+ * control's `aria-describedby` automatically.
+ *
+ * @param props - The field description props
+ * @param props.className - Additional CSS classes to apply.
+ * @param props.children - Description text content (supports links).
+ * @param props... - All other standard HTML paragraph element props.
+ *
+ * @example
+ * ```tsx
+ * <FieldDescription>Enter your full name as it appears on your ID.</FieldDescription>
+ * ```
+ */
+export const FieldDescription = ({ className, id, ...props }) => {
+    const ctx = useFieldContext();
+    const descriptionId = id ?? (ctx ? `${ctx.fieldId}-description` : undefined);
+    return (_jsx(FieldPrimitive.Description, { className: cn("text-muted-foreground text-paragraph-sm font-normal group-has-[[data-orientation=horizontal]]/field:text-balance", "last:mt-0 nth-last-2:-mt-1 [[data-variant=legend]+&]:-mt-1.5", "[&>a:hover]:text-primary [&>a]:underline [&>a]:underline-offset-4", className), "data-component": "field-description", "data-slot": "field-description", ...(descriptionId === undefined ? {} : { id: descriptionId }), ...props }));
+};

package/dist/components/field/field-error.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Error message display for field validation (Base UI `Field.Error`),
+ * rendered as a polite live region (`role="alert"`). Inside a `<Field>` it
+ * joins the control's `aria-describedby` while shown. Accepts one or many
+ * errors (deduplicated by message; multiple render as a list) or explicit
+ * `children`, and renders nothing when empty.
+ *
+ * @param props - The field error props
+ * @param props.errors - Array of error objects with optional message property.
+ * @param props.children - Custom error content (overrides errors array).
+ * @param props.className - Additional CSS classes to apply.
+ * @param props... - All other standard HTML div element props.
+ *
+ * @example
+ * ```tsx
+ * <FieldError errors={[{ message: "This field is required" }]} />
+ * <FieldError>Custom error message</FieldError>
+ * ```
+ */
+export declare const FieldError: ({ className, children, errors, id, ...props }: React.ComponentProps<"div"> & {
+    errors?: ({
+        message?: string;
+    } | undefined)[];
+}) => import("react").JSX.Element | null;

package/dist/components/field/field-error.js

@@ -0,0 +1,59 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Field as FieldPrimitive } from "@base-ui/react/field";
+import { cn } from "@instruments/materia-ui/utils/cn";
+import { useMemo } from "react";
+import { useFieldContext } from "../field/field-context.js";
+import { Flex } from "../flex.js";
+/**
+ * Error message display for field validation (Base UI `Field.Error`),
+ * rendered as a polite live region (`role="alert"`). Inside a `<Field>` it
+ * joins the control's `aria-describedby` while shown. Accepts one or many
+ * errors (deduplicated by message; multiple render as a list) or explicit
+ * `children`, and renders nothing when empty.
+ *
+ * @param props - The field error props
+ * @param props.errors - Array of error objects with optional message property.
+ * @param props.children - Custom error content (overrides errors array).
+ * @param props.className - Additional CSS classes to apply.
+ * @param props... - All other standard HTML div element props.
+ *
+ * @example
+ * ```tsx
+ * <FieldError errors={[{ message: "This field is required" }]} />
+ * <FieldError>Custom error message</FieldError>
+ * ```
+ */
+export const FieldError = ({ className, children, errors, id, ...props }) => {
+    const ctx = useFieldContext();
+    const errorId = id ?? (ctx ? `${ctx.fieldId}-error` : undefined);
+    // Memoise only the deduplicated error data - building JSX inside a memo
+    // before the early return below trips rerender-memo-before-early-return.
+    const uniqueErrors = useMemo(() => {
+        if (errors === undefined || errors.length === 0) {
+            return null;
+        }
+        return [
+            ...new Map(errors.map((error) => [error?.message, error])).values(),
+        ];
+    }, [errors]);
+    let content;
+    if (children !== undefined && children !== null) {
+        content = children;
+    }
+    else if (uniqueErrors === null) {
+        content = null;
+    }
+    else if (uniqueErrors.length === 1) {
+        content = uniqueErrors[0]?.message;
+    }
+    else {
+        content = (_jsx(Flex, { as: "ul", className: "ml-4 list-disc", direction: "column", gap: "2xs", children: uniqueErrors.map((error) => error?.message !== undefined && error.message !== "" ? (_jsx("li", { children: error.message }, error.message)) : null) }));
+    }
+    if (content === undefined || content === null || content === "") {
+        return null;
+    }
+    // `match` mounts the Base UI error whenever we have content, independent of
+    // its own validity tracking; our `children` replace its built-in message.
+    return (_jsx(FieldPrimitive.Error, { "aria-live": "polite", className: cn("text-destructive text-paragraph-sm font-normal", className), "data-component": "field-error", "data-slot": "field-error", match: true, role: "alert", ...(errorId === undefined ? {} : { id: errorId }), ...props, children: content }));
+};

package/dist/components/field/field-group.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Container for grouping multiple fields together with consistent spacing.
+ *
+ * @param props - The field group props
+ * @param props.className - Additional CSS classes to apply.
+ * @param props.children - Field components to group.
+ * @param props... - All other standard HTML div element props.
+ *
+ * @example
+ * ```tsx
+ * <FieldGroup>
+ *   <Field>...</Field>
+ *   <Field>...</Field>
+ * </FieldGroup>
+ * ```
+ */
+export declare const FieldGroup: ({ className, ...props }: React.ComponentProps<"div">) => import("react").JSX.Element;

package/dist/components/field/field-group.js

@@ -0,0 +1,20 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { cn } from "@instruments/materia-ui/utils/cn";
+import { Flex } from "../flex.js";
+/**
+ * Container for grouping multiple fields together with consistent spacing.
+ *
+ * @param props - The field group props
+ * @param props.className - Additional CSS classes to apply.
+ * @param props.children - Field components to group.
+ * @param props... - All other standard HTML div element props.
+ *
+ * @example
+ * ```tsx
+ * <FieldGroup>
+ *   <Field>...</Field>
+ *   <Field>...</Field>
+ * </FieldGroup>
+ * ```
+ */
+export const FieldGroup = ({ className, ...props }) => (_jsx(Flex, { className: cn("group/field-group @container/field-group w-full gap-7 data-[slot=checkbox-group]:gap-3 [&>[data-slot=field-group]]:gap-4", className), "data-component": "field-group", "data-slot": "field-group", direction: "column", ...props }));

package/dist/components/field/field-label.d.ts

@@ -0,0 +1,21 @@
+import { Label } from "@instruments/materia-ui/components/label";
+/**
+ * Label for a field (Base UI `Field.Label`). Inside a `<Field>` it is
+ * associated with the field's control automatically, so clicking it focuses
+ * the control and no `htmlFor` is needed. Can wrap interactive elements like
+ * checkboxes/radios for larger click targets. When rendered inside an invalid
+ * `<Field>`, receives `data-invalid` so the label text turns destructive.
+ *
+ * @param props - The field label props
+ * @param props.className - Additional CSS classes to apply.
+ * @param props.children - Label text or interactive elements.
+ * @param props.htmlFor - Optional explicit target; overrides the automatic association.
+ * @param props... - All other Label component props.
+ *
+ * @example
+ * ```tsx
+ * <FieldLabel>Email Address</FieldLabel>
+ * <FieldLabel><Checkbox /> Accept terms</FieldLabel>
+ * ```
+ */
+export declare const FieldLabel: ({ className, htmlFor, ...props }: React.ComponentProps<typeof Label>) => import("react").JSX.Element;