@instruments/materia-ui 0.1.0

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

@@ -0,0 +1,74 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { ToggleGroup } from "@base-ui/react/toggle-group";
+import { ScrollArea } from "@instruments/materia-ui/components/scroll-area";
+import { ScrollFade } from "@instruments/materia-ui/components/scroll-fade";
+import { cn } from "@instruments/materia-ui/utils/cn";
+import { useEffect, useId, useMemo, useRef, useState } from "react";
+import { getResponsiveSizeOverrides, resolveResponsiveBase, } from "../../tokens/responsive.js";
+import { Flex } from "../flex.js";
+import { SEGMENTED_GAP, SEGMENTED_SHELL_BASE, SEGMENTED_SHELL_PADDING, } from "../segmented/segmented-root.js";
+import { SegmentedControlContext } from "./segmented-control-context.js";
+import { useSingleSelection } from "./use-single-selection.js";
+/**
+ * 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
+ */
+const SegmentedControl = ({ className, size = "sm", fullWidth = false, value, defaultValue, onValueChange, children, ...props }) => {
+    const resolvedSize = resolveResponsiveBase(size, "sm");
+    const instanceId = useId();
+    const containerRef = useRef(null);
+    const [showEndFade, setShowEndFade] = useState(false);
+    const selection = useSingleSelection({
+        defaultValue,
+        onValueChange,
+        value,
+    });
+    const contextValue = useMemo(() => ({
+        activeValue: selection.value,
+        fullWidth,
+        instanceId,
+        responsiveSize: size,
+        size: resolvedSize,
+    }), [selection.value, fullWidth, instanceId, size, resolvedSize]);
+    useEffect(() => {
+        const viewport = containerRef.current?.querySelector('[data-slot="scroll-area-viewport"]') ?? null;
+        const checkScroll = () => {
+            if (viewport === null) {
+                return;
+            }
+            const isScrollable = viewport.scrollWidth > viewport.clientWidth + 1;
+            const isAtEnd = viewport.scrollLeft + viewport.clientWidth >= viewport.scrollWidth - 1;
+            setShowEndFade(isScrollable && !isAtEnd);
+        };
+        // The observer reports the initial size on `observe`, so no separate first
+        // measurement is needed.
+        const observer = new ResizeObserver(checkScroll);
+        if (viewport !== null) {
+            observer.observe(viewport);
+            viewport.addEventListener("scroll", checkScroll, { passive: true });
+        }
+        return () => {
+            observer.disconnect();
+            viewport?.removeEventListener("scroll", checkScroll);
+        };
+    }, []);
+    return (_jsx(ToggleGroup, { className: cn(SEGMENTED_SHELL_BASE, "group/segmented-control inline-flex h-auto max-w-full items-center overflow-hidden", SEGMENTED_SHELL_PADDING[resolvedSize], getResponsiveSizeOverrides(size, SEGMENTED_SHELL_PADDING), fullWidth && "flex w-full", className), "data-component": "segmented-control", "data-size": resolvedSize, "data-slot": "segmented-control", onValueChange: (groupValue) => {
+            // Single-select group: Base UI sends `[]` when the active item is
+            // re-clicked; the selection hook swallows that deselect.
+            selection.onValueChange(groupValue[0] ?? "");
+        }, value: [selection.value], ...props, children: _jsx(SegmentedControlContext.Provider, { value: contextValue, children: _jsxs("div", { className: "relative min-w-0 flex-1", ref: containerRef, children: [_jsx(ScrollArea, { hideScrollbar: true, orientation: "horizontal", children: _jsx(Flex, { align: "center", className: cn(SEGMENTED_GAP[resolvedSize], getResponsiveSizeOverrides(size, SEGMENTED_GAP), fullWidth && "w-full"), inline: true, children: children }) }), showEndFade && (_jsx(ScrollFade, { className: "rounded-r-full", orientation: "horizontal", position: "end", size: "sm", theme: "gray" }))] }) }) }));
+};
+export { SegmentedControl };

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

@@ -0,0 +1,9 @@
+/**
+ * segmentedControlItemVariants class helper for `SegmentedControlItem`.
+ *
+ * Structure mirrors `tabsTriggerVariants` (pill): the `size` variant only sets
+ * text size; ALL padding is applied through size-keyed compound variants.
+ */
+export declare const segmentedControlItemVariants: (props?: ({
+    size?: "2xl" | "2xs" | "3xl" | "base" | "lg" | "sm" | "xl" | "xs" | null | undefined;
+} & import("class-variance-authority/types").ClassProp) | undefined) => string;

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

