@instruments/materia-ui 0.1.0

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

@@ -0,0 +1,70 @@
+import type { useRender } from "@base-ui/react/use-render";
+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 { PillEmphasis, PillSize, PillTone, pillVariants } from "../pill/pill-variants.js";
+/** Badge tone - aliased from shared PillTone */
+export type BadgeTone = PillTone;
+export type BadgeSize = PillSize;
+export type BadgeEmphasis = PillEmphasis;
+export interface BadgeProps extends React.HTMLAttributes<HTMLDivElement>, Omit<VariantProps<typeof pillVariants>, "size"> {
+    /** Replace the rendered `span` with another element or component. */
+    render?: useRender.RenderProp | undefined;
+    /** Ref to the rendered element. */
+    ref?: React.Ref<HTMLElement> | undefined;
+    /**
+     * Badge size - a single token or a per-breakpoint object like
+     * `{ base: "sm", md: "lg" }`. Forwarded to the underlying Pill. @default "base"
+     */
+    size?: ResponsiveValue<PillSize>;
+    disabled?: boolean;
+    /** Force focus ring display (for documentation/testing) */
+    focused?: boolean;
+    /** Force hover state display (for documentation/testing) */
+    hovered?: boolean;
+    icon?: LucideIcon | React.ComponentType<React.SVGProps<SVGSVGElement>>;
+    /** @default "start" */
+    iconPlacement?: "start" | "end";
+    /** Left segment of a split badge; renders a divider before `value`. */
+    label?: string;
+    /** Show loading spinner */
+    loading?: boolean;
+    /** Label shown during loading */
+    loadingLabel?: string;
+    testid?: string;
+    /** Right (emphasised) segment; shown alone when no `label` is set. */
+    value?: string;
+    /**
+     * Badge display mode. `"count"` renders a circular number badge (full radius +
+     * `tabular-nums`) for notification/count use; it **owns the radius axis** and
+     * overrides any `radius` prop. Pair with `accessibleLabel` when standalone.
+     * @default "default"
+     */
+    mode?: "default" | "count";
+    /**
+     * Accessible name for a standalone `mode="count"` badge (e.g. `"3 unread"`).
+     * Renders as `sr-only` text with the visible number hidden from assistive
+     * tech. When the badge sits inside an icon-only trigger, instead set
+     * `aria-hidden` on the badge and fold the count into the trigger's own
+     * `aria-label` ("Notifications, 3 unread").
+     */
+    accessibleLabel?: string;
+    /**
+     * Draw a 2px ring in the page's `background` colour around the badge, to
+     * separate it from the surface it overlaps when it sits on a corner.
+     * @default false
+     */
+    ring?: boolean;
+}
+/**
+ * Display-only pill for contextual metadata - status, category, or counts.
+ * Pass `label`+`value` for a split badge; compose `BadgeDot`/`BadgeButton` as children.
+ *
+ * @bestPractice Badge is display-only - never attach `onClick`; use `Tag` (interactive) or wrap a `Button`.
+ * @bestPractice For a notification count use `mode="count"` (circular, tabular figures), not `radius="full"` + manual classes.
+ * @bestPractice A standalone count needs an `accessibleLabel` ("3 unread"); inside an icon-only trigger, mark the badge `aria-hidden` and fold the count into the trigger's `aria-label`.
+ * @bestPractice A badge overlapping a corner of another surface takes `ring` so a 2px `background`-coloured ring separates it from what's beneath; set it only where the badge truly overlaps, and the page surface should be `background`.
+ * @category feedback
+ */
+export declare const Badge: ({ className, tone, size, emphasis, radius, asInput, render, disabled, testid, label, value, icon, iconPlacement, focused, hovered, loading, loadingLabel, mode, accessibleLabel, ring, children, ...props }: BadgeProps) => React.JSX.Element;

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

