@instruments/materia-ui 0.1.0

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

@@ -0,0 +1,109 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Combobox as ComboboxPrimitive } from "@base-ui/react/combobox";
+import { Button } from "@instruments/materia-ui/components/button";
+import { Flex } from "@instruments/materia-ui/components/flex";
+import { Icon } from "@instruments/materia-ui/components/icon";
+import { cn } from "@instruments/materia-ui/utils/cn";
+import { useVirtualizer } from "@tanstack/react-virtual";
+import { CheckIcon, ChevronsUpDownIcon, SearchIcon } from "lucide-react";
+import { useImperativeHandle, useRef, useState } from "react";
+import { useControllableState } from "../../hooks/use-controllable-state.js";
+import { POPOVER_CONTENT_ANIMATION, POPOVER_SURFACE, } from "../../tokens/overlay-styles.js";
+const OPTION_CLASSES = "data-highlighted:bg-muted data-highlighted:text-accent-foreground relative flex w-full cursor-default items-center rounded-full py-2.5 pr-8 pl-4 text-paragraph-sm outline-hidden select-none";
+/** A single selectable option row, shared by virtualised and plain lists. */
+const ComboboxOption = ({ item, className, ...props }) => (_jsxs(ComboboxPrimitive.Item, { className: cn(OPTION_CLASSES, className), "data-slot": "combobox-item", value: item, ...props, children: [item.label, _jsx(ComboboxPrimitive.ItemIndicator, { className: "absolute right-2 flex size-4 items-center justify-center", children: _jsx(Icon, { icon: CheckIcon, size: "xs" }) })] }));
+/**
+ * Absolutely-positioned virtualised option rows, driven by Base UI's filtered
+ * items (`virtualized` mode: the root tracks highlight by index, we mount the
+ * window).
+ *
+ * The scroll element lives inside the popup portal, which mounts after the
+ * "open" render, so it is tracked in state: the virtualizer re-binds and
+ * measures the moment the list mounts instead of rendering zero rows.
+ */
+const VirtualizedOptions = ({ virtualization, virtualizerRef, }) => {
+    const filteredItems = ComboboxPrimitive.useFilteredItems();
+    const [scrollEl, setScrollEl] = useState(null);
+    // oxlint-disable-next-line react/incompatible-library -- TanStack returns unmemoisable functions; the React Compiler skips this component by design
+    const rowVirtualizer = useVirtualizer({
+        count: filteredItems.length,
+        estimateSize: () => virtualization.estimateSizePx ?? 40,
+        getScrollElement: () => scrollEl,
+        overscan: virtualization.overscan ?? 8,
+    });
+    useImperativeHandle(virtualizerRef, () => rowVirtualizer);
+    return (_jsx("div", { className: "overflow-y-auto overscroll-contain", ref: setScrollEl, role: "presentation", style: { maxHeight: virtualization.maxHeightPx ?? 300 }, children: _jsx("div", { className: "relative w-full", role: "presentation", style: { height: rowVirtualizer.getTotalSize() }, children: rowVirtualizer.getVirtualItems().map((virtualRow) => {
+                const item = filteredItems[virtualRow.index];
+                if (!item) {
+                    return null;
+                }
+                return (_jsx(ComboboxOption, { "aria-posinset": virtualRow.index + 1, "aria-setsize": filteredItems.length, className: "absolute top-0 left-0", index: virtualRow.index, item: item, style: {
+                        height: virtualRow.size,
+                        transform: `translateY(${virtualRow.start}px)`,
+                    } }, item.value));
+            }) }) }));
+};
+/** Select-style trigger; Base UI supplies `role="combobox"` and the open state. */
+const ComboboxTriggerButton = ({ className, ...props }) => (_jsx(Button, { tone: "neutral", emphasis: "outline", className: cn("bg-input text-paragraph-sm w-full justify-between rounded-md font-normal", className), "data-component": "combobox", pressed: false, suffixIcon: ChevronsUpDownIcon, suffixIconClassName: "opacity-50", ...props }));
+/** Case-insensitive substring match of `query` against an item's label or value. */
+const matchesComboboxItem = (item, query) => {
+    const q = query.trim().toLowerCase();
+    if (!q) {
+        return true;
+    }
+    return (item.label.toLowerCase().includes(q) || item.value.toLowerCase().includes(q));
+};
+const itemToStringLabel = (item) => item.label;
+const itemToStringValue = (item) => item.value;
+const isItemEqualToValue = (item, value) => item.value === value.value;
+/**
+ * Rows are not all mounted under virtualisation, so keyboard highlight has to
+ * scroll the virtualizer itself when it lands outside the mounted window.
+ */
+const scrollHighlightIntoView = (virtualizer, item, { reason, index }) => {
+    if (!item || !virtualizer) {
+        return;
+    }
+    const isEnd = index === virtualizer.options.count - 1;
+    if (reason === "none" || (reason === "keyboard" && (index === 0 || isEnd))) {
+        queueMicrotask(() => {
+            virtualizer.scrollToIndex(index, { align: isEnd ? "start" : "end" });
+        });
+    }
+};
+/**
+ * Searchable select: a button trigger opening a filterable option list in a popover.
+ * Works controlled (`value` + `onValueChange`) or uncontrolled; supports virtualisation for large lists.
+ *
+ * @bestPractice Use `Combobox` when the user filters/searches a long list; use `Select` for a short closed list, or a domain variant like `CountryCombobox` for known sets.
+ * @bestPractice `onValueChange` fires with `""` when the current selection is toggled off - treat empty string as "cleared", not as a real value.
+ * @bestPractice For lists in the hundreds+, pass `virtualization={{ enabled: true }}` so only visible rows mount instead of every option.
+ * @bestPractice Provide `items` as `{ label, value }[]` - the visible text comes from `label` while selection is tracked by `value`.
+ * @category forms
+ */
+export const Combobox = ({ items, value, onValueChange, placeholder = "Select…", buttonClassName, contentClassName, disabled, size = "xl", virtualization, "data-testid": dataTestId, }) => {
+    // Controlled when `value` is provided (incl. ""); otherwise track internally,
+    // seeded from the first `value`.
+    const [currentValue, setValue] = useControllableState({
+        defaultValue: value ?? "",
+        onChange: onValueChange,
+        value,
+    });
+    const virtualizerRef = useRef(null);
+    const selected = items.find((i) => i.value === currentValue) ?? null;
+    const shouldVirtualize = Boolean(virtualization?.enabled);
+    const handleValueChange = (item) => {
+        // Picking the current option again toggles the selection off.
+        setValue(!item || item.value === currentValue ? "" : item.value);
+    };
+    const handleItemHighlighted = (item, details) => {
+        scrollHighlightIntoView(virtualizerRef.current, item, details);
+    };
+    return (_jsxs(ComboboxPrimitive.Root, { autoHighlight: true, disabled: disabled, filter: matchesComboboxItem, isItemEqualToValue: isItemEqualToValue, itemToStringLabel: itemToStringLabel, itemToStringValue: itemToStringValue, items: items, onItemHighlighted: shouldVirtualize ? handleItemHighlighted : undefined, onValueChange: handleValueChange, value: selected, virtualized: shouldVirtualize, children: [_jsx(ComboboxPrimitive.Trigger
+            // It renders the kit's Button, a native <button>.
+            , { 
+                // It renders the kit's Button, a native <button>.
+                nativeButton: true, render: _jsx(ComboboxTriggerButton, { className: buttonClassName, "data-testid": dataTestId, size: size }), children: selected?.label ?? placeholder }), _jsx(ComboboxPrimitive.Portal, { children: _jsx(ComboboxPrimitive.Positioner, { align: "start", className: "z-50", sideOffset: 4, children: _jsxs(ComboboxPrimitive.Popup, { "aria-label": placeholder, className: cn(`${POPOVER_CONTENT_ANIMATION} ${POPOVER_SURFACE} w-(--anchor-width) min-w-32 origin-(--transform-origin) rounded-3xl`, contentClassName), "data-component": "combobox-content", "data-slot": "combobox-content", children: [_jsxs(Flex, { align: "center", className: "h-9 border-b px-3", "data-slot": "combobox-input-wrapper", gap: "xs", children: [_jsx(Icon, { className: "shrink-0 opacity-50", icon: SearchIcon, size: "xs" }), _jsx(ComboboxPrimitive.Input, { className: "placeholder:text-muted-foreground text-paragraph-sm flex h-10 w-full bg-transparent py-3 outline-hidden disabled:cursor-not-allowed disabled:opacity-50", "data-slot": "combobox-input", placeholder: "Search\u2026" })] }), _jsx(ComboboxPrimitive.Empty, { className: "text-paragraph-sm py-6 text-center empty:p-0", "data-slot": "combobox-empty", children: "No results found." }), _jsx(ComboboxPrimitive.List, { className: cn("p-1 empty:p-0", !shouldVirtualize &&
+                                    "max-h-75 scroll-py-1 overflow-x-hidden overflow-y-auto"), children: shouldVirtualize && virtualization ? (_jsx(VirtualizedOptions, { virtualization: virtualization, virtualizerRef: virtualizerRef })) : ((item) => (_jsx(ComboboxOption, { item: item }, item.value))) })] }) }) })] }));
+};