@@ -0,0 +1,31 @@
+import { focusRing } from "@instruments/materia-ui/tokens/focus-ring";
+import { cn } from "@instruments/materia-ui/utils/cn";
+import { cva } from "class-variance-authority";
+import { DISABLED } from "../../tokens/input-shell.js";
+import { typedEntries } from "../../utils/typed-entries.js";
+import { SEGMENTED_TRIGGER_PADDING, SEGMENTED_TRIGGER_TEXT, } from "../segmented/segmented-root.js";
+/**
+ * Item padding lives in compound variants (mirroring `tabsTriggerVariants`) so a
+ * single size dimension drives text (base `size` variant) and padding
+ * (compounds) without competing padding utilities colliding under
+ * tailwind-merge.
+ */
+const triggerPaddingCompoundVariants = typedEntries(SEGMENTED_TRIGGER_PADDING).map(([size, className]) => ({
+    className,
+    size,
+}));
+/**
+ * segmentedControlItemVariants class helper for `SegmentedControlItem`.
+ *
+ * Structure mirrors `tabsTriggerVariants` (pill): the `size` variant only sets
+ * text size; ALL padding is applied through size-keyed compound variants.
+ */
+export const segmentedControlItemVariants = cva(cn(focusRing(), "text-muted-foreground relative inline-flex shrink-0 cursor-pointer items-center justify-center rounded-full font-medium whitespace-nowrap", `transition-color-shadow-border ${DISABLED}`, "data-pressed:text-foreground dark:text-gray-500 dark:data-pressed:text-gray-100", "[&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4"), {
+    compoundVariants: triggerPaddingCompoundVariants,
+    defaultVariants: {
+        size: "sm",
+    },
+    variants: {
+        size: { ...SEGMENTED_TRIGGER_TEXT },
+    },
+});

package/dist/components/segmented-control/use-single-selection.d.ts

@@ -0,0 +1,28 @@
+/** Inputs to {@link useSingleSelection}. */
+interface UseSingleSelectionOptions<T extends string> {
+    /** Uncontrolled initial value. Ignored once `value` is provided. */
+    defaultValue?: T | undefined;
+    /** Fires with the newly selected value - never with `""`. */
+    onValueChange?: ((value: T) => void) | undefined;
+    /** Controlled value. Present → the hook is controlled. */
+    value?: T | undefined;
+}
+/** The always-selected value plus a change handler that ignores deselection. */
+interface UseSingleSelectionResult<T extends string> {
+    onValueChange: (next: T | "") => void;
+    /** `""` only before anything is selected (no `value`/`defaultValue`). */
+    value: T | "";
+}
+/**
+ * Enforced single-selection state for a single-select ToggleGroup.
+ *
+ * The group emits an empty selection when the active item is re-clicked (a deselect). This hook
+ * swallows that empty value so one option is ALWAYS selected - the active
+ * segment can never be toggled off. Controlled when `value` is provided,
+ * uncontrolled otherwise (seeded from `defaultValue`).
+ *
+ * It imports only the shared controllable-state hook, never component code,
+ * so other single-select controls can adopt it.
+ */
+export declare const useSingleSelection: <T extends string>({ defaultValue, onValueChange, value, }: UseSingleSelectionOptions<T>) => UseSingleSelectionResult<T>;
+export {};

package/dist/components/segmented-control/use-single-selection.js

@@ -0,0 +1,29 @@
+"use client";
+import { useControllableState } from "../../hooks/use-controllable-state.js";
+/**
+ * Enforced single-selection state for a single-select ToggleGroup.
+ *
+ * The group emits an empty selection when the active item is re-clicked (a deselect). This hook
+ * swallows that empty value so one option is ALWAYS selected - the active
+ * segment can never be toggled off. Controlled when `value` is provided,
+ * uncontrolled otherwise (seeded from `defaultValue`).
+ *
+ * It imports only the shared controllable-state hook, never component code,
+ * so other single-select controls can adopt it.
+ */
+export const useSingleSelection = ({ defaultValue, onValueChange, value, }) => {
+    const [currentValue, setValue] = useControllableState({
+        defaultValue: defaultValue ?? "",
+        value,
+    });
+    const handleValueChange = (next) => {
+        // Enforced selection: The group reports an empty selection on a re-click of the active item.
+        // Ignore it so the current value stays selected.
+        if (next === "") {
+            return;
+        }
+        setValue(next);
+        onValueChange?.(next);
+    };
+    return { onValueChange: handleValueChange, value: currentValue };
+};

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