@@ -0,0 +1,104 @@
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Fragment } from "react";
+import { resolveResponsiveBase } from "../../tokens/responsive.js";
+import { cn } from "../../utils/cn.js";
+import { hasText } from "../../utils/type-guards.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";
+import { VisuallyHidden } from "../visually-hidden.js";
+const badgeSizeToIconSize = (key = "base") => PILL_ICON_SIZE_MAP[key ?? "base"] ?? "sm";
+/** Build the textual content: split label/value, value-only, or children. */
+const renderBadgeText = (label, value, children) => {
+    // Every branch below can end up as an element inside the FLAT array the
+    // icon and loading arms build, so each carries its own key. Without one,
+    // `<Badge icon={...}>` warned about a missing key on every render.
+    if (hasText(label) && hasText(value)) {
+        return (_jsxs(Fragment, { children: [_jsx("span", { className: "trim-both", children: label }), _jsx("span", { "aria-hidden": "true", className: "h-3.5 w-px bg-current opacity-20" }), _jsx("span", { className: "trim-both font-medium", children: value })] }, "badge-text"));
+    }
+    if (hasText(value)) {
+        return (_jsx("span", { className: "trim-both", children: value }, "badge-text"));
+    }
+    return children;
+};
+/**
+ * Decoration and text, as an array: every element in it carries its own key.
+ */
+const buildBaseContent = ({ icon, iconPlacement, iconSize, loading, loadingLabel, textContent, }) => {
+    if (loading) {
+        return [
+            _jsx(Spinner, { size: iconSize }, "badge-spinner"),
+            loadingLabel === undefined ? (textContent) : (_jsx(Fragment, { children: loadingLabel }, "badge-loading-label")),
+        ];
+    }
+    if (icon) {
+        const iconElement = _jsx(Icon, { icon: icon, size: iconSize }, "badge-icon");
+        return [
+            iconPlacement === "start" ? iconElement : null,
+            textContent,
+            iconPlacement === "end" ? iconElement : null,
+        ];
+    }
+    return textContent;
+};
+/** Count badges name themselves with sr-only text and hide the bare digits. */
+const withAccessibleLabel = (baseContent, isCount, accessibleLabel) => isCount && hasText(accessibleLabel) ? (_jsxs(_Fragment, { children: [_jsx("span", { "aria-hidden": "true", children: baseContent }), _jsx(VisuallyHidden, { children: accessibleLabel })] })) : (baseContent);
+/** Forward only the Pill props that were actually set (exact optional types). */
+const getOptionalPillProps = ({ asInput, disabled, emphasis, tone, }) => {
+    const optional = {};
+    if (emphasis !== undefined) {
+        optional.emphasis = emphasis;
+    }
+    if (tone !== undefined) {
+        optional.tone = tone;
+    }
+    if (asInput !== undefined) {
+        optional.asInput = asInput;
+    }
+    if (disabled !== undefined) {
+        optional.disabled = disabled;
+    }
+    return optional;
+};
+/**
+ * Display-only pill for contextual metadata - status, category, or counts.
+ * Pass `label`+`value` for a split badge; compose `BadgeDot`/`BadgeButton` as children.
+ *
+ * @bestPractice Badge is display-only - never attach `onClick`; use `Tag` (interactive) or wrap a `Button`.
+ * @bestPractice For a notification count use `mode="count"` (circular, tabular figures), not `radius="full"` + manual classes.
+ * @bestPractice A standalone count needs an `accessibleLabel` ("3 unread"); inside an icon-only trigger, mark the badge `aria-hidden` and fold the count into the trigger's `aria-label`.
+ * @bestPractice A badge overlapping a corner of another surface takes `ring` so a 2px `background`-coloured ring separates it from what's beneath; set it only where the badge truly overlaps, and the page surface should be `background`.
+ * @category feedback
+ */
+export const Badge = ({ className, tone, size, emphasis, radius = "rounded", asInput, render, disabled, testid, label, value, icon, iconPlacement = "start", focused, hovered, loading = false, loadingLabel, mode = "default", accessibleLabel, ring = false, children, ...props }) => {
+    // Icon + spinner take a single token; resolve the responsive base. The Pill
+    // itself receives the full responsive `size` and layers `md:*` overrides.
+    const iconSize = badgeSizeToIconSize(resolveResponsiveBase(size, "base"));
+    // If both label and value are provided, render split badge with divider
+    // If only value is provided, render it as content
+    // Otherwise use children
+    const baseContent = buildBaseContent({
+        icon,
+        iconPlacement,
+        iconSize,
+        loading,
+        loadingLabel,
+        textContent: renderBadgeText(label, value, children),
+    });
+    // `mode="count"` is a circular number badge: it owns the radius axis (forces
+    // `full`) and applies tabular figures + tight padding, so a single digit reads
+    // as a circle (min-w == height) and multi-digit counts grow into a pill. A bare
+    // number is meaningless to assistive tech, so `accessibleLabel` supplies an
+    // sr-only name and hides the visible digits from AT.
+    const isCount = mode === "count";
+    const resolvedRadius = isCount ? "full" : radius;
+    const content = withAccessibleLabel(baseContent, isCount, accessibleLabel);
+    const optionalPillProps = getOptionalPillProps({
+        asInput,
+        disabled,
+        emphasis,
+        tone,
+    });
+    return (_jsx(Pill, { className: cn(isCount ? "px-1 tabular-nums" : undefined, ring && "ring-background ring-2", className), "data-focused": focused === true ? true : undefined, "data-hovered": hovered === true ? true : undefined, "data-loading": loading || undefined, "data-mode": isCount ? "count" : undefined, "data-slot": "badge", "data-testid": testid, radius: resolvedRadius, render: render, size: size, ...optionalPillProps, ...props, children: content }));
+};

