@tensor_1/react 2.24.0 → 2.26.0

package/dist/components/SearchSuggest.d.ts

@@ -0,0 +1,87 @@
+import * as react from 'react';
+import { HTMLAttributes, ReactNode, Ref } from 'react';
+
+/** One result row. */
+interface SearchSuggestOption {
+    /** Stable id, returned by `onSelect`. */
+    id: string;
+    /** The result's name. Matched letters are emphasised. */
+    title: string;
+    /** Where the result lives, outermost first (a breadcrumb). Middle crumbs truncate first. */
+    meta?: readonly string[];
+    /** One or two lines of context, clamped at two lines. Matched letters are emphasised. */
+    description?: string;
+    /** Optional leading glyph (decorative). */
+    icon?: ReactNode;
+}
+/** A labelled action inside the list (the footer row, the heading action). */
+interface SearchSuggestAction {
+    /** Visible text of the action. */
+    label: string;
+    /** Runs when the action is chosen. */
+    onSelect: () => void;
+}
+/** Props of {@link SearchSuggest}. */
+interface SearchSuggestProps extends Omit<HTMLAttributes<HTMLDivElement>, 'onChange' | 'onSelect' | 'title' | 'defaultValue'> {
+    /** The text in the field (controlled). */
+    value: string;
+    /** Called on every edit, and with an empty string when the field is cleared. */
+    onValueChange: (value: string) => void;
+    /** The suggestions to show, best first. The consumer filters; this component only renders. */
+    options: readonly SearchSuggestOption[];
+    /** Called when a row is chosen by click or Enter. The list closes afterwards. */
+    onSelect: (id: string, option: SearchSuggestOption) => void;
+    /** Accessible name of the field (there is no visible label; the placeholder is not a label). */
+    label: string;
+    placeholder?: string;
+    /** Text to emphasise in rows. Defaults to `value`. */
+    highlight?: string;
+    /** A title above the options, e.g. "Recently opened". */
+    heading?: string;
+    /** A small action next to the heading, e.g. "Clear". */
+    headingAction?: SearchSuggestAction;
+    /** A last row after the options, e.g. "Show all 23 results". Reachable by arrow keys. */
+    footer?: SearchSuggestAction;
+    /** The field is fetching suggestions: a spinner shows in the field and, with no options yet, in the list. */
+    loading?: boolean;
+    /** Announced while loading, and shown in the list when it has no rows yet. */
+    loadingLabel?: string;
+    /** Shown when the field has text, nothing is loading and there are no options. */
+    empty?: ReactNode;
+    /** Shown instead of the empty state when suggestions could not be loaded. */
+    error?: ReactNode;
+    /** A keyboard hint shown in the empty, unfocused field, e.g. "/". */
+    shortcutHint?: string;
+    /** Accessible name of the clear button (default "Clear search"). */
+    clearLabel?: string;
+    /** A polite announcement, e.g. "8 results". Rendered in a visually hidden live region. */
+    status?: string;
+    /** `lg` for a page-level search (hubs, start pages); `md` for a field in a toolbar or header. */
+    size?: 'md' | 'lg';
+    /** Controlled open state of the suggestion list (optional). */
+    open?: boolean;
+    /** Called when the list opens or closes. */
+    onOpenChange?: (open: boolean) => void;
+    /**
+     * `absolute` (default) places the list under the field inside its own box. `fixed` floats it on
+     * the viewport, so a clipping ancestor (`overflow: hidden` toolbars and headers) cannot cut it off;
+     * it follows the field on scroll and resize and flips above it when there is no room below.
+     */
+    strategy?: 'absolute' | 'fixed';
+    /** Focus the field from outside (e.g. a "/" shortcut). */
+    inputRef?: Ref<HTMLInputElement | null>;
+    /** Focus the field on mount. */
+    autoFocus?: boolean;
+    /** Form field name of the input. */
+    name?: string;
+}
+/**
+ * A search field with a suggestion list underneath: the "search and jump" pattern of Windows
+ * Settings, Android Settings and most docs sites. Each row shows a name, where it lives and a line
+ * of context. ARIA combobox pattern: focus stays in the field, arrow keys move the active row
+ * (`aria-activedescendant`), Enter opens it (the first row when none is active), Escape closes the
+ * list and a second Escape clears the text.
+ */
+declare function SearchSuggest({ value, onValueChange, options, onSelect, label, placeholder, highlight, heading, headingAction, footer, loading, loadingLabel, empty, error, shortcutHint, clearLabel, status, size, open: openProp, strategy, onOpenChange, inputRef, autoFocus, name, className, onBlur, ...props }: SearchSuggestProps): react.JSX.Element;
+
+export { SearchSuggest, type SearchSuggestAction, type SearchSuggestOption, type SearchSuggestProps };

package/dist/components/SearchSuggest.js

