@sableui/react 0.6.2 → 0.7.1

package/dist/components/disclosure-picker/disclosure-picker.js

@@ -0,0 +1,417 @@
+"use client";
+
+// src/components/disclosure-picker/disclosure-picker.tsx
+import {
+  createContext,
+  useCallback,
+  useContext,
+  useEffect,
+  useMemo,
+  useRef,
+  useState
+} from "react";
+import { Icon } from "../../icon/index.js";
+import { cn } from "../../lib/cn.js";
+import { FIELD_SHELL_XS } from "../../lib/field-shell.js";
+import { useIsomorphicLayoutEffect } from "../../lib/use-isomorphic-layout-effect.js";
+import { Collapsible, CollapsiblePanel, CollapsibleTrigger } from "../collapsible/collapsible.js";
+import { SearchInput } from "../search-input/search-input.js";
+import { jsx, jsxs } from "react/jsx-runtime";
+var Context = createContext(null);
+function usePicker(part) {
+  const ctx = useContext(Context);
+  if (!ctx) throw new Error(`<${part}> must be rendered inside <DisclosurePicker>.`);
+  return ctx;
+}
+function useDisclosurePicker() {
+  const { open, setOpen, size } = usePicker("useDisclosurePicker");
+  return { open, close: () => setOpen(false), size };
+}
+var SEARCH_SELECTOR = "[data-disclosure-picker-search] input";
+var OPTION = '[role="option"]';
+var ENABLED_OPTION = '[role="option"]:not([aria-disabled="true"])';
+var CHOSEN_OPTION = '[role="option"][aria-selected="true"]';
+function chosenOption(panel) {
+  if (!panel) return null;
+  return panel.querySelector(CHOSEN_OPTION) ?? panel.querySelector(ENABLED_OPTION);
+}
+function DisclosurePicker({
+  open: openProp,
+  defaultOpen = false,
+  onOpenChange,
+  size = "md",
+  className,
+  ref,
+  children,
+  ...props
+}) {
+  const [uncontrolled, setUncontrolled] = useState(defaultOpen);
+  const controlled = openProp !== void 0;
+  const open = controlled ? openProp : uncontrolled;
+  const rootRef = useRef(null);
+  const triggerRef = useRef(null);
+  const panelRef = useRef(null);
+  const intentRef = useRef(null);
+  const focusInsideRef = useRef(false);
+  const setOpen = useCallback(
+    (next) => {
+      if (!controlled) setUncontrolled(next);
+      onOpenChange?.(next);
+    },
+    [controlled, onOpenChange]
+  );
+  const focusList = useCallback((preferSearch) => {
+    const panel = panelRef.current;
+    const search = preferSearch ? panel?.querySelector(SEARCH_SELECTOR) : null;
+    (search ?? chosenOption(panel))?.focus({ preventScroll: true });
+  }, []);
+  useEffect(() => {
+    const root = rootRef.current;
+    if (!open || !root) {
+      const active = document.activeElement;
+      const lost = !active || active === document.body;
+      if (panelRef.current?.contains(active) || focusInsideRef.current && lost) {
+        triggerRef.current?.focus({ preventScroll: true });
+      }
+      focusInsideRef.current = false;
+      return;
+    }
+    const observer = typeof ResizeObserver === "undefined" ? null : new ResizeObserver(() => root.scrollIntoView?.({ block: "nearest" }));
+    observer?.observe(root);
+    const settle = window.setTimeout(() => observer?.disconnect(), 500);
+    const frame = requestAnimationFrame(() => {
+      const panel = panelRef.current;
+      const chosen = panel?.querySelector(CHOSEN_OPTION);
+      const list = chosen?.closest('[role="listbox"]');
+      if (list && chosen && list.scrollHeight > list.clientHeight) {
+        list.scrollTop = chosen.offsetTop - (list.clientHeight - chosen.offsetHeight) / 2;
+      }
+      const intent = intentRef.current;
+      intentRef.current = null;
+      if (!intent) return;
+      const hasSearch = !!panel?.querySelector(SEARCH_SELECTOR);
+      const finePointer = typeof window.matchMedia === "function" && window.matchMedia("(pointer: fine)").matches;
+      if (intent === "keyboard") focusList(true);
+      else if (hasSearch && finePointer) focusList(true);
+    });
+    return () => {
+      observer?.disconnect();
+      window.clearTimeout(settle);
+      cancelAnimationFrame(frame);
+    };
+  }, [open, focusList]);
+  const value = useMemo(
+    () => ({ open, setOpen, size, triggerRef, panelRef, intentRef, focusList }),
+    [open, setOpen, size, focusList]
+  );
+  return /* @__PURE__ */ jsx(Context.Provider, { value, children: /* @__PURE__ */ jsx(
+    Collapsible,
+    {
+      ref: (node) => {
+        rootRef.current = node;
+        if (typeof ref === "function") ref(node);
+        else if (ref) ref.current = node;
+      },
+      open,
+      onOpenChange: (next) => {
+        if (!next) intentRef.current = null;
+        setOpen(next);
+      },
+      "data-size": size,
+      onFocus: (event) => {
+        if (panelRef.current?.contains(event.target)) focusInsideRef.current = true;
+      },
+      onBlur: (event) => {
+        if (!panelRef.current?.contains(event.relatedTarget)) focusInsideRef.current = false;
+      },
+      className: cn(
+        // Breathing room when the row scrolls itself into view.
+        "scroll-my-3",
+        size === "xs" ? "rounded-[var(--panel-field-radius,var(--radius-xs))]" : "rounded-sm",
+        // Open, the row and its list share one recessed well.
+        open && "sable-well",
+        className
+      ),
+      ...props,
+      children
+    }
+  ) });
+}
+DisclosurePicker.displayName = "DisclosurePicker";
+function DisclosurePickerTrigger({
+  label,
+  media,
+  children,
+  className,
+  ref,
+  onKeyDown,
+  onPointerDown,
+  ...props
+}) {
+  const { open, setOpen, size, triggerRef, intentRef, focusList } = usePicker("DisclosurePickerTrigger");
+  return /* @__PURE__ */ jsxs(
+    CollapsibleTrigger,
+    {
+      ref: (node) => {
+        triggerRef.current = node;
+        if (typeof ref === "function") ref(node);
+        else if (ref) ref.current = node;
+      },
+      onPointerDown: (event) => {
+        intentRef.current = "pointer";
+        onPointerDown?.(event);
+      },
+      onKeyDown: (event) => {
+        onKeyDown?.(event);
+        if (event.defaultPrevented) return;
+        if (event.key === "Enter" || event.key === " ") intentRef.current = "keyboard";
+        if (event.key === "Escape" && open) {
+          event.preventDefault();
+          event.stopPropagation();
+          setOpen(false);
+        }
+        if (event.key === "ArrowDown") {
+          event.preventDefault();
+          if (open) focusList(true);
+          else {
+            intentRef.current = "keyboard";
+            setOpen(true);
+          }
+        }
+      },
+      className: cn(
+        "group/disclosure-picker flex w-full items-center gap-2 text-start text-foreground motion-interactive",
+        "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring disabled:cursor-not-allowed disabled:opacity-50",
+        size === "xs" ? cn("h-(--control-xs) px-1.5", FIELD_SHELL_XS) : cn(
+          // Hover is a step off whatever surface the row sits on, never a
+          // fixed fill: a popover-coloured hover read as a hole in the panel.
+          "h-(--control-md) rounded-[inherit] px-3 sable-surface-interactive",
+          // Closed, the row is its own well; open, the root's well holds both.
+          !open && "sable-well"
+        ),
+        className
+      ),
+      ...props,
+      children: [
+        label != null ? /* @__PURE__ */ jsx("span", { className: cn("shrink-0 truncate text-muted-foreground", size === "xs" ? "w-16 text-ui-md" : "w-20 text-body-sm"), children: label }) : null,
+        media != null ? /* @__PURE__ */ jsx("span", { className: "flex shrink-0 items-center", children: media }) : null,
+        /* @__PURE__ */ jsx("span", { className: cn("min-w-0 flex-1 truncate", size === "xs" ? "text-ui-md" : "text-body-md"), children }),
+        /* @__PURE__ */ jsx(
+          Icon,
+          {
+            name: "chevron-down",
+            className: "shrink-0 text-sm text-muted-foreground motion-interactive group-data-[panel-open]/disclosure-picker:rotate-180"
+          }
+        )
+      ]
+    }
+  );
+}
+DisclosurePickerTrigger.displayName = "DisclosurePickerTrigger";
+function DisclosurePickerPanel({ search, children, className, ...props }) {
+  const { open, setOpen, panelRef, focusList } = usePicker("DisclosurePickerPanel");
+  const clear = search?.value ? search.onValueChange : null;
+  useEffect(() => {
+    if (!open && clear) clear("");
+  }, [open, clear]);
+  return /* @__PURE__ */ jsx(CollapsiblePanel, { ...props, children: /* @__PURE__ */ jsxs(
+    "div",
+    {
+      ref: panelRef,
+      onKeyDown: (event) => {
+        if (event.key === "Escape") {
+          event.preventDefault();
+          event.stopPropagation();
+          const target = event.target;
+          if (search?.value && target.matches(SEARCH_SELECTOR)) search.onValueChange("");
+          else setOpen(false);
+        } else if (event.key === "ArrowDown" && event.target.matches(SEARCH_SELECTOR)) {
+          event.preventDefault();
+          focusList(false);
+        }
+      },
+      className: cn("grid gap-1 border-t border-hairline p-1.5", className),
+      children: [
+        search ? /* @__PURE__ */ jsx("div", { "data-disclosure-picker-search": "", children: /* @__PURE__ */ jsx(
+          SearchInput,
+          {
+            value: search.value,
+            onValueChange: search.onValueChange,
+            placeholder: search.placeholder ?? "Search",
+            "aria-label": search.label ?? search.placeholder ?? "Search"
+          }
+        ) }) : null,
+        children
+      ]
+    }
+  ) });
+}
+DisclosurePickerPanel.displayName = "DisclosurePickerPanel";
+var ListCtx = createContext(null);
+var TYPEAHEAD_MS = 500;
+function textOf(option) {
+  return (option.dataset.textValue ?? option.querySelector("[data-disclosure-picker-label]")?.textContent ?? option.textContent ?? "").trim().toLowerCase();
+}
+function moveTo(option) {
+  if (!option) return;
+  option.focus({ preventScroll: true });
+  option.scrollIntoView?.({ block: "nearest" });
+}
+function DisclosurePickerList({ value, onValueChange, className, ref, onKeyDown, onFocus, children, ...props }) {
+  const { setOpen, size, panelRef } = usePicker("DisclosurePickerList");
+  const listRef = useRef(null);
+  const typeahead = useRef({ text: "", timer: 0 });
+  const pick = useCallback(
+    (next) => {
+      if (next !== value) onValueChange(next);
+      setOpen(false);
+    },
+    [value, onValueChange, setOpen]
+  );
+  useIsomorphicLayoutEffect(() => {
+    const list = listRef.current;
+    if (!list) return;
+    const options = [...list.querySelectorAll(OPTION)];
+    const enabled = (option) => option.getAttribute("aria-disabled") !== "true";
+    const stop = options.find((option) => option === document.activeElement) ?? options.find((option) => option.getAttribute("aria-selected") === "true" && enabled(option)) ?? options.find(enabled);
+    for (const option of options) option.tabIndex = option === stop ? 0 : -1;
+  });
+  useEffect(() => () => window.clearTimeout(typeahead.current.timer), []);
+  const handleKeyDown = (event) => {
+    onKeyDown?.(event);
+    const list = listRef.current;
+    if (event.defaultPrevented || !list) return;
+    const current = event.target.closest(OPTION);
+    if (!current || !list.contains(current)) return;
+    const options = [...list.querySelectorAll(ENABLED_OPTION)];
+    const index = options.indexOf(current);
+    const run = typeahead.current;
+    const typing = event.key.length === 1 && !event.ctrlKey && !event.metaKey && !event.altKey;
+    if (typing && (event.key !== " " || run.text)) {
+      event.preventDefault();
+      window.clearTimeout(run.timer);
+      run.text += event.key.toLowerCase();
+      run.timer = window.setTimeout(() => {
+        run.text = "";
+      }, TYPEAHEAD_MS);
+      const repeat = [...run.text].every((char) => char === run.text[0]);
+      const needle = repeat ? run.text[0] : run.text;
+      const from = repeat ? index + 1 : Math.max(index, 0);
+      const ordered = [...options.slice(from), ...options.slice(0, from)];
+      moveTo(ordered.find((option) => textOf(option).startsWith(needle)));
+      return;
+    }
+    switch (event.key) {
+      case "ArrowDown":
+        event.preventDefault();
+        moveTo(options[Math.min(index + 1, options.length - 1)]);
+        break;
+      case "ArrowUp": {
+        event.preventDefault();
+        const search = index <= 0 ? panelRef.current?.querySelector(SEARCH_SELECTOR) : null;
+        if (search) search.focus();
+        else moveTo(options[Math.max(index - 1, 0)]);
+        break;
+      }
+      case "Home":
+        event.preventDefault();
+        moveTo(options[0]);
+        break;
+      case "End":
+        event.preventDefault();
+        moveTo(options[options.length - 1]);
+        break;
+      case "Enter":
+      case " ": {
+        event.preventDefault();
+        const next = current.getAttribute("aria-disabled") === "true" ? void 0 : current.dataset.value;
+        if (next !== void 0) pick(next);
+        break;
+      }
+    }
+  };
+  const context = useMemo(() => ({ value, size, pick }), [value, size, pick]);
+  return /* @__PURE__ */ jsx(ListCtx.Provider, { value: context, children: /* @__PURE__ */ jsx(
+    "div",
+    {
+      ref: (node) => {
+        listRef.current = node;
+        if (typeof ref === "function") ref(node);
+        else if (ref) ref.current = node;
+      },
+      role: "listbox",
+      onKeyDown: handleKeyDown,
+      onFocus: (event) => {
+        onFocus?.(event);
+        const option = event.target.closest(OPTION);
+        if (!option || !listRef.current?.contains(option)) return;
+        for (const other of listRef.current.querySelectorAll(OPTION)) other.tabIndex = other === option ? 0 : -1;
+      },
+      className: cn("relative grid max-h-64 gap-0.5 overflow-y-auto scrollbar-quiet", className),
+      ...props,
+      children
+    }
+  ) });
+}
+DisclosurePickerList.displayName = "DisclosurePickerList";
+function DisclosurePickerOption({
+  value,
+  children,
+  media,
+  note,
+  disabled = false,
+  textValue,
+  className,
+  onClick,
+  ...props
+}) {
+  const list = useContext(ListCtx);
+  if (!list) throw new Error("<DisclosurePickerOption> must be rendered inside <DisclosurePickerList>.");
+  const { size, pick } = list;
+  const selected = list.value === value;
+  return /* @__PURE__ */ jsxs(
+    "div",
+    {
+      ...props,
+      role: "option",
+      "aria-selected": selected,
+      "aria-disabled": disabled || void 0,
+      "data-value": value,
+      "data-text-value": textValue,
+      "data-selected": selected ? "" : void 0,
+      onClick: (event) => {
+        onClick?.(event);
+        if (!event.defaultPrevented && !disabled) pick(value);
+      },
+      className: cn(
+        "flex items-center gap-3 rounded-sm px-(--item-px) text-start motion-interactive",
+        "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring aria-disabled:cursor-not-allowed aria-disabled:opacity-50",
+        size === "xs" ? "min-h-(--control-xs)" : "min-h-(--control-sm) py-1",
+        // Chosen: lifted out of the well, like a segmented control's knob.
+        selected ? "bg-popover shadow-sm" : "sable-surface-interactive",
+        className
+      ),
+      children: [
+        /* @__PURE__ */ jsxs("span", { className: "flex min-w-0 flex-1 items-center gap-2", children: [
+          media != null ? /* @__PURE__ */ jsx("span", { className: "flex shrink-0 items-center", children: media }) : null,
+          /* @__PURE__ */ jsx("span", { "data-disclosure-picker-label": "", className: cn("min-w-0 truncate", size === "xs" ? "text-ui-md" : "text-body-md"), children })
+        ] }),
+        note != null ? /* @__PURE__ */ jsx("span", { className: cn("shrink-0 text-muted-foreground", size === "xs" ? "text-ui-sm" : "text-caption"), children: note }) : selected ? /* @__PURE__ */ jsx(Icon, { name: "check", className: "shrink-0 text-sm" }) : null
+      ]
+    }
+  );
+}
+DisclosurePickerOption.displayName = "DisclosurePickerOption";
+function DisclosurePickerEmpty({ children, className }) {
+  return /* @__PURE__ */ jsx("p", { className: cn("px-2.5 py-2 text-caption text-muted-foreground", className), children });
+}
+DisclosurePickerEmpty.displayName = "DisclosurePickerEmpty";
+export {
+  DisclosurePicker,
+  DisclosurePickerEmpty,
+  DisclosurePickerList,
+  DisclosurePickerOption,
+  DisclosurePickerPanel,
+  DisclosurePickerTrigger,
+  useDisclosurePicker
+};