package/dist/components/badge.d.ts

@@ -0,0 +1,7 @@
+export type { BadgeButtonProps } from "./badge/badge-button.js";
+export { BadgeButton } from "./badge/badge-button.js";
+export type { BadgeDotProps } from "./badge/badge-dot.js";
+export { BadgeDot } from "./badge/badge-dot.js";
+export type { BadgeEmphasis, BadgeProps, BadgeSize, BadgeTone, } from "./badge/badge-root.js";
+export { Badge } from "./badge/badge-root.js";
+export { pillVariants } from "./pill/pill-variants.js";

package/dist/components/badge.js

@@ -0,0 +1,4 @@
+export { BadgeButton } from "./badge/badge-button.js";
+export { BadgeDot } from "./badge/badge-dot.js";
+export { Badge } from "./badge/badge-root.js";
+export { pillVariants } from "./pill/pill-variants.js";

package/dist/components/border-beam/border-beam-root.d.ts

@@ -0,0 +1,45 @@
+import type { DropShadowSize } from "@instruments/materia-ui/tokens/shadows";
+import type { ReactNode } from "react";
+export interface BorderBeamProps {
+    /** Drives fade in/out of the beam */
+    visible?: boolean | undefined;
+    /** Multiplier on peak alpha (0–1) */
+    strength?: number | undefined;
+    /** Beam peak colour (any CSS colour). Defaults to the theme foreground so
+     * the sweep reads on light and dark surfaces alike - pass a hue to tint it,
+     * e.g. a detected colour inviting interaction. */
+    color?: string | undefined;
+    /** Full rotation period in seconds */
+    duration?: number | undefined;
+    /** Ring border-radius (defaults to fully round) */
+    radius?: number | string | undefined;
+    /** Ring stroke thickness in px */
+    thickness?: number | undefined;
+    /** Drop-shadow token applied to the ring, or `"none"` to disable */
+    shadowSize?: DropShadowSize | "none" | undefined;
+    /** Positional overrides forwarded to the ring */
+    className?: string | undefined;
+    /**
+     * When provided, the beam wraps `children` in a relative container.
+     * When omitted, the beam assumes the nearest ancestor is already `position: relative`.
+     */
+    children?: ReactNode | undefined;
+}
+/**
+ * A soft rotating "border beam" shimmer used to draw attention to an element
+ * before the user interacts with it.
+ *
+ * Two usage shapes:
+ *   1. Wrapper - pass `children` and the beam wraps them in a relative box.
+ *   2. Overlay - render without children inside an existing relative parent.
+ *
+ * Honours `prefers-reduced-motion` (renders nothing - a static ring would be
+ * louder than the animated sweep it's meant to replace). When `visible` flips
+ * to `false`, the beam fades out then unmounts so its rAF loop stops.
+ *
+ * @bestPractice Animate the `--border-beam-angle` custom property (as the source does), never `rotate` the masked ring - a rotated box swings its mask outside a wide pill's bounds and renders as a stray streak, not a border orbit.
+ * @bestPractice Requires `ReducedMotionProvider`; under reduced motion it renders nothing (a static ring would read louder than the sweep it replaces), so don't add your own fallback border.
+ * @bestPractice Use it as an attention / "try me" cue on an idle surface, not a loading state - content placeholders want `Skeleton`, and a periodic liveness flick wants `Shine`.
+ * @category motion
+ */
+export declare const BorderBeam: ({ visible, strength, color, duration, radius, thickness, shadowSize, className, children, }: BorderBeamProps) => import("react").JSX.Element;