@@ -0,0 +1,3 @@
+export { segmentedControlAnatomy } from "./segmented-control/segmented-control-anatomy.js";
+export { SegmentedControlItem, type SegmentedControlItemProps, } from "./segmented-control/segmented-control-item.js";
+export { SegmentedControl, type SegmentedControlProps, } from "./segmented-control/segmented-control-root.js";

package/dist/components/segmented-control.js

@@ -0,0 +1,3 @@
+export { segmentedControlAnatomy } from "./segmented-control/segmented-control-anatomy.js";
+export { SegmentedControlItem, } from "./segmented-control/segmented-control-item.js";
+export { SegmentedControl, } from "./segmented-control/segmented-control-root.js";

package/dist/components/segmented.d.ts

@@ -0,0 +1 @@
+export { SEGMENTED_GAP, SEGMENTED_INDICATOR_ACTIVE_CLASS, SEGMENTED_INDICATOR_CLASS, SEGMENTED_SHELL_BASE, SEGMENTED_SHELL_PADDING, SEGMENTED_TRIGGER_PADDING, } from "./segmented/segmented-variants.js";

package/dist/components/segmented.js

@@ -0,0 +1 @@
+export { SEGMENTED_GAP, SEGMENTED_INDICATOR_ACTIVE_CLASS, SEGMENTED_INDICATOR_CLASS, SEGMENTED_SHELL_BASE, SEGMENTED_SHELL_PADDING, SEGMENTED_TRIGGER_PADDING, } from "./segmented/segmented-variants.js";

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

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

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

@@ -0,0 +1,49 @@
+import { defineAnatomy } from "../../tokens/anatomy.js";
+/**
+ * selectAnatomy helper for SelectAnatomy.
+ * Import from "@instruments/materia-ui/components/select-anatomy".
+ */
+export const selectAnatomy = defineAnatomy({
+    children: [
+        {
+            description: "Button showing current value",
+            label: "SelectTrigger",
+            slot: "select-trigger",
+        },
+        {
+            description: "Displayed selected value",
+            label: "SelectValue",
+            slot: "select-value",
+        },
+        {
+            children: [
+                {
+                    description: "Grouped options",
+                    label: "SelectGroup",
+                    slot: "select-group",
+                },
+                {
+                    description: "Group label",
+                    label: "SelectLabel",
+                    slot: "select-label",
+                },
+                {
+                    description: "Selectable option",
+                    label: "SelectItem",
+                    slot: "select-item",
+                },
+                {
+                    description: "Visual divider",
+                    label: "SelectSeparator",
+                    slot: "select-separator",
+                },
+            ],
+            description: "Dropdown options container",
+            label: "SelectContent",
+            slot: "select-content",
+        },
+    ],
+    description: "Dropdown selection input",
+    label: "Select",
+    slot: "select",
+});

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

@@ -0,0 +1,15 @@
+import { Select as SelectPrimitive } from "@base-ui/react/select";
+import type { ComponentSize } from "../../tokens/size.js";
+import type { WithTestId } from "../../utils/with-test-id.js";
+type SelectPositionerProps = Pick<SelectPrimitive.Positioner.Props, "align" | "alignItemWithTrigger" | "alignOffset" | "anchor" | "arrowPadding" | "collisionAvoidance" | "collisionBoundary" | "collisionPadding" | "positionMethod" | "side" | "sideOffset" | "sticky">;
+/**
+ * Portalled popover holding the options; sits under the trigger by default
+ * (`alignItemWithTrigger={false}`) and its `size` flows to descendant
+ * SelectItems via context to keep them in sync. Positioning props go to the
+ * Base UI Positioner.
+ */
+declare const SelectContent: ({ className, children, align, alignItemWithTrigger, side, sideOffset, alignOffset, anchor, arrowPadding, collisionAvoidance, collisionBoundary, collisionPadding, positionMethod, sticky, size, testId, ...props }: WithTestId<Omit<SelectPrimitive.Popup.Props, "className"> & SelectPositionerProps & {
+    className?: string;
+    size?: ComponentSize;
+}>) => import("react").JSX.Element;
+export { SelectContent };

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

