@instruments/materia-ui 0.1.0

package/dist/components/search-input/search-input-root.js

@@ -0,0 +1,87 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { cn } from "@instruments/materia-ui/utils/cn";
+import { Search, X } from "lucide-react";
+import { useControllableState } from "../../hooks/use-controllable-state.js";
+import { resolveResponsiveBase } from "../../tokens/responsive.js";
+import { Flex } from "../flex.js";
+import { InputGroupButton } from "../input-group/input-group-button.js";
+import { InputGroupIcon } from "../input-group/input-group-icon.js";
+import { InputGroupInput } from "../input-group/input-group-input.js";
+import { InputGroup } from "../input-group/input-group-root.js";
+import { Kbd } from "../kbd/kbd-root.js";
+import { SearchInputSuggestions } from "./search-input-suggestions.js";
+/** Overlay suggestion text sized to match InputGroupInput at each size. */
+const SUGGESTION_TEXT_CLASSES = {
+    "2xl": "text-paragraph",
+    "2xs": "text-caption",
+    "3xl": "text-paragraph",
+    base: "text-paragraph-sm",
+    lg: "text-paragraph-sm",
+    sm: "text-paragraph-sm",
+    xl: "text-paragraph-sm",
+    xs: "text-caption",
+};
+/** Trailing control: the shortcut hint while empty, the clear button once filled. */
+const SearchInputTrailing = ({ isEmpty, onClear, shortcutHint, size, }) => {
+    if (!isEmpty) {
+        return (_jsx(InputGroupButton, { "aria-label": "Clear search", "data-slot": "search-input-clear", icon: X, onClick: onClear, type: "button" }));
+    }
+    if (shortcutHint === undefined || shortcutHint.length === 0) {
+        return null;
+    }
+    return (_jsx(Kbd, { "data-slot": "search-input-shortcut", size: size, children: shortcutHint }));
+};
+/**
+ * Search input over InputGroup: a search icon, a built-in clear button that
+ * appears once the field has a value, and an optional keyboard-shortcut hint
+ * shown while it's empty. Pass `suggestions` for an animated "Try: …"
+ * placeholder that cycles while the field is empty.
+ * Import from "@instruments/materia-ui/components/search-input".
+ *
+ * @example
+ * ```tsx
+ * <SearchInput
+ *   onChange={setQuery}
+ *   placeholder="Search products..."
+ *   shortcutHint="⌘K"
+ *   value={query}
+ * />
+ * ```
+ *
+ * @example Animated suggestions
+ * ```tsx
+ * <SearchInput
+ *   onChange={setQuery}
+ *   suggestions={["white dove", "alabaster", "naval"]}
+ *   value={query}
+ * />
+ * ```
+ *
+ * @bestPractice Use `SearchInput` for search/filter fields - it supplies the search icon, a clear button, and (via `shortcutHint`) a `Kbd` hint; don't rebuild these on a plain `Input`.
+ * @bestPractice `onChange` receives the next string on every keystroke and on clear (not a DOM event) - pass `value` for controlled use or `defaultValue` for uncontrolled.
+ * @bestPractice Pass cycling placeholder ideas via `suggestions` (which suppresses the static `placeholder`); `shortcutHint` shows only while empty and is swapped for the clear button once the field has a value.
+ * @bestPractice Pill (`radius="full"`) at the 48px `xl` default is the search signature - so leave both defaults alone in standard search/filter placements; pass `size` explicitly for compact embedded contexts (popovers, table headers).
+ * @category forms
+ */
+export const SearchInput = ({ className, size = "xl", radius = "full", hasError = false, disabled = false, value, defaultValue = "", onChange, onClear, shortcutHint, placeholder, suggestions, suggestionPrefix = "Try:", suggestionIntervalMs = 5000, testId, ...props }) => {
+    // Single-token size for children that don't accept a responsive object
+    // (Kbd + the suggestion-text class lookup). The InputGroup itself receives
+    // the full responsive `size` and layers its own `md:*` overrides.
+    const baseSize = resolveResponsiveBase(size, "base");
+    const [currentValue, setValue] = useControllableState({
+        defaultValue,
+        onChange,
+        value,
+    });
+    const isEmpty = currentValue.length === 0;
+    const showSuggestions = isEmpty && suggestions !== undefined && suggestions.length > 0;
+    const handleChange = (event) => {
+        setValue(event.target.value);
+    };
+    const handleClear = () => {
+        setValue("");
+        onClear?.();
+    };
+    return (_jsxs(InputGroup, { className: className, disabled: disabled, hasError: hasError, radius: radius, size: size, children: [_jsx(InputGroupIcon, { icon: Search }), _jsxs(Flex, { align: "center", className: "relative min-w-0 flex-1 self-stretch", children: [_jsx(InputGroupInput, { className: cn("[&::-webkit-search-cancel-button]:appearance-none"), "data-slot": "search-input-control", onChange: handleChange, placeholder: showSuggestions ? " " : placeholder, ...(testId === undefined ? {} : { testId }), type: "search", value: currentValue, ...props }), showSuggestions && suggestions !== undefined ? (_jsx(SearchInputSuggestions, { className: SUGGESTION_TEXT_CLASSES[baseSize], intervalMs: suggestionIntervalMs, prefix: suggestionPrefix, suggestions: suggestions, visible: showSuggestions })) : null] }), _jsx(SearchInputTrailing, { isEmpty: isEmpty, onClear: handleClear, shortcutHint: shortcutHint, size: baseSize })] }));
+};