package/dist/components/combobox.d.ts

@@ -0,0 +1 @@
+export { Combobox, type ComboboxItem, type ComboboxProps, type ComboboxVirtualizationOptions, } from "./combobox/combobox-root.js";

package/dist/components/combobox.js

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

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

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

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

@@ -0,0 +1,56 @@
+import { defineAnatomy } from "../../tokens/anatomy.js";
+/**
+ * commandAnatomy helper for CommandAnatomy.
+ * Import from "@instruments/materia-ui/components/command-anatomy".
+ */
+export const commandAnatomy = defineAnatomy({
+    children: [
+        {
+            description: "Search input field",
+            label: "CommandInput",
+            slot: "command-input",
+        },
+        {
+            children: [
+                {
+                    description: "No results message",
+                    label: "CommandEmpty",
+                    slot: "command-empty",
+                },
+                {
+                    children: [
+                        {
+                            description: "Group heading",
+                            label: "CommandGroup heading",
+                            slot: "command-group-heading",
+                        },
+                        {
+                            description: "Selectable command item",
+                            label: "CommandItem",
+                            slot: "command-item",
+                        },
+                    ],
+                    description: "Grouped items with heading",
+                    label: "CommandGroup",
+                    slot: "command-group",
+                },
+                {
+                    description: "Visual divider",
+                    label: "CommandSeparator",
+                    slot: "command-separator",
+                },
+            ],
+            description: "Results container",
+            label: "CommandList",
+            slot: "command-list",
+        },
+        {
+            description: "Keyboard shortcut hint",
+            label: "CommandShortcut",
+            slot: "command-shortcut",
+        },
+    ],
+    description: "Command palette / search interface",
+    label: "Command",
+    slot: "command",
+});

