@tensor_1/react 2.46.0 → 2.48.0

package/dist/components/Combobox.d.ts

@@ -1,19 +1,40 @@
 import * as react from 'react';
-import { HTMLAttributes } from 'react';
-import { ComboboxOption } from '../combobox-model.js';
+import { HTMLAttributes, AriaAttributes } from 'react';
+import { ComboboxOption, ComboboxGroup } from '../combobox-model.js';
+import { Placement } from '../overlay-position.js';
 
 interface ComboboxProps extends Omit<HTMLAttributes<HTMLDivElement>, 'onChange'> {
-    options: readonly ComboboxOption[];
+    /** The options, and groups of options (`{ label, options }`, HAR-1588). */
+    options: readonly (ComboboxOption | ComboboxGroup)[];
     value?: string;
     defaultValue?: string;
     onValueChange?: (value: string, option: ComboboxOption) => void;
+    /** The field's name. Not used as its name when `aria-labelledby` points at a visible label. */
     label: string;
     placeholder?: string;
+    /** Shown in the open list when nothing matches (outside the listbox, so it is never an option). */
     emptyLabel: string;
     name?: string;
     disabled?: boolean;
+    /** Ids of the visible label(s) that name the field; replaces `label` as its name. */
+    'aria-labelledby'?: string;
+    /** Ids of hint or error text; lands on the input. */
+    'aria-describedby'?: string;
+    'aria-invalid'?: AriaAttributes['aria-invalid'];
+    /** Id of the input itself (for a `<label for>`); `id` stays on the wrapper. */
+    inputId?: string;
+    /** Preferred side of the list. Default `'bottom-start'`; it flips when there is no room. */
+    placement?: Placement;
 }
-/** Searchable single-select combobox with keyboard navigation and no framework dependencies. */
-declare function Combobox({ options, value, defaultValue, onValueChange, label, placeholder, emptyLabel, name, disabled, className, ...props }: ComboboxProps): react.JSX.Element;
+/**
+ * An editable combobox (HAR-1588): type to filter, choose with the keyboard or the pointer. It
+ * follows the WAI-ARIA APG combobox with a listbox popup, at parity with `Select`: the list is a
+ * top-layer popover placed with `useAnchoredPosition`, so a Drawer, a Popover or an
+ * `overflow: hidden` cell never clips it; ↑ ↓ PageUp PageDown move (Home and End too while an
+ * option is active), disabled options are skipped and the list does not wrap; Enter chooses;
+ * Escape closes the list and puts the chosen option's text back, as leaving the field does.
+ * Groups render as `role="group"`; the no-match row sits outside the listbox.
+ */
+declare function Combobox({ options, value, defaultValue, onValueChange, label, placeholder, emptyLabel, name, disabled, className, 'aria-labelledby': ariaLabelledBy, 'aria-describedby': ariaDescribedBy, 'aria-invalid': ariaInvalid, inputId, placement, ...props }: ComboboxProps): react.JSX.Element;
 
-export { Combobox, ComboboxOption, type ComboboxProps };
+export { Combobox, ComboboxGroup, ComboboxOption, type ComboboxProps };

package/dist/components/Combobox.js

@@ -1,8 +1,15 @@
 "use client";
 import { jsx, jsxs } from "react/jsx-runtime";
-import { useEffect, useId, useMemo, useRef, useState } from "react";
+import { Fragment, useEffect, useId, useLayoutEffect, useMemo, useRef, useState } from "react";
 import { cx } from "../cx.js";