package/dist/components/search-input/search-input-suggestions.d.ts

@@ -0,0 +1,17 @@
+interface SearchInputSuggestionsProps {
+    suggestions: readonly string[];
+    /** Cycling is paused (and the overlay hidden) while false. */
+    visible: boolean;
+    prefix: string;
+    intervalMs: number;
+    className: string;
+}
+/**
+ * Internal overlay for SearchInput: a static prefix plus a cycling suggestion
+ * that crossfades in place. `mode="popLayout"` keeps the outgoing word in the
+ * DOM (out of flow) while the next fades in, so the prefix is never left
+ * stranded alone - and the motion is a calm opacity crossfade with a hair of
+ * vertical drift, not a blurred conveyor. Honours prefers-reduced-motion.
+ */
+export declare const SearchInputSuggestions: ({ suggestions, visible, prefix, intervalMs, className, }: SearchInputSuggestionsProps) => import("react").JSX.Element | null;
+export {};

package/dist/components/search-input/search-input-suggestions.js

@@ -0,0 +1,49 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { durations } from "@instruments/materia-ui/tokens/motion";
+import { cn } from "@instruments/materia-ui/utils/cn";
+import { AnimatePresence, useReducedMotion } from "motion/react";
+import * as m from "motion/react-m";
+import { useEffect, useRef, useState } from "react";
+import { Flex } from "../flex.js";
+import { Grid } from "../grid.js";
+/** Cycle an index through `[0, length)` on an interval, paused while hidden. */
+const useCyclingIndex = (length, isPaused, intervalMs) => {
+    const [index, setIndex] = useState(0);
+    const timeoutRef = useRef(null);
+    useEffect(() => {
+        if (!isPaused && length > 1) {
+            const cycle = () => {
+                setIndex((prev) => (prev + 1) % length);
+                timeoutRef.current = setTimeout(cycle, intervalMs);
+            };
+            timeoutRef.current = setTimeout(cycle, intervalMs);
+        }
+        return () => {
+            if (timeoutRef.current !== null) {
+                clearTimeout(timeoutRef.current);
+            }
+        };
+    }, [isPaused, length, intervalMs]);
+    return length === 0 ? 0 : index % length;
+};
+/**
+ * Internal overlay for SearchInput: a static prefix plus a cycling suggestion
+ * that crossfades in place. `mode="popLayout"` keeps the outgoing word in the
+ * DOM (out of flow) while the next fades in, so the prefix is never left
+ * stranded alone - and the motion is a calm opacity crossfade with a hair of
+ * vertical drift, not a blurred conveyor. Honours prefers-reduced-motion.
+ */
+export const SearchInputSuggestions = ({ suggestions, visible, prefix, intervalMs, className, }) => {
+    const prefersReducedMotion = useReducedMotion();
+    const index = useCyclingIndex(suggestions.length, !visible, intervalMs);
+    const suggestion = suggestions[index] ?? suggestions[0];
+    if (!visible || suggestion === undefined || suggestion === "") {
+        return null;
+    }
+    return (_jsxs(Flex, { align: "center", "aria-hidden": true, className: cn("text-muted-foreground pointer-events-none absolute inset-y-0 left-0 whitespace-nowrap", className), children: [prefix ? _jsxs("span", { children: [prefix, "\u00A0"] }) : null, _jsx(Grid, { as: "span", columns: "none", gap: "none", inline: true, children: _jsx(AnimatePresence, { initial: false, children: _jsx(m.span, { animate: { opacity: 1 }, className: "col-start-1 row-start-1", exit: { opacity: 0 }, initial: { opacity: 0 }, transition: {
+                            duration: prefersReducedMotion === true
+                                ? durations.quick
+                                : durations.normal,
+                        }, children: suggestion }, suggestion) }) })] }));
+};