package/dist/components/command/command-dialog.d.ts

@@ -0,0 +1,30 @@
+import { Dialog, DialogContent } from "@instruments/materia-ui/components/dialog";
+import type * as React from "react";
+import type { CommandProps, CommandSource } from "../command/command-root.js";
+export type CommandDialogProps<Item> = Omit<React.ComponentProps<typeof Dialog>, "children"> & CommandSource<Item> & Pick<CommandProps<Item>, "filter" | "limit" | "mode"> & {
+    /** Palette content, typically `CommandInput`, `CommandEmpty` and `CommandList`. */
+    children?: React.ReactNode;
+    /** Accessible title for the dialog (visually hidden by default). */
+    title?: string;
+    /** Accessible description for the dialog (visually hidden by default). */
+    description?: string;
+    /** Extra class names applied to the `DialogContent` wrapper. */
+    className?: string;
+    /** Whether to show the dialog close button. */
+    showCloseButton?: boolean;
+    /** Extra props applied to the rendered dialog content element. */
+    contentProps?: Omit<React.ComponentProps<typeof DialogContent>, "children"> & React.HTMLAttributes<HTMLDivElement> & {
+        "data-testid"?: string;
+    };
+};
+/**
+ * CommandDialog wraps `Command` in a dialog, with screen-reader-only title and
+ * description for accessibility. Focus moves to the search field on open and
+ * returns to the trigger on close.
+ *
+ * Import from "@instruments/materia-ui/components/command".
+ *
+ * @bestPractice Close the dialog from each `CommandItem`'s `onClick` once its action has run - choosing an item does not close it by itself.
+ * @bestPractice Pass `filter={null}` to list the entries unfiltered, for example when the application filters them itself.
+ */
+export declare const CommandDialog: <Item>(props: CommandDialogProps<Item>) => React.JSX.Element;