package/dist/components/disclosure-picker/disclosure-picker.meta.js

@@ -0,0 +1,213 @@
+// src/components/disclosure-picker/disclosure-picker.meta.ts
+var disclosurePickerMeta = {
+  name: "DisclosurePicker",
+  summary: "A property row that names the current value and opens its list in place, beneath the row, instead of in a popup \u2014 for a tool panel or settings column where the choice is made while looking at what it changes. Built on Collapsible; the list is a listbox \u2014 arrow keys move, Enter or a click picks, applies and closes \u2014 and an optional search field filters long lists.",
+  status: "stable",
+  keywords: [
+    "disclosure picker",
+    "inline picker",
+    "in-place select",
+    "expanding list",
+    "property row",
+    "font picker",
+    "preset picker",
+    "inspector",
+    "picker row"
+  ],
+  usage: {
+    description: "Use DisclosurePicker for one-of-many choices in a docked panel or inspector where a popup would cover the preview the choice is about: the row shows the current value (in its own face, with a tile, as the content warrants), and the list opens beneath it, pushing the panel down. Use Select for a form field or anywhere a popup is fine; use Combobox when people type to find an option among hundreds; use RadioGroup or RadioCard when every option should stay visible. Nothing applies while arrowing through the list \u2014 only Enter, Space or a click picks \u2014 so it suits choices with a cost (a confirm, a font load, a reset); where each option should apply as focus lands on it, that is a radio group (ThemeSelector, RadioGroup).",
+    bestPractices: [
+      {
+        guidance: "do",
+        description: "Enable search (`search` on DisclosurePickerPanel) only for long lists \u2014 roughly a dozen options or more, i.e. once the list scrolls. A short list (a handful of presets) reads faster with no field to skip past; the panel then has no search row and no gap."
+      },
+      {
+        guidance: "do",
+        description: "Show the value as the thing it is: a font row renders the family in its own face, a theme row leads with a ThemePreview tile in `media`. The row is a preview of the choice, not a label for it."
+      },
+      {
+        guidance: "do",
+        description: 'Use `size="xs"` in a property grid (a compact Density / PanelSection), where it sits on the inset panel-field fill beside ScrubField and an xs SelectTrigger. Keep `md` in a settings column or a simple panel.'
+      },
+      {
+        guidance: "do",
+        description: "When several rows share a panel, control `open` from the parent so only one list is open at a time \u2014 two open lists push each other and the preview out of view."
+      },
+      {
+        guidance: "do",
+        description: "Use it for a choice with a cost \u2014 one that opens a confirm, loads something, or resets other settings. Arrow keys only move focus; onValueChange fires once, on Enter, Space or a click, and only when the pick differs from `value`."
+      },
+      {
+        guidance: "do",
+        description: "Give options a leading visual with `media` (a ThemePreview tile, a swatch) instead of nesting another component's list: ThemeSelector's radio list applies each theme as the arrow keys land on it, which defeats commit-on-Enter. A list the picker cannot express (a Tree) can still close the row with `useDisclosurePicker().close()`."
+      },
+      {
+        guidance: "do",
+        description: "Render DisclosurePickerEmpty in place of the list when a search matches nothing, not inside it \u2014 a listbox holds only options."
+      },
+      {
+        guidance: "dont",
+        description: "Use it in a page-register form. A form field that pushes the form down on open reads as a layout jump; that is Select's job."
+      },
+      {
+        guidance: "dont",
+        description: "Rebuild the row from a Collapsible with hand-copied classes. The disclosure, the well, the hover step, the xs field shell, focus return and scroll-into-view all live here; two hand copies of this row in one panel is how it came to exist."
+      },
+      {
+        guidance: "dont",
+        description: "Turn search on for a short list just because the other rows have it. A search field over six options is a control with nothing to do."
+      }
+    ],
+    anatomy: [
+      { name: "DisclosurePicker", required: true, description: "Root. Owns open state, size, focus return and scroll-into-view." },
+      { name: "DisclosurePickerTrigger", required: true, description: "The row: optional `label` caption, optional `media`, the value, and a chevron that flips when open." },
+      { name: "DisclosurePickerPanel", required: true, description: "What opens beneath the row: the opt-in search field, then the list." },
+      { name: "DisclosurePickerList", required: false, description: "A listbox of options that scrolls past 16rem. Arrow keys move; Enter, Space or a click picks." },
+      { name: "DisclosurePickerOption", required: false, description: "One option row, with optional leading media and trailing note. Chosen, it lifts out of the well; focused, it takes the ring." },
+      { name: "DisclosurePickerEmpty", required: false, description: "The no-match line, rendered in place of the list when a search filters everything out." }
+    ]
+  },
+  related: {
+    components: ["Collapsible", "Select", "Combobox", "SearchInput", "RadioGroup", "ThemeSelector", "FontPicker", "PropertyRow"]
+  },
+  props: [
+    { name: "open", type: "boolean", description: "Controlled open state. Pair with onOpenChange." },
+    { name: "defaultOpen", type: "boolean", default: "false", description: "Uncontrolled initial open state." },
+    { name: "onOpenChange", type: "(open: boolean) => void", description: "Called with the next open state \u2014 from the trigger, a pick, or Escape." },
+    {
+      name: "size",
+      type: '"md" | "xs"',
+      default: '"md"',
+      description: "md is a --control-md row (40px comfortable) in a settings column, its own well when closed. xs is the property-grid rung: a --control-xs row on the inset panel-field fill with ui-tier type. Height, padding, radius, type and surface move together."
+    },
+    { name: "className", type: "string", description: "Merged onto the root (layout only \u2014 the look comes from size)." }
+  ],
+  subcomponents: [
+    {
+      name: "DisclosurePickerTrigger",
+      type: "{ label?: ReactNode; media?: ReactNode; children?: ReactNode } + Base UI Collapsible.Trigger props",
+      description: "The row. `label` is a muted leading caption on a fixed column so stacked rows align; `media` a leading visual (a ThemePreview tile); children the value, truncated on one line. ArrowDown opens it, and steps into the list once open."
+    },
+    {
+      name: "DisclosurePickerPanel",
+      type: "{ search?: { value: string; onValueChange(value: string): void; placeholder?: string; label?: string } } + Collapsible.Panel props",
+      description: "Opens beneath the row. `search` opts in to a SearchInput above the list (off by default); it is controlled because the consumer filters, and it is cleared when the row closes. Escape clears a query first, then closes; ArrowDown in the field steps into the list."
+    },
+    {
+      name: "DisclosurePickerList",
+      type: "{ value: string; onValueChange(value: string): void; aria-label?: string } + div props",
+      description: "A listbox. ArrowUp/ArrowDown, Home/End and type-ahead move focus without applying anything (ArrowUp from the first option returns to the search field); Enter, Space or a click picks the focused option \u2014 onValueChange fires once, only when it differs from `value` \u2014 and closes the row. Escape closes without a pick."
+    },
+    {
+      name: "DisclosurePickerOption",
+      type: "{ value: string; children?: ReactNode; media?: ReactNode; note?: ReactNode; disabled?: boolean; textValue?: string }",
+      description: "One option row. `media` is a leading visual (a ThemePreview tile); `note` a muted trailing annotation \u2014 options without one show a check when chosen. `disabled` skips it for the keyboard and refuses the pick; `textValue` is what type-ahead matches when the name is not plain text."
+    },
+    { name: "DisclosurePickerEmpty", type: "{ children?: ReactNode }", description: "The no-match line, rendered in place of the list." },
+    {
+      name: "useDisclosurePicker",
+      type: '() => { open: boolean; close(): void; size: "md" | "xs" }',
+      description: "For a list the picker does not own (a Tree) that should close the row when something is picked."
+    }
+  ],
+  tokensUsed: ["foreground", "muted-foreground", "popover", "hairline", "panel-field", "panel-field-hover", "ring", "accent"],
+  a11y: [
+    "The trigger is a real <button>; Base UI wires aria-expanded and aria-controls to the panel. Its accessible name is its text (caption + value) unless an aria-label is given.",
+    'The list is role="listbox" with role="option" rows; aria-selected marks the committed value, not the focused row, so a screen reader hears both where focus is and what is chosen. Selection does not follow focus: ArrowUp/ArrowDown, Home/End and type-ahead move focus (roving tabindex \u2014 one tab stop, so Tab leaves the list in one step) and apply nothing; Enter, Space or a click picks, applies and closes. Disabled options carry aria-disabled and are skipped.',
+    "Why a listbox and not a radio group: a radio group's checked state follows focus, so every arrow press would be a pick \u2014 wrong for a choice that opens a confirm, loads a font or resets settings. Base UI ships no standalone listbox (Select is popup-only, Combobox's inline list is focus-in-the-input, Composite is internal), so the keyboard model lives here.",
+    "Opening from the keyboard (Enter, Space, ArrowDown) moves focus into the panel: the search field when there is one, otherwise the chosen option (or the first). A pointer open focuses the search field on a fine pointer only, so touch does not raise the on-screen keyboard.",
+    "Escape closes the row without changing the value (clearing a query first) and returns focus to the trigger; a pick does the same. Focus is not pulled back when it has already moved on, e.g. to a confirm dialog the pick opened.",
+    "The panel animates with motion-disclosure, which is static under prefers-reduced-motion or MotionProvider off; the scroll that keeps the row in view is instant, never smooth."
+  ],
+  motion: [
+    { slot: "arrival", recipe: "none", part: "root", why: "A property row is present from first paint; animating it in would stage chrome the user is already scanning." },
+    {
+      slot: "response",
+      recipe: "motion-interactive",
+      part: "DisclosurePickerTrigger",
+      why: "The row reads as a value, not a button; the hover step is what says it opens before it is clicked."
+    },
+    {
+      slot: "transition",
+      recipe: "motion-disclosure",
+      part: "DisclosurePickerPanel",
+      why: "The list pushes the panel down; growing its height ties the movement below to this row rather than to a layout jump."
+    },
+    { slot: "activity", recipe: "none", part: "root", why: "Nothing is indeterminate: the options are resident. A list that loads should show its own loader inside the panel." }
+  ],
+  examples: [
+    {
+      label: "A short list \u2014 no search",
+      code: `const [preset, setPreset] = useState("comfortable")
+const [open, setOpen] = useState(false)
+<DisclosurePicker open={open} onOpenChange={setOpen} className="w-72">
+  <DisclosurePickerTrigger label="Density">{preset === "compact" ? "Compact" : "Comfortable"}</DisclosurePickerTrigger>
+  <DisclosurePickerPanel>
+    <DisclosurePickerList aria-label="Density" value={preset} onValueChange={setPreset}>
+      <DisclosurePickerOption value="comfortable">Comfortable</DisclosurePickerOption>
+      <DisclosurePickerOption value="compact">Compact</DisclosurePickerOption>
+    </DisclosurePickerList>
+  </DisclosurePickerPanel>
+</DisclosurePicker>`
+    },
+    {
+      label: "A long list \u2014 search opted in",
+      code: `const COUNTRIES = ["Argentina", "Australia", "Austria", "Belgium", "Brazil", "Canada", "Chile", "Denmark", "Finland", "France", "Germany", "Ireland", "Italy", "Japan", "Mexico", "Norway", "Portugal", "Spain", "Sweden"]
+const [country, setCountry] = useState("Canada")
+const [query, setQuery] = useState("")
+const shown = COUNTRIES.filter((name) => name.toLowerCase().includes(query.trim().toLowerCase()))
+<DisclosurePicker className="w-72">
+  <DisclosurePickerTrigger label="Country">{country}</DisclosurePickerTrigger>
+  <DisclosurePickerPanel search={{ value: query, onValueChange: setQuery, placeholder: \`Search \${COUNTRIES.length} countries\` }}>
+    {shown.length > 0 ? (
+      <DisclosurePickerList aria-label="Country" value={country} onValueChange={setCountry}>
+        {shown.map((name) => (
+          <DisclosurePickerOption key={name} value={name}>{name}</DisclosurePickerOption>
+        ))}
+      </DisclosurePickerList>
+    ) : (
+      <DisclosurePickerEmpty>No countries match \u201C{query}\u201D.</DisclosurePickerEmpty>
+    )}
+  </DisclosurePickerPanel>
+</DisclosurePicker>`
+    },
+    {
+      label: "A theme picker \u2014 media tiles, commit on Enter",
+      code: `const { themeId, setThemeId, themes, mode } = useSableTheme()
+const current = themes.find((theme) => theme.id === themeId)
+<DisclosurePicker>
+  <DisclosurePickerTrigger aria-label={\`Theme: \${current?.label}\`} media={current ? <ThemePreview theme={current} mode={mode} size="sm" /> : null}>
+    {current?.label}
+  </DisclosurePickerTrigger>
+  <DisclosurePickerPanel>
+    <DisclosurePickerList aria-label="Theme" value={themeId} onValueChange={setThemeId}>
+      {themes.map((theme) => (
+        <DisclosurePickerOption key={theme.id} value={theme.id} media={<ThemePreview theme={theme} mode={mode} size="sm" />}>
+          {theme.label}
+        </DisclosurePickerOption>
+      ))}
+    </DisclosurePickerList>
+  </DisclosurePickerPanel>
+</DisclosurePicker>`
+    },
+    {
+      label: "Property-grid rung",
+      code: `const [blend, setBlend] = useState("normal")
+<Density value="compact" className="w-64">
+  <DisclosurePicker size="xs">
+    <DisclosurePickerTrigger label="Blend">{blend}</DisclosurePickerTrigger>
+    <DisclosurePickerPanel>
+      <DisclosurePickerList aria-label="Blend mode" value={blend} onValueChange={setBlend}>
+        <DisclosurePickerOption value="normal">normal</DisclosurePickerOption>
+        <DisclosurePickerOption value="multiply">multiply</DisclosurePickerOption>
+        <DisclosurePickerOption value="screen">screen</DisclosurePickerOption>
+      </DisclosurePickerList>
+    </DisclosurePickerPanel>
+  </DisclosurePicker>
+</Density>`
+    }
+  ]
+};
+export {
+  disclosurePickerMeta
+};

package/dist/components/disclosure-picker/index.js

@@ -0,0 +1,21 @@
+// src/components/disclosure-picker/index.ts
+import {
+  DisclosurePicker,
+  DisclosurePickerTrigger,
+  DisclosurePickerPanel,
+  DisclosurePickerList,
+  DisclosurePickerOption,
+  DisclosurePickerEmpty,
+  useDisclosurePicker
+} from "./disclosure-picker.js";
+import { disclosurePickerMeta } from "./disclosure-picker.meta.js";
+export {
+  DisclosurePicker,
+  DisclosurePickerEmpty,
+  DisclosurePickerList,
+  DisclosurePickerOption,
+  DisclosurePickerPanel,
+  DisclosurePickerTrigger,
+  disclosurePickerMeta,
+  useDisclosurePicker
+};