package/dist/components/search-input.d.ts

@@ -0,0 +1,2 @@
+export type { SearchInputProps } from "./search-input/search-input-root.js";
+export { SearchInput } from "./search-input/search-input-root.js";

package/dist/components/search-input.js

@@ -0,0 +1 @@
+export { SearchInput } from "./search-input/search-input-root.js";

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

@@ -0,0 +1,47 @@
+import { useRender } from "@base-ui/react/use-render";
+import type { LayoutElement, LayoutHostAttributes, LayoutHostKey } from "../../tokens/element.js";
+import type { ResponsiveMode, LayoutResponsiveValue } from "../../tokens/responsive.js";
+import type { SectionSpace } from "../../tokens/responsive-classes.js";
+import type { ComponentSize } from "../../tokens/size.js";
+export interface SectionProps 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 <Section as="section" />
+     */
+    as?: LayoutElement;
+    /**
+     * Horizontal gutter. Defaults to `"gutter"` - the single app-wide
+     * `--page-gutter` (16px, 24px from `sm`). Pass `"none"` for no gutter (e.g. a
+     * full-bleed band whose gutter is owned by the app shell), or a
+     * `ComponentSize` for an explicit non-standard px.
+     */
+    inset?: LayoutResponsiveValue<ComponentSize> | "none" | "gutter";
+    /** Responsive mode: `"screen"` (viewport) or `"container"` (container queries). */
+    responsiveMode?: ResponsiveMode;
+    /** Vertical rhythm (py). Responsive; defaults to `base` (py-6). */
+    space?: LayoutResponsiveValue<SectionSpace>;
+}
+/**
+ * Section is a full-width vertical-rhythm band. Unlike `Container` it does not
+ * constrain width - use it for full-bleed padded regions, and nest a
+ * `Container` inside when the content should also be centred. RSC-safe.
+ *
+ * Import from "@instruments/materia-ui/components/section".
+ *
+ * @example
+ * ```tsx
+ * <Section>{children}</Section>
+ * // → py-6 px-page-gutter
+ * ```
+ *
+ * @bestPractice `Section` is full-width (padding only, no max-width) - nest a `Container` inside when content should also be centred; use `Container` alone when you just need the width cap.
+ * @bestPractice Tune vertical rhythm with `space` (its `py`, default `base`); `as`/`render` are mutually exclusive with `render` winning (dev-warned).
+ * @category layout
+ */
+export declare const Section: ({ as, className, ref, render, inset, responsiveMode, space, ...props }: SectionProps) => import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>>;

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