package/dist/components/command/command-dialog.js

@@ -0,0 +1,23 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Dialog, DialogContent, DialogDescription, DialogHeader, DialogTitle, } from "@instruments/materia-ui/components/dialog";
+import { cn } from "@instruments/materia-ui/utils/cn";
+import { Command } from "../command/command-root.js";
+/**
+ * CommandDialog wraps `Command` in a dialog, with screen-reader-only title and
+ * description for accessibility. Focus moves to the search field on open and
+ * returns to the trigger on close.
+ *
+ * Import from "@instruments/materia-ui/components/command".
+ *
+ * @bestPractice Close the dialog from each `CommandItem`'s `onClick` once its action has run - choosing an item does not close it by itself.
+ * @bestPractice Pass `filter={null}` to list the entries unfiltered, for example when the application filters them itself.
+ */
+export const CommandDialog = (props) => {
+    const { title = "Command Palette", description = "Search for a command to run…", children, className, showCloseButton = true, contentProps, filter, groups: _groups, items: _items, limit, mode, ...dialogProps } = props;
+    // Narrow on `props` so the palette receives exactly one of items or groups.
+    const source = props.groups === undefined
+        ? { items: props.items }
+        : { groups: props.groups };
+    return (_jsxs(Dialog, { ...dialogProps, children: [_jsxs(DialogHeader, { className: "sr-only", children: [_jsx(DialogTitle, { children: title }), _jsx(DialogDescription, { children: description })] }), _jsx(DialogContent, { className: cn("overflow-hidden p-0", className), showCloseButton: showCloseButton, ...contentProps, children: _jsx(Command, { className: "rounded-none border-0 shadow-none **:data-[slot=command-input-wrapper]:h-12 [&_[data-slot=command-group]]:px-2 [&_[data-slot=command-group]~[data-slot=command-group]]:pt-0 [&_[data-slot=command-input]]:h-12 [&_[data-slot=command-item]]:px-2 [&_[data-slot=command-item]]:py-3 [&_[data-slot=command-item]_svg]:size-5", ...source, filter: filter, limit: limit, mode: mode, children: children }) })] }));
+};

package/dist/components/command/command-empty.d.ts

@@ -0,0 +1,10 @@
+import { Autocomplete as AutocompletePrimitive } from "@base-ui/react/autocomplete";
+import type * as React from "react";
+/**
+ * CommandEmpty shows its children only when no item matches the query, and
+ * announces the change to screen readers. Place it beside `CommandList`.
+ * Import from "@instruments/materia-ui/components/command".
+ */
+export declare const CommandEmpty: ({ className, ...props }: Omit<React.ComponentProps<typeof AutocompletePrimitive.Empty>, "className"> & {
+    className?: string;
+}) => React.JSX.Element;

package/dist/components/command/command-empty.js

@@ -0,0 +1,10 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Autocomplete as AutocompletePrimitive } from "@base-ui/react/autocomplete";
+import { cn } from "@instruments/materia-ui/utils/cn";
+/**
+ * CommandEmpty shows its children only when no item matches the query, and
+ * announces the change to screen readers. Place it beside `CommandList`.
+ * Import from "@instruments/materia-ui/components/command".
+ */
+export const CommandEmpty = ({ className, ...props }) => (_jsx(AutocompletePrimitive.Empty, { className: cn("text-paragraph-sm py-6 text-center empty:p-0", className), "data-component": "command-empty", "data-slot": "command-empty", ...props }));

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

@@ -0,0 +1,17 @@
+import { Autocomplete as AutocompletePrimitive } from "@base-ui/react/autocomplete";
+import type * as React from "react";
+/**
+ * CommandGroup groups related command items under an optional heading. Pass the
+ * group's filtered `items` and render them with `CommandCollection`.
+ * Import from "@instruments/materia-ui/components/command".
+ */
+export declare const CommandGroup: ({ className, heading, children, ...props }: Omit<React.ComponentProps<typeof AutocompletePrimitive.Group>, "className"> & {
+    className?: string;
+    /** Heading shown above the group's items; omit for an unlabelled group. */
+    heading?: React.ReactNode;
+}) => React.JSX.Element;
+/**
+ * CommandCollection renders a group's filtered items through its function child.
+ * Import from "@instruments/materia-ui/components/command".
+ */
+export declare const CommandCollection: typeof AutocompletePrimitive.Collection;

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