-import { filterComboboxOptions } from "../combobox-model.js";
+import { filterComboboxItems } from "../combobox-model.js";
+import { useAnchoredPosition, zoomOf } from "../hooks/useAnchoredPosition.js";
+import { CheckIcon } from "../icons/components.js";
+import { buildSelectModel, firstEnabled, lastEnabled, moveActive } from "../select-model.js";
+const useIsomorphicLayoutEffect = typeof document !== "undefined" ? useLayoutEffect : useEffect;
+const OFFSET = 4;
+const EDGE = 8;
+const MAX_HEIGHT = 320;
 function Combobox({
   options,
   value,
@@ -14,105 +21,235 @@ function Combobox({
   name,
   disabled,
   className,
+  "aria-labelledby": ariaLabelledBy,
+  "aria-describedby": ariaDescribedBy,
+  "aria-invalid": ariaInvalid,
+  inputId,
+  placement = "bottom-start",
   ...props
 }) {
-  const generatedId = useId();
-  const listboxId = `${generatedId}-listbox`;
+  const uid = useId();
+  const listboxId = `${uid}-listbox`;
+  const optionId = (index) => `${listboxId}-${index}`;
   const rootRef = useRef(null);
+  const inputRef = useRef(null);
+  const popupRef = useRef(null);
+  const listRef = useRef(null);
   const [internalValue, setInternalValue] = useState(defaultValue ?? "");
   const selectedValue = value ?? internalValue;
-  const selected = options.find((option) => option.value === selectedValue);
+  const all = useMemo(() => buildSelectModel(options).all, [options]);
+  const selected = all.find((entry) => entry.option.value === selectedValue)?.option;
   const [query, setQuery] = useState(selected?.label ?? "");
+  const [filter, setFilter] = useState("");
   const [open, setOpen] = useState(false);
-  const [activeIndex, setActiveIndex] = useState(0);
-  const filtered = useMemo(() => filterComboboxOptions(options, open ? query : ""), [open, options, query]);
-  const activeOption = filtered[activeIndex];
+  const [activeIndex, setActiveIndex] = useState(-1);
+  const model = useMemo(() => buildSelectModel(filterComboboxItems(options, open ? filter : "")), [open, options, filter]);
+  const entries = model.entries;
+  const active = activeIndex >= 0 ? entries[activeIndex] : void 0;
+  const selectedLabel = () => all.find((entry) => entry.option.value === selectedValue)?.option.label ?? "";
   useEffect(() => {
-    if (!open) setQuery(options.find((option) => option.value === selectedValue)?.label ?? "");
+    if (!open) setQuery(selectedLabel());
   }, [open, options, selectedValue]);
-  const select = (option) => {
-    if (option.disabled) return;
+  const openList = (target = "selected", list = entries) => {
+    if (disabled) return;
+    const chosen = list.findIndex((entry) => entry.option.value === selectedValue && !entry.disabled);
+    setActiveIndex(target === "last" ? lastEnabled(list) : target === "first" || chosen < 0 ? firstEnabled(list) : chosen);
+    setOpen(true);
+  };
+  const select = (entry) => {
+    if (!entry || entry.disabled) return;
+    const option = entry.option;
     if (value == null) setInternalValue(option.value);
     setQuery(option.label);
+    setFilter("");
     setOpen(false);
+    setActiveIndex(-1);
     onValueChange?.(option.value, option);
   };
-  const move = (step) => {
-    if (!filtered.length) return;
-    let next = activeIndex;
-    for (let attempts = 0; attempts < filtered.length; attempts += 1) {
-      next = (next + step + filtered.length) % filtered.length;
-      if (!filtered[next]?.disabled) break;
-    }
-    setActiveIndex(next);
+  const restore = () => {
+    setFilter("");
+    setOpen(false);
+    setActiveIndex(-1);
+    setQuery(selectedLabel());
   };
   const handleKeyDown = (event) => {
-    if (event.key === "ArrowDown" || event.key === "ArrowUp") {
-      event.preventDefault();
-      if (!open) setOpen(true);
-      else move(event.key === "ArrowDown" ? 1 : -1);
-    } else if (event.key === "Enter" && open && activeOption) {
-      event.preventDefault();
-      select(activeOption);
-    } else if (event.key === "Escape") {
-      setOpen(false);
-      setQuery(selected?.label ?? "");
+    if (event.nativeEvent.isComposing || event.keyCode === 229) return;
+    const { key, altKey } = event;
+    switch (key) {
+      case "ArrowDown":
+      case "ArrowUp":
+        event.preventDefault();
+        if (!open) {
+          openList(key === "ArrowUp" && !altKey ? "last" : "selected");
+          return;
+        }
+        if (altKey) return;
+        setActiveIndex((index) => moveActive(entries, index, key === "ArrowDown" ? 1 : -1));
+        return;
+      case "PageDown":
+      case "PageUp":
+        if (!open) return;
+        event.preventDefault();
+        setActiveIndex((index) => moveActive(entries, index, key === "PageDown" ? 10 : -10));
+        return;
+      case "Home":
+      case "End":
+        if (!open || activeIndex < 0) return;
+        event.preventDefault();
+        setActiveIndex(key === "Home" ? firstEnabled(entries) : lastEnabled(entries));
+        return;
+      case "Enter":
+        if (open && active) {
+          event.preventDefault();
+          select(active);
+        }
+        return;
+      case "Escape":
+        if (open || query !== selectedLabel()) {
+          event.preventDefault();
+          event.stopPropagation();
+          restore();
+        }
+        return;
+      default:
     }
   };
   const handleBlur = (event) => {
-    if (!rootRef.current?.contains(event.relatedTarget)) {
-      setOpen(false);
-      setQuery(options.find((option) => option.value === selectedValue)?.label ?? "");
-    }
+    const next = event.relatedTarget;
+    if (!rootRef.current?.contains(next)) restore();
   };
   const handleChange = (event) => {
-    setQuery(event.target.value);
-    setActiveIndex(0);
+    const text = event.target.value;
+    setQuery(text);
+    setFilter(text);
+    const list = buildSelectModel(filterComboboxItems(options, text)).entries;
+    setActiveIndex(firstEnabled(list));
     setOpen(true);
   };
+  useIsomorphicLayoutEffect(() => {
+    if (open && activeIndex >= entries.length) setActiveIndex(firstEnabled(entries));
+  }, [open, entries.length]);
+  useIsomorphicLayoutEffect(() => {
+    const popup = popupRef.current;
+    const input = inputRef.current;
+    if (!popup || !input) return;
+    const isOpen = () => {
+      try {
+        return popup.matches(":popover-open");
+      } catch {
+        return false;
+      }
+    };
+    if (open) {
+      const zoom = zoomOf(input);
+      const r = input.getBoundingClientRect();
+      const room = Math.max(r.top, window.innerHeight - r.bottom) / zoom - OFFSET - EDGE;
+      popup.style.minWidth = `${Math.round(r.width / zoom)}px`;
+      popup.style.maxHeight = `${Math.max(96, Math.min(MAX_HEIGHT, Math.floor(room)))}px`;
+      try {
+        if (!isOpen()) popup.showPopover();
+      } catch {
+      }
+    } else {
+      try {
+        if (isOpen()) popup.hidePopover();
+      } catch {
+      }
+    }
+  }, [open]);
+  useAnchoredPosition(inputRef, popupRef, { open, placement, offset: OFFSET, padding: EDGE });
+  useIsomorphicLayoutEffect(() => {
+    const list = listRef.current;
+    if (!open || !list || activeIndex < 0) return;
+    const el = list.ownerDocument.getElementById(optionId(activeIndex));
+    if (!el || !list.contains(el)) return;
+    const top = el.offsetTop;
+    const bottom = top + el.offsetHeight;
+    if (top < list.scrollTop) list.scrollTop = top;
+    else if (bottom > list.scrollTop + list.clientHeight) list.scrollTop = bottom - list.clientHeight;
+  }, [open, activeIndex]);
+  const popoverAttr = { popover: "manual" };
+  const invalid = ariaInvalid != null && ariaInvalid !== false && ariaInvalid !== "false";
+  const renderEntry = (entry) => /* @__PURE__ */ jsxs(
+    "div",
+    {
+      id: optionId(entry.index),
+      className: "uix-listbox__option",
+      role: "option",
+      "aria-selected": entry.option.value === selectedValue,
+      "aria-disabled": entry.disabled || void 0,
+      "data-active": open && entry.index === activeIndex || void 0,
+      onMouseDown: (event) => event.preventDefault(),
+      onPointerMove: () => {
+        if (entry.index !== activeIndex && !entry.disabled) setActiveIndex(entry.index);
+      },
+      onClick: () => select(entry),
+      children: [
+        /* @__PURE__ */ jsx("span", { className: "uix-listbox__text", children: /* @__PURE__ */ jsx("span", { className: "uix-listbox__label", children: entry.option.label }) }),
+        /* @__PURE__ */ jsx("span", { className: "uix-listbox__check", "aria-hidden": "true", children: entry.option.value === selectedValue && /* @__PURE__ */ jsx(CheckIcon, { size: "sm" }) })
+      ]
+    },
+    `${entry.option.value}-${entry.index}`
+  );
   return /* @__PURE__ */ jsxs("div", { ref: rootRef, className: cx("uix-combobox", className), onBlur: handleBlur, ...props, children: [
     name && /* @__PURE__ */ jsx("input", { type: "hidden", name, value: selectedValue }),
     /* @__PURE__ */ jsx(
       "input",
       {
+        ref: inputRef,
+        id: inputId,
         className: "uix-input",
         role: "combobox",
-        "aria-label": label,
+        "aria-label": ariaLabelledBy ? void 0 : label,
+        "aria-labelledby": ariaLabelledBy,
+        "aria-describedby": ariaDescribedBy,
+        "aria-invalid": invalid || void 0,
         "aria-autocomplete": "list",
         "aria-expanded": open,
         "aria-controls": listboxId,
-        "aria-activedescendant": open && activeOption ? `${listboxId}-${activeIndex}` : void 0,
+        "aria-activedescendant": open && active ? optionId(activeIndex) : void 0,
+        autoComplete: "off",
+        spellCheck: false,
         value: query,
         placeholder,
         disabled,
         onChange: handleChange,
         onFocus: () => {
           setQuery("");
-          setOpen(true);
-          setActiveIndex(Math.max(0, options.findIndex((option) => option.value === selectedValue)));
+          openList("selected", buildSelectModel(options).entries);
         },
         onKeyDown: handleKeyDown
       }
     ),
-    open && /* @__PURE__ */ jsxs("ul", { id: listboxId, className: "uix-listbox uix-combobox__listbox", role: "listbox", children: [
-      filtered.length === 0 && /* @__PURE__ */ jsx("li", { className: "uix-listbox__empty", children: emptyLabel }),
-      filtered.map((option, index) => /* @__PURE__ */ jsx(
-        "li",
-        {
-          id: `${listboxId}-${index}`,
-          className: "uix-listbox__option",
-          role: "option",
-          "aria-selected": option.value === selectedValue,
-          "aria-disabled": option.disabled || void 0,
-          "data-active": index === activeIndex || void 0,
-          onMouseDown: (event) => event.preventDefault(),
-          onMouseEnter: () => setActiveIndex(index),
-          onClick: () => select(option),
-          children: option.label
-        },
-        option.value
-      ))
-    ] })
+    /* @__PURE__ */ jsxs(
+      "div",
+      {
+        ref: popupRef,
+        className: "uix-select__popup uix-combobox__popup",
+        hidden: !open,
+        ...popoverAttr,
+        onMouseDown: (event) => event.preventDefault(),
+        children: [
+          /* @__PURE__ */ jsx(
+            "div",
+            {
+              ref: listRef,
+              id: listboxId,
+              role: "listbox",
+              "aria-label": label,
+              className: "uix-listbox uix-select__listbox",
+              hidden: entries.length === 0 || void 0,
+              children: model.sections.map((section, i) => section.label != null ? /* @__PURE__ */ jsxs("div", { role: "group", className: "uix-listbox__group", "aria-labelledby": `${uid}-group-${i}`, "aria-disabled": section.disabled || void 0, children: [
+                /* @__PURE__ */ jsx("div", { id: `${uid}-group-${i}`, role: "presentation", className: "uix-listbox__group-label", children: section.label }),
+                section.entries.map(renderEntry)
+              ] }, `g${i}`) : /* @__PURE__ */ jsx(Fragment, { children: section.entries.map(renderEntry) }, `s${i}`))
+            }
+          ),
+          entries.length === 0 && /* @__PURE__ */ jsx("div", { className: "uix-select__state", children: emptyLabel })
+        ]
+      }
+    ),
+    /* @__PURE__ */ jsx("span", { className: "uix-visually-hidden", role: "status", "aria-live": "polite", children: open && entries.length === 0 ? emptyLabel : "" })
   ] });
 }
 export {

package/dist/components/CommandPalette.d.ts

@@ -1,5 +1,6 @@
 import * as react from 'react';
 import { ReactNode, HTMLAttributes, InputHTMLAttributes } from 'react';
+import { CommandPaletteItem } from '../command-palette-model.js';
 
 interface CommandPaletteProps extends HTMLAttributes<HTMLDivElement> {
     /** TENSOR RX-125 (UIX-04): translatable; English default. */
@@ -12,6 +13,40 @@ interface CommandPaletteProps extends HTMLAttributes<HTMLDivElement> {
     /** Props for the search input (value/onChange/placeholder wired by the consumer). */
     inputProps?: InputHTMLAttributes<HTMLInputElement>;
     children?: ReactNode;
+    /**
+     * Items mode (HAR-1378): pass the commands and the palette filters them itself (case and
+     * diacritics folded, best match first), groups them, moves the active one with ↑ / ↓ (Home / End
+     * while the query is empty) through `aria-activedescendant`, and runs it on Enter or a click.
+     * Without `items`, `children` render as before and the consumer wires everything.
+     */
+    items?: readonly CommandPaletteItem[];
+    /** Items mode: the query (controlled). Pair with `onQueryChange`. */
+    query?: string;
+    /** Items mode: the query as it changes (also when the palette clears it on close). */
+    onQueryChange?: (query: string) => void;
+    /** Items mode: what an empty query shows above all items, under the `recentLabel` heading. */
+    recent?: readonly CommandPaletteItem[];
+    /** Items mode: your own matching instead of the built-in one (`filterCommandItems`). */
+    filter?: (items: readonly CommandPaletteItem[], query: string) => CommandPaletteItem[];
+    /** Items mode: called with every chosen item, after its own `onSelect`, e.g. to record it as recent. */
+    onItemSelect?: (item: CommandPaletteItem) => void;
+    /** Items mode: follow an item's `href` with your router. Default: the browser goes there. */
+    onNavigate?: (href: string, item: CommandPaletteItem) => void;
+    /** Items mode: shown when nothing matches. Default: `UixLabelsProvider` `commandPalette.empty`, then "No results". */
+    emptyLabel?: ReactNode;
+    /** Items mode: the heading of `recent`. Default: `commandPalette.recent`, then "Recent". */
+    recentLabel?: string;
+    /** Items mode: the input's placeholder. */
+    placeholder?: string;
+    /**
+     * Items mode: host the palette in a modal native `<dialog>` (focus stays inside, Escape and a
+     * click outside close it, focus returns to the opener). Closing it clears the query. Without
+     * `open`, the palette renders in place.
+     */
+    open?: boolean;
+    onOpenChange?: (open: boolean) => void;
+    /** Items mode: render at most this many found items (the count still says how many were found). Default 100. */
+    limit?: number;
 }
 /**
  * ⌘K command palette surface over `.uix-cmdk`. Presentational: mount it inside a
@@ -23,7 +58,7 @@ interface CommandPaletteProps extends HTMLAttributes<HTMLDivElement> {
  * popover it sits in `[data-uix-instant]`: it opens and closes with no animation, without the
  * consumer knowing the attribute (or the older `data-uix-cmdk-dialog`).
  */
-declare function CommandPalette({ inputProps, children, inputLabel: inputLabelProp, resultsLabel, className, ...props }: CommandPaletteProps): react.JSX.Element;
+declare function CommandPalette(props: CommandPaletteProps): react.JSX.Element;
 interface CommandGroupProps {
     label?: ReactNode;
     children?: ReactNode;