package/dist/components/border-beam/border-beam-root.js

@@ -0,0 +1,77 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { FadeOverlay } from "@instruments/materia-ui/components/fade-overlay";
+import { easings } from "@instruments/materia-ui/tokens/motion";
+import { dropShadows } from "@instruments/materia-ui/tokens/shadows";
+import { cn } from "@instruments/materia-ui/utils/cn";
+import * as m from "motion/react-m";
+import { useMemo } from "react";
+import { isNumber } from "../../utils/type-guards.js";
+/** Jo's original flat-topped profile: full peak across a 70° arc with 35°
+ * ramps either side (~140° visible). A narrower graded "comet" was tried and
+ * reverted - at a 1.5px stroke it read as invisible, not subtle.
+ * The untinted beam mixes from the theme foreground token, not white: the
+ * ring straddles the wrapped element's own edge, so a hardcoded white glint
+ * vanished on any light surface (and a dark one would vanish on dark). */
+const buildConicGradient = (strength, color) => {
+    const alpha = Math.max(0, Math.min(1, 0.95 * strength));
+    const peakColor = color !== undefined && color !== "" ? color : "var(--color-foreground)";
+    const peak = `color-mix(in srgb, ${peakColor} ${Math.round(alpha * 100)}%, transparent)`;
+    return [
+        "conic-gradient(",
+        "from var(--border-beam-angle, 0deg),",
+        "transparent 0deg,",
+        "transparent 110deg,",
+        `${peak} 145deg,`,
+        `${peak} 215deg,`,
+        "transparent 250deg,",
+        "transparent 360deg",
+        ")",
+    ].join(" ");
+};
+const BorderBeamRing = ({ strength, color, duration, radius, thickness, filterShadow, className, }) => {
+    const gradient = buildConicGradient(strength, color);
+    const innerStyle = useMemo(() => ({
+        WebkitMask: "linear-gradient(#fff 0 0) content-box, linear-gradient(#fff 0 0)",
+        WebkitMaskComposite: "xor",
+        background: gradient,
+        borderRadius: radius,
+        filter: filterShadow,
+        mask: "linear-gradient(#fff 0 0) content-box, linear-gradient(#fff 0 0)",
+        maskComposite: "exclude",
+        padding: thickness,
+    }), [gradient, radius, filterShadow, thickness]);
+    return (_jsx(m.div, { animate: { opacity: [0.7, 1, 0.7] }, "aria-hidden": true, className: cn("pointer-events-none absolute inset-0", className), "data-slot": "border-beam", style: {
+            borderRadius: radius,
+            clipPath: `inset(0 round ${isNumber(radius) ? `${radius}px` : radius})`,
+        }, transition: {
+            duration: duration * 1.5,
+            ease: easings.inOut,
+            repeat: Number.POSITIVE_INFINITY,
+        }, children: _jsx(m.div, { animate: { "--border-beam-angle": ["0deg", "360deg"] }, className: "absolute inset-0", style: innerStyle, transition: {
+                duration,
+                ease: "linear",
+                repeat: Number.POSITIVE_INFINITY,
+            } }) }));
+};
+/**
+ * A soft rotating "border beam" shimmer used to draw attention to an element
+ * before the user interacts with it.
+ *
+ * Two usage shapes:
+ *   1. Wrapper - pass `children` and the beam wraps them in a relative box.
+ *   2. Overlay - render without children inside an existing relative parent.
+ *
+ * Honours `prefers-reduced-motion` (renders nothing - a static ring would be
+ * louder than the animated sweep it's meant to replace). When `visible` flips
+ * to `false`, the beam fades out then unmounts so its rAF loop stops.
+ *
+ * @bestPractice Animate the `--border-beam-angle` custom property (as the source does), never `rotate` the masked ring - a rotated box swings its mask outside a wide pill's bounds and renders as a stray streak, not a border orbit.
+ * @bestPractice Requires `ReducedMotionProvider`; under reduced motion it renders nothing (a static ring would read louder than the sweep it replaces), so don't add your own fallback border.
+ * @bestPractice Use it as an attention / "try me" cue on an idle surface, not a loading state - content placeholders want `Skeleton`, and a periodic liveness flick wants `Shine`.
+ * @category motion
+ */
+export const BorderBeam = ({ visible = true, strength = 0.25, color, duration = 4, radius = 9999, thickness = 1.5, shadowSize = "sm", className, children, }) => {
+    const filterShadow = shadowSize === "none" ? "none" : dropShadows[shadowSize];
+    return (_jsx(FadeOverlay, { className: className, overlay: _jsx(BorderBeamRing, { color: color, duration: duration, filterShadow: filterShadow, radius: radius, strength: strength, thickness: thickness }), radius: radius, visible: visible, children: children }));
+};