@@ -0,0 +1,15 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Autocomplete as AutocompletePrimitive } from "@base-ui/react/autocomplete";
+import { cn } from "@instruments/materia-ui/utils/cn";
+/**
+ * CommandGroup groups related command items under an optional heading. Pass the
+ * group's filtered `items` and render them with `CommandCollection`.
+ * Import from "@instruments/materia-ui/components/command".
+ */
+export const CommandGroup = ({ className, heading, children, ...props }) => (_jsxs(AutocompletePrimitive.Group, { className: cn("text-foreground overflow-hidden p-1", className), "data-component": "command-group", "data-slot": "command-group", ...props, children: [heading === undefined ? null : (_jsx(AutocompletePrimitive.GroupLabel, { className: "text-muted-foreground text-caption px-2 py-1.5 font-medium", "data-component": "command-group-heading", "data-slot": "command-group-heading", children: heading })), children] }));
+/**
+ * CommandCollection renders a group's filtered items through its function child.
+ * Import from "@instruments/materia-ui/components/command".
+ */
+export const CommandCollection = AutocompletePrimitive.Collection;

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

@@ -0,0 +1,9 @@
+import { Autocomplete as AutocompletePrimitive } from "@base-ui/react/autocomplete";
+import type * as React from "react";
+/**
+ * CommandInput renders the search field for a Command; typing filters the list.
+ * Import from "@instruments/materia-ui/components/command".
+ */
+export declare const CommandInput: ({ className, ...props }: Omit<React.ComponentProps<typeof AutocompletePrimitive.Input>, "className"> & {
+    className?: string;
+}) => React.JSX.Element;

package/dist/components/command/command-input.js

@@ -0,0 +1,12 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Autocomplete as AutocompletePrimitive } from "@base-ui/react/autocomplete";
+import { focusRing } from "@instruments/materia-ui/tokens/focus-ring";
+import { cn } from "@instruments/materia-ui/utils/cn";
+import { Search } from "lucide-react";
+import { Icon } from "../icon.js";
+/**
+ * CommandInput renders the search field for a Command; typing filters the list.
+ * Import from "@instruments/materia-ui/components/command".
+ */
+export const CommandInput = ({ className, ...props }) => (_jsxs(AutocompletePrimitive.InputGroup, { className: "flex h-9 items-center gap-2 border-b px-3", "data-component": "command-input-wrapper", "data-slot": "command-input-wrapper", children: [_jsx(Icon, { className: "shrink-0 opacity-50", icon: Search, size: "xs" }), _jsx(AutocompletePrimitive.Input, { className: cn(focusRing(), "placeholder:text-muted-foreground text-paragraph-sm flex h-10 w-full rounded-lg bg-transparent py-3 disabled:cursor-not-allowed disabled:opacity-50", "focus-visible:ring-inset", className), "data-component": "command-input", "data-slot": "command-input", ...props })] }));

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

@@ -0,0 +1,11 @@
+import { Autocomplete as AutocompletePrimitive } from "@base-ui/react/autocomplete";
+import type * as React from "react";
+/**
+ * CommandItem is one entry in a Command list. Pass the item being rendered as
+ * `value`; `onClick` fires for a pointer click and for `Enter` while the item is
+ * highlighted.
+ * Import from "@instruments/materia-ui/components/command".
+ */
+export declare const CommandItem: ({ className, ...props }: Omit<React.ComponentProps<typeof AutocompletePrimitive.Item>, "className"> & {
+    className?: string;
+}) => React.JSX.Element;

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