@@ -0,0 +1,23 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Select as SelectPrimitive } from "@base-ui/react/select";
+import { cn } from "@instruments/materia-ui/utils/cn";
+import { ChevronDown, ChevronUp } from "lucide-react";
+import { useMemo } from "react";
+import { POPOVER_CONTENT_ANIMATION } from "../../tokens/overlay-styles.js";
+import { Icon } from "../icon.js";
+import { SelectContext } from "../select/select-context.js";
+const SELECT_ARROW_CLASSES = "bg-popover z-1 flex w-full cursor-default items-center justify-center py-1";
+const SelectScrollUpButton = ({ className, testId, ...props }) => (_jsx(SelectPrimitive.ScrollUpArrow, { className: cn(SELECT_ARROW_CLASSES, className), "data-component": "select-scroll-up-button", "data-slot": "select-scroll-up-button", "data-testid": testId, ...props, children: _jsx(Icon, { icon: ChevronUp, size: "xs" }) }));
+const SelectScrollDownButton = ({ className, testId, ...props }) => (_jsx(SelectPrimitive.ScrollDownArrow, { className: cn(SELECT_ARROW_CLASSES, className), "data-component": "select-scroll-down-button", "data-slot": "select-scroll-down-button", "data-testid": testId, ...props, children: _jsx(Icon, { icon: ChevronDown, size: "xs" }) }));
+/**
+ * Portalled popover holding the options; sits under the trigger by default
+ * (`alignItemWithTrigger={false}`) and its `size` flows to descendant
+ * SelectItems via context to keep them in sync. Positioning props go to the
+ * Base UI Positioner.
+ */
+const SelectContent = ({ className, children, align = "start", alignItemWithTrigger = false, side, sideOffset = 4, alignOffset, anchor, arrowPadding, collisionAvoidance, collisionBoundary, collisionPadding, positionMethod, sticky, size = "sm", testId, ...props }) => {
+    const contextValue = useMemo(() => ({ size }), [size]);
+    return (_jsx(SelectPrimitive.Portal, { children: _jsx(SelectContext.Provider, { value: contextValue, children: _jsx(SelectPrimitive.Positioner, { align: align, alignItemWithTrigger: alignItemWithTrigger, alignOffset: alignOffset, anchor: anchor, arrowPadding: arrowPadding, className: "z-50", collisionAvoidance: collisionAvoidance, collisionBoundary: collisionBoundary, collisionPadding: collisionPadding, positionMethod: positionMethod, side: side, sideOffset: sideOffset, sticky: sticky, children: _jsxs(SelectPrimitive.Popup, { className: cn(`${POPOVER_CONTENT_ANIMATION} bg-popover text-popover-foreground relative max-h-(--available-height) min-w-(--anchor-width) origin-(--transform-origin) overflow-x-hidden overflow-y-auto rounded-3xl border p-1.5 shadow-md dark:shadow-none`, className), "data-component": "select-content", "data-slot": "select-content", "data-testid": testId, ...props, children: [_jsx(SelectScrollUpButton, {}), _jsx(SelectPrimitive.List, { className: "w-full scroll-my-1 p-1", children: children }), _jsx(SelectScrollDownButton, {})] }) }) }) }));
+};
+export { SelectContent };

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

@@ -0,0 +1,7 @@
+import type { ComponentSize } from "../../tokens/size.js";
+interface SelectContextValue {
+    size: ComponentSize;
+}
+declare const SelectContext: import("react").Context<SelectContextValue>;
+declare const useSelectContext: () => SelectContextValue;
+export { SelectContext, useSelectContext };

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

@@ -0,0 +1,7 @@
+"use client";
+import { createContext, use } from "react";
+const SelectContext = createContext({
+    size: "sm",
+});
+const useSelectContext = () => use(SelectContext);
+export { SelectContext, useSelectContext };

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