package/dist/components/border-beam.d.ts

@@ -0,0 +1,2 @@
+export type { BorderBeamProps } from "./border-beam/border-beam-root.js";
+export { BorderBeam } from "./border-beam/border-beam-root.js";

package/dist/components/border-beam.js

@@ -0,0 +1 @@
+export { BorderBeam } from "./border-beam/border-beam-root.js";

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

@@ -0,0 +1,30 @@
+import { useRender } from "@base-ui/react/use-render";
+import type { LayoutElement, LayoutHostAttributes, LayoutHostKey } from "../../tokens/element.js";
+export interface BoxProps extends Omit<useRender.ComponentProps<"div">, LayoutHostKey>, LayoutHostAttributes {
+    /**
+     * Render as a different host element from the closed layout vocabulary
+     * ({@link LayoutElement}). The set is deliberately closed: `as="button"` is a
+     * type error, because the design-system answer is the Button component. Event handlers
+     * and the ref accept any host element.
+     *
+     * `as` and `render` are mutually exclusive; if both are passed, `render`
+     * wins (a dev-only warning fires).
+     * @example <Box as="span" />
+     */
+    as?: LayoutElement;
+}
+/**
+ * The escape hatch: a raw host element with a `className`, still checked for
+ * tokens-only classes. Box renders the chosen {@link LayoutElement} with no
+ * layout opinions of its own (no margin, width, or padding, unlike Container),
+ * so it suits decorative wrappers that a styled primitive would visually break. Reach for it only when no styled primitive fits; the
+ * `className` you pass is governed by the same tokens-only scan as everything
+ * else. RSC-safe.
+ *
+ * @bestPractice `Box` renders the chosen element with no layout opinions (no margin/width/padding, unlike `Container`); use it as a neutral wrapper when a styled primitive would interfere.
+ * @bestPractice Use `as="span"` for a decorative inline wrapper; reach for `Box` only when no styled primitive fits - its `className` is still checked for tokens-only classes.
+ * @bestPractice `as` and `render` are mutually exclusive (`render` wins, dev-warned); `as` draws from the closed layout vocabulary.
+ * @bestPractice Use `as` to change the element (a tag); use `render` only to swap in a component (e.g. a router Link). Never `render={<Box as=…/>}` - pass `as` directly.
+ * @category layout
+ */
+export declare const Box: ({ as, className, ref, render, ...props }: BoxProps) => import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>>;

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