@@ -0,0 +1,11 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Autocomplete as AutocompletePrimitive } from "@base-ui/react/autocomplete";
+import { cn } from "@instruments/materia-ui/utils/cn";
+/**
+ * CommandItem is one entry in a Command list. Pass the item being rendered as
+ * `value`; `onClick` fires for a pointer click and for `Enter` while the item is
+ * highlighted.
+ * Import from "@instruments/materia-ui/components/command".
+ */
+export const CommandItem = ({ className, ...props }) => (_jsx(AutocompletePrimitive.Item, { className: cn("text-paragraph-sm relative flex w-full cursor-default items-center gap-2 rounded-sm px-2.5 py-1.5 outline-none select-none", "hover:bg-accent hover:text-accent-foreground", "data-disabled:pointer-events-none data-disabled:opacity-50", "data-highlighted:bg-accent data-highlighted:text-accent-foreground", "[&_svg]:pointer-events-none [&_svg]:size-4 [&_svg]:shrink-0", className), "data-component": "command-item", "data-slot": "command-item", ...props }));

package/dist/components/command/command-list.d.ts

@@ -0,0 +1,11 @@
+import { Autocomplete as AutocompletePrimitive } from "@base-ui/react/autocomplete";
+import type * as React from "react";
+/**
+ * CommandList is the scrollable container for a Command's filtered items.
+ * Pass a function child: it receives each filtered item (or group, for grouped
+ * `items`) and returns a `CommandItem` (or `CommandGroup`).
+ * Import from "@instruments/materia-ui/components/command".
+ */
+export declare const CommandList: ({ className, ...props }: Omit<React.ComponentProps<typeof AutocompletePrimitive.List>, "className"> & {
+    className?: string;
+}) => React.JSX.Element;

package/dist/components/command/command-list.js

@@ -0,0 +1,11 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Autocomplete as AutocompletePrimitive } from "@base-ui/react/autocomplete";
+import { cn } from "@instruments/materia-ui/utils/cn";
+/**
+ * CommandList is the scrollable container for a Command's filtered items.
+ * Pass a function child: it receives each filtered item (or group, for grouped
+ * `items`) and returns a `CommandItem` (or `CommandGroup`).
+ * Import from "@instruments/materia-ui/components/command".
+ */
+export const CommandList = ({ className, ...props }) => (_jsx(AutocompletePrimitive.List, { className: cn("max-h-75 scroll-py-1 overflow-x-hidden overflow-y-auto overscroll-contain empty:hidden", className), "data-component": "command-list", "data-slot": "command-list", ...props }));

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

@@ -0,0 +1,40 @@
+import { Autocomplete as AutocompletePrimitive } from "@base-ui/react/autocomplete";
+import type * as React from "react";
+/** A titled set of items, for a grouped `Command`. */
+export interface CommandGroupData<Item> {
+    /** Heading shown above the group's items. */
+    value: string;
+    /** The group's items. */
+    items: readonly Item[];
+}
+/** What a `Command` lists: a flat `items` array, or `groups` of items - never both. */
+export type CommandSource<Item> = {
+    /** The entries the palette lists and filters. */
+    items: readonly Item[];
+    groups?: never;
+} | {
+    /** Titled groups of entries; `CommandList`'s function child receives each group. */
+    groups: readonly CommandGroupData<Item>[];
+    items?: never;
+};
+/** Props for {@link Command}. */
+export type CommandProps<Item> = Omit<AutocompletePrimitive.Root.Props<Item>, "children" | "inline" | "items" | "open"> & CommandSource<Item> & {
+    /** Palette parts: `CommandInput`, `CommandEmpty` and `CommandList`. */
+    children?: React.ReactNode;
+    /** Extra classes for the palette container. */
+    className?: string;
+};
+/**
+ * The inline command palette: a search field filtering a keyboard-navigable
+ * list, built on Base UI Autocomplete in inline mode. The list is always open;
+ * typing filters the entries and the first match is highlighted, so `Enter`
+ * activates it.
+ * Import from "@instruments/materia-ui/components/command".
+ *
+ * @bestPractice For a ⌘K overlay use `CommandDialog` - `Command` alone is the inline, non-floating palette container.
+ * @bestPractice Pass the entries as `items`, or as titled `groups`, and render them with a function child of `CommandList`; filtering only sees those entries, so items written as static JSX are not filtered.
+ * @bestPractice Act on a choice with `CommandItem`'s `onClick`, which fires for a pointer click and for `Enter` on the highlighted item.
+ * @bestPractice A plain click-triggered action menu is `DropdownMenu`; a remembered selection is `Combobox`.
+ * @category navigation
+ */
+export declare const Command: <Item>(props: CommandProps<Item>) => React.JSX.Element;

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