@@ -0,0 +1,48 @@
+import { useRender } from "@base-ui/react/use-render";
+import { cn } from "@instruments/materia-ui/utils/cn";
+import { pushResponsiveClasses } from "../../tokens/responsive.js";
+import { PADDING_X_CLASS, SECTION_SPACE_CLASS, } from "../../tokens/responsive-classes.js";
+import { reportDevIssue } from "../../utils/dev-issue.js";
+/**
+ * Section is a full-width vertical-rhythm band. Unlike `Container` it does not
+ * constrain width - use it for full-bleed padded regions, and nest a
+ * `Container` inside when the content should also be centred. RSC-safe.
+ *
+ * Import from "@instruments/materia-ui/components/section".
+ *
+ * @example
+ * ```tsx
+ * <Section>{children}</Section>
+ * // → py-6 px-page-gutter
+ * ```
+ *
+ * @bestPractice `Section` is full-width (padding only, no max-width) - nest a `Container` inside when content should also be centred; use `Container` alone when you just need the width cap.
+ * @bestPractice Tune vertical rhythm with `space` (its `py`, default `base`); `as`/`render` are mutually exclusive with `render` winning (dev-warned).
+ * @category layout
+ */
+export const Section = ({ as, className, ref, render, inset = "gutter", responsiveMode = "screen", space = "base", ...props }) => {
+    if (render !== undefined && as !== undefined) {
+        reportDevIssue("Section: `as` and `render` are mutually exclusive; `render` wins and `as` is ignored.");
+    }
+    const classes = [];
+    pushResponsiveClasses(classes, space, SECTION_SPACE_CLASS, responsiveMode);
+    if (inset === "gutter") {
+        // The single app-wide gutter, numerically identical to the former default
+        // `px-4 sm:px-6` but sourced from one `--page-gutter` token.
+        classes.push("px-page-gutter");
+    }
+    else if (inset !== "none") {
+        pushResponsiveClasses(classes, inset, PADDING_X_CLASS, responsiveMode);
+    }
+    return useRender({
+        defaultTagName: as ?? "div",
+        props: {
+            className: cn(classes.join(" "), className),
+            "data-component": "section",
+            "data-slot": "section",
+            ...props,
+        },
+        ref,
+        render,
+    });
+};

package/dist/components/section.d.ts

@@ -0,0 +1 @@
+export { Section, type SectionProps } from "./section/section-root.js";

package/dist/components/section.js

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

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

@@ -0,0 +1,12 @@
+/**
+ * Shared class-name token primitives for the segmented-control visual language.
+ *
+ * Consumed by SegmentedControl, Tabs, and TabNavigation so they render an
+ * identical shell, padding, gap, and active indicator at any size.
+ * Not components - these are Tailwind class strings and size→class maps.
+ *
+ * @bestPractice These are class-name strings and size→class maps, not components - apply them via `className`, never render them as JSX.
+ * @bestPractice Reuse these tokens to give a custom control the segmented "pill" shell; for actual segmented UIs prefer `SegmentedControl`; `Tabs` and `TabNavigation` consume the same tokens for panel and navigation switching.
+ * @category forms
+ */
+export { SEGMENTED_GAP, SEGMENTED_INDICATOR_ACTIVE_CLASS, SEGMENTED_INDICATOR_CLASS, SEGMENTED_SHELL_BASE, SEGMENTED_SHELL_PADDING, SEGMENTED_TRIGGER_PADDING, SEGMENTED_TRIGGER_TEXT, } from "./segmented-variants.js";

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

@@ -0,0 +1,12 @@
+/**
+ * Shared class-name token primitives for the segmented-control visual language.
+ *
+ * Consumed by SegmentedControl, Tabs, and TabNavigation so they render an
+ * identical shell, padding, gap, and active indicator at any size.
+ * Not components - these are Tailwind class strings and size→class maps.
+ *
+ * @bestPractice These are class-name strings and size→class maps, not components - apply them via `className`, never render them as JSX.
+ * @bestPractice Reuse these tokens to give a custom control the segmented "pill" shell; for actual segmented UIs prefer `SegmentedControl`; `Tabs` and `TabNavigation` consume the same tokens for panel and navigation switching.
+ * @category forms
+ */
+export { SEGMENTED_GAP, SEGMENTED_INDICATOR_ACTIVE_CLASS, SEGMENTED_INDICATOR_CLASS, SEGMENTED_SHELL_BASE, SEGMENTED_SHELL_PADDING, SEGMENTED_TRIGGER_PADDING, SEGMENTED_TRIGGER_TEXT, } from "./segmented-variants.js";