@@ -0,0 +1,33 @@
+import { useRender } from "@base-ui/react/use-render";
+import { cn } from "@instruments/materia-ui/utils/cn";
+import { reportDevIssue } from "../../utils/dev-issue.js";
+/**
+ * The escape hatch: a raw host element with a `className`, still checked for
+ * tokens-only classes. Box renders the chosen {@link LayoutElement} with no
+ * layout opinions of its own (no margin, width, or padding, unlike Container),
+ * so it suits decorative wrappers that a styled primitive would visually break. Reach for it only when no styled primitive fits; the
+ * `className` you pass is governed by the same tokens-only scan as everything
+ * else. RSC-safe.
+ *
+ * @bestPractice `Box` renders the chosen element with no layout opinions (no margin/width/padding, unlike `Container`); use it as a neutral wrapper when a styled primitive would interfere.
+ * @bestPractice Use `as="span"` for a decorative inline wrapper; reach for `Box` only when no styled primitive fits - its `className` is still checked for tokens-only classes.
+ * @bestPractice `as` and `render` are mutually exclusive (`render` wins, dev-warned); `as` draws from the closed layout vocabulary.
+ * @bestPractice Use `as` to change the element (a tag); use `render` only to swap in a component (e.g. a router Link). Never `render={<Box as=…/>}` - pass `as` directly.
+ * @category layout
+ */
+export const Box = ({ as, className, ref, render, ...props }) => {
+    if (render !== undefined && as !== undefined) {
+        reportDevIssue("Box: `as` and `render` are mutually exclusive; `render` wins and `as` is ignored.");
+    }
+    return useRender({
+        defaultTagName: as ?? "div",
+        props: {
+            className: cn(className),
+            "data-component": "box",
+            "data-slot": "box",
+            ...props,
+        },
+        ref,
+        render,
+    });
+};

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

@@ -0,0 +1,39 @@
+/**
+ * Type-level surface guards for Box's closed `as` vocabulary (plan M1b).
+ *
+ * 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.
+ *
+ * The experiment's load-bearing invariant is the CLOSED SET: `as` draws from
+ * {@link LayoutElement} only, so `as="button"` is a type error (the DS answer is
+ * the Button component), not a silent escape hatch. If the union ever widens to
+ * `string`, the rejection guards below stop satisfying `extends true` and the
+ * typecheck fails.
+ */
+import type { ComponentProps, ReactElement } from "react";
+import type { Box } from "./box-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 Box props. */
+type Accepts<V> = V extends ComponentProps<typeof Box> ? true : false;
+export type NavAccepted = Expect<Accepts<{
+    as: "nav";
+}>>;
+export type SpanAccepted = Expect<Accepts<{
+    as: "span";
+}>>;
+export type ButtonRejected = Expect<Not<Accepts<{
+    as: "button";
+}>>>;
+export type AnchorRejected = Expect<Not<Accepts<{
+    as: "a";
+}>>>;
+export type InputRejected = Expect<Not<Accepts<{
+    as: "input";
+}>>>;
+export type RenderAccepted = Expect<Accepts<{
+    render: ReactElement;
+}>>;
+export {};

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

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

package/dist/components/box.d.ts

@@ -0,0 +1 @@
+export { Box, type BoxProps } from "./box/box-root.js";

package/dist/components/box.js

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

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

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

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

@@ -0,0 +1,46 @@
+import { defineAnatomy } from "../../tokens/anatomy.js";
+/**
+ * breadcrumbAnatomy helper for BreadcrumbAnatomy.
+ * Import from "@instruments/materia-ui/components/breadcrumb-anatomy".
+ */
+export const breadcrumbAnatomy = defineAnatomy({
+    children: [
+        {
+            children: [
+                {
+                    children: [
+                        {
+                            description: "Clickable link",
+                            label: "BreadcrumbLink",
+                            slot: "breadcrumb-link",
+                        },
+                        {
+                            description: "Current page (non-link)",
+                            label: "BreadcrumbCurrent",
+                            slot: "breadcrumb-page",
+                        },
+                    ],
+                    description: "Single breadcrumb entry",
+                    label: "BreadcrumbItem",
+                    slot: "breadcrumb-item",
+                },
+                {
+                    description: "Visual divider",
+                    label: "BreadcrumbSeparator",
+                    slot: "breadcrumb-separator",
+                },
+                {
+                    description: "Collapsed items indicator",
+                    label: "BreadcrumbEllipsis",
+                    slot: "breadcrumb-ellipsis",
+                },
+            ],
+            description: "Container for breadcrumb items",
+            label: "BreadcrumbList",
+            slot: "breadcrumb-list",
+        },
+    ],
+    description: "Navigation showing current location in hierarchy",
+    label: "Breadcrumb",
+    slot: "breadcrumb",
+});

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