@@ -0,0 +1,28 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Autocomplete as AutocompletePrimitive } from "@base-ui/react/autocomplete";
+import { Flex } from "@instruments/materia-ui/components/flex";
+import { cn } from "@instruments/materia-ui/utils/cn";
+/**
+ * The inline command palette: a search field filtering a keyboard-navigable
+ * list, built on Base UI Autocomplete in inline mode. The list is always open;
+ * typing filters the entries and the first match is highlighted, so `Enter`
+ * activates it.
+ * Import from "@instruments/materia-ui/components/command".
+ *
+ * @bestPractice For a ⌘K overlay use `CommandDialog` - `Command` alone is the inline, non-floating palette container.
+ * @bestPractice Pass the entries as `items`, or as titled `groups`, and render them with a function child of `CommandList`; filtering only sees those entries, so items written as static JSX are not filtered.
+ * @bestPractice Act on a choice with `CommandItem`'s `onClick`, which fires for a pointer click and for `Enter` on the highlighted item.
+ * @bestPractice A plain click-triggered action menu is `DropdownMenu`; a remembered selection is `Combobox`.
+ * @category navigation
+ */
+export const Command = (props) => {
+    const { className, children, groups: _groups, items: _items, autoHighlight = "always", keepHighlight = true, ...rootProps } = props;
+    const palette = (_jsx(Flex, { className: cn("bg-popover text-popover-foreground size-full overflow-hidden rounded-lg border shadow-xs", className), "data-component": "command", "data-slot": "command", direction: "column", children: children }));
+    // Narrow on `props` so the flat and grouped sources each meet the Base UI
+    // overload written for them.
+    if (props.groups === undefined) {
+        return (_jsx(AutocompletePrimitive.Root, { ...rootProps, autoHighlight: autoHighlight, inline: true, items: props.items, keepHighlight: keepHighlight, open: true, children: palette }));
+    }
+    return (_jsx(AutocompletePrimitive.Root, { ...rootProps, autoHighlight: autoHighlight, inline: true, items: props.groups, keepHighlight: keepHighlight, open: true, children: palette }));
+};

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

@@ -0,0 +1,9 @@
+import { Autocomplete as AutocompletePrimitive } from "@base-ui/react/autocomplete";
+import type * as React from "react";
+/**
+ * CommandSeparator visually separates groups or items.
+ * Import from "@instruments/materia-ui/components/command".
+ */
+export declare const CommandSeparator: ({ className, ...props }: Omit<React.ComponentProps<typeof AutocompletePrimitive.Separator>, "className"> & {
+    className?: string;
+}) => React.JSX.Element;

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

@@ -0,0 +1,9 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Autocomplete as AutocompletePrimitive } from "@base-ui/react/autocomplete";
+import { cn } from "@instruments/materia-ui/utils/cn";
+/**
+ * CommandSeparator visually separates groups or items.
+ * Import from "@instruments/materia-ui/components/command".
+ */
+export const CommandSeparator = ({ className, ...props }) => (_jsx(AutocompletePrimitive.Separator, { className: cn("bg-border -mx-1 h-px", className), "data-component": "command-separator", "data-slot": "command-separator", ...props }));

package/dist/components/command/command-shortcut.d.ts

@@ -0,0 +1,6 @@
+import type * as React from "react";
+/**
+ * CommandShortcut helper for displaying keyboard shortcuts.
+ * Import from "@instruments/materia-ui/components/command".
+ */
+export declare const CommandShortcut: ({ className, ...props }: React.ComponentProps<"span">) => React.JSX.Element;

package/dist/components/command/command-shortcut.js

@@ -0,0 +1,7 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { cn } from "@instruments/materia-ui/utils/cn";
+/**
+ * CommandShortcut helper for displaying keyboard shortcuts.
+ * Import from "@instruments/materia-ui/components/command".
+ */
+export const CommandShortcut = ({ className, ...props }) => (_jsx("span", { className: cn("text-muted-foreground text-caption ml-auto", className), "data-component": "command-shortcut", "data-slot": "command-shortcut", ...props }));

