@ciridae/ui 0.17.0 → 1.0.1

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

@@ -0,0 +1,10 @@
+/** A newly issued secret, which the server returns once and keeps only a hash of. */
+export type IssuedSecret = {
+    name: string;
+    secret: string;
+};
+/** Shows a secret the one time it can be copied; closes back to the caller with `onClose`. */
+export declare function OneTimeSecretDialog({ issued, onClose, }: {
+    issued: IssuedSecret | null;
+    onClose: () => void;
+}): import("@types/react").JSX.Element;

package/dist/components/secret-dialog.js

@@ -0,0 +1,12 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { CodeBlock } from "./data-display.js";
+import { useCiridaeLocale } from "./locale.js";
+import { Dialog } from "./overlays.js";
+/** Shows a secret the one time it can be copied; closes back to the caller with `onClose`. */
+export function OneTimeSecretDialog({ issued, onClose, }) {
+    const { labels } = useCiridaeLocale();
+    return (_jsx(Dialog, { open: issued !== null, onOpenChange: (nextOpen) => {
+            if (!nextOpen)
+                onClose();
+        }, title: issued ? labels.secret.titleFor(issued.name) : labels.secret.title, kind: "info", children: issued && (_jsx(CodeBlock, { copy: issued.secret, copyLabel: "secret", children: issued.secret })) }));
+}

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

@@ -0,0 +1,23 @@
+import { type ComponentProps, type ReactNode } from "react";
+import type { Tone } from "./badge.js";
+export type SegmentedBarSegment = {
+    id: string;
+    label: string;
+    value: number;
+    /** The segment's color by meaning; `neutral` by default. */
+    tone?: Tone;
+    /** A color of its own, such as a CSS variable the app themes, over `tone`. */
+    color?: string;
+};
+export type SegmentedBarProps = Omit<ComponentProps<"div">, "children"> & {
+    segments: readonly SegmentedBarSegment[];
+    /** Lists the segments under the bar; true by default. */
+    legend?: boolean;
+    /** The card a hovered or focused segment opens. */
+    renderDetail?: (segment: SegmentedBarSegment) => ReactNode;
+    /** Runs as a segment is clicked, such as opening the records it counts. */
+    onSegmentSelect?: (segment: SegmentedBarSegment) => void;
+    /** How a value reads in the legend and a segment's name; the locale's number by default. */
+    formatValue?: (value: number) => string;
+};
+export declare function SegmentedBar({ segments, legend, renderDetail, onSegmentSelect, formatValue, className, ...props }: SegmentedBarProps): import("@types/react").JSX.Element;

package/dist/components/segmented-bar.js