package/dist/components/segmented/segmented-variants.d.ts

@@ -0,0 +1,39 @@
+import type { ComponentSize } from "../../tokens/size.js";
+/**
+ * Shared shell classes for segmented controls (Tabs default, ToggleGroup pill).
+ *
+ * Uses the `surface-inset` semantic token so the shell adapts to any parent
+ * surface via alpha blending - the token handles the light/dark swap in CSS,
+ * so no `dark:` variants are needed at the call site.
+ */
+export declare const SEGMENTED_SHELL_BASE = "rounded-full bg-surface-inset text-muted-foreground";
+/** Shared shell padding scale by size. */
+export declare const SEGMENTED_SHELL_PADDING: Record<ComponentSize, string>;
+/**
+ * Shared trigger/item text-size scale by size. `SegmentedControl` items,
+ * `TabsTrigger` and `TabNavigationLink` all read it, so they render identical
+ * type at a given size. Layer per-breakpoint `md:text-*` overrides on top via
+ * `getResponsiveSizeOverrides`.
+ */
+export declare const SEGMENTED_TRIGGER_TEXT: Record<ComponentSize, string>;
+/**
+ * Trigger icon size by trigger size: one step below the label so the icon sits
+ * slightly smaller than the text. Shared by TabsTrigger and TabNavigationLink.
+ */
+export declare const SEGMENTED_ICON_SIZE: Record<ComponentSize, ComponentSize>;
+/** Trigger dot size by trigger size. Dots track the icon ramp. */
+export declare const SEGMENTED_DOT_SIZE: Record<ComponentSize, ComponentSize>;
+/** Shared trigger/item padding scale by size. */
+export declare const SEGMENTED_TRIGGER_PADDING: Record<ComponentSize, string>;
+/** Shared inner gap scale by size (space between triggers inside the shell). */
+export declare const SEGMENTED_GAP: Record<ComponentSize, string>;
+/**
+ * Shared active indicator visual treatment.
+ *
+ * Uses `surface-raised` + `border-subtle` so the active pill stands out from
+ * the inset shell in both themes without `dark:` variants - the tokens encode
+ * "raised solid surface in light, translucent lift in dark".
+ */
+export declare const SEGMENTED_INDICATOR_CLASS = "border border-border-subtle bg-surface-raised shadow-xs";
+/** Shared active indicator utility for Base UI `data-pressed` toggle selectors. */
+export declare const SEGMENTED_INDICATOR_ACTIVE_CLASS = "data-pressed:border-border-subtle data-pressed:bg-surface-raised data-pressed:shadow-xs";

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