@@ -0,0 +1,38 @@
+import { useRender } from "@base-ui/react/use-render";
+import type * as React from "react";
+/**
+ * Navigation landmark for a breadcrumb trail; renders a labelled `<nav>`.
+ *
+ * @bestPractice When the trail sits directly above the page heading, stop at the last navigable ancestor and let the heading name the current page. Use `BreadcrumbCurrent` only when no adjacent heading supplies that context.
+ * @bestPractice Render router links via `<BreadcrumbLink render={<Link href="…" />}>` with a framework `<Link>` - the bare default is an `<a>`.
+ * @bestPractice Collapse overflow with `BreadcrumbEllipsis` hosting a menu of the hidden crumbs, rather than dropping items silently.
+ * @category navigation
+ */
+declare const Breadcrumb: ({ ...props }: React.ComponentProps<"nav"> & {
+    separator?: React.ReactNode;
+}) => React.JSX.Element;
+/**
+ * Ordered list of crumbs; the first and last items render in the foreground colour.
+ */
+declare const BreadcrumbList: ({ className, ...props }: React.ComponentProps<"ol">) => React.JSX.Element;
+/**
+ * Wraps a single crumb - a link, the current page, or a collapsed-menu trigger.
+ */
+declare const BreadcrumbItem: ({ className, ...props }: React.ComponentProps<"li">) => React.JSX.Element;
+/**
+ * A navigable ancestor crumb; pass `render` to render through a router `Link`.
+ */
+declare const BreadcrumbLink: ({ className, ref, render, ...props }: useRender.ComponentProps<"a">) => React.ReactElement<unknown, string | React.JSXElementConstructor<any>>;
+/**
+ * The terminal, non-interactive current page; marked `aria-current="page"`.
+ */
+declare const BreadcrumbCurrent: ({ className, ...props }: React.ComponentProps<"span">) => React.JSX.Element;
+/**
+ * Divider between crumbs; aria-hidden, and defaults to a chevron when no children are given.
+ */
+declare const BreadcrumbSeparator: ({ children, className, ...props }: React.ComponentProps<"li">) => React.JSX.Element;
+/**
+ * Placeholder for collapsed crumbs; typically wraps a menu trigger revealing the hidden path.
+ */
+declare const BreadcrumbEllipsis: ({ className, ...props }: React.ComponentProps<"span">) => React.JSX.Element;
+export { Breadcrumb, BreadcrumbCurrent, BreadcrumbEllipsis, BreadcrumbItem, BreadcrumbLink, BreadcrumbList, BreadcrumbSeparator, };

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

