@tensor_1/react 2.47.0 → 2.49.0

package/dist/components/SearchSuggest.js

@@ -5,6 +5,7 @@ import { cx } from "../cx.js";
 import { useUixLabels } from "../labels-context.js";
 import { useAnchoredPosition } from "../hooks/useAnchoredPosition.js";
 import { searchSegments } from "../search-suggest-model.js";
+import { useDelayedPending } from "../hooks/useDelayedPending.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" }),
@@ -23,6 +24,7 @@ function SearchSuggest({
   onValueChange,
   options,
   onSelect,
+  freeText = false,
   label,
   placeholder,
   highlight,
@@ -47,6 +49,9 @@ function SearchSuggest({
   name,
   inputId,
   inputDescribedBy,
+  inputLabelledBy,
+  disabled = false,
+  invalid = false,
   className,
   onBlur,
   ...props
@@ -67,15 +72,34 @@ function SearchSuggest({
   };
   const [focused, setFocused] = useState(false);
   const [activeState, setActive] = useState(-1);
+  const showSpinner = useDelayedPending(loading) && !disabled;
+  const [labelled, setLabelled] = useState(false);
+  useEffect(() => {
+    setLabelled((fieldRef.current?.labels?.length ?? 0) > 0);
+  });
   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 showLoading = showSpinner && loading && options.length === 0;
+  const current = { empty: hasText && error == null && empty != null, error: error ?? null };
+  const settled = useRef({ empty: false, error: null });
+  useEffect(() => {
+    if (!loading) settled.current = current;
+  });
+  const state = options.length > 0 || showLoading ? null : loading ? settled.current : current;
+  const shownError = state?.error ?? null;
+  const showEmpty = !!state?.empty && shownError == null;
   const showIdle = idle != null && itemCount === 0 && !loading && error == null && !showEmpty;
-  const visible = open && (itemCount > 0 || showLoading || showEmpty || showIdle || error != null);
+  const visible = open && !disabled && (itemCount > 0 || showLoading || showEmpty || showIdle || shownError != null);
+  const [entered, setEntered] = useState(false);
+  const wasVisible = useRef(false);
+  useEffect(() => {
+    if (!open) setEntered(false);
+    else if (!visible && wasVisible.current) setEntered(true);
+    wasVisible.current = visible;
+  }, [open, visible]);
   const optionId = (index) => `${id}-option-${index}`;
   useEffect(() => {
     if (!visible || active < 0) return;
@@ -84,8 +108,10 @@ function SearchSuggest({
   }, [active, visible]);
   const choose = (index) => {
     const option = options[index];
-    if (option) onSelect(option.id, option);
-    else if (footer && index === options.length) footer.onSelect();
+    if (option) {
+      if (freeText && option.title !== value) onValueChange(option.title);
+      onSelect?.(option.id, option);
+    } else if (footer && index === options.length) footer.onSelect();
     else return;
     setOpen(false);
     setActive(-1);
@@ -107,9 +133,9 @@ function SearchSuggest({
           return;
         }
         setActive((stored) => {
-          const current = stored < itemCount ? stored : -1;
-          if (current < 0) return down ? 0 : itemCount - 1;
-          return (current + (down ? 1 : -1) + itemCount) % itemCount;
+          const current2 = stored < itemCount ? stored : -1;
+          if (current2 < 0) return down ? 0 : itemCount - 1;
+          return (current2 + (down ? 1 : -1) + itemCount) % itemCount;
         });
         return;
       }
@@ -121,11 +147,20 @@ function SearchSuggest({
         }
         return;
       case "Enter":
+        if (loading && !freeText) {
+          event.preventDefault();
+          return;
+        }
         if (visible && active >= 0) {
           event.preventDefault();
           choose(active);
           return;
         }
+        if (freeText) {
+          event.preventDefault();
+          if (open) setOpen(false);
+          return;
+        }
         if (visible && hasText && options.length) {
           event.preventDefault();
           choose(0);
@@ -137,7 +172,7 @@ function SearchSuggest({
           event.stopPropagation();
           setOpen(false);
           setActive(-1);
-        } else if (value) {
+        } else if (value && !freeText) {
           event.preventDefault();
           event.stopPropagation();
           onValueChange("");
@@ -179,13 +214,13 @@ function SearchSuggest({
     "div",
     {
       ref: rootRef,
-      className: cx("uix-search-suggest", size === "lg" && "uix-search-suggest--lg", className),
+      className: cx("uix-search-suggest", size === "lg" && "uix-search-suggest--lg", freeText && "uix-search-suggest--free-text", 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, {}) }),
+          !freeText && /* @__PURE__ */ jsx("span", { className: "uix-search-suggest__lead", "aria-hidden": "true", children: /* @__PURE__ */ jsx(SearchIcon, {}) }),
           /* @__PURE__ */ jsx(
             "input",
             {
@@ -195,7 +230,10 @@ function SearchSuggest({
               className: "uix-input uix-search-suggest__input",
               type: "text",
               role: "combobox",
-              "aria-label": label,
+              "aria-label": inputLabelledBy || labelled ? void 0 : label,
+              "aria-labelledby": inputLabelledBy,
+              "aria-invalid": invalid || void 0,
+              disabled,
               "aria-autocomplete": "list",
               "aria-expanded": visible,
               "aria-controls": listboxId,
@@ -203,7 +241,7 @@ function SearchSuggest({
               "aria-busy": loading || void 0,
               autoComplete: "off",
               spellCheck: false,
-              enterKeyHint: "search",
+              enterKeyHint: freeText ? "done" : "search",
               name,
               value,
               placeholder,
@@ -222,12 +260,12 @@ function SearchSuggest({
             }
           ),
           /* @__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 })
+            showSpinner && /* @__PURE__ */ jsx(Spinner, { className: "uix-search-suggest__spinner", label: loadingLabel }),
+            !showSpinner && value && !disabled && /* @__PURE__ */ jsx("button", { type: "button", className: "uix-search-suggest__clear", "aria-label": clearLabel, onMouseDown: keepFocus, onClick: clear, children: /* @__PURE__ */ jsx(ClearIcon, {}) }),
+            !showSpinner && !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: [
+        /* @__PURE__ */ jsxs("div", { ref: popupRef, className: "uix-search-suggest__popup", "data-strategy": floating ? "fixed" : void 0, "data-settled": entered ? "" : 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 })
@@ -296,7 +334,7 @@ function SearchSuggest({
             /* @__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 }),
+          shownError != null && /* @__PURE__ */ jsx("div", { className: "uix-search-suggest__state", children: shownError }),
           showEmpty && /* @__PURE__ */ jsx("div", { className: "uix-search-suggest__state", children: empty }),
           showIdle && /* @__PURE__ */ jsx("div", { className: "uix-search-suggest__state", children: idle }),
           note != null && options.length > 0 && /* @__PURE__ */ jsx("div", { className: "uix-search-suggest__note", children: note })

package/dist/components/Segmented.d.ts

@@ -1,5 +1,6 @@
 import * as react from 'react';
 import { HTMLAttributes, ReactNode, ButtonHTMLAttributes } from 'react';
+import { UixRenderLink } from '../link.js';
 
 interface SegmentedProps extends Omit<HTMLAttributes<HTMLDivElement>, 'onChange'> {
     /** The currently-selected option value. */
@@ -12,8 +13,15 @@ interface SegmentedProps extends Omit<HTMLAttributes<HTMLDivElement>, 'onChange'
      * toggle bar. `'radio'`: `role="radiogroup"` of `role="radio"` with `aria-checked`, for a
      * setting with exactly one value (theme, density, language). Name the group with
      * `aria-label` or `aria-labelledby` in either mode. The keyboard model is the same in both.
+     *
+     * `'link'` (HAR-1380): navigation, not a choice, such as a language switcher where each
+     * option is a URL. A `<nav>` (named by your `aria-label`) around a list of links, each
+     * option needs an `href`, and the one whose `value` is `value` carries `aria-current="page"`.
+     * The same pill look; every link is its own tab stop and Enter follows it, like any nav.
      */
-    selection?: 'toggle' | 'radio';
+    selection?: 'toggle' | 'radio' | 'link';
+    /** `selection="link"`: renders each option's link with your router. Default: `<a>`. */
+    renderLink?: UixRenderLink;
     children?: ReactNode;
 }
 /**
@@ -27,9 +35,13 @@ interface SegmentedProps extends Omit<HTMLAttributes<HTMLDivElement>, 'onChange'
  * enabled option and select it, wrapping at the ends; Home and End jump; Left/Right swap in
  * a right-to-left group. Before 2.32.0 every option was its own tab stop.
  */
-declare function Segmented({ value, onChange, selection, children, className, onKeyDown, ...props }: SegmentedProps): react.JSX.Element;
+declare function Segmented({ value, onChange, selection, renderLink, children, className, onKeyDown, ...props }: SegmentedProps): react.JSX.Element;
 interface SegmentedOptionProps extends Omit<ButtonHTMLAttributes<HTMLButtonElement>, 'value' | 'onChange'> {
     value: string;
+    /** In a `selection="link"` group: where the option goes. Required there, ignored otherwise. */
+    href?: string;
+    /** In a `selection="link"` group: the target's language, e.g. `de` on a locale switcher. */
+    hrefLang?: string;
     children?: ReactNode;
 }
 /**
@@ -38,6 +50,29 @@ interface SegmentedOptionProps extends Omit<ButtonHTMLAttributes<HTMLButtonEleme
  * `.uix-segmented__option[aria-pressed="true"]` (or `[aria-checked="true"]` in a
  * `selection="radio"` group).
  */
-declare function SegmentedOption({ value, children, className, onClick, ...props }: SegmentedOptionProps): react.JSX.Element;
+declare function SegmentedOption({ value, href, hrefLang, children, className, onClick, ...props }: SegmentedOptionProps): react.JSX.Element;
+interface LocaleSwitcherLocale {
+    /** BCP 47 code: `de`, `bs`, `en-GB`. Sets the link's `lang` and `hreflang`. */
+    code: string;
+    /** What the option shows: "Deutsch", or a short "DE". */
+    label: ReactNode;
+    /** This page in that language. */
+    href: string;
+}
+interface LocaleSwitcherProps extends Omit<HTMLAttributes<HTMLElement>, 'children' | 'onChange'> {
+    /** One link per language, in the order shown. */
+    locales: readonly LocaleSwitcherLocale[];
+    /** The code of the page's language; that link is `aria-current="page"`. */
+    current: string;
+    /** Names the navigation, in the page's language: "Language", "Sprache". */
+    label: string;
+    /** Renders each link with your router (locale-aware links keep client navigation). */
+    renderLink?: UixRenderLink;
+}
+/**
+ * A language switcher (HAR-1380; MOTUS C-12): a `Segmented selection="link"` whose links carry
+ * `lang` and `hreflang`, so each language's name is read in that language.
+ */
+declare function LocaleSwitcher({ locales, current, label, renderLink, ...props }: LocaleSwitcherProps): react.JSX.Element;
 
-export { Segmented, SegmentedOption, type SegmentedOptionProps, type SegmentedProps };
+export { LocaleSwitcher, type LocaleSwitcherLocale, type LocaleSwitcherProps, Segmented, SegmentedOption, type SegmentedOptionProps, type SegmentedProps };

package/dist/components/Segmented.js

@@ -1,15 +1,19 @@
 "use client";
-import { jsx } from "react/jsx-runtime";
+import { jsx, jsxs } from "react/jsx-runtime";
 import { createContext, useContext, useEffect, useMemo, useRef } from "react";
 import { cx } from "../cx.js";
+import { renderUixLink } from "../link.js";
+import { useSlidingIndicator } from "../hooks/useSlidingIndicator.js";
 const SegmentedCtx = createContext({});
 const OPTION = ".uix-segmented__option";
-function Segmented({ value, onChange, selection = "toggle", children, className, onKeyDown, ...props }) {
+function Segmented({ value, onChange, selection = "toggle", renderLink, children, className, onKeyDown, ...props }) {
   const ref = useRef(null);
-  const contextValue = useMemo(() => ({ value, onChange, selection }), [value, onChange, selection]);
+  const contextValue = useMemo(() => ({ value, onChange, selection, renderLink }), [value, onChange, selection, renderLink]);
+  const indicatorRef = useRef(null);
+  useSlidingIndicator(ref, indicatorRef, `${OPTION}:is([aria-pressed="true"], [aria-checked="true"])`);
   useEffect(() => {
     const group = ref.current;
-    if (!group) return;
+    if (!group || selection === "link") return;
     const all = Array.from(group.querySelectorAll(OPTION));
     const enabled = all.filter((o) => !o.disabled);
     const current = enabled.find((o) => o.getAttribute("aria-pressed") === "true" || o.getAttribute("aria-checked") === "true") ?? enabled[0];
@@ -55,10 +59,18 @@ function Segmented({ value, onChange, selection = "toggle", children, className,
     target.focus();
     target.click();
   };
-  return /* @__PURE__ */ jsx(SegmentedCtx.Provider, { value: contextValue, children: /* @__PURE__ */ jsx("div", { ref, role: selection === "radio" ? "radiogroup" : "group", className: cx("uix-segmented", className), onKeyDown: handleKeyDown, ...props, children }) });
+  if (selection === "link") {
+    return /* @__PURE__ */ jsx(SegmentedCtx.Provider, { value: contextValue, children: /* @__PURE__ */ jsx("nav", { className: cx("uix-segmented-nav", className), onKeyDown, ...props, children: /* @__PURE__ */ jsx("ul", { className: "uix-segmented", role: "list", children }) }) });
+  }
+  return /* @__PURE__ */ jsx(SegmentedCtx.Provider, { value: contextValue, children: /* @__PURE__ */ jsxs("div", { ref, role: selection === "radio" ? "radiogroup" : "group", className: cx("uix-segmented", className), onKeyDown: handleKeyDown, ...props, children: [
+    children,
+    /* @__PURE__ */ jsx("span", { ref: indicatorRef, className: "uix-segmented__indicator", "aria-hidden": "true", hidden: true })
+  ] }) });
 }
 function SegmentedOption({
   value,
+  href,
+  hrefLang,
   children,
   className,
   onClick,
@@ -67,6 +79,24 @@ function SegmentedOption({
   const ctx = useContext(SegmentedCtx);
   const selected = ctx.value === value;
   const radio = ctx.selection === "radio";
+  if (ctx.selection === "link") {
+    const { type: _type, disabled, form: _form, formAction: _formAction, name: _name, ...linkProps } = props;
+    if (disabled || !href) {
+      return /* @__PURE__ */ jsx("li", { children: /* @__PURE__ */ jsx("a", { ...linkProps, hrefLang, className: cx("uix-segmented__option", className), "aria-disabled": "true", "aria-current": selected ? "page" : void 0, children }) });
+    }
+    return /* @__PURE__ */ jsx("li", { children: renderUixLink(ctx.renderLink, {
+      ...linkProps,
+      href,
+      hrefLang,
+      className: cx("uix-segmented__option", className),
+      "aria-current": selected ? "page" : void 0,
+      onClick: (event) => {
+        ctx.onChange?.(value);
+        onClick?.(event);
+      },
+      children
+    }) });
+  }
   return /* @__PURE__ */ jsx(
     "button",
     {
@@ -85,7 +115,11 @@ function SegmentedOption({
     }
   );
 }
+function LocaleSwitcher({ locales, current, label, renderLink, ...props }) {
+  return /* @__PURE__ */ jsx(Segmented, { selection: "link", value: current, "aria-label": label, renderLink, ...props, children: locales.map((locale) => /* @__PURE__ */ jsx(SegmentedOption, { value: locale.code, href: locale.href, hrefLang: locale.code, lang: locale.code, children: locale.label }, locale.code)) });
+}
 export {
+  LocaleSwitcher,
   Segmented,
   SegmentedOption
 };

package/dist/components/Select.d.ts

@@ -27,7 +27,8 @@ interface SelectLabels {
     results: string;
 }
 interface SelectProps extends Omit<SelectHTMLAttributes<HTMLSelectElement>, 'size'> {
-    size?: 'sm' | 'md';
+    /** `sm` 28 px, `md` 36 px (default), `lg` 44 px, the public touch-target size (HAR-1812). */
+    size?: 'sm' | 'md' | 'lg';
     /** The options as data, instead of `<option>` / `<optgroup>` children. */
     options?: readonly (SelectOption | SelectGroup)[];
     /**
@@ -64,7 +65,7 @@ interface SelectProps extends Omit<SelectHTMLAttributes<HTMLSelectElement>, 'siz
  * A select that draws its own list (HAR-1572): the WAI-ARIA APG select-only combobox — focus
  * stays on the trigger, `aria-activedescendant` marks the active option — in a top-layer popover
  * placed with `useAnchoredPosition`, or a bottom sheet on a phone. A visually hidden native
- * `<select>` carries `name`, `required`, `form`, `multiple` and the value, so `<option>` children,
+ * select element (the form proxy) carries `name`, `required`, `form`, `multiple` and the value, so `<option>` children,
  * `onChange(e)` with `e.target.value`, FormData, `form.reset()`, `ref` and react-hook-form keep
  * working; `ref` points at that select.
  */

package/dist/components/Select.js

@@ -4,6 +4,7 @@ import { Children, Fragment as Fragment2, forwardRef, isValidElement, useCallbac
 import { cx } from "../cx.js";
 import { useUixLabels } from "../labels-context.js";
 import { useAnchoredPosition, zoomOf } from "../hooks/useAnchoredPosition.js";
+import { markKeyOpened, watchInputModality } from "../motion.js";
 import { Drawer } from "./Drawer.js";
 import {
   buildSelectModel,
@@ -542,18 +543,23 @@ const Select = forwardRef(function Select2(props, forwardedRef) {
       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`;
+      if (!isOpen()) markKeyOpened(popup);
       try {
         if (!isOpen()) popup.showPopover();
       } catch {
       }
       if (isSearchable) searchRef.current?.focus({ preventScroll: true });
     } else {
+      if (isOpen()) markKeyOpened(popup);
       try {
         if (isOpen()) popup.hidePopover();
       } catch {
       }
     }
   }, [showing, isSearchable]);
+  useEffect(() => {
+    watchInputModality();
+  }, []);
   useAnchoredPosition(triggerRef, popupRef, { open: showing, placement, offset: OFFSET, padding: EDGE });
   useEffect(() => {
     if (open && mode === "sheet") (isSearchable ? searchRef.current : listRef.current)?.focus({ preventScroll: true });
@@ -706,7 +712,7 @@ const Select = forwardRef(function Select2(props, forwardedRef) {
         ref: triggerRef,
         type: "button",
         role: "combobox",
-        className: cx("uix-select", size === "sm" && "uix-select--sm", className),
+        className: cx("uix-select", size !== "md" && `uix-select--${size}`, className),
         style,
         disabled,
         "aria-label": ariaLabel,

package/dist/components/ShortcutHint.d.ts

@@ -5,17 +5,18 @@ interface ShortcutHintProps {
     keys: KeyShortcut;
     /** Text before the keys, e.g. an icon button's name. */
     label?: string;
-    /** Set the button's `aria-keyshortcuts`. `false` when the button already has its own (a prop, or a Tooltip's). */
-    ownsAria: boolean;
+    /** The control's own `aria-describedby`: the spoken keys are added after it, never instead. */
+    describedBy?: string;
 }
 /**
- * The hover / keyboard-focus hint of a `Button` with `shortcut` (HAR-2031). In the button it
- * leaves only an empty, hidden marker, so the button's text, name, layout and selectors are
- * unchanged (no wrapper, no sibling). The bubble itself is portalled after mount into the
- * nearest `<dialog>` (outside one a modal dialog makes everything inert) or `<body>`, as a
- * top-layer popover, `aria-hidden`: assistive technology gets the key from the button's
- * `aria-keyshortcuts`, which this sets for the viewer's platform (Mod is Meta on Apple, Control
- * elsewhere) unless the button already has its own.
+ * The hover / keyboard-focus hint of a `Button` or `ButtonLink` with `shortcut` (HAR-2031,
+ * HAR-2416). In the control it leaves only an empty, hidden marker, so the control's text, name,
+ * layout and selectors are unchanged (no wrapper, no sibling). The bubble itself is portalled
+ * after mount into the nearest `<dialog>` (outside one a modal dialog makes everything inert) or
+ * `<body>`, as a top-layer popover, `aria-hidden`. Screen readers hear the keys once, as the
+ * control's description ("Control+K"; ⌘ is "Command" on Apple), the same way a `Tooltip` with a
+ * shortcut says them: the description is the one channel every screen reader announces, and an
+ * `aria-keyshortcuts` beside it was read a second time by those that announce that too.
  *
  * It opens on hover and on keyboard focus (`:focus-visible`), so focus a menu or dialog sends back
  * after a mouse choice does not open it. It closes on leave, blur, Escape and when the button is
@@ -24,6 +25,6 @@ interface ShortcutHintProps {
  *
  * It is its own client component so that `Button`, which has no hooks, still renders on a server.
  */
-declare function ShortcutHint({ keys, label, ownsAria }: ShortcutHintProps): react.JSX.Element;
+declare function ShortcutHint({ keys, label, describedBy }: ShortcutHintProps): react.JSX.Element;
 
 export { ShortcutHint, type ShortcutHintProps };

package/dist/components/ShortcutHint.js

@@ -1,9 +1,9 @@
 "use client";
 import { Fragment, jsx, jsxs } from "react/jsx-runtime";
-import { useEffect, useLayoutEffect, useRef, useState } from "react";
+import { useEffect, useId, useLayoutEffect, useRef, useState } from "react";
 import { createPortal } from "react-dom";
 import { useAnchoredPosition } from "../hooks/useAnchoredPosition.js";
-import { KbdCombo, ariaKeyShortcuts, useKbdPlatform } from "./Kbd.js";
+import { KbdCombo, spokenKeys, useKbdPlatform } from "./Kbd.js";
 const useIsomorphicLayoutEffect = typeof document !== "undefined" ? useLayoutEffect : useEffect;
 const isShown = (el) => {
   try {
@@ -20,26 +20,15 @@ const focusVisible = (el) => {
   }
 };
 const stop = (event) => event.stopPropagation();
-function ShortcutHint({ keys, label, ownsAria }) {
+function ShortcutHint({ keys, label, describedBy }) {
   const markerRef = useRef(null);
   const bubbleRef = useRef(null);
   const anchorRef = useRef(null);
   const [host, setHost] = useState(null);
   const [open, setOpen] = useState(false);
   const platform = useKbdPlatform();
-  const shortcuts = ariaKeyShortcuts(keys, platform);
+  const spokenId = `${useId()}-keys`;
   useAnchoredPosition(anchorRef, bubbleRef, { open, placement: "top", offset: 6 });
-  useIsomorphicLayoutEffect(() => {
-    const button = markerRef.current?.parentElement;
-    if (!button || !ownsAria) return void 0;
-    const before = button.getAttribute("aria-keyshortcuts");
-    button.setAttribute("aria-keyshortcuts", shortcuts);
-    return () => {
-      if (button.getAttribute("aria-keyshortcuts") !== shortcuts) return;
-      if (before == null) button.removeAttribute("aria-keyshortcuts");
-      else button.setAttribute("aria-keyshortcuts", before);
-    };
-  }, [shortcuts, ownsAria]);
   useIsomorphicLayoutEffect(() => {
     const button = markerRef.current?.parentElement ?? null;
     anchorRef.current = button;
@@ -49,6 +38,17 @@ function ShortcutHint({ keys, label, ownsAria }) {
     }
     setHost(button.closest("dialog") ?? button.ownerDocument.body);
   }, []);
+  useIsomorphicLayoutEffect(() => {
+    const control = anchorRef.current;
+    if (!host || !control) return void 0;
+    const value = [describedBy, spokenId].filter(Boolean).join(" ");
+    control.setAttribute("aria-describedby", value);
+    return () => {
+      if (control.getAttribute("aria-describedby") !== value) return;
+      if (describedBy) control.setAttribute("aria-describedby", describedBy);
+      else control.removeAttribute("aria-describedby");
+    };
+  }, [host, describedBy, spokenId]);
   useEffect(() => {
     const button = anchorRef.current;
     const bubble = bubbleRef.current;
@@ -85,7 +85,10 @@ function ShortcutHint({ keys, label, ownsAria }) {
       if (focusVisible(button)) show();
     };
     const onKey = (event) => {
-      if (event.key === "Escape") hide();
+      if (event.key !== "Escape" || !isShown(bubble)) return;
+      event.preventDefault();
+      event.stopPropagation();
+      hide();
     };
     const watch = new MutationObserver(() => {
       if (button.hasAttribute("disabled") || button.getAttribute("aria-disabled") === "true") hide();
@@ -97,7 +100,7 @@ function ShortcutHint({ keys, label, ownsAria }) {
     button.addEventListener("blur", hide);
     bubble.addEventListener("mouseenter", show);
     bubble.addEventListener("mouseleave", hideSoon);
-    button.ownerDocument.addEventListener("keydown", onKey);
+    button.ownerDocument.addEventListener("keydown", onKey, true);
     return () => {
       window.clearTimeout(timer);
       watch.disconnect();
@@ -107,7 +110,7 @@ function ShortcutHint({ keys, label, ownsAria }) {
       button.removeEventListener("blur", hide);
       bubble.removeEventListener("mouseenter", show);
       bubble.removeEventListener("mouseleave", hideSoon);
-      button.ownerDocument.removeEventListener("keydown", onKey);
+      button.ownerDocument.removeEventListener("keydown", onKey, true);
       if (isShown(bubble)) {
         try {
           bubble.hidePopover();
@@ -120,26 +123,29 @@ function ShortcutHint({ keys, label, ownsAria }) {
   return /* @__PURE__ */ jsxs(Fragment, { children: [
     /* @__PURE__ */ jsx("span", { ref: markerRef, hidden: true, "data-uix-shortcut-hint": "" }),
     host && createPortal(
-      /* @__PURE__ */ jsxs(
-        "span",
-        {
-          ref: bubbleRef,
-          className: "uix-tooltip__bubble uix-tooltip__bubble--hint",
-          "aria-hidden": "true",
-          ...bubbleAttr,
-          onClick: stop,
-          onDoubleClick: stop,
-          onContextMenu: stop,
-          onPointerDown: stop,
-          onPointerUp: stop,
-          onMouseDown: stop,
-          onMouseUp: stop,
-          children: [
-            label && /* @__PURE__ */ jsx("span", { children: label }),
-            /* @__PURE__ */ jsx("span", { className: "uix-tooltip__shortcut", children: /* @__PURE__ */ jsx(KbdCombo, { keys: [...keys], platform }) })
-          ]
-        }
-      ),
+      /* @__PURE__ */ jsxs(Fragment, { children: [
+        /* @__PURE__ */ jsx("span", { id: spokenId, hidden: true, children: spokenKeys(keys, platform) }),
+        /* @__PURE__ */ jsxs(
+          "span",
+          {
+            ref: bubbleRef,
+            className: "uix-tooltip__bubble uix-tooltip__bubble--hint",
+            "aria-hidden": "true",
+            ...bubbleAttr,
+            onClick: stop,
+            onDoubleClick: stop,
+            onContextMenu: stop,
+            onPointerDown: stop,
+            onPointerUp: stop,
+            onMouseDown: stop,
+            onMouseUp: stop,
+            children: [
+              label && /* @__PURE__ */ jsx("span", { children: label }),
+              /* @__PURE__ */ jsx("span", { className: "uix-tooltip__shortcut", children: /* @__PURE__ */ jsx(KbdCombo, { keys: [...keys], platform }) })
+            ]
+          }
+        )
+      ] }),
       host
     )
   ] });

package/dist/components/Sidebar.d.ts

@@ -1,17 +1,42 @@
 import * as react from 'react';
 import { ReactNode, AnchorHTMLAttributes, HTMLAttributes } from 'react';
+import { KeyShortcut } from './Kbd.js';
 
+/** The search row under the sidebar head (HAR-1371): it opens your search or command palette. */
+interface SidebarSearch {
+    /** The row's words, e.g. "Search". In the rail they are the button's name only. */
+    label: ReactNode;
+    /**
+     * The keys that open the same search, shown at the end of the row and given to assistive
+     * technology as `aria-keyshortcuts`, e.g. `['Mod', 'K']`. Showing them does not bind them:
+     * your command palette (or app) listens for the keys.
+     */
+    shortcut?: KeyShortcut;
+    onActivate: () => void;
+}
 interface SidebarProps extends HTMLAttributes<HTMLElement> {
     collapsed?: boolean;
     nav?: 'full' | 'rail';
     onToggle?: () => void;
     brand?: ReactNode;
     toggleIcon?: ReactNode;
+    /**
+     * Controls in the head beside the brand (HAR-1371): a mode toggle, a "…" utility `Menu`,
+     * collapse-all. Icon buttons (`Button icon size="sm"`) fit the row. Hidden in the rail.
+     */
+    actions?: ReactNode;
+    /** A search row under the head that opens your search (HAR-1371). */
+    search?: SidebarSearch;
+    /**
+     * A slot pinned to the bottom of the sidebar (HAR-1371), for an `AccountMenu`. In the rail it
+     * keeps what it renders; give an `AccountMenu` `collapsed` there.
+     */
+    footer?: ReactNode;
     children?: ReactNode;
     expandLabel?: string;
     collapseLabel?: string;
 }
-declare function Sidebar({ collapsed, nav, onToggle, brand, toggleIcon, children, expandLabel: expandLabelProp, collapseLabel: collapseLabelProp, className, ...props }: SidebarProps): react.JSX.Element;
+declare function Sidebar({ collapsed, nav, onToggle, brand, toggleIcon, actions, search, footer, children, expandLabel: expandLabelProp, collapseLabel: collapseLabelProp, className, ...props }: SidebarProps): react.JSX.Element;
 interface SidebarSectionProps {
     label?: string;
     children?: ReactNode;
@@ -29,7 +54,13 @@ interface NavItemProps extends AnchorHTMLAttributes<HTMLAnchorElement> {
     description?: ReactNode;
     children?: ReactNode;
 }
-declare function NavItem({ icon, badge, active, as: Tag, description, children, className, ...props }: NavItemProps): react.JSX.Element;
+/**
+ * One navigation row: a link (`as="a"`, default) or, for a row that acts in place (a mode toggle,
+ * an account menu), a `button`. The forwarded ref reaches the rendered `<a>` or `<button>`
+ * (HAR-1810), so a row can anchor a `Popover` (`anchor={ref}`); `popoverTarget` and other button
+ * attributes pass through with `as="button"`.
+ */
+declare const NavItem: react.ForwardRefExoticComponent<NavItemProps & react.RefAttributes<HTMLButtonElement | HTMLAnchorElement>>;
 interface NavGroupProps {
     icon?: ReactNode;
     label: ReactNode;
@@ -44,6 +75,7 @@ interface SubNavItemProps extends AnchorHTMLAttributes<HTMLAnchorElement> {
     as?: 'a' | 'button';
     children?: ReactNode;
 }
-declare function SubNavItem({ active, as: Tag, children, className, ...props }: SubNavItemProps): react.JSX.Element;
+/** A nested navigation row. Like `NavItem`, it forwards its ref to the `<a>` or `<button>` (HAR-1810). */
+declare const SubNavItem: react.ForwardRefExoticComponent<SubNavItemProps & react.RefAttributes<HTMLButtonElement | HTMLAnchorElement>>;
 
-export { NavGroup, type NavGroupProps, NavItem, type NavItemProps, Sidebar, type SidebarProps, SidebarSection, type SidebarSectionProps, SubNavItem, type SubNavItemProps };
+export { NavGroup, type NavGroupProps, NavItem, type NavItemProps, Sidebar, type SidebarProps, type SidebarSearch, SidebarSection, type SidebarSectionProps, SubNavItem, type SubNavItemProps };