@@ -0,0 +1,75 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/*
+ * A whole split into its parts, such as unpaid invoices by the stage they wait at: one bar of
+ * segments sized by value, and a legend of each part's label and value under it. Hovering or
+ * focusing a segment dims the rest and, with `renderDetail`, opens a card about it, such as its
+ * total and a way into those records. Parts with no value keep their legend row but no segment.
+ */
+import { Fragment, useState } from "react";
+import { css, cva, cx } from "#primitives/css";
+import { useCiridaeLocale } from "./locale.js";
+import { Popover } from "./overlays.js";
+const root = css({ display: "flex", flexDirection: "column", gap: "layout.sectionGap" });
+const bar = css({ display: "flex", gap: "layout.tightGap", height: "8px" });
+const toneColor = cva({
+    variants: {
+        tone: {
+            neutral: { background: "fg.subtle" },
+            info: { background: "accent.blue" },
+            success: { background: "accent.green" },
+            warning: { background: "accent.yellow" },
+            danger: { background: "accent.red" },
+        },
+    },
+});
+const segmentButton = css({
+    minWidth: "8px",
+    height: "100%",
+    padding: "0",
+    border: "0",
+    borderRadius: "round",
+    cursor: "pointer",
+    transitionProperty: "opacity",
+    transitionDuration: "fast",
+    "&[data-dimmed]": { opacity: "0.5" },
+    _focusVisible: { focusRing: "outer" },
+});
+const legendRow = css({
+    display: "flex",
+    justifyContent: "space-between",
+    flexWrap: "wrap",
+    gap: "layout.contentGap",
+    paddingTop: "panel.comfortable",
+    borderTop: "1px solid token(colors.border.panel)",
+});
+const legendItem = css({ display: "inline-flex", alignItems: "center", gap: "layout.contentGap" });
+const legendKey = css({
+    display: "inline-flex",
+    alignItems: "center",
+    gap: "control.iconGap",
+    color: "fg.secondary",
+    fontSize: "code",
+});
+const swatch = css({ width: "6px", height: "12px", borderRadius: "control" });
+export function SegmentedBar({ segments, legend = true, renderDetail, onSegmentSelect, formatValue, className, ...props }) {
+    const { formatNumber } = useCiridaeLocale();
+    const format = formatValue ?? ((value) => formatNumber(value));
+    const [markedId, setMarkedId] = useState(null);
+    const mark = (id, marked) => setMarkedId((current) => (marked ? id : current === id ? null : current));
+    const colorOf = (segment) => ({
+        className: segment.color ? undefined : toneColor({ tone: segment.tone ?? "neutral" }),
+        style: segment.color ? { background: segment.color } : undefined,
+    });
+    return (_jsxs("div", { ...props, className: cx(root, className), "data-ciridae-ui": "", children: [_jsx("div", { className: bar, children: segments
+                    .filter((segment) => segment.value > 0)
+                    .map((segment) => {
+                    const color = colorOf(segment);
+                    const button = (_jsx("button", { type: "button", className: cx(segmentButton, color.className), style: { ...color.style, flexGrow: segment.value, flexBasis: 0 }, "aria-label": `${segment.label}, ${format(segment.value)}`, "data-dimmed": markedId !== null && markedId !== segment.id ? "" : undefined, onClick: onSegmentSelect && (() => onSegmentSelect(segment)), onMouseEnter: renderDetail ? undefined : () => mark(segment.id, true), onMouseLeave: renderDetail ? undefined : () => mark(segment.id, false) }));
+                    if (!renderDetail)
+                        return _jsx(Fragment, { children: button }, segment.id);
+                    return (_jsx(Popover, { openOnHover: true, density: "compact", width: "narrow", onOpenChange: (open) => mark(segment.id, open), trigger: button, children: renderDetail(segment) }, segment.id));
+                }) }), legend && (_jsx("div", { className: legendRow, children: segments.map((segment) => {
+                    const color = colorOf(segment);
+                    return (_jsxs("span", { className: legendItem, children: [_jsxs("span", { className: legendKey, children: [_jsx("span", { className: cx(swatch, color.className), style: color.style }), segment.label] }), format(segment.value)] }, segment.id));
+                }) }))] }));
+}

package/dist/components/select.d.ts