@@ -0,0 +1,83 @@
+/**
+ * Shared shell classes for segmented controls (Tabs default, ToggleGroup pill).
+ *
+ * Uses the `surface-inset` semantic token so the shell adapts to any parent
+ * surface via alpha blending - the token handles the light/dark swap in CSS,
+ * so no `dark:` variants are needed at the call site.
+ */
+export const SEGMENTED_SHELL_BASE = "rounded-full bg-surface-inset text-muted-foreground";
+/** Shared shell padding scale by size. */
+export const SEGMENTED_SHELL_PADDING = {
+    "2xl": "p-1.5",
+    "2xs": "p-0.5",
+    "3xl": "p-1.5",
+    base: "p-0.5",
+    lg: "p-1",
+    sm: "p-0.5",
+    xl: "p-1",
+    xs: "p-0.5",
+};
+/**
+ * Shared trigger/item text-size scale by size. `SegmentedControl` items,
+ * `TabsTrigger` and `TabNavigationLink` all read it, so they render identical
+ * type at a given size. Layer per-breakpoint `md:text-*` overrides on top via
+ * `getResponsiveSizeOverrides`.
+ */
+export const SEGMENTED_TRIGGER_TEXT = {
+    "2xl": "text-paragraph-sm",
+    "2xs": "text-2xs",
+    "3xl": "text-paragraph-sm",
+    base: "text-paragraph-sm",
+    lg: "text-paragraph-sm",
+    sm: "text-paragraph-sm",
+    xl: "text-paragraph-sm",
+    xs: "text-caption",
+};
+/**
+ * Trigger icon size by trigger size: one step below the label so the icon sits
+ * slightly smaller than the text. Shared by TabsTrigger and TabNavigationLink.
+ */
+export const SEGMENTED_ICON_SIZE = {
+    "2xl": "base",
+    "2xs": "2xs",
+    "3xl": "lg",
+    base: "xs",
+    lg: "sm",
+    sm: "xs",
+    xl: "sm",
+    xs: "2xs",
+};
+/** Trigger dot size by trigger size. Dots track the icon ramp. */
+export const SEGMENTED_DOT_SIZE = SEGMENTED_ICON_SIZE;
+/** Shared trigger/item padding scale by size. */
+export const SEGMENTED_TRIGGER_PADDING = {
+    "2xl": "px-7 py-4",
+    "2xs": "px-2 py-1",
+    "3xl": "px-8 py-5",
+    base: "px-3.5 py-2.5",
+    lg: "px-5 py-3",
+    sm: "px-3 py-2",
+    xl: "px-6 py-3.5",
+    xs: "px-2.5 py-1.5",
+};
+/** Shared inner gap scale by size (space between triggers inside the shell). */
+export const SEGMENTED_GAP = {
+    "2xl": "gap-1.5",
+    "2xs": "gap-0.5",
+    "3xl": "gap-2",
+    base: "gap-1",
+    lg: "gap-1",
+    sm: "gap-0.5",
+    xl: "gap-1.5",
+    xs: "gap-0.5",
+};
+/**
+ * Shared active indicator visual treatment.
+ *
+ * Uses `surface-raised` + `border-subtle` so the active pill stands out from
+ * the inset shell in both themes without `dark:` variants - the tokens encode
+ * "raised solid surface in light, translucent lift in dark".
+ */
+export const SEGMENTED_INDICATOR_CLASS = "border border-border-subtle bg-surface-raised shadow-xs";
+/** Shared active indicator utility for Base UI `data-pressed` toggle selectors. */
+export const SEGMENTED_INDICATOR_ACTIVE_CLASS = "data-pressed:border-border-subtle data-pressed:bg-surface-raised data-pressed:shadow-xs";

package/dist/components/segmented-control/segmented-control-anatomy.d.ts

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

package/dist/components/segmented-control/segmented-control-anatomy.js

@@ -0,0 +1,24 @@
+import { defineAnatomy } from "../../tokens/anatomy.js";
+/**
+ * segmentedControlAnatomy helper for SegmentedControl.
+ * Import from "@instruments/materia-ui/components/segmented-control".
+ */
+export const segmentedControlAnatomy = defineAnatomy({
+    children: [
+        {
+            children: [
+                {
+                    description: "Animated pill that slides to the active segment",
+                    label: "SegmentedControlIndicator",
+                    slot: "segmented-control-indicator",
+                },
+            ],
+            description: "A single selectable segment",
+            label: "SegmentedControlItem",
+            slot: "segmented-control-item",
+        },
+    ],
+    description: "Single-select mode / value switcher",
+    label: "SegmentedControl",
+    slot: "segmented-control",
+});

package/dist/components/segmented-control/segmented-control-context.d.ts

@@ -0,0 +1,22 @@
+import type { ResponsiveValue } from "../../tokens/responsive.js";
+import type { ComponentSize } from "../../tokens/size.js";
+/** Shared state passed from `SegmentedControl` down to each item. */
+export interface SegmentedControlContextValue {
+    /** The currently selected value (always non-empty - one is always selected). */
+    activeValue: string;
+    /** When true, items flex to fill the control width equally. */
+    fullWidth: boolean;
+    /** Unique per-instance id backing the indicator `layoutId`. */
+    instanceId: string;
+    /** The raw `size` prop (single token or per-breakpoint object) for overrides. */
+    responsiveSize: ResponsiveValue<ComponentSize>;
+    /** The base size token, resolved from `responsiveSize`. */
+    size: ComponentSize;
+}
+/**
+ * SegmentedControlContext - item props read shared state (active value, size,
+ * fullWidth, instance id) from here.
+ */
+export declare const SegmentedControlContext: import("react").Context<SegmentedControlContextValue>;
+/** Read the enclosing {@link SegmentedControlContext}. */
+export declare const useSegmentedControlContext: () => SegmentedControlContextValue;