@@ -0,0 +1,8 @@
+import { Select as SelectPrimitive } from "@base-ui/react/select";
+import type { WithTestId } from "../../utils/with-test-id.js";
+/**
+ * Groups related SelectItems, associating them with a sibling SelectLabel for
+ * accessible labelling of the section.
+ */
+declare const SelectGroup: ({ testId, ...props }: WithTestId<SelectPrimitive.Group.Props>) => import("react").JSX.Element;
+export { SelectGroup };

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

@@ -0,0 +1,9 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Select as SelectPrimitive } from "@base-ui/react/select";
+/**
+ * Groups related SelectItems, associating them with a sibling SelectLabel for
+ * accessible labelling of the section.
+ */
+const SelectGroup = ({ testId, ...props }) => (_jsx(SelectPrimitive.Group, { "data-component": "select-group", "data-slot": "select-group", "data-testid": testId, ...props }));
+export { SelectGroup };

package/dist/components/select/select-item.d.ts

@@ -0,0 +1,10 @@
+import { Select as SelectPrimitive } from "@base-ui/react/select";
+import type { WithTestId } from "../../utils/with-test-id.js";
+/**
+ * A selectable option; shows a check indicator when active and derives its
+ * padding and sizing from the parent SelectContent's `size` (via context).
+ */
+declare const SelectItem: ({ className, children, testId, ...props }: WithTestId<Omit<SelectPrimitive.Item.Props, "className"> & {
+    className?: string;
+}>) => import("react").JSX.Element;
+export { SelectItem };

package/dist/components/select/select-item.js

@@ -0,0 +1,46 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Select as SelectPrimitive } from "@base-ui/react/select";
+import { cn } from "@instruments/materia-ui/utils/cn";
+import { Check } from "lucide-react";
+import { Center } from "../center.js";
+import { Icon } from "../icon.js";
+import { MENU_ITEM_ICON_SIZES, MENU_ITEM_SIZE_CLASSES } from "../menu-item.js";
+import { useSelectContext } from "../select/select-context.js";
+/**
+ * Right padding override per size to make room for the check indicator.
+ * Replaces the symmetric px-* from MENU_ITEM_SIZE_CLASSES on the right side.
+ */
+const SELECT_ITEM_RIGHT_PADDING = {
+    "2xl": "pr-10",
+    "2xs": "pr-6",
+    "3xl": "pr-12",
+    base: "pr-8",
+    lg: "pr-9",
+    sm: "pr-8",
+    xl: "pr-10",
+    xs: "pr-7",
+};
+/** Indicator container position and size per item size. */
+const SELECT_INDICATOR_CLASSES = {
+    "2xl": "right-4 size-4.5",
+    "2xs": "right-1.5 size-3",
+    "3xl": "right-5 size-5",
+    base: "right-2.5 size-3.5",
+    lg: "right-3 size-4",
+    sm: "right-2 size-3.5",
+    xl: "right-3.5 size-4",
+    xs: "right-2 size-3",
+};
+/**
+ * A selectable option; shows a check indicator when active and derives its
+ * padding and sizing from the parent SelectContent's `size` (via context).
+ */
+const SelectItem = ({ className, children, testId, ...props }) => {
+    const { size } = useSelectContext();
+    return (_jsxs(SelectPrimitive.Item, { className: cn("data-highlighted:bg-accent data-highlighted:text-accent-foreground [&_svg:not([class*='text-'])]:text-muted-foreground relative flex w-full cursor-default items-center outline-hidden select-none data-[disabled]:pointer-events-none data-[disabled]:opacity-50 [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4", MENU_ITEM_SIZE_CLASSES[size], SELECT_ITEM_RIGHT_PADDING[size], 
+        // Figma binds rounded-xs (4px) on select rows - squarer than the pill
+        // items of Dropdown/Context menus.
+        "rounded-xs", className), "data-component": "select-item", "data-slot": "select-item", "data-testid": testId, ...props, children: [_jsx(Center, { as: "span", className: cn("absolute", SELECT_INDICATOR_CLASSES[size]), children: _jsx(SelectPrimitive.ItemIndicator, { children: _jsx(Icon, { className: "text-muted-foreground/70", icon: Check, size: MENU_ITEM_ICON_SIZES[size] }) }) }), _jsx(SelectPrimitive.ItemText, { className: "flex items-center gap-2", children: children })] }));
+};
+export { SelectItem };

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