@@ -0,0 +1,84 @@
+import { type ReactNode } from "react";
+export type SelectOption = {
+    label: string;
+    value: string;
+};
+/**
+ * The kit's control heights: `small` is the small button's 30px, `medium` the default 38px. A
+ * small select is the glass pill beside other filters; a medium one is a form's field.
+ */
+export type ControlSize = "small" | "medium";
+export type SelectProps = {
+    options: readonly SelectOption[];
+    value?: string;
+    onValueChange?: (value: string | null) => void;
+    /** The locale's "Select…" by default. */
+    placeholder?: string;
+    /** Names the trigger for assistive tech; inside a labelled field the field's label does. */
+    label?: string;
+    /** `medium` is the Round 2 field height; `small` is the pill beside other filters. */
+    size?: ControlSize;
+    /** Defaults to the flat `field` at medium and the glass `raised` face when small. */
+    variant?: "field" | "raised";
+    /** Submits the value with an enclosing form under this name. */
+    name?: string;
+    /** Blocks the enclosing form's submission until a value is chosen. */
+    required?: boolean;
+    disabled?: boolean;
+};
+export declare function Select({ options, value, onValueChange, placeholder, label, size: controlSize, variant, name, required, disabled, }: SelectProps): import("@types/react").JSX.Element;
+export type SlicerProps = Omit<SelectProps, "size" | "variant" | "placeholder"> & {
+    /** What the slicer filters by, shown muted before the chosen value. */
+    label: string;
+};
+export declare function Slicer({ options, value, onValueChange, label, name, required, disabled, }: SlicerProps): import("@types/react").JSX.Element;
+export type ComboboxProps<Option extends SelectOption> = {
+    options: readonly Option[];
+    value?: string;
+    onValueChange?: (value: string | null) => void;
+    /** The locale's "Search…" by default. */
+    placeholder?: string;
+    /**
+     * Names the field for assistive tech; inside a labelled field the field's label does. Compact,
+     * it is also the slicer's visible dimension.
+     */
+    label?: string;
+    /** `medium` is a field to type in; `small` is a `Slicer` pill whose menu leads with search. */
+    size?: ControlSize;
+    /** Draws an option's row, such as an avatar before a name. The chosen value stays its label. */
+    renderOption?: (option: Option) => ReactNode;
+    /** The locale's "No results" by default. */
+    emptyMessage?: ReactNode;
+    /** Submits the selected value with an enclosing form under this name. */
+    name?: string;
+    /** Blocks the enclosing form's submission until a value is chosen. */
+    required?: boolean;
+    disabled?: boolean;
+    /** Searches on the server: receives the typed query, debounced. */
+    onSearch?: (query: string) => void;
+    /** The options for the latest query are still loading. */
+    loading?: boolean;
+    /** Opens on mount, such as an inline editor that starts with its list open. */
+    defaultOpen?: boolean;
+    onOpenChange?: (open: boolean) => void;
+    /** Focuses the field to type in on mount. */
+    autoFocus?: boolean;
+};
+/**
+ * A `Select` whose options are narrowed by typing. Without `onSearch`, Base UI filters `options`
+ * itself. With `onSearch`, the caller owns the options: typing reports the query once it pauses,
+ * and the list shows whatever `options` the caller passes back, with `loading` while it fetches.
+ */
+export declare function Combobox<Option extends SelectOption>({ options, value, onValueChange, placeholder: ownPlaceholder, label: ownLabel, size: controlSize, renderOption, emptyMessage, name, required, disabled, onSearch, loading, defaultOpen, onOpenChange, autoFocus, }: ComboboxProps<Option>): import("@types/react").JSX.Element;
+export declare function FilterPopover({ label, count, open, onOpenChange, onClear, children, }: {
+    /** The locale's "Filters" by default. */
+    label?: ReactNode;
+    /** How many of the filters inside are set; shown on the pill when any are. */
+    count?: number;
+    open?: boolean;
+    onOpenChange?: (open: boolean) => void;
+    /** Adds Clear under the filters while any are set. */
+    onClear?: () => void;
+    /** The filters, such as compact `Combobox` and `Slicer` pills. */
+    children: ReactNode;
+}): import("@types/react").JSX.Element;

package/dist/components/select.js