package/dist/components/segmented-control/segmented-control-context.js

@@ -0,0 +1,15 @@
+"use client";
+import { createContext, use } from "react";
+/**
+ * SegmentedControlContext - item props read shared state (active value, size,
+ * fullWidth, instance id) from here.
+ */
+export const SegmentedControlContext = createContext({
+    activeValue: "",
+    fullWidth: false,
+    instanceId: "",
+    responsiveSize: "sm",
+    size: "sm",
+});
+/** Read the enclosing {@link SegmentedControlContext}. */
+export const useSegmentedControlContext = () => use(SegmentedControlContext);

package/dist/components/segmented-control/segmented-control-indicator.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Animated active-segment indicator. A single instance is mounted under the
+ * active item and slides between segments via a shared `layoutId`, so switching
+ * selection animates the pill rather than cross-fading two pills.
+ *
+ * @internal
+ */
+export declare const SegmentedControlIndicator: () => import("react").JSX.Element;

package/dist/components/segmented-control/segmented-control-indicator.js

@@ -0,0 +1,18 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { springs } from "@instruments/materia-ui/tokens/motion";
+import { cn } from "@instruments/materia-ui/utils/cn";
+import * as m from "motion/react-m";
+import { SEGMENTED_INDICATOR_CLASS } from "../segmented/segmented-root.js";
+import { useSegmentedControlContext } from "./segmented-control-context.js";
+/**
+ * Animated active-segment indicator. A single instance is mounted under the
+ * active item and slides between segments via a shared `layoutId`, so switching
+ * selection animates the pill rather than cross-fading two pills.
+ *
+ * @internal
+ */
+export const SegmentedControlIndicator = () => {
+    const { instanceId } = useSegmentedControlContext();
+    return (_jsx(m.span, { "aria-hidden": true, className: cn("absolute inset-0 rounded-full", SEGMENTED_INDICATOR_CLASS), "data-slot": "segmented-control-indicator", layoutId: `segmented-control-indicator-${instanceId}`, transition: springs.swift }));
+};

package/dist/components/segmented-control/segmented-control-item.d.ts

@@ -0,0 +1,24 @@
+import { Toggle as TogglePrimitive } from "@base-ui/react/toggle";
+import type { LucideIcon } from "lucide-react";
+import type { ComponentType, SVGProps } from "react";
+/** Props for {@link SegmentedControlItem}. */
+export interface SegmentedControlItemProps extends Omit<TogglePrimitive.Props, "className" | "value"> {
+    className?: string;
+    /** Identifier reported to `onValueChange` when this segment is selected. */
+    value: string;
+    /** Optional trailing count, muted and tabular. */
+    count?: number;
+    /** Status dot colour (CSS colour value) rendered before the label. */
+    dot?: string;
+    /** Leading icon; icon-only items must supply `aria-label` (dev-warned otherwise). */
+    icon?: LucideIcon | ComponentType<SVGProps<SVGSVGElement>>;
+}
+/**
+ * A single selectable segment within a {@link SegmentedControl}, keyed by
+ * `value`. Reads size / active state / fullWidth from context. When active it
+ * mounts the shared {@link SegmentedControlIndicator}; content (dot, icon,
+ * label, count) sits above the indicator on its own z-layer. Warns in
+ * development when an icon-only item lacks an accessible name.
+ */
+declare const SegmentedControlItem: ({ className, children, icon, count, dot, value, ...props }: SegmentedControlItemProps) => import("react").JSX.Element;
+export { SegmentedControlItem };

package/dist/components/segmented-control/segmented-control-item.js