@@ -0,0 +1,11 @@
+import { Select as SelectPrimitive } from "@base-ui/react/select";
+import type { WithTestId } from "../../utils/with-test-id.js";
+/**
+ * SelectLabel UI component.
+ * Import from "@instruments/materia-ui/components/select".
+ * Built on Base UI primitives for accessible behaviour.
+ */
+declare const SelectLabel: ({ className, testId, ...props }: WithTestId<Omit<SelectPrimitive.GroupLabel.Props, "className"> & {
+    className?: string;
+}>) => import("react").JSX.Element;
+export { SelectLabel };

package/dist/components/select/select-label.js

@@ -0,0 +1,11 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Select as SelectPrimitive } from "@base-ui/react/select";
+import { cn } from "@instruments/materia-ui/utils/cn";
+/**
+ * SelectLabel UI component.
+ * Import from "@instruments/materia-ui/components/select".
+ * Built on Base UI primitives for accessible behaviour.
+ */
+const SelectLabel = ({ className, testId, ...props }) => (_jsx(SelectPrimitive.GroupLabel, { className: cn("text-muted-foreground text-caption px-2 py-1.5", className), "data-component": "select-label", "data-slot": "select-label", "data-testid": testId, ...props }));
+export { SelectLabel };

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

@@ -0,0 +1,15 @@
+import { Select as SelectPrimitive } from "@base-ui/react/select";
+import type { WithTestId } from "../../utils/with-test-id.js";
+/**
+ * Root of the select - an accessible listbox built on Base UI that owns open
+ * state and the chosen value; drive it with `value`/`onValueChange`
+ * (controlled) or `defaultValue` (uncontrolled).
+ *
+ * @bestPractice `Select` is only the state root - compose `SelectTrigger`, `SelectValue`, `SelectContent`, and `SelectItem`s inside it or nothing renders.
+ * @bestPractice Use `Select` to pick one option from a short closed list; when users need type-to-filter, use `Combobox` instead.
+ * @bestPractice Drive it with `value` + `onValueChange` (controlled) or `defaultValue` (uncontrolled), and give it an accessible name via the trigger (`Field`/`Label`).
+ * @bestPractice Pass `items` (a value-to-label map or `{ value, label }[]`) so the trigger shows the selected label even before the popup has mounted.
+ * @category forms
+ */
+declare const Select: <Value, Multiple extends boolean | undefined = false>({ testId, ...props }: WithTestId<SelectPrimitive.Root.Props<Value, Multiple>>) => import("react").JSX.Element;
+export { Select };

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

@@ -0,0 +1,16 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Select as SelectPrimitive } from "@base-ui/react/select";
+/**
+ * Root of the select - an accessible listbox built on Base UI that owns open
+ * state and the chosen value; drive it with `value`/`onValueChange`
+ * (controlled) or `defaultValue` (uncontrolled).
+ *
+ * @bestPractice `Select` is only the state root - compose `SelectTrigger`, `SelectValue`, `SelectContent`, and `SelectItem`s inside it or nothing renders.
+ * @bestPractice Use `Select` to pick one option from a short closed list; when users need type-to-filter, use `Combobox` instead.
+ * @bestPractice Drive it with `value` + `onValueChange` (controlled) or `defaultValue` (uncontrolled), and give it an accessible name via the trigger (`Field`/`Label`).
+ * @bestPractice Pass `items` (a value-to-label map or `{ value, label }[]`) so the trigger shows the selected label even before the popup has mounted.
+ * @category forms
+ */
+const Select = ({ testId, ...props }) => (_jsx(SelectPrimitive.Root, { "data-component": "select", "data-slot": "select", "data-testid": testId, ...props }));
+export { Select };

package/dist/components/select/select-separator.d.ts

@@ -0,0 +1,11 @@
+import { Select as SelectPrimitive } from "@base-ui/react/select";
+import type { WithTestId } from "../../utils/with-test-id.js";
+/**
+ * SelectSeparator UI component.
+ * Import from "@instruments/materia-ui/components/select".
+ * Built on Base UI primitives for accessible behaviour.
+ */
+declare const SelectSeparator: ({ className, testId, ...props }: WithTestId<Omit<SelectPrimitive.Separator.Props, "className"> & {
+    className?: string;
+}>) => import("react").JSX.Element;
+export { SelectSeparator };

package/dist/components/select/select-separator.js