package/dist/components/command.d.ts

@@ -0,0 +1,14 @@
+export { CommandDialog, type CommandDialogProps, } from "./command/command-dialog.js";
+export { CommandEmpty } from "./command/command-empty.js";
+export { CommandCollection, CommandGroup } from "./command/command-group.js";
+export { CommandInput } from "./command/command-input.js";
+export { CommandItem } from "./command/command-item.js";
+export { CommandList } from "./command/command-list.js";
+/**
+ * Command palette parts built on Base UI Autocomplete: a search field that
+ * filters a keyboard-navigable list of actions.
+ */
+export { Command, type CommandGroupData, type CommandProps, type CommandSource, } from "./command/command-root.js";
+export { CommandSeparator } from "./command/command-separator.js";
+export { CommandShortcut } from "./command/command-shortcut.js";
+export { commandAnatomy } from "./command/command-anatomy.js";

package/dist/components/command.js

@@ -0,0 +1,15 @@
+"use client";
+export { CommandDialog, } from "./command/command-dialog.js";
+export { CommandEmpty } from "./command/command-empty.js";
+export { CommandCollection, CommandGroup } from "./command/command-group.js";
+export { CommandInput } from "./command/command-input.js";
+export { CommandItem } from "./command/command-item.js";
+export { CommandList } from "./command/command-list.js";
+/**
+ * Command palette parts built on Base UI Autocomplete: a search field that
+ * filters a keyboard-navigable list of actions.
+ */
+export { Command, } from "./command/command-root.js";
+export { CommandSeparator } from "./command/command-separator.js";
+export { CommandShortcut } from "./command/command-shortcut.js";
+export { commandAnatomy } from "./command/command-anatomy.js";

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

@@ -0,0 +1,57 @@
+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 { ContainerSize, SectionSpace } from "../../tokens/responsive-classes.js";
+import type { ComponentSize } from "../../tokens/size.js";
+export interface ContainerProps 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 <Container as="section" />
+     */
+    as?: LayoutElement;
+    /** Drop the max-width and let the container fill its parent. */
+    fluid?: boolean;
+    /**
+     * Horizontal gutter. Defaults to `"gutter"` - the single app-wide
+     * `--page-gutter` (16px, 24px from `sm`) that the header and `SidebarInset`
+     * also use, so page content lines up with the app chrome. Pass `"none"` for a
+     * bare centred column, or a `ComponentSize` for an explicit non-standard px.
+     */
+    inset?: LayoutResponsiveValue<ComponentSize> | "none" | "gutter";
+    /** Responsive mode: `"screen"` (viewport) or `"container"` (container queries). */
+    responsiveMode?: ResponsiveMode;
+    /** Max-width token. Responsive; defaults to `7xl`. */
+    size?: LayoutResponsiveValue<ContainerSize>;
+    /** Vertical rhythm (py). Responsive; omitted by default. */
+    space?: LayoutResponsiveValue<SectionSpace>;
+}
+/**
+ * Container centres page content within a max-width and applies the canonical
+ * horizontal gutter. It is the RSC-safe page-shell primitive: pair it with
+ * `Section` for vertical rhythm, or pass `space` to fold the band into one node.
+ *
+ * Import from "@instruments/materia-ui/components/container".
+ *
+ * @example
+ * ```tsx
+ * <Container>{children}</Container>
+ * // → mx-auto max-w-7xl px-page-gutter
+ * ```
+ *
+ * @example
+ * ```tsx
+ * <Container as="section" size="7xl" space="xl">{children}</Container>
+ * // → <section class="mx-auto max-w-7xl px-4 py-12 sm:px-6">
+ * ```
+ *
+ * @bestPractice `Container` constrains width and applies the page gutter; `Section` is the full-bleed vertical-rhythm band - nest a `Container` inside a `Section` when content must be both padded and centred.
+ * @bestPractice Fold a single band into one node with `space` (its `py`) instead of nesting a `Section`; pass `fluid` to drop the max-width.
+ * @category layout
+ */
+export declare const Container: ({ as, className, ref, render, fluid, inset, responsiveMode, size, space, ...props }: ContainerProps) => import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>>;