@@ -0,0 +1,27 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Toggle as TogglePrimitive } from "@base-ui/react/toggle";
+import { Dot } from "@instruments/materia-ui/components/dot";
+import { Icon } from "@instruments/materia-ui/components/icon";
+import { cn } from "@instruments/materia-ui/utils/cn";
+import { getResponsiveSizeOverrides } from "../../tokens/responsive.js";
+import { warnMissingAriaLabel } from "../../utils/warn-missing-aria-label.js";
+import { Flex } from "../flex.js";
+import { SEGMENTED_TRIGGER_PADDING } from "../segmented/segmented-root.js";
+import { useSegmentedControlContext } from "./segmented-control-context.js";
+import { SegmentedControlIndicator } from "./segmented-control-indicator.js";
+import { segmentedControlItemVariants } from "./segmented-control-variants.js";
+/**
+ * A single selectable segment within a {@link SegmentedControl}, keyed by
+ * `value`. Reads size / active state / fullWidth from context. When active it
+ * mounts the shared {@link SegmentedControlIndicator}; content (dot, icon,
+ * label, count) sits above the indicator on its own z-layer. Warns in
+ * development when an icon-only item lacks an accessible name.
+ */
+const SegmentedControlItem = ({ className, children, icon, count, dot, value, ...props }) => {
+    const { activeValue, fullWidth, responsiveSize, size } = useSegmentedControlContext();
+    warnMissingAriaLabel(icon, children, props["aria-label"], props["aria-labelledby"]);
+    const isActive = activeValue === value;
+    return (_jsxs(TogglePrimitive, { className: cn(segmentedControlItemVariants({ size }), getResponsiveSizeOverrides(responsiveSize, SEGMENTED_TRIGGER_PADDING), fullWidth && "flex-1", className), "data-slot": "segmented-control-item", value: value, ...props, children: [isActive && _jsx(SegmentedControlIndicator, {}), _jsxs(Flex, { align: "center", as: "span", className: "relative z-10 gap-1.5", inline: true, children: [dot !== undefined && dot !== "" ? _jsx(Dot, { color: dot, size: "xs" }) : null, icon ? _jsx(Icon, { icon: icon, size: "xs" }) : null, children, count !== undefined && (_jsx("span", { className: "text-muted-foreground tabular-nums", children: count }))] })] }));
+};
+export { SegmentedControlItem };

package/dist/components/segmented-control/segmented-control-root.d.ts

@@ -0,0 +1,35 @@
+import { ToggleGroup } from "@base-ui/react/toggle-group";
+import type { ResponsiveValue } from "../../tokens/responsive.js";
+import type { ComponentSize } from "../../tokens/size.js";
+/** Props for {@link SegmentedControl}. */
+export type SegmentedControlProps<T extends string = string> = Omit<ToggleGroup.Props<T>, "className" | "defaultValue" | "multiple" | "onValueChange" | "value"> & {
+    className?: string;
+    /** Controlled selected value. */
+    value?: T;
+    /** Uncontrolled initial value. */
+    defaultValue?: T;
+    /** Fires with the newly selected value - never with "". */
+    onValueChange?: (value: T) => void;
+    /** @default "sm" */
+    size?: ResponsiveValue<ComponentSize>;
+    /** @default false */
+    fullWidth?: boolean;
+};
+/**
+ * A single-select, always-one-selected control that switches between a small
+ * set of visible options - a view or mode switcher rendered as a pill of
+ * segments. Built on Base UI ToggleGroup (single-select) but kept permanently
+ * selected: re-clicking the active segment never clears it.
+ *
+ * Compose it from {@link SegmentedControlItem}s; shared `size` / `fullWidth` /
+ * active state flow to them through context. Controlled via `value`, or
+ * uncontrolled via `defaultValue`. Items scroll horizontally with a trailing
+ * fade hint when they overflow.
+ *
+ * @bestPractice One value is always selected - the active segment cannot be deselected; for deselectable or multi-select sets reach for ToggleGroup.
+ * @bestPractice Switching visible content panels is Tabs; navigating URLs is TabNavigation - SegmentedControl is an input that selects a value or mode.
+ * @bestPractice Icon-only items must carry an `aria-label`.
+ * @category forms
+ */
+declare const SegmentedControl: <T extends string = string>({ className, size, fullWidth, value, defaultValue, onValueChange, children, ...props }: SegmentedControlProps<T>) => import("react").JSX.Element;
+export { SegmentedControl };