@@ -0,0 +1,11 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Select as SelectPrimitive } from "@base-ui/react/select";
+import { cn } from "@instruments/materia-ui/utils/cn";
+/**
+ * SelectSeparator UI component.
+ * Import from "@instruments/materia-ui/components/select".
+ * Built on Base UI primitives for accessible behaviour.
+ */
+const SelectSeparator = ({ className, testId, ...props }) => (_jsx(SelectPrimitive.Separator, { className: cn("bg-border pointer-events-none -mx-1 my-1 h-px", className), "data-component": "select-separator", "data-slot": "select-separator", "data-testid": testId, ...props }));
+export { SelectSeparator };

package/dist/components/select/select-trigger.d.ts

@@ -0,0 +1,18 @@
+import { Select as SelectPrimitive } from "@base-ui/react/select";
+import type { ResponsiveSize } from "@instruments/materia-ui/tokens/size";
+import type { WithTestId } from "../../utils/with-test-id.js";
+import type { ButtonProps } from "../button.js";
+/**
+ * Button that opens the listbox and displays the selected value (or the
+ * SelectValue placeholder), with a trailing chevron; forwards Button styling
+ * props - defaults to `size="lg"`, `emphasis="outline"`, `tone="neutral"`.
+ */
+declare const SelectTrigger: ({ className, children, testId, tone, size, emphasis, radius, pressed, ...props }: WithTestId<Omit<SelectPrimitive.Trigger.Props, "className" | "render"> & Pick<ButtonProps, "emphasis" | "pressed" | "radius" | "tone"> & {
+    className?: string;
+    /**
+     * Trigger size - a single token or a per-breakpoint object like
+     * `{ base: "sm", md: "xl" }`. Forwarded to the underlying Button. @default "xl"
+     */
+    size?: ResponsiveSize;
+}>) => import("react").JSX.Element;
+export { SelectTrigger };

package/dist/components/select/select-trigger.js

@@ -0,0 +1,14 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Select as SelectPrimitive } from "@base-ui/react/select";
+import { cn } from "@instruments/materia-ui/utils/cn";
+import { ChevronDown } from "lucide-react";
+import { Button } from "../button.js";
+import { Icon } from "../icon.js";
+/**
+ * Button that opens the listbox and displays the selected value (or the
+ * SelectValue placeholder), with a trailing chevron; forwards Button styling
+ * props - defaults to `size="lg"`, `emphasis="outline"`, `tone="neutral"`.
+ */
+const SelectTrigger = ({ className, children, testId, tone = "neutral", size = "xl", emphasis = "outline", radius = "rounded", pressed = false, ...props }) => (_jsxs(SelectPrimitive.Trigger, { render: _jsx(Button, { emphasis: emphasis, className: cn("bg-input data-placeholder:text-muted-foreground text-paragraph-sm justify-between rounded-md *:data-[slot=select-value]:line-clamp-1 *:data-[slot=select-value]:flex *:data-[slot=select-value]:items-center *:data-[slot=select-value]:gap-2", className), pressed: pressed, radius: radius, size: size, tone: tone }), "data-component": "select-trigger", "data-slot": "select-trigger", "data-testid": testId, ...props, children: [children, _jsx(SelectPrimitive.Icon, { className: "flex", children: _jsx(Icon, { className: "opacity-50", icon: ChevronDown, size: "xs" }) })] }));
+export { SelectTrigger };

package/dist/components/select/select-value.d.ts

@@ -0,0 +1,8 @@
+import { Select as SelectPrimitive } from "@base-ui/react/select";
+import type { WithTestId } from "../../utils/with-test-id.js";
+/**
+ * Renders the selected option's label inside the trigger, falling back to
+ * `placeholder` when nothing is selected.
+ */
+declare const SelectValue: ({ testId, ...props }: WithTestId<SelectPrimitive.Value.Props>) => import("react").JSX.Element;
+export { SelectValue };

package/dist/components/select/select-value.js

@@ -0,0 +1,9 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Select as SelectPrimitive } from "@base-ui/react/select";
+/**
+ * Renders the selected option's label inside the trigger, falling back to
+ * `placeholder` when nothing is selected.
+ */
+const SelectValue = ({ testId, ...props }) => (_jsx(SelectPrimitive.Value, { "data-component": "select-value", "data-slot": "select-value", "data-testid": testId, ...props }));
+export { SelectValue };

package/dist/components/select.d.ts