@@ -0,0 +1,374 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Combobox as BaseCombobox } from "@base-ui/react/combobox";
+import { Select as BaseSelect } from "@base-ui/react/select";
+import { CaretDownIcon, CaretUpIcon, CheckIcon, FunnelSimpleIcon } from "@phosphor-icons/react";
+import { useDebouncedCallback } from "@tanstack/react-pacer";
+import { useVirtualizer } from "@tanstack/react-virtual";
+import { useCallback, useEffect, useRef, useState } from "react";
+import { css, cva, cx } from "#primitives/css";
+import { Button } from "./button.js";
+import { useFieldControl, useInField } from "./field-context.js";
+import { HotkeyLayer } from "./hotkeys.js";
+import { icon, Spinner } from "./icon.js";
+import { useCiridaeLocale } from "./locale.js";
+import { Popover } from "./overlays.js";
+/*
+ * Open, a trigger and its menu read as one control: the menu sits flush on the trigger's edge, and
+ * the corners and border where they meet go square and quiet, on whichever side the menu opened.
+ */
+const attachedTrigger = {
+    "&[data-popup-open][data-popup-side=bottom]": {
+        borderBottomLeftRadius: "0",
+        borderBottomRightRadius: "0",
+        borderBottomColor: "border.subtle",
+    },
+    "&[data-popup-open][data-popup-side=top]": {
+        borderTopLeftRadius: "0",
+        borderTopRightRadius: "0",
+        borderTopColor: "border.subtle",
+    },
+};
+/** Which side of its trigger the open popup sits on, read from the popup's own `data-side`. */
+function usePopupSide() {
+    const [side, setSide] = useState(null);
+    const popupRef = useCallback((popup) => {
+        if (!popup)
+            return;
+        const read = () => setSide(popup.getAttribute("data-side"));
+        read();
+        const observer = new MutationObserver(read);
+        observer.observe(popup, { attributes: true, attributeFilter: ["data-side"] });
+        return () => observer.disconnect();
+    }, []);
+    return { side: side ?? undefined, popupRef };
+}
+/*
+ * Round 2 draws three select triggers. `field` is the input's flat well, for a form. `raised` is
+ * the glass face of a toolbar control; at the compact size it is a pill. Open, every one takes the
+ * control border its menu continues.
+ */
+const trigger = cva({
+    base: {
+        display: "inline-flex",
+        alignItems: "center",
+        justifyContent: "space-between",
+        gap: "control.iconGap",
+        paddingInline: "control.compactInline",
+        border: "1px solid",
+        borderRadius: "control",
+        color: "fg.primary",
+        fontFamily: "sans",
+        fontWeight: "medium",
+        letterSpacing: "compact",
+        whiteSpace: "nowrap",
+        cursor: "pointer",
+        transitionProperty: "background, border-color",
+        transitionDuration: "fast",
+        "&[data-popup-open]": { borderColor: "border.control" },
+        ...attachedTrigger,
+        _focusVisible: { focusRing: "outer" },
+        "&:disabled, &[data-disabled]": { opacity: "disabled", cursor: "not-allowed" },
+    },
+    variants: {
+        variant: {
+            field: { background: "bg.field", borderColor: "border.control" },
+            // The gradient edge is `data-edge="toolbar"` on the trigger; the border stays clear for it.
+            raised: {
+                background: "bg.glass",
+                borderColor: "transparent",
+                _hover: { background: "bg.glassHover" },
+            },
+        },
+        size: {
+            regular: { minWidth: "overlay.menu", height: "control.default", fontSize: "body" },
+            /** Sized to its value, for a row of filters beside other compact controls. */
+            compact: {
+                height: "control.small",
+                paddingInlineEnd: "control.iconInline",
+                fontSize: "caption",
+            },
+        },
+    },
+    compoundVariants: [
+        { variant: "raised", size: "compact", css: { borderRadius: "action" } },
+        { variant: "raised", size: "regular", css: { gap: "layout.controlGap" } },
+    ],
+    defaultVariants: { variant: "field", size: "regular" },
+});
+/** The positioner is the positioned element, so it carries the stacking order. */
+const positioner = css({ zIndex: "popover" });
+/* Flush: the menu is the trigger's width and continues its open border, its rows run edge to edge,
+   and their text lines up under the trigger's own. The trigger's edge is the seam between them. A
+   long list stops at `overlay.menuList`, or the room left in the viewport, and scrolls inside. */
+const popup = cva({
+    base: {
+        display: "flex",
+        flexDirection: "column",
+        width: "var(--anchor-width)",
+        maxHeight: "min(token(sizes.overlay.menuList), var(--available-height))",
+        padding: "none",
+        overflow: "hidden",
+        border: "1px solid token(colors.border.control)",
+        background: "bg.card",
+        boxShadow: "card",
+        "&[data-side=bottom]": { borderTop: "0", borderTopLeftRadius: "0", borderTopRightRadius: "0" },
+        "&[data-side=top]": {
+            borderBottom: "0",
+            borderBottomLeftRadius: "0",
+            borderBottomRightRadius: "0",
+        },
+    },
+    // The trigger's own corners: a field's near-square ones, a compact pill's rounder ones. A compact
+    // trigger is sized to its value, so its menu may run wider to keep every option whole.
+    variants: {
+        size: {
+            regular: { borderRadius: "control" },
+            compact: { borderRadius: "action", width: "max-content", minWidth: "var(--anchor-width)" },
+        },
+    },
+    defaultVariants: { size: "regular" },
+});
+const item = cva({
+    base: {
+        display: "flex",
+        alignItems: "center",
+        justifyContent: "space-between",
+        gap: "layout.contentGap",
+        height: "menu.item",
+        paddingInline: "control.compactInline",
+        color: "fg.muted",
+        fontSize: "caption",
+        cursor: "pointer",
+        _highlighted: { background: "bg.rowHover", color: "fg.primary" },
+        "&[data-selected]": { color: "fg.primary" },
+        // The menu is only as wide as its trigger, so a long option truncates rather than widening it.
+        "& > :first-child": { minWidth: "0", overflow: "hidden", textOverflow: "ellipsis" },
+        whiteSpace: "nowrap",
+    },
+    // A compact trigger's menu reads at the trigger's own text size.
+    variants: {
+        size: { regular: {}, compact: { height: "select.compactItem" } },
+    },
+    defaultVariants: { size: "compact" },
+});
+const itemIndicator = css({ display: "inline-flex", flexShrink: "0" });
+/** Scrolls inside the capped popup; opening scrolls the chosen option into view. */
+const list = css({ overflowY: "auto", overscrollBehavior: "contain" });
+function density(size) {
+    return size === "small" ? "compact" : "regular";
+}
+function SelectMenu({ options, size, popupRef, }) {
+    return (_jsx(BaseSelect.Portal, { children: _jsx(HotkeyLayer, { children: _jsx(BaseSelect.Positioner, { className: positioner, sideOffset: 0, align: "start", alignItemWithTrigger: false, children: _jsx(BaseSelect.Popup, { ref: popupRef, className: popup({ size }), "data-ciridae-ui": "", children: _jsx(BaseSelect.List, { className: list, children: options.map((option) => (_jsxs(BaseSelect.Item, { className: item({ size }), value: option.value, children: [_jsx(BaseSelect.ItemText, { children: option.label }), _jsx(BaseSelect.ItemIndicator, { className: itemIndicator, children: _jsx(CheckIcon, { className: icon({ size: "small" }) }) })] }, option.value))) }) }) }) }) }));
+}
+export function Select({ options, value, onValueChange, placeholder, label, size: controlSize = "small", variant = controlSize === "small" ? "raised" : "field", name, required, disabled, }) {
+    const { side, popupRef } = usePopupSide();
+    const { labels } = useCiridaeLocale();
+    const fieldIds = useFieldControl({});
+    const inField = useInField();
+    const size = density(controlSize);
+    return (_jsxs(BaseSelect.Root, { items: options, value: value, onValueChange: onValueChange, name: name, required: required, disabled: disabled, children: [_jsxs(BaseSelect.Trigger, { ...fieldIds, className: trigger({ variant, size }), "aria-label": label ?? (inField ? undefined : labels.select.label), "data-ciridae-ui": "", "data-edge": variant === "raised" ? "toolbar" : undefined, "data-popup-side": side, children: [_jsx(BaseSelect.Value, { placeholder: placeholder ?? labels.select.placeholder }), _jsx(BaseSelect.Icon, { children: _jsx(CaretUpIcon, { className: icon({ size: "compact" }) }) })] }), _jsx(SelectMenu, { options: options, size: size, popupRef: popupRef })] }));
+}
+/*
+ * A slicer is a filter's pill: the dimension it cuts by, then the value chosen, then the caret.
+ * The same menu as `Select`; only the trigger names what it filters.
+ */
+const slicerTrigger = css({
+    height: "control.compact",
+    borderRadius: "action",
+    fontSize: "caption",
+    justifyContent: "flex-start",
+});
+const slicerLabel = css({ color: "fg.muted" });
+const slicerValue = css({ flex: "1", textAlign: "start" });
+/** A combobox role takes no name from its content, so a slicer names its dimension and value. */
+function slicerName(label, options, value) {
+    const chosen = options.find((option) => option.value === value);
+    return chosen ? `${label}: ${chosen.label}` : label;
+}
+export function Slicer({ options, value, onValueChange, label, name, required, disabled, }) {
+    const { side, popupRef } = usePopupSide();
+    return (_jsxs(BaseSelect.Root, { items: options, value: value, onValueChange: onValueChange, name: name, required: required, disabled: disabled, children: [_jsxs(BaseSelect.Trigger, { className: cx(trigger({ variant: "raised", size: "compact" }), slicerTrigger), "aria-label": slicerName(label, options, value), "data-ciridae-ui": "", "data-edge": "toolbar", "data-popup-side": side, children: [_jsx("span", { className: slicerLabel, "data-slicer-label": "", children: label }), _jsx(BaseSelect.Value, { className: slicerValue }), _jsx(BaseSelect.Icon, { children: _jsx(CaretDownIcon, { className: icon({ size: "small" }) }) })] }), _jsx(SelectMenu, { options: options, size: "compact", popupRef: popupRef })] }));
+}
+/* A regular combobox is a field: the well holds the typed query and a caret, and open, it joins
+   its menu exactly as a `Select` does. The ring shows only while closed, since open the menu is
+   the focus. */
+const comboboxField = css({
+    display: "flex",
+    alignItems: "center",
+    width: "100%",
+    minWidth: "overlay.menu",
+    height: "control.default",
+    border: "1px solid token(colors.border.control)",
+    borderRadius: "control",
+    background: "bg.field",
+    ...attachedTrigger,
+    "&:has(input:focus-visible):not([data-popup-open])": { focusRing: "outer" },
+    "&[data-disabled]": { opacity: "disabled", cursor: "not-allowed" },
+});
+const comboboxInput = css({
+    flex: "1",
+    minWidth: "0",
+    height: "100%",
+    paddingInline: "control.compactInline",
+    border: "0",
+    background: "transparent",
+    color: "fg.primary",
+    fontFamily: "sans",
+    fontSize: "body",
+    fontWeight: "medium",
+    letterSpacing: "compact",
+    outline: "none",
+    "&::placeholder": { color: "fg.subtle" },
+    "&:disabled": { cursor: "not-allowed" },
+});
+const comboboxCaret = css({
+    display: "inline-flex",
+    alignItems: "center",
+    alignSelf: "stretch",
+    paddingInlineEnd: "control.compactInline",
+    border: "0",
+    background: "transparent",
+    color: "fg.primary",
+    cursor: "pointer",
+    outline: "none",
+    "&:disabled": { cursor: "not-allowed" },
+});
+/* A compact combobox is a slicer that searches: the same pill, with the query typed in a row at
+   the top of its menu. The menu keeps one width while typing narrows it. */
+const comboboxPopup = cva({
+    variants: {
+        size: {
+            regular: {},
+            compact: { width: "max(var(--anchor-width), token(sizes.overlay.menu))" },
+        },
+    },
+});
+const comboboxSearch = css({
+    flexShrink: "0",
+    width: "100%",
+    height: "select.compactItem",
+    paddingInline: "control.compactInline",
+    border: "0",
+    borderBottom: "1px solid token(colors.border.subtle)",
+    background: "transparent",
+    color: "fg.primary",
+    fontFamily: "sans",
+    fontSize: "caption",
+    fontWeight: "medium",
+    letterSpacing: "compact",
+    outline: "none",
+    "&::placeholder": { color: "fg.subtle" },
+});
+const optionContent = css({
+    display: "flex",
+    alignItems: "center",
+    gap: "control.iconGap",
+    flex: "1",
+    minWidth: "0",
+    overflow: "hidden",
+    textOverflow: "ellipsis",
+});
+const emptyMessageStyle = css({
+    paddingBlock: "control.compactBlock",
+    paddingInline: "control.compactInline",
+    color: "fg.muted",
+    fontSize: "caption",
+    // Base UI keeps the empty slot mounted while options are listed.
+    "&:empty": { display: "none" },
+});
+/** How long typing pauses before a server-searched `Combobox` asks for new options. */
+const searchDebounceMs = 300;
+/**
+ * A `Select` whose options are narrowed by typing. Without `onSearch`, Base UI filters `options`
+ * itself. With `onSearch`, the caller owns the options: typing reports the query once it pauses,
+ * and the list shows whatever `options` the caller passes back, with `loading` while it fetches.
+ */
+export function Combobox({ options, value, onValueChange, placeholder: ownPlaceholder, label: ownLabel, size: controlSize = "medium", renderOption, emptyMessage, name, required, disabled, onSearch, loading = false, defaultOpen, onOpenChange, autoFocus, }) {
+    const { labels } = useCiridaeLocale();
+    const fieldIds = useFieldControl({});
+    const inField = useInField();
+    const size = density(controlSize);
+    const placeholder = ownPlaceholder ?? labels.common.searchPlaceholder;
+    const label = ownLabel ?? labels.select.searchLabel;
+    const inputLabel = ownLabel ?? (inField ? undefined : labels.select.searchLabel);
+    // A server search replaces `options`; keep the chosen option so the input still names it.
+    const [chosen, setChosen] = useState(null);
+    const search = useDebouncedCallback((query) => onSearch?.(query), {
+        wait: searchDebounceMs,
+    });
+    const selected = options.find((option) => option.value === value) ?? (chosen?.value === value ? chosen : null);
+    // Past `virtualizeOptionsPast` options the list draws only those near the view; the arrow
+    // keys still walk every option, and the list scrolls to the one they land on.
+    const virtualized = options.length > virtualizeOptionsPast;
+    const scrollToOption = useRef(null);
+    return (_jsxs(BaseCombobox.Root, { items: options, value: selected, onValueChange: (option) => {
+            setChosen(option);
+            onValueChange?.(option?.value ?? null);
+        }, name: name, required: required, disabled: disabled, defaultOpen: defaultOpen, onOpenChange: onOpenChange && ((open) => onOpenChange(open)), virtualized: virtualized, onItemHighlighted: (_option, details) => {
+            if (virtualized && details.reason === "keyboard")
+                scrollToOption.current?.(details.index);
+        }, ...(onSearch && {
+            filter: null,
+            onInputValueChange: (input, details) => {
+                if (details.reason === "input-change" || details.reason === "input-clear")
+                    search(input);
+            },
+        }), children: [size === "compact" ? (_jsxs(BaseCombobox.Trigger, { className: cx(trigger({ variant: "raised", size: "compact" }), slicerTrigger), "aria-label": slicerName(label, options, value), "data-ciridae-ui": "", "data-edge": "toolbar", children: [_jsx("span", { className: slicerLabel, "data-slicer-label": "", children: label }), _jsx("span", { className: slicerValue, children: selected?.label }), _jsx(CaretDownIcon, { className: icon({ size: "small" }) })] })) : (_jsxs(BaseCombobox.InputGroup, { className: comboboxField, "data-ciridae-ui": "", children: [_jsx(BaseCombobox.Input, { ...fieldIds, className: comboboxInput, "aria-label": inputLabel, placeholder: placeholder, autoFocus: autoFocus }), _jsx(BaseCombobox.Trigger, { className: comboboxCaret, "aria-label": label, tabIndex: -1, children: _jsx(CaretUpIcon, { className: icon({ size: "compact" }) }) })] })), _jsx(BaseCombobox.Portal, { children: _jsx(HotkeyLayer, { children: _jsx(BaseCombobox.Positioner, { className: positioner, sideOffset: 0, align: "start", children: _jsxs(BaseCombobox.Popup, { className: css(popup.raw({ size }), comboboxPopup.raw({ size })), "data-ciridae-ui": "", children: [size === "compact" && (_jsx(BaseCombobox.Input, { className: comboboxSearch, "aria-label": label, placeholder: placeholder })), loading ? (_jsx("div", { className: emptyMessageStyle, children: _jsx(Spinner, { size: "compact" }) })) : (_jsx(BaseCombobox.Empty, { className: emptyMessageStyle, children: emptyMessage ?? labels.common.noResults })), virtualized ? (_jsx(VirtualOptions, { size: size, renderOption: renderOption, scrollToOption: scrollToOption })) : (_jsx(BaseCombobox.List, { className: list, children: (option) => (_jsxs(BaseCombobox.Item, { className: item({ size }), value: option, children: [_jsx("span", { className: optionContent, children: renderOption ? renderOption(option) : option.label }), _jsx(BaseCombobox.ItemIndicator, { className: itemIndicator, children: _jsx(CheckIcon, { className: icon({ size: "small" }) }) })] }, option.value)) }))] }) }) }) })] }));
+}
+/** Past this many options a combobox draws only those near the view. */
+const virtualizeOptionsPast = 50;
+/** An option row's height before it is measured. */
+const optionHeights = { regular: 38, compact: 30 };
+// The options lie over a box as tall as all of them, each moved down to its place.
+const virtualOptions = css({
+    position: "relative",
+    "& > *": { position: "absolute", top: "0", insetInline: "0" },
+});
+/** The filtered options near the view, inside the combobox's list, which scrolls them. */
+function VirtualOptions({ size, renderOption, scrollToOption, }) {
+    const shown = BaseCombobox.useFilteredItems();
+    const [listElement, setListElement] = useState(null);
+    const virtualizer = useVirtualizer({
+        count: shown.length,
+        getScrollElement: () => listElement,
+        estimateSize: () => optionHeights[size],
+        getItemKey: (index) => shown[index]?.value ?? index,
+        overscan: 8,
+    });
+    useEffect(() => {
+        scrollToOption.current = (index) => virtualizer.scrollToIndex(index, { align: "auto" });
+        return () => {
+            scrollToOption.current = null;
+        };
+    }, [scrollToOption, virtualizer]);
+    return (_jsx(BaseCombobox.List, { ref: setListElement, className: list, children: _jsx("div", { className: virtualOptions, style: { height: virtualizer.getTotalSize() }, children: virtualizer.getVirtualItems().map((virtualItem) => {
+                const option = shown[virtualItem.index];
+                return (option && (_jsxs(BaseCombobox.Item, { ref: virtualizer.measureElement, "data-index": virtualItem.index, index: virtualItem.index, value: option, className: item({ size }), style: { transform: `translateY(${virtualItem.start}px)` }, children: [_jsx("span", { className: optionContent, children: renderOption ? renderOption(option) : option.label }), _jsx(BaseCombobox.ItemIndicator, { className: itemIndicator, children: _jsx(CheckIcon, { className: icon({ size: "small" }) }) })] }, option.value)));
+            }) }) }));
+}
+/*
+ * Filters a toolbar has no room to show: a slicer-faced pill that counts the ones set, opening a
+ * popover that stacks them, each as wide as the stack.
+ */
+const filterCount = css({
+    display: "inline-grid",
+    placeItems: "center",
+    minWidth: "indicator.count",
+    height: "indicator.count",
+    paddingInline: "layout.tightGap",
+    borderRadius: "control",
+    background: "bg.selected",
+    color: "fg.primary",
+    fontSize: "avatar.small",
+    fontVariantNumeric: "tabular-nums",
+});
+const filterStack = css({
+    display: "grid",
+    gap: "layout.controlGap",
+    width: "overlay.tooltip",
+    maxWidth: "100%",
+});
+export function FilterPopover({ label, count = 0, open, onOpenChange, onClear, children, }) {
+    const { labels } = useCiridaeLocale();
+    return (_jsx(Popover, { open: open, onOpenChange: onOpenChange && ((next) => onOpenChange(next)), density: "compact", trigger: _jsxs("button", { type: "button", className: cx(trigger({ variant: "raised", size: "compact" }), slicerTrigger), "data-ciridae-ui": "", "data-edge": "toolbar", children: [_jsx(FunnelSimpleIcon, { className: icon({ size: "small" }) }), label ?? labels.select.filters, count > 0 && _jsx("span", { className: filterCount, children: count })] }), children: _jsxs("div", { className: filterStack, children: [children, onClear && count > 0 && (_jsx(Button, { variant: "ghost", className: css({ justifySelf: "start" }), onClick: onClear, children: labels.filters.clearAll }))] }) }));
+}

