@sableui/react 0.6.2 → 0.7.1

package/dist/components/combobox/combobox.meta.js

@@ -0,0 +1,217 @@
+// src/components/combobox/combobox.meta.ts
+var comboboxMeta = {
+  name: "Combobox",
+  summary: "Autocomplete over Base UI Combobox \u2014 type-to-filter, roving focus, ARIA combobox/listbox wiring, collision-aware positioning, Esc/outside dismissal. A search input (with chevron trigger) plus a portal-rendered popup of filterable items.",
+  keywords: [
+    "combobox",
+    "autocomplete",
+    "typeahead",
+    "search select",
+    "filter",
+    "suggestions",
+    "picker"
+  ],
+  usage: {
+    description: "Use Combobox when users choose from a list that benefits from typing, filtering, or autocomplete \u2014 one value, or several with `multiple` and ComboboxChips (tags, collaborators, categories). Use Select for short finite sets, a Checkbox group when every choice should stay visible, and CommandMenu for global actions.",
+    bestPractices: [
+      {
+        guidance: "do",
+        description: "Pass items so internal filtering, empty state, and accessibility wiring have the full option set."
+      },
+      {
+        guidance: "do",
+        description: "Use ComboboxEmpty with helpful copy for zero matches."
+      },
+      {
+        guidance: "do",
+        description: "Wrap in Field when the combobox is part of a form."
+      },
+      {
+        guidance: "dont",
+        description: "Use Combobox for tiny option sets where Select or Radio would be easier to scan."
+      },
+      {
+        guidance: "do",
+        description: "Reach for ComboboxVirtualList past roughly a thousand rows, and leave filtering to the root. It reads the filtered list through useFilteredItems(), so the rendered rows and the rows Base UI navigates cannot drift apart."
+      },
+      {
+        guidance: "do",
+        description: "Use `multiple` with ComboboxChips for several values from a filterable set, and keep chip labels short so the field does not turn into a paragraph."
+      },
+      {
+        guidance: "dont",
+        description: "Use Combobox as a command launcher. Use CommandMenu for actions and navigation."
+      },
+      {
+        guidance: "dont",
+        description: "Take filtering over with filteredItems in order to virtualize. Base UI ignores filteredItems while the untouched field still holds the selected item's label, so the list you render and the list it indexes diverge \u2014 and the symptom is clicking one row and getting another."
+      }
+    ],
+    anatomy: [
+      {
+        name: "Root",
+        required: true,
+        description: "Owns selected value, input value, filtering, and open state."
+      },
+      {
+        name: "Input",
+        required: true,
+        description: "The searchable text field and trigger."
+      },
+      {
+        name: "Chips",
+        required: false,
+        description: "The field for `multiple`, used in place of Input: one removable chip per selected item plus the text input, in one wrapping shell."
+      },
+      {
+        name: "Content",
+        required: true,
+        description: "The positioned popup surface."
+      },
+      {
+        name: "List",
+        required: true,
+        description: "The listbox inside the popup. Takes a render function that receives each filtered item."
+      },
+      {
+        name: "Item",
+        required: true,
+        description: "A selectable suggestion row."
+      },
+      {
+        name: "Empty",
+        required: false,
+        description: "Fallback shown when filtering returns no items."
+      }
+    ]
+  },
+  related: {
+    components: ["Select", "Checkbox", "CommandMenu", "Field", "SearchInput", "Badge"],
+    patterns: ["SettingsPage", "ListDetailPage"]
+  },
+  status: "stable",
+  props: [
+    {
+      name: "Combobox (Root)",
+      type: "Base UI Combobox.Root props (items, value, defaultValue, onValueChange, inputValue, onInputValueChange, open, onOpenChange, multiple, autoHighlight, filter, disabled)",
+      default: "\u2014",
+      description: "Groups all parts and owns selection + filter state. Pass `items` (flat array or groups) to enable internal filtering and ComboboxEmpty."
+    },
+    {
+      name: "items",
+      type: "readonly any[] | readonly ComboboxItemGroup[]",
+      default: "\u2014",
+      description: "The pool of options, flat or grouped ({ value, items }). Drives type-to-filter and is required for ComboboxEmpty to render its fallback."
+    },
+    {
+      name: "multiple",
+      type: "boolean",
+      default: "false",
+      description: "Select several items instead of one. `value` / `defaultValue` / `onValueChange` become arrays, choosing an item toggles its membership, and the popup stays open between picks. Pair it with ComboboxChips in place of ComboboxInput; every other part is unchanged."
+    },
+    {
+      name: "virtualized",
+      type: "boolean",
+      default: "false",
+      description: "Tells Base UI the DOM holds only part of the list. Required when using ComboboxVirtualList."
+    }
+  ],
+  subcomponents: [
+    {
+      name: "ComboboxInput",
+      type: 'Base UI Combobox.Input props (minus the native `size` attribute) + size?: "md" | "xs" + className',
+      description: 'The search field, styled like Input, wrapped with an InputGroup + chevron Trigger that toggles the popup. The chevron flips while the popup is open (data-[popup-open] on the toggle). `size="xs"` is the property-grid rung and mirrors SelectTrigger\'s `xs` exactly \u2014 same height, radius and inset surface \u2014 so a combobox and a select in one panel are the same shape holding different content (a font-family picker directly above a font-weight select is the case it exists for). Note the type: the native numeric `size` attribute is omitted rather than shadowed, because intersecting a string union onto it resolves to `never` and breaks every call site.'
+    },
+    {
+      name: "ComboboxChips",
+      type: 'Base UI Combobox.Input props (minus the native `size` attribute) + size?: "md" | "xs" + chipLabel?: (item) => string + className',
+      description: 'The field for a `multiple` combobox, used in place of ComboboxInput. Each selected item renders as a soft `sm` Badge with a ghost `icon-xs` Button that removes it (labelled "Remove {label}"), followed by the text input; the shell wraps and grows as chips are added. `chipLabel` turns an item into its chip text \u2014 defaults to the item for strings/numbers and its `label` field for objects. Keyboard is Base UI\'s: Backspace in an empty field removes the last chip, \u2190/\u2192 move between chips, Backspace/Delete removes the highlighted one. `size="xs"` mirrors ComboboxInput\'s property-grid rung.'
+    },
+    {
+      name: "ComboboxContent",
+      type: "Base UI Popup props + { side?: Side; align?: Align; sideOffset?: number; scroll?: boolean; className?: string }",
+      description: "Portal + Positioner + Popup \u2014 it does not render a list, so put a ComboboxList (or ComboboxVirtualList) inside it. Width matches the input via --anchor-width. side is which side of the input the popup renders against (auto-flips on collision), align its alignment along that side, sideOffset the gap in px. Defaults to side='bottom', align='start', sideOffset=6, scroll=true. Pass scroll={false} when a ComboboxVirtualList inside owns the scrolling."
+    },
+    {
+      name: "ComboboxList",
+      type: "Base UI Combobox.List props (children: ReactNode | (item, index) => ReactNode)",
+      description: "The listbox. Required inside ComboboxContent: pass a render function and it is called once per filtered item (or per group when `items` is grouped), so the rendered rows always match Base UI's filtering."
+    },
+    {
+      name: "ComboboxVirtualList",
+      type: "{ itemHeight: number; groupLabelHeight?: number; overscan?: number; children: (item, { index }) => ReactNode; renderGroupLabel?; className?; itemClassName? }",
+      description: "A windowed list: only the rows on screen exist. Fixed row heights (nothing is measured, so late-arriving content changes how a row looks and never where the rows are). Filtering stays Base UI's \u2014 the component reads the filtered list through useFilteredItems() \u2014 and groups keep their role=group wrapper and label association. Needs virtualized on the root and scroll={false} on ComboboxContent."
+    },
+    {
+      name: "ComboboxItem",
+      type: "Base UI Combobox.Item props + className (value, disabled, index, onClick)",
+      description: "A suggestion row. Highlights via data-[highlighted]; shows a trailing check (ItemIndicator) when it matches the selected value."
+    },
+    {
+      name: "ComboboxEmpty",
+      type: "Base UI Combobox.Empty props + className",
+      description: "Fallback shown when the filtered list is empty. Requires the `items` prop on the root."
+    },
+    {
+      name: "ComboboxGroup",
+      type: "Base UI Combobox.Group props + className",
+      description: "Groups related items under an accessible label auto-associated with the group."
+    },
+    {
+      name: "ComboboxGroupLabel",
+      type: "Base UI Combobox.GroupLabel props + className",
+      description: "The label for a ComboboxGroup. Auto-associated with the group it sits in."
+    }
+  ],
+  tokensUsed: [
+    "input",
+    "card",
+    "foreground",
+    "muted-foreground",
+    "ring",
+    "destructive",
+    "popover",
+    "popover-foreground",
+    "border",
+    "accent",
+    "accent-foreground",
+    "primary",
+    "secondary",
+    "secondary-foreground"
+  ],
+  a11y: [
+    "Base UI provides role=combobox/listbox/option, roving tabindex, arrow-key navigation, and type-to-filter.",
+    "Esc and outside-press dismiss; focus returns to the input on close.",
+    "The chevron Trigger carries an aria-label and toggles the suggestions popup.",
+    "ComboboxEmpty announces filter results politely; keep it mounted (do not conditionally render it).",
+    "Animate open/close via data-[starting-style]/data-[ending-style] attributes.",
+    "With `multiple`, the listbox is multi-selectable and each chip's remove button is labelled `Remove {label}`; Backspace in an empty field removes the last chip and \u2190/\u2192 move between chips, so every chip is reachable without a pointer.",
+    "ComboboxVirtualList gives every rendered row aria-setsize (the full filtered count) and aria-posinset, so a screen reader is told the size of the list rather than the size of the window.",
+    "A highlight that lands on a row the window has not rendered is scrolled into view by the root, which forwards it to the list; Base UI's own scrollIntoView only reaches rows that exist."
+  ],
+  examples: [
+    {
+      label: "Basic",
+      code: '<Combobox items={fruits}><ComboboxInput placeholder="Search fruit\u2026" /><ComboboxContent><ComboboxEmpty>No matches.</ComboboxEmpty><ComboboxList>{(item) => (<ComboboxItem key={item} value={item}>{item}</ComboboxItem>)}</ComboboxList></ComboboxContent></Combobox>'
+    },
+    {
+      label: "Controlled value",
+      code: "<Combobox items={fruits} value={value} onValueChange={setValue}><ComboboxInput /><ComboboxContent><ComboboxList>{(item) => (<ComboboxItem key={item} value={item}>{item}</ComboboxItem>)}</ComboboxList></ComboboxContent></Combobox>"
+    },
+    {
+      label: "Multiple selection",
+      code: '<Combobox multiple items={tags} value={value} onValueChange={setValue}><ComboboxChips placeholder="Add tags\u2026" /><ComboboxContent><ComboboxEmpty>No matching tags.</ComboboxEmpty><ComboboxList>{(item) => (<ComboboxItem key={item} value={item}>{item}</ComboboxItem>)}</ComboboxList></ComboboxContent></Combobox>'
+    },
+    {
+      label: "Virtualized (long list)",
+      code: '<Combobox virtualized items={districts} value={district} onValueChange={setDistrict}><ComboboxInput placeholder="Search districts\u2026" /><ComboboxContent scroll={false}><ComboboxEmpty>No district matches.</ComboboxEmpty><ComboboxVirtualList itemHeight={32}>{(item) => item.label}</ComboboxVirtualList></ComboboxContent></Combobox>'
+    },
+    {
+      label: "Inside Field",
+      code: '<Field label="Creator" description="Search by display name."><Combobox items={creators} value={creator} onValueChange={setCreator}><ComboboxInput placeholder="Search creators" /><ComboboxContent><ComboboxEmpty>No creators found.</ComboboxEmpty><ComboboxList>{(item) => (<ComboboxItem key={item.id} value={item}>{item.name}</ComboboxItem>)}</ComboboxList></ComboboxContent></Combobox></Field>'
+    }
+  ]
+};
+export {
+  comboboxMeta
+};