@@ -0,0 +1,299 @@
+"use client";
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+import { useEffect, useId, useImperativeHandle, useLayoutEffect, useRef, useState } from "react";
+import { cx } from "../cx.js";
+import { useAnchoredPosition } from "../hooks/useAnchoredPosition.js";
+import { searchSegments } from "../search-suggest-model.js";
+import { Spinner } from "./Spinner.js";
+const SearchIcon = () => /* @__PURE__ */ jsxs("svg", { viewBox: "0 0 24 24", fill: "none", stroke: "currentColor", strokeWidth: "2", strokeLinecap: "round", strokeLinejoin: "round", "aria-hidden": "true", children: [
+  /* @__PURE__ */ jsx("circle", { cx: "11", cy: "11", r: "7" }),
+  /* @__PURE__ */ jsx("path", { d: "m20 20-3.5-3.5" })
+] });
+const ClearIcon = () => /* @__PURE__ */ jsx("svg", { viewBox: "0 0 16 16", fill: "none", stroke: "currentColor", strokeWidth: 1.5, strokeLinecap: "round", "aria-hidden": "true", children: /* @__PURE__ */ jsx("path", { d: "M4 4l8 8M12 4l-8 8" }) });
+function Emphasised({ text, query }) {
+  return /* @__PURE__ */ jsx(Fragment, { children: searchSegments(text, query).map(
+    (segment, index) => segment.match ? /* @__PURE__ */ jsx("mark", { className: "uix-search-suggest__match", children: segment.text }, index) : /* @__PURE__ */ jsx("span", { children: segment.text }, index)
+  ) });
+}
+const keepFocus = (event) => event.preventDefault();
+const useIsomorphicLayoutEffect = typeof document !== "undefined" ? useLayoutEffect : useEffect;
+function SearchSuggest({
+  value,
+  onValueChange,
+  options,
+  onSelect,
+  label,
+  placeholder,
+  highlight,
+  heading,
+  headingAction,
+  footer,
+  loading = false,
+  loadingLabel,
+  empty,
+  error,
+  shortcutHint,
+  clearLabel = "Clear search",
+  status,
+  size = "md",
+  open: openProp,
+  strategy = "absolute",
+  onOpenChange,
+  inputRef,
+  autoFocus,
+  name,
+  className,
+  onBlur,
+  ...props
+}) {
+  const id = useId();
+  const listboxId = `${id}-listbox`;
+  const headingId = `${id}-heading`;
+  const rootRef = useRef(null);
+  const fieldRef = useRef(null);
+  useImperativeHandle(inputRef, () => fieldRef.current, []);
+  const [openState, setOpenState] = useState(false);
+  const open = openProp ?? openState;
+  const setOpen = (next) => {
+    if (openProp === void 0) setOpenState(next);
+    if (next !== open) onOpenChange?.(next);
+  };
+  const [focused, setFocused] = useState(false);
+  const [activeState, setActive] = useState(-1);
+  const itemCount = options.length + (footer ? 1 : 0);
+  const active = activeState < itemCount ? activeState : -1;
+  const optionKey = options.map((option) => option.id).join("|");
+  useEffect(() => setActive(-1), [optionKey]);
+  const hasText = value.trim().length > 0;
+  const showEmpty = hasText && !loading && !error && options.length === 0 && empty != null;
+  const showLoading = loading && options.length === 0;
+  const visible = open && (itemCount > 0 || showLoading || showEmpty || error != null);
+  const optionId = (index) => `${id}-option-${index}`;
+  useEffect(() => {
+    if (!visible || active < 0) return;
+    const node = document.getElementById(optionId(active));
+    node?.scrollIntoView?.({ block: "nearest" });
+  }, [active, visible]);
+  const choose = (index) => {
+    const option = options[index];
+    if (option) onSelect(option.id, option);
+    else if (footer && index === options.length) footer.onSelect();
+    else return;
+    setOpen(false);
+    setActive(-1);
+  };
+  const handleKeyDown = (event) => {
+    if (event.nativeEvent.isComposing || event.keyCode === 229) return;
+    switch (event.key) {
+      case "ArrowDown":
+      case "ArrowUp": {
+        event.preventDefault();
+        if (!itemCount) {
+          setOpen(true);
+          return;
+        }
+        const down = event.key === "ArrowDown";
+        if (!visible) {
+          setOpen(true);
+          setActive(down ? 0 : itemCount - 1);
+          return;
+        }
+        setActive((stored) => {
+          const current = stored < itemCount ? stored : -1;
+          if (current < 0) return down ? 0 : itemCount - 1;
+          return (current + (down ? 1 : -1) + itemCount) % itemCount;
+        });
+        return;
+      }
+      case "Home":
+      case "End":
+        if (visible && active >= 0 && itemCount) {
+          event.preventDefault();
+          setActive(event.key === "Home" ? 0 : itemCount - 1);
+        }
+        return;
+      case "Enter":
+        if (visible && active >= 0) {
+          event.preventDefault();
+          choose(active);
+          return;
+        }
+        if (visible && hasText && options.length) {
+          event.preventDefault();
+          choose(0);
+        }
+        return;
+      case "Escape":
+        if (visible) {
+          event.preventDefault();
+          event.stopPropagation();
+          setOpen(false);
+          setActive(-1);
+        } else if (value) {
+          event.preventDefault();
+          event.stopPropagation();
+          onValueChange("");
+        }
+        return;
+      default:
+    }
+  };
+  const handleBlur = (event) => {
+    onBlur?.(event);
+    if (!rootRef.current?.contains(event.relatedTarget)) {
+      setFocused(false);
+      setOpen(false);
+      setActive(-1);
+    }
+  };
+  const clear = () => {
+    onValueChange("");
+    setActive(-1);
+    fieldRef.current?.focus();
+  };
+  const activeId = visible && active >= 0 ? optionId(active) : void 0;
+  const fieldBoxRef = useRef(null);
+  const popupRef = useRef(null);
+  const floating = strategy === "fixed";
+  useIsomorphicLayoutEffect(() => {
+    const popup = popupRef.current;
+    const box = fieldBoxRef.current;
+    if (!floating || !visible || !popup || !box) return;
+    const size2 = () => {
+      popup.style.width = `${box.offsetWidth}px`;
+    };
+    size2();
+    window.addEventListener("resize", size2);
+    return () => window.removeEventListener("resize", size2);
+  }, [floating, visible]);
+  useAnchoredPosition(floating ? fieldBoxRef : null, popupRef, { open: floating && visible, placement: "bottom-start", offset: 4 });
+  return /* @__PURE__ */ jsxs(
+    "div",
+    {
+      ref: rootRef,
+      className: cx("uix-search-suggest", size === "lg" && "uix-search-suggest--lg", className),
+      "data-open": visible || void 0,
+      onBlur: handleBlur,
+      ...props,
+      children: [
+        /* @__PURE__ */ jsxs("div", { ref: fieldBoxRef, className: "uix-search-suggest__field", children: [
+          /* @__PURE__ */ jsx("span", { className: "uix-search-suggest__lead", "aria-hidden": "true", children: /* @__PURE__ */ jsx(SearchIcon, {}) }),
+          /* @__PURE__ */ jsx(
+            "input",
+            {
+              ref: fieldRef,
+              className: "uix-input uix-search-suggest__input",
+              type: "text",
+              role: "combobox",
+              "aria-label": label,
+              "aria-autocomplete": "list",
+              "aria-expanded": visible,
+              "aria-controls": listboxId,
+              "aria-activedescendant": activeId,
+              "aria-busy": loading || void 0,
+              autoComplete: "off",
+              spellCheck: false,
+              enterKeyHint: "search",
+              name,
+              value,
+              placeholder,
+              autoFocus,
+              onChange: (event) => {
+                onValueChange(event.target.value);
+                setActive(-1);
+                setOpen(true);
+              },
+              onFocus: () => {
+                setFocused(true);
+                setOpen(true);
+              },
+              onClick: () => setOpen(true),
+              onKeyDown: handleKeyDown
+            }
+          ),
+          /* @__PURE__ */ jsxs("span", { className: "uix-search-suggest__trail", children: [
+            loading && /* @__PURE__ */ jsx(Spinner, { className: "uix-search-suggest__spinner", label: loadingLabel }),
+            !loading && value && /* @__PURE__ */ jsx("button", { type: "button", className: "uix-search-suggest__clear", "aria-label": clearLabel, onMouseDown: keepFocus, onClick: clear, children: /* @__PURE__ */ jsx(ClearIcon, {}) }),
+            !loading && !value && !focused && shortcutHint && /* @__PURE__ */ jsx("kbd", { className: "uix-kbd", "aria-hidden": "true", children: shortcutHint })
+          ] })
+        ] }),
+        /* @__PURE__ */ jsxs("div", { ref: popupRef, className: "uix-search-suggest__popup", "data-strategy": floating ? "fixed" : void 0, hidden: !visible, children: [
+          heading && options.length > 0 && /* @__PURE__ */ jsxs("div", { className: "uix-search-suggest__header", children: [
+            /* @__PURE__ */ jsx("span", { className: "uix-search-suggest__heading", id: headingId, children: heading }),
+            headingAction && /* @__PURE__ */ jsx("button", { type: "button", className: "uix-search-suggest__header-action", onMouseDown: keepFocus, onClick: headingAction.onSelect, children: headingAction.label })
+          ] }),
+          /* @__PURE__ */ jsxs(
+            "ul",
+            {
+              id: listboxId,
+              role: "listbox",
+              className: "uix-search-suggest__list",
+              "aria-label": heading && options.length > 0 ? void 0 : label,
+              "aria-labelledby": heading && options.length > 0 ? headingId : void 0,
+              "aria-busy": loading || void 0,
+              children: [
+                options.map((option, index) => {
+                  const crumbs = option.meta ?? [];
+                  const descId = option.description ? `${optionId(index)}-desc` : void 0;
+                  return /* @__PURE__ */ jsxs(
+                    "li",
+                    {
+                      id: optionId(index),
+                      role: "option",
+                      "aria-selected": index === active,
+                      "aria-label": crumbs.length ? `${option.title}, ${crumbs.join(" \u203A ")}` : option.title,
+                      "aria-describedby": descId,
+                      className: "uix-search-suggest__option",
+                      "data-active": index === active || void 0,
+                      onMouseDown: keepFocus,
+                      onMouseMove: () => {
+                        if (active !== index) setActive(index);
+                      },
+                      onClick: () => choose(index),
+                      children: [
+                        option.icon != null && /* @__PURE__ */ jsx("span", { className: "uix-search-suggest__icon", "aria-hidden": "true", children: option.icon }),
+                        /* @__PURE__ */ jsxs("span", { className: "uix-search-suggest__body", children: [
+                          /* @__PURE__ */ jsx("span", { className: "uix-search-suggest__title", children: /* @__PURE__ */ jsx(Emphasised, { text: option.title, query: highlight ?? value }) }),
+                          crumbs.length > 0 && /* @__PURE__ */ jsx("span", { className: "uix-search-suggest__meta", title: crumbs.join(" \u203A "), children: crumbs.map((crumb, crumbIndex) => /* @__PURE__ */ jsx("span", { className: "uix-search-suggest__crumb", children: crumb }, crumbIndex)) }),
+                          option.description && /* @__PURE__ */ jsx("span", { id: descId, className: "uix-search-suggest__desc", children: /* @__PURE__ */ jsx(Emphasised, { text: option.description, query: highlight ?? value }) })
+                        ] })
+                      ]
+                    },
+                    option.id
+                  );
+                }),
+                footer && /* @__PURE__ */ jsx(
+                  "li",
+                  {
+                    id: optionId(options.length),
+                    role: "option",
+                    "aria-selected": active === options.length,
+                    className: "uix-search-suggest__footer",
+                    "data-active": active === options.length || void 0,
+                    onMouseDown: keepFocus,
+                    onMouseMove: () => {
+                      if (active !== options.length) setActive(options.length);
+                    },
+                    onClick: () => choose(options.length),
+                    children: footer.label
+                  }
+                )
+              ]
+            }
+          ),
+          showLoading && // The field's spinner is the announced status; this row is the visual echo in the list.
+          /* @__PURE__ */ jsxs("div", { className: "uix-search-suggest__state", "aria-hidden": "true", children: [
+            /* @__PURE__ */ jsx("span", { className: "uix-spinner" }),
+            loadingLabel && /* @__PURE__ */ jsx("span", { children: loadingLabel })
+          ] }),
+          error != null && options.length === 0 && !loading && /* @__PURE__ */ jsx("div", { className: "uix-search-suggest__state", children: error }),
+          showEmpty && /* @__PURE__ */ jsx("div", { className: "uix-search-suggest__state", children: empty })
+        ] }),
+        /* @__PURE__ */ jsx("span", { className: "uix-visually-hidden", role: "status", "aria-live": "polite", children: status ?? "" })
+      ]
+    }
+  );
+}
+export {
+  SearchSuggest
+};

package/dist/hooks/backdropDismiss.d.ts

@@ -0,0 +1,7 @@
+import { MouseEventHandler, MouseEvent } from 'react';
+
+declare function isBackdropClick(e: MouseEvent<HTMLDialogElement>): boolean;
+/** The dialog's onClick: runs the consumer's own onClick first, then closes on a backdrop click. */
+declare function backdropDismiss(onClose: (() => void) | undefined, onClick?: MouseEventHandler<HTMLDialogElement>, enabled?: boolean): MouseEventHandler<HTMLDialogElement>;
+
+export { backdropDismiss, isBackdropClick };

package/dist/hooks/backdropDismiss.js

@@ -0,0 +1,16 @@
+function isBackdropClick(e) {
+  if (e.target !== e.currentTarget) return false;
+  const r = e.currentTarget.getBoundingClientRect();
+  if (r.width === 0) return false;
+  return e.clientX < r.left || e.clientX > r.right || e.clientY < r.top || e.clientY > r.bottom;
+}
+function backdropDismiss(onClose, onClick, enabled = true) {
+  return (e) => {
+    onClick?.(e);
+    if (enabled && onClose && isBackdropClick(e)) onClose();
+  };
+}
+export {
+  backdropDismiss,
+  isBackdropClick
+};