package/dist/components/settings.d.ts

@@ -0,0 +1,34 @@
+import { type PanelProps } from "./panel.js";
+import type { ComponentProps, ReactElement, ReactNode } from "react";
+export type SettingsSectionLink<Value extends string = string> = {
+    value: Value;
+    label: string;
+    icon?: ReactNode;
+    /** Makes the section a link to this address. */
+    href?: string;
+    /** The section's link element, such as a router's `<Link to="...">`. */
+    render?: ReactElement;
+};
+export type SettingsLayoutProps<Value extends string> = Omit<ComponentProps<"div">, "children" | "onChange"> & {
+    sections: readonly SettingsSectionLink<Value>[];
+    /** The open section. */
+    value: Value;
+    /** A section was chosen; links navigate on their own and report it too. */
+    onValueChange?: (value: Value) => void;
+    children: ReactNode;
+    labels?: Partial<{
+        navigation: string;
+    }>;
+};
+export declare function SettingsLayout<Value extends string>({ sections, value, onValueChange, children, labels: ownLabels, className, ...props }: SettingsLayoutProps<Value>): import("@types/react").JSX.Element;
+/** A settings section's single column of panels; the shell header carries the page's title. */
+export declare function SettingsColumn({ className, ...props }: ComponentProps<"div">): import("@types/react").JSX.Element;
+/** One group of settings, under an optional heading with an optional action beside it. */
+export declare function SettingsPanel({ title, action, children, ...props }: Omit<PanelProps, "title" | "padding" | "tone"> & {
+    title?: ReactNode;
+    action?: ReactNode;
+}): import("@types/react").JSX.Element;
+/** A label and its value or control on one line inside a settings panel. */
+export declare function SettingsRow({ label, children, className, ...props }: ComponentProps<"div"> & {
+    label: ReactNode;
+}): import("@types/react").JSX.Element;