@@ -0,0 +1,9 @@
+export { SelectContent } from "./select/select-content.js";
+export { SelectGroup } from "./select/select-group.js";
+export { SelectItem } from "./select/select-item.js";
+export { SelectLabel } from "./select/select-label.js";
+export { Select } from "./select/select-root.js";
+export { SelectSeparator } from "./select/select-separator.js";
+export { SelectTrigger } from "./select/select-trigger.js";
+export { SelectValue } from "./select/select-value.js";
+export { selectAnatomy } from "./select/select-anatomy.js";

package/dist/components/select.js

@@ -0,0 +1,9 @@
+export { SelectContent } from "./select/select-content.js";
+export { SelectGroup } from "./select/select-group.js";
+export { SelectItem } from "./select/select-item.js";
+export { SelectLabel } from "./select/select-label.js";
+export { Select } from "./select/select-root.js";
+export { SelectSeparator } from "./select/select-separator.js";
+export { SelectTrigger } from "./select/select-trigger.js";
+export { SelectValue } from "./select/select-value.js";
+export { selectAnatomy } from "./select/select-anatomy.js";

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

@@ -0,0 +1,31 @@
+import { Separator as SeparatorPrimitive } from "@base-ui/react/separator";
+declare const VARIANT_CLASSES: {
+    readonly accent: "bg-gray-300";
+    readonly default: "bg-border";
+    readonly muted: "bg-gray-200";
+    readonly strong: "bg-gray-400";
+};
+type SeparatorVariant = keyof typeof VARIANT_CLASSES;
+interface SeparatorProps extends SeparatorPrimitive.Props {
+    /** Visual weight of the separator line. @default "default" */
+    variant?: SeparatorVariant;
+}
+/**
+ * Visual rule dividing content sections, horizontally or vertically.
+ *
+ * Renders a Base UI `Separator` (`role="separator"`). Pass `aria-hidden` when
+ * the rule is purely decorative and should stay out of the accessibility tree.
+ *
+ * @example
+ * ```tsx
+ * <Separator />
+ * <Separator orientation="vertical" variant="accent" className="h-6" />
+ * ```
+ *
+ * @bestPractice It is announced as a separator by default - pass `aria-hidden` when the rule is purely decorative.
+ * @bestPractice For an inline rule set `orientation="vertical"` and give it an explicit height (e.g. `className="h-6"`) - a vertical separator has no intrinsic length.
+ * @category layout
+ */
+declare const Separator: ({ className, orientation, variant, ...props }: SeparatorProps) => import("react").JSX.Element;
+export type { SeparatorVariant };
+export { Separator };

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

@@ -0,0 +1,28 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Separator as SeparatorPrimitive } from "@base-ui/react/separator";
+import { cn } from "@instruments/materia-ui/utils/cn";
+const VARIANT_CLASSES = {
+    accent: "bg-gray-300",
+    default: "bg-border",
+    muted: "bg-gray-200",
+    strong: "bg-gray-400",
+};
+/**
+ * Visual rule dividing content sections, horizontally or vertically.
+ *
+ * Renders a Base UI `Separator` (`role="separator"`). Pass `aria-hidden` when
+ * the rule is purely decorative and should stay out of the accessibility tree.
+ *
+ * @example
+ * ```tsx
+ * <Separator />
+ * <Separator orientation="vertical" variant="accent" className="h-6" />
+ * ```
+ *
+ * @bestPractice It is announced as a separator by default - pass `aria-hidden` when the rule is purely decorative.
+ * @bestPractice For an inline rule set `orientation="vertical"` and give it an explicit height (e.g. `className="h-6"`) - a vertical separator has no intrinsic length.
+ * @category layout
+ */
+const Separator = ({ className, orientation = "horizontal", variant = "default", ...props }) => (_jsx(SeparatorPrimitive, { className: cn("shrink-0 data-[orientation=horizontal]:h-px data-[orientation=horizontal]:w-full data-[orientation=vertical]:h-full data-[orientation=vertical]:w-px", VARIANT_CLASSES[variant], className), "data-component": "separator", "data-slot": "separator", orientation: orientation, ...props }));
+export { Separator };

package/dist/components/separator.d.ts

@@ -0,0 +1 @@
+export { Separator, type SeparatorVariant } from "./separator/separator-root.js";

package/dist/components/separator.js

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