package/dist/components/combobox/index.js

@@ -0,0 +1,37 @@
+// src/components/combobox/index.ts
+import {
+  Combobox,
+  ComboboxValue,
+  ComboboxClear,
+  ComboboxPortal,
+  ComboboxInput,
+  ComboboxChips,
+  ComboboxContent,
+  ComboboxList,
+  ComboboxItem,
+  ComboboxItemIndicator,
+  ComboboxEmpty,
+  ComboboxGroup,
+  ComboboxGroupLabel,
+  ComboboxVirtualList,
+  useComboboxFilteredItems
+} from "./combobox.js";
+import { comboboxMeta } from "./combobox.meta.js";
+export {
+  Combobox,
+  ComboboxChips,
+  ComboboxClear,
+  ComboboxContent,
+  ComboboxEmpty,
+  ComboboxGroup,
+  ComboboxGroupLabel,
+  ComboboxInput,
+  ComboboxItem,
+  ComboboxItemIndicator,
+  ComboboxList,
+  ComboboxPortal,
+  ComboboxValue,
+  ComboboxVirtualList,
+  comboboxMeta,
+  useComboboxFilteredItems
+};

package/dist/components/command-menu/command-menu-trigger.js

@@ -0,0 +1,122 @@
+"use client";
+
+// src/components/command-menu/command-menu-trigger.tsx
+import { useEffect, useRef, useSyncExternalStore } from "react";
+import { Icon } from "../../icon/index.js";
+import { cn } from "../../lib/cn.js";
+import { useTypeTier } from "../../lib/density.js";
+import { FIELD_SHELL } from "../../lib/field-shell.js";
+import { useIsomorphicLayoutEffect } from "../../lib/use-isomorphic-layout-effect.js";
+import { Kbd, KbdGroup } from "../kbd/kbd.js";
+import { jsx, jsxs } from "react/jsx-runtime";
+var COMMAND_MENU_INPUT_ATTR = "data-command-menu-input";
+var NON_TEXT_INPUTS = /* @__PURE__ */ new Set([
+  "button",
+  "checkbox",
+  "color",
+  "file",
+  "image",
+  "radio",
+  "range",
+  "reset",
+  "submit"
+]);
+function isEditable(target) {
+  if (!(target instanceof Element)) return false;
+  if (target.closest(`[${COMMAND_MENU_INPUT_ATTR}]`)) return false;
+  if (target instanceof HTMLTextAreaElement || target instanceof HTMLSelectElement)
+    return true;
+  if (target instanceof HTMLInputElement)
+    return !NON_TEXT_INPUTS.has(target.type);
+  if (target instanceof HTMLElement && target.isContentEditable) return true;
+  return target.closest('[contenteditable]:not([contenteditable="false"])') !== null;
+}
+function detectApple() {
+  if (typeof navigator === "undefined") return false;
+  const nav = navigator;
+  const platform = nav.userAgentData?.platform || nav.platform || nav.userAgent || "";
+  return /mac|iphone|ipad|ipod/i.test(platform);
+}
+var noopSubscribe = () => () => {
+};
+function useIsApple() {
+  return useSyncExternalStore(noopSubscribe, detectApple, () => false);
+}
+function useCommandMenuShortcut(onShortcut, key = "k") {
+  const handler = useRef(onShortcut);
+  useIsomorphicLayoutEffect(() => {
+    handler.current = onShortcut;
+  });
+  useEffect(() => {
+    if (key === false || typeof window === "undefined") return;
+    const wanted = key.toLowerCase();
+    const apple = detectApple();
+    function onKeyDown(event) {
+      if (event.defaultPrevented || event.isComposing) return;
+      if (typeof event.key !== "string" || event.key.toLowerCase() !== wanted) return;
+      const mod = apple ? event.metaKey : event.ctrlKey;
+      const other = apple ? event.ctrlKey : event.metaKey;
+      if (!mod || other || event.altKey || event.shiftKey) return;
+      if (isEditable(event.target)) return;
+      event.preventDefault();
+      handler.current(event);
+    }
+    window.addEventListener("keydown", onKeyDown);
+    return () => window.removeEventListener("keydown", onKeyDown);
+  }, [key]);
+}
+function CommandMenuTrigger({
+  onOpen,
+  onClick,
+  placeholder = "Search",
+  shortcut = "k",
+  size = "md",
+  className,
+  type,
+  ...props
+}) {
+  const tier = useTypeTier();
+  const apple = useIsApple();
+  useCommandMenuShortcut(() => onOpen?.(), props.disabled ? false : shortcut);
+  const keyLabel = shortcut === false ? null : shortcut.toUpperCase();
+  return /* @__PURE__ */ jsxs(
+    "button",
+    {
+      type: type ?? "button",
+      "aria-haspopup": "dialog",
+      "aria-keyshortcuts": keyLabel ? `${apple ? "Meta" : "Control"}+${keyLabel}` : void 0,
+      onClick: (event) => {
+        onClick?.(event);
+        if (!event.defaultPrevented) onOpen?.();
+      },
+      className: cn(
+        // FIELD_SHELL carries motion-interactive too; it is restated here so
+        // the hover it eases is visibly paired with its recipe.
+        "flex w-full items-center gap-2 text-start text-muted-foreground motion-interactive hover:text-foreground",
+        FIELD_SHELL,
+        size === "sm" ? `h-(--control-sm) ps-2.5 pe-1.5 ${tier.supporting}` : `h-(--control-md) ps-3 pe-2 ${tier.body}`,
+        className
+      ),
+      ...props,
+      children: [
+        /* @__PURE__ */ jsx(Icon, { name: "search", className: "shrink-0 text-sm" }),
+        /* @__PURE__ */ jsx("span", { className: "min-w-0 flex-1 truncate", children: placeholder }),
+        keyLabel ? (
+          // aria-hidden: the shortcut is announced once, through
+          // aria-keyshortcuts, rather than read out as part of the name.
+          // One cap per key (Kbd's own guidance) — "Ctrl K" in a single cap
+          // read as one key.
+          /* @__PURE__ */ jsxs(KbdGroup, { "aria-hidden": true, className: "shrink-0", children: [
+            /* @__PURE__ */ jsx(Kbd, { children: apple ? "\u2318" : "Ctrl" }),
+            /* @__PURE__ */ jsx(Kbd, { children: keyLabel })
+          ] })
+        ) : null
+      ]
+    }
+  );
+}
+CommandMenuTrigger.displayName = "CommandMenuTrigger";
+export {
+  CommandMenuTrigger,
+  useCommandMenuShortcut
+};