@@ -0,0 +1,51 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useRender } from "@base-ui/react/use-render";
+import { cn } from "@instruments/materia-ui/utils/cn";
+import { ChevronRight, MoreHorizontal } from "lucide-react";
+import { Center } from "../center.js";
+import { Flex } from "../flex.js";
+import { Icon } from "../icon.js";
+import { VisuallyHidden } from "../visually-hidden.js";
+/**
+ * Navigation landmark for a breadcrumb trail; renders a labelled `<nav>`.
+ *
+ * @bestPractice When the trail sits directly above the page heading, stop at the last navigable ancestor and let the heading name the current page. Use `BreadcrumbCurrent` only when no adjacent heading supplies that context.
+ * @bestPractice Render router links via `<BreadcrumbLink render={<Link href="…" />}>` with a framework `<Link>` - the bare default is an `<a>`.
+ * @bestPractice Collapse overflow with `BreadcrumbEllipsis` hosting a menu of the hidden crumbs, rather than dropping items silently.
+ * @category navigation
+ */
+const Breadcrumb = ({ ...props }) => _jsx("nav", { "aria-label": "breadcrumb", "data-slot": "breadcrumb", ...props });
+/**
+ * Ordered list of crumbs; the first and last items render in the foreground colour.
+ */
+const BreadcrumbList = ({ className, ...props }) => (_jsx(Flex, { align: "center", as: "ol", className: cn("text-muted-foreground text-paragraph-sm gap-1.5 wrap-break-word", '[&>li[data-slot="breadcrumb-item"]:first-of-type]:text-foreground [&>li[data-slot="breadcrumb-item"]:last-of-type]:text-foreground', className), "data-slot": "breadcrumb-list", wrap: "wrap", ...props }));
+/**
+ * Wraps a single crumb - a link, the current page, or a collapsed-menu trigger.
+ */
+const BreadcrumbItem = ({ className, ...props }) => (_jsx(Flex, { align: "center", as: "li", className: cn("gap-1.5", className), "data-slot": "breadcrumb-item", inline: true, ...props }));
+/**
+ * A navigable ancestor crumb; pass `render` to render through a router `Link`.
+ */
+const BreadcrumbLink = ({ className, ref, render, ...props }) => useRender({
+    defaultTagName: "a",
+    props: {
+        className: cn("hover:text-foreground transition-colors", className),
+        "data-slot": "breadcrumb-link",
+        ...props,
+    },
+    ref,
+    render,
+});
+/**
+ * The terminal, non-interactive current page; marked `aria-current="page"`.
+ */
+const BreadcrumbCurrent = ({ className, ...props }) => (_jsx("span", { "aria-current": "page", className: cn("text-foreground font-normal", className), "data-slot": "breadcrumb-page", ...props }));
+/**
+ * Divider between crumbs; aria-hidden, and defaults to a chevron when no children are given.
+ */
+const BreadcrumbSeparator = ({ children, className, ...props }) => (_jsx("li", { "aria-hidden": "true", className: cn("[&>svg]:size-3", className), "data-slot": "breadcrumb-separator", role: "presentation", ...props, children: children ?? (_jsx(Icon, { className: "rtl:rotate-180", icon: ChevronRight, size: "2xs" })) }));
+/**
+ * Placeholder for collapsed crumbs; typically wraps a menu trigger revealing the hidden path.
+ */
+const BreadcrumbEllipsis = ({ className, ...props }) => (_jsxs(Center, { "aria-hidden": "true", as: "span", className: cn("size-9", className), "data-slot": "breadcrumb-ellipsis", role: "presentation", ...props, children: [_jsx(Icon, { icon: MoreHorizontal, size: "xs" }), _jsx(VisuallyHidden, { children: "More" })] }));
+export { Breadcrumb, BreadcrumbCurrent, BreadcrumbEllipsis, BreadcrumbItem, BreadcrumbLink, BreadcrumbList, BreadcrumbSeparator, };

package/dist/components/breadcrumb.d.ts

@@ -0,0 +1,2 @@
+export { breadcrumbAnatomy } from "./breadcrumb/breadcrumb-anatomy.js";
+export { Breadcrumb, BreadcrumbCurrent, BreadcrumbEllipsis, BreadcrumbItem, BreadcrumbLink, BreadcrumbList, BreadcrumbSeparator, } from "./breadcrumb/breadcrumb-root.js";

package/dist/components/breadcrumb.js

@@ -0,0 +1,2 @@
+export { breadcrumbAnatomy } from "./breadcrumb/breadcrumb-anatomy.js";
+export { Breadcrumb, BreadcrumbCurrent, BreadcrumbEllipsis, BreadcrumbItem, BreadcrumbLink, BreadcrumbList, BreadcrumbSeparator, } from "./breadcrumb/breadcrumb-root.js";

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

@@ -0,0 +1,32 @@
+import type { ReactNode } from "react";
+import type { ComponentSize } from "../../tokens/size.js";
+import type { ButtonIcon } from "./button-helpers.js";
+interface ButtonContentProps {
+    children: ReactNode;
+    /** When true, render the collapsing label track (icon → label on hover). */
+    expandable: boolean;
+    /** Negative-margin class that cancels the size gap while collapsed. */
+    expandableCollapsedMargin: string;
+    dot: string | undefined;
+    dotPlacement: "start" | "end";
+    dotSize: ComponentSize;
+    hasChildren: boolean;
+    icon: ButtonIcon;
+    iconChanged: boolean;
+    iconClassName: string | undefined;
+    iconKey: string;
+    iconSize: ComponentSize;
+    isIconButton: boolean | ButtonIcon;
+    loading: boolean;
+    loadingLabel: string | undefined;
+    spinnerSize: ComponentSize;
+    suffixIcon: ButtonIcon;
+    suffixIconChanged: boolean;
+    suffixIconClassName: string | undefined;
+    suffixIconKey: string;
+}
+/**
+ * Compose the button's inner content across loading / icon variants.
+ */
+declare const renderButtonContent: (p: ButtonContentProps) => ReactNode;
+export { renderButtonContent };