@mortenbrudvik/waveui 0.4.0 → 0.7.0

package/dist/hooks/useTriggerElement.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"useTriggerElement.cjs","names":["FOCUSABLE_SELECTOR","isHiddenInput","isFocusable","getFirstTabbable","React","STATE_ARIA","unwrapFragment","isCloneableElement","useMergedRefs","useEventCallback","mergeProps","renderTrigger","require_runtime","require_dev","require_useEventCallback","require_focus","require_useMergedRefs","require_mergeProps","require_renderTrigger","react","GENERIC_ROLES","isNonGenericRole","role","first","isInTabOrder","tabIndex","NATIVE_CONTROL_SELECTOR","isWidgetElement","el","getTriggerTarget","widget","candidate","getTriggerFocusTarget","trigger","target","useTriggerFocusRef","createTriggerFocusRef","triggerRef","isElementNode","value","withoutStateAria","rest","props","key","pickStateAria","values","moveStateAria","previous","useTriggerElement","options","wrapperFallback","setWrapperFallback","isRenderProp","children","content","singleElement","cloneable","asChild","cloneTarget","allProps","triggerProps","ourRef","ourProps","omitStateAria","childRef","attachedRef","detectAttach","node","mergedRef","componentName","autoWrapper","wrapper","wrapperIsTrigger","movedAria","span","spread","name","ourId","resolvedId","reportId","onResolvedId","_theirRef","theirProps","_ourRef","ourRest","merged","wrapperProps","renderProps"],"sources":["../../src/hooks/useTriggerElement.tsx"],"sourcesContent":["import * as React from 'react';\nimport { mergeProps } from '../lib/mergeProps';\nimport {\n  isCloneableElement,\n  renderTrigger,\n  STATE_ARIA,\n  unwrapFragment,\n  type TriggerChildren,\n} from '../lib/renderTrigger';\nimport { warnOnce } from '../lib/dev';\nimport { FOCUSABLE_SELECTOR, getFirstTabbable, isFocusable, isHiddenInput } from '../lib/focus';\nimport { useMergedRefs } from './useMergedRefs';\nimport { useEventCallback } from './useEventCallback';\n\n/**\n * Options of {@link useTriggerElement}. (`triggerProps.ref`, the hook's second argument, may be an\n * inline callback: it is re-attached after each commit; a stable ref is attached once.)\n */\nexport interface UseTriggerElementOptions {\n  /** Public name used in development warnings, e.g. `'Dialog.Trigger'`. */\n  componentName: string;\n  /**\n   * `false` renders the 0.4 wrapper `<span>` around the children instead of cloning; the state\n   * ARIA moves onto the element inside it, as for the automatic fallback. @default true\n   */\n  asChild?: boolean;\n  /**\n   * Called (from an effect) with the id the trigger element ends up with: the child's own `id` when\n   * it has one, otherwise `triggerProps.id`. Roots store it for `aria-labelledby`.\n   */\n  onResolvedId?: (id: string) => void;\n  /**\n   * Context-menu mode (`openOnContext`): the trigger is a region, not a menu button, so its\n   * element carries no `aria-haspopup`, `aria-expanded` or `aria-controls`. A cloned child and a\n   * wrapper span do not receive them from `triggerProps` (the state-ARIA move of the wrapper span\n   * is skipped too). A render-prop child still receives every trigger prop; when its element\n   * carries them after a commit, they are removed from it and a development warning is logged\n   * once (`<componentName>:context-state-aria`).\n   * @default false\n   */\n  omitStateAria?: boolean;\n}\n\ntype UnknownProps = Record<string, unknown>;\n\n/** Roles that make an element no widget of its own. */\nconst GENERIC_ROLES: ReadonlySet<string> = new Set(['generic', 'none', 'presentation']);\n\n/** Whether a `role` value (attribute or prop) names a role other than a generic one. */\nfunction isNonGenericRole(role: unknown): boolean {\n  if (typeof role !== 'string') return false;\n  const first = role.trim().split(/\\s+/)[0];\n  return first !== '' && !GENERIC_ROLES.has(first);\n}\n\n/** Whether a `tabIndex` prop puts its element in the tab order. */\nfunction isInTabOrder(tabIndex: unknown): boolean {\n  if (typeof tabIndex === 'number') return tabIndex >= 0;\n  return typeof tabIndex === 'string' && tabIndex.trim() !== '' && Number(tabIndex) >= 0;\n}\n\n/** Native controls, whose own role can carry the state ARIA. */\nconst NATIVE_CONTROL_SELECTOR = 'a[href], button, input, select, summary, textarea';\n\n/**\n * Whether `el` can carry the state ARIA: its `role` names a role other than a generic one, or it\n * has none and is a native control. A `<span>` or `<div>` without a role is generic, whatever its\n * `tabIndex` (axe `aria-allowed-attr`).\n */\nfunction isWidgetElement(el: Element): boolean {\n  const role = el.getAttribute('role');\n  if (role !== null && role.trim() !== '') return isNonGenericRole(role);\n  return el.matches(NATIVE_CONTROL_SELECTOR);\n}\n\n/**\n * The element that acts as the trigger rendered as `el` (a cloned child, or the wrapper `<span>`\n * of `asChild={false}`, of text children and of the automatic fallback): `el` itself when it is a\n * widget (a native control, or an element given a role other than a generic one) in the tab order\n * by markup (`tabIndex >= 0`: a button, a span given `role=\"button\"` and `tabIndex={0}`); else the\n * first element inside it in the tab order by markup; else `el` when it is a widget out of the tab\n * order (a span given only `role=\"button\"`, a `<button tabIndex={-1}>`); else `null`. `tabIndex`\n * alone never makes a generic element the trigger: it cannot carry the state ARIA. The trigger's\n * state ARIA belongs on it, and focus returns to it ({@link getTriggerFocusTarget}). Read from the\n * markup, not `getFirstTabbable`: that skips an `inert` subtree, and the page around a trigger is\n * inert while its modal dialog is open. Internal (not exported from the package entry).\n */\nexport function getTriggerTarget(el: HTMLElement): HTMLElement | null {\n  const widget = isWidgetElement(el);\n  if (widget && el.tabIndex >= 0) return el;\n  for (const candidate of el.querySelectorAll<HTMLElement>(FOCUSABLE_SELECTOR)) {\n    if (!isHiddenInput(candidate) && candidate.tabIndex >= 0) return candidate;\n  }\n  return widget ? el : null;\n}\n\n/**\n * The element that takes focus for the trigger rendered as `trigger`: the one rule of every focus\n * return of Menu, Popover, Dialog and Drawer (Escape, outside press, item activation, Tab and\n * Shift+Tab, the Close part). It is the {@link getTriggerTarget} element, which carries the state\n * ARIA, when that can take focus now (a `<button tabIndex={-1}>` child; the button inside a\n * `tabIndex={-1}` wrapper span, or inside a span given only a `role`); else the first tabbable\n * element inside `trigger` (a wrapper span whose first control is disabled or hidden, with another\n * one after it); else `trigger` itself when it can take focus (a span holding only text, given a\n * `tabIndex` but no widget role); else `null`. Internal (not exported from the package entry).\n */\nexport function getTriggerFocusTarget(trigger: HTMLElement | null): HTMLElement | null {\n  if (!trigger) return null;\n  const target = getTriggerTarget(trigger);\n  if (target && isFocusable(target)) return target;\n  return getFirstTabbable(trigger) ?? (isFocusable(trigger) ? trigger : null);\n}\n\n/**\n * A read-only ref for `useRestoreFocus`'s `triggerRef` and `useDismiss`'s `anchorRef` (Menu,\n * Popover; the anchor is where a surface opened from the popup restores focus once its opener is\n * gone): resolved when it is read, to {@link getTriggerFocusTarget} of the element in\n * `triggerRef`, or to that element itself when nothing in it can take focus (the restore then goes\n * to the element next to where it is, as for any opener that cannot take focus). Stable while\n * `triggerRef` is.\n */\nexport function useTriggerFocusRef(\n  triggerRef: React.RefObject<HTMLElement | null>,\n): React.RefObject<HTMLElement | null> {\n  return React.useMemo(() => createTriggerFocusRef(triggerRef), [triggerRef]);\n}\n\nfunction createTriggerFocusRef(\n  triggerRef: React.RefObject<HTMLElement | null>,\n): React.RefObject<HTMLElement | null> {\n  return {\n    get current() {\n      const trigger = triggerRef.current;\n      return trigger && (getTriggerFocusTarget(trigger) ?? trigger);\n    },\n  };\n}\n\nfunction isElementNode(value: unknown): value is Element {\n  return typeof value === 'object' && value !== null && (value as Node).nodeType === 1;\n}\n\ntype StateAriaValues = Partial<Record<(typeof STATE_ARIA)[number], unknown>>;\n\n/** `props` without the state ARIA keys (context-menu mode). */\nfunction withoutStateAria(props: UnknownProps): UnknownProps {\n  const rest = { ...props };\n  for (const key of STATE_ARIA) delete rest[key];\n  return rest;\n}\n\n/** The state ARIA keys present in `props` (a key given as `undefined` removes the attribute). */\nfunction pickStateAria(props: UnknownProps): StateAriaValues {\n  const values: StateAriaValues = {};\n  for (const key of STATE_ARIA) {\n    if (key in props) values[key] = props[key];\n  }\n  return values;\n}\n\n/** Writes `values` onto `target` and returns a cleanup that restores its own attributes. */\nfunction moveStateAria(target: Element, values: StateAriaValues): () => void {\n  const previous = Object.keys(values).map((key) => [key, target.getAttribute(key)] as const);\n  for (const [key, value] of Object.entries(values)) {\n    if (value === undefined || value === null) target.removeAttribute(key);\n    else target.setAttribute(key, String(value));\n  }\n  return () => {\n    for (const [key, value] of previous) {\n      if (value === null) target.removeAttribute(key);\n      else target.setAttribute(key, value);\n    }\n  };\n}\n\n/**\n * Renders a trigger (`Dialog.Trigger`, `Drawer.Trigger`, `Popover.Trigger`, `Menu.Trigger`,\n * `.Close`): puts `triggerProps` on the consumer's element.\n *\n * - **Single element child** (default): cloned with the trigger props merged in (`mergeProps`):\n *   handlers composed (the child's run first; `preventDefault()` skips the trigger's), classes and\n *   styles merged, the child's own `id` kept, and live `aria-expanded` / `aria-controls` /\n *   `aria-haspopup` always winning over the child's values. The trigger ref and the child's own ref\n *   are merged with {@link useMergedRefs}, so a ref that keeps its identity is attached once and\n *   the element is not detached and re-attached on every render (stable positioning anchor and\n *   focus-restore target). A Fragment around a single element (`<><Button /></>`) is unwrapped and\n *   its element cloned.\n * - **`triggerProps.ref`** does not have to be stable: an inline callback or a fresh `mergeRefs(…)`\n *   result is detached and re-attached after each commit (as React does for an inline ref), and a\n *   state-setting ref (`ref: setAnchor`) never loops. Pass a stable ref (an object ref, a\n *   `useCallback` or a state setter) so floating-ui's reference and restore targets are set once.\n * - **Render-prop child**: called with `triggerProps` (all of them, whatever `asChild` says).\n * - **`asChild={false}`**: the 0.4 wrapper `<span>` carrying the trigger props except the state\n *   ARIA, which moves as in the automatic fallback below (so a button inside is announced as\n *   opening the popup).\n * - **Text, a Fragment of several elements, several children**: a wrapper `<span>` (with a\n *   development warning from `renderTrigger`) carrying the trigger props except the state ARIA,\n *   which moves as in the automatic fallback below.\n * - **A wrapper span the consumer made the trigger** (a `role` such as `\"button\"` and\n *   `tabIndex={0}` passed to the trigger, e.g. `<Menu.Trigger asChild={false} role=\"button\"\n *   tabIndex={0}>Actions</Menu.Trigger>`): the span keeps the state ARIA, as the element that\n *   takes focus and is announced ({@link getTriggerTarget}). A span given only such a role gets\n *   it too (after mount) when nothing inside it is in the tab order; `tabIndex` alone leaves the\n *   span generic, so the state ARIA moves as below.\n * - **Automatic fallback**: when the cloned child has not attached its ref by the end of the mount\n *   layout effect (a custom component that neither forwards `ref` nor spreads props), the hook\n *   switches once to the wrapper span — whose click handler catches the bubbling click, so the\n *   trigger keeps working — and warns in development. The span keeps the other trigger props (`id`,\n *   handlers, ref), but the state ARIA (`aria-haspopup`, `aria-expanded`, `aria-controls`), which\n *   a generic span cannot carry, moves after each commit onto the first element inside it in the\n *   tab order (the child's own values restored when it stops being that element), or is dropped\n *   when there is none. A component that forwards `ref` but drops `onClick` cannot be detected.\n * - **Context-menu mode** (`omitStateAria`): a cloned child and a wrapper span get no\n *   `aria-haspopup`, `aria-expanded` or `aria-controls` (nothing moves inside the span either); a\n *   render-prop child receives them with the other props, and the ones it spreads are removed from\n *   its element after each commit, with a one-time development warning.\n *\n * @param children      The trigger's children.\n * @param triggerProps  Props for the trigger element (`id`, state ARIA, handlers, `ref`; the ref may\n *   change between renders, a stable one is attached once).\n * @param options       See {@link UseTriggerElementOptions}.\n */\nexport function useTriggerElement<P>(\n  children: TriggerChildren<P> | React.ReactNode,\n  triggerProps: P,\n  options: UseTriggerElementOptions,\n): React.ReactNode {\n  const { componentName, asChild = true, onResolvedId, omitStateAria = false } = options;\n  const [wrapperFallback, setWrapperFallback] = React.useState(false);\n\n  const isRenderProp = typeof children === 'function';\n  // A Fragment around one element is that element (children of a conditional expression).\n  const content = isRenderProp ? null : unwrapFragment(children as React.ReactNode);\n  const singleElement = isCloneableElement(content);\n  const cloneable = asChild && !wrapperFallback && singleElement;\n  const cloneTarget = cloneable ? (content as React.ReactElement<UnknownProps>) : null;\n  const allProps = triggerProps as UnknownProps;\n  const ourRef = allProps.ref as React.Ref<Element> | undefined;\n  // The props this hook puts on an element itself (a render-prop child receives `triggerProps`).\n  const ourProps = omitStateAria ? withoutStateAria(allProps) : allProps;\n  // The cloned child's own `ref` prop is read to merge it (React 19 keeps `ref` in props).\n  const childRef = cloneTarget\n    ? (cloneTarget.props.ref as React.Ref<Element> | undefined)\n    : undefined;\n\n  const attachedRef = React.useRef<Element | null>(null);\n  const detectAttach = React.useCallback((node: Element | null) => {\n    attachedRef.current = isElementNode(node) ? node : null;\n  }, []);\n  const mergedRef = useMergedRefs<Element>(ourRef, childRef, detectAttach);\n\n  React.useLayoutEffect(() => {\n    if (!cloneable || attachedRef.current) return;\n    warnOnce(\n      `trigger-ref:${componentName}`,\n      `${componentName}: its child did not attach the trigger ref (a component that neither forwards \\`ref\\` nor spreads its props). It is rendered inside a <span> wrapper instead; forward \\`ref\\` and spread props onto the element, or pass asChild={false}.`,\n    );\n    // C-HOOKS site 2: the child never attached its ref after mount; switch to the wrapper span once.\n    setWrapperFallback(true);\n  }, [cloneable, componentName]);\n\n  // A wrapper span: the explicit one of `asChild={false}`, the automatic fallback of a single\n  // element child, or children that cannot be cloned (text, several elements). The trigger is the\n  // element inside, so the state ARIA, which a generic span cannot carry, goes to the first element\n  // it rendered in the tab order — unless the consumer made the span itself the trigger (a widget\n  // `role` and `tabIndex={0}`, see getTriggerTarget): then the span keeps it from the first render.\n  // A span given only such a role gets it after mount when nothing inside it is in the tab order.\n  const autoWrapper = asChild && wrapperFallback && singleElement;\n  const wrapper = !isRenderProp && !cloneable;\n  const wrapperIsTrigger =\n    wrapper && isNonGenericRole(ourProps.role) && isInTabOrder(ourProps.tabIndex);\n  const movedAria = wrapper && !wrapperIsTrigger && !omitStateAria ? pickStateAria(ourProps) : null;\n  // No deps: runs after every commit of the trigger (which re-renders on every state change), so\n  // the attributes follow the live state and the child's current first tabbable element. A new\n  // target rendered by the child without a trigger commit is picked up at the next one.\n  React.useLayoutEffect(() => {\n    const span = attachedRef.current;\n    if (!movedAria || !span) return undefined;\n    const target = getTriggerTarget(span as HTMLElement);\n    return target ? moveStateAria(target, movedAria) : undefined;\n  });\n\n  // Context-menu mode: the state ARIA a render-prop child spread onto its element is removed after\n  // each commit (React writes it again only when a value changes). No deps: every commit.\n  React.useLayoutEffect(() => {\n    const el = attachedRef.current;\n    if (!omitStateAria || !isRenderProp || !el) return;\n    const spread = STATE_ARIA.filter((name) => el.hasAttribute(name));\n    if (spread.length === 0) return;\n    for (const name of spread) el.removeAttribute(name);\n    warnOnce(\n      `${componentName}:context-state-aria`,\n      `${componentName}: the trigger element is a context-menu region (openOnContext), which is not a menu button: do not spread aria-haspopup, aria-expanded and aria-controls onto it.`,\n    );\n  });\n\n  const ourId = typeof ourProps.id === 'string' ? ourProps.id : undefined;\n  const childId =\n    cloneTarget && typeof cloneTarget.props.id === 'string' ? cloneTarget.props.id : undefined;\n  const resolvedId = childId ?? ourId;\n  const reportId = useEventCallback(onResolvedId);\n  React.useEffect(() => {\n    if (resolvedId) reportId(resolvedId);\n  }, [resolvedId, reportId]);\n\n  if (cloneTarget) {\n    const { ref: _theirRef, ...theirProps } = cloneTarget.props;\n    const { ref: _ourRef, ...ourRest } = ourProps;\n    const merged = mergeProps(ourRest, theirProps, { oursWin: STATE_ARIA });\n    return React.cloneElement(cloneTarget, { ...merged, ref: mergedRef });\n  }\n\n  if (wrapper) {\n    const { ref: _ourRef, ...ourRest } = ourProps;\n    const wrapperProps: UnknownProps = { ...ourRest, ref: mergedRef };\n    if (!wrapperIsTrigger || omitStateAria) for (const key of STATE_ARIA) delete wrapperProps[key];\n    // The explicit 0.4 span renders the children as given. Otherwise `asChild` lets renderTrigger\n    // warn about children it cannot clone; the automatic fallback (a single element, never cloned\n    // again) warned above.\n    return asChild\n      ? renderTrigger(content, wrapperProps, { componentName, asChild: !autoWrapper })\n      : renderTrigger(children, wrapperProps, { componentName, asChild: false });\n  }\n\n  // A render-prop child. In context-menu mode its element is found through the merged ref, so the\n  // state ARIA it spreads can be removed.\n  const renderProps = omitStateAria ? ({ ...allProps, ref: mergedRef } as P) : triggerProps;\n  return renderTrigger(children, renderProps, { componentName, asChild: false });\n}\n"],"mappings":"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"}

package/dist/hooks/useTriggerElement.mjs

@@ -0,0 +1,126 @@
+"use client";
+import { warnOnce as e } from "../lib/dev.mjs";
+import { useEventCallback as t } from "./useEventCallback.mjs";
+import { FOCUSABLE_SELECTOR as n, getFirstTabbable as r, isFocusable as i, isHiddenInput as a } from "../lib/focus.mjs";
+import { useMergedRefs as o } from "./useMergedRefs.mjs";
+import { mergeProps as s } from "../lib/mergeProps.mjs";
+import { STATE_ARIA as c, isCloneableElement as l, renderTrigger as u, unwrapFragment as d } from "../lib/renderTrigger.mjs";
+import * as f from "react";
+//#region src/hooks/useTriggerElement.tsx
+var p = /* @__PURE__ */ new Set([
+	"generic",
+	"none",
+	"presentation"
+]);
+function m(e) {
+	if (typeof e != "string") return !1;
+	let t = e.trim().split(/\s+/)[0];
+	return t !== "" && !p.has(t);
+}
+function h(e) {
+	return typeof e == "number" ? e >= 0 : typeof e == "string" && e.trim() !== "" && Number(e) >= 0;
+}
+var g = "a[href], button, input, select, summary, textarea";
+function _(e) {
+	let t = e.getAttribute("role");
+	return t !== null && t.trim() !== "" ? m(t) : e.matches(g);
+}
+function v(e) {
+	let t = _(e);
+	if (t && e.tabIndex >= 0) return e;
+	for (let t of e.querySelectorAll(n)) if (!a(t) && t.tabIndex >= 0) return t;
+	return t ? e : null;
+}
+function y(e) {
+	if (!e) return null;
+	let t = v(e);
+	return t && i(t) ? t : r(e) ?? (i(e) ? e : null);
+}
+function b(e) {
+	return f.useMemo(() => x(e), [e]);
+}
+function x(e) {
+	return { get current() {
+		let t = e.current;
+		return t && (y(t) ?? t);
+	} };
+}
+function S(e) {
+	return typeof e == "object" && !!e && e.nodeType === 1;
+}
+function C(e) {
+	let t = { ...e };
+	for (let e of c) delete t[e];
+	return t;
+}
+function w(e) {
+	let t = {};
+	for (let n of c) n in e && (t[n] = e[n]);
+	return t;
+}
+function T(e, t) {
+	let n = Object.keys(t).map((t) => [t, e.getAttribute(t)]);
+	for (let [n, r] of Object.entries(t)) r == null ? e.removeAttribute(n) : e.setAttribute(n, String(r));
+	return () => {
+		for (let [t, r] of n) r === null ? e.removeAttribute(t) : e.setAttribute(t, r);
+	};
+}
+function E(n, r, i) {
+	let { componentName: a, asChild: p = !0, onResolvedId: g, omitStateAria: _ = !1 } = i, [y, b] = f.useState(!1), x = typeof n == "function", E = x ? null : d(n), D = l(E), O = p && !y && D, k = O ? E : null, A = r, j = A.ref, M = _ ? C(A) : A, N = k ? k.props.ref : void 0, P = f.useRef(null), F = f.useCallback((e) => {
+		P.current = S(e) ? e : null;
+	}, []), I = o(j, N, F);
+	f.useLayoutEffect(() => {
+		O && !P.current && (e(`trigger-ref:${a}`, `${a}: its child did not attach the trigger ref (a component that neither forwards \`ref\` nor spreads its props). It is rendered inside a <span> wrapper instead; forward \`ref\` and spread props onto the element, or pass asChild={false}.`), b(!0));
+	}, [O, a]);
+	let L = p && y && D, R = !x && !O, z = R && m(M.role) && h(M.tabIndex), B = R && !z && !_ ? w(M) : null;
+	f.useLayoutEffect(() => {
+		let e = P.current;
+		if (!B || !e) return;
+		let t = v(e);
+		return t ? T(t, B) : void 0;
+	}), f.useLayoutEffect(() => {
+		let t = P.current;
+		if (!_ || !x || !t) return;
+		let n = c.filter((e) => t.hasAttribute(e));
+		if (n.length !== 0) {
+			for (let e of n) t.removeAttribute(e);
+			e(`${a}:context-state-aria`, `${a}: the trigger element is a context-menu region (openOnContext), which is not a menu button: do not spread aria-haspopup, aria-expanded and aria-controls onto it.`);
+		}
+	});
+	let V = typeof M.id == "string" ? M.id : void 0, H = (k && typeof k.props.id == "string" ? k.props.id : void 0) ?? V, U = t(g);
+	if (f.useEffect(() => {
+		H && U(H);
+	}, [H, U]), k) {
+		let { ref: e, ...t } = k.props, { ref: n, ...r } = M, i = s(r, t, { oursWin: c });
+		return f.cloneElement(k, {
+			...i,
+			ref: I
+		});
+	}
+	if (R) {
+		let { ref: e, ...t } = M, r = {
+			...t,
+			ref: I
+		};
+		if (!z || _) for (let e of c) delete r[e];
+		return p ? u(E, r, {
+			componentName: a,
+			asChild: !L
+		}) : u(n, r, {
+			componentName: a,
+			asChild: !1
+		});
+	}
+	let W = _ ? {
+		...A,
+		ref: I
+	} : r;
+	return u(n, W, {
+		componentName: a,
+		asChild: !1
+	});
+}
+//#endregion
+export { y as getTriggerFocusTarget, v as getTriggerTarget, E as useTriggerElement, b as useTriggerFocusRef };
+
+//# sourceMappingURL=useTriggerElement.mjs.map

package/dist/hooks/useTriggerElement.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"useTriggerElement.mjs","names":["React","GENERIC_ROLES","isNonGenericRole","role","first","isInTabOrder","tabIndex","NATIVE_CONTROL_SELECTOR","isWidgetElement","el","getTriggerTarget","widget","candidate","FOCUSABLE_SELECTOR","isHiddenInput","getTriggerFocusTarget","trigger","target","isFocusable","getFirstTabbable","useTriggerFocusRef","createTriggerFocusRef","triggerRef","isElementNode","value","withoutStateAria","rest","props","key","STATE_ARIA","pickStateAria","values","moveStateAria","previous","useTriggerElement","options","wrapperFallback","setWrapperFallback","isRenderProp","children","content","unwrapFragment","singleElement","isCloneableElement","cloneable","asChild","cloneTarget","allProps","triggerProps","ourRef","ourProps","omitStateAria","childRef","attachedRef","detectAttach","node","mergedRef","useMergedRefs","warnOnce","componentName","autoWrapper","wrapper","wrapperIsTrigger","movedAria","span","spread","name","ourId","resolvedId","reportId","useEventCallback","onResolvedId","_theirRef","theirProps","_ourRef","ourRest","merged","mergeProps","wrapperProps","renderTrigger","renderProps"],"sources":["../../src/hooks/useTriggerElement.tsx"],"sourcesContent":["import * as React from 'react';\nimport { mergeProps } from '../lib/mergeProps';\nimport {\n  isCloneableElement,\n  renderTrigger,\n  STATE_ARIA,\n  unwrapFragment,\n  type TriggerChildren,\n} from '../lib/renderTrigger';\nimport { warnOnce } from '../lib/dev';\nimport { FOCUSABLE_SELECTOR, getFirstTabbable, isFocusable, isHiddenInput } from '../lib/focus';\nimport { useMergedRefs } from './useMergedRefs';\nimport { useEventCallback } from './useEventCallback';\n\n/**\n * Options of {@link useTriggerElement}. (`triggerProps.ref`, the hook's second argument, may be an\n * inline callback: it is re-attached after each commit; a stable ref is attached once.)\n */\nexport interface UseTriggerElementOptions {\n  /** Public name used in development warnings, e.g. `'Dialog.Trigger'`. */\n  componentName: string;\n  /**\n   * `false` renders the 0.4 wrapper `<span>` around the children instead of cloning; the state\n   * ARIA moves onto the element inside it, as for the automatic fallback. @default true\n   */\n  asChild?: boolean;\n  /**\n   * Called (from an effect) with the id the trigger element ends up with: the child's own `id` when\n   * it has one, otherwise `triggerProps.id`. Roots store it for `aria-labelledby`.\n   */\n  onResolvedId?: (id: string) => void;\n  /**\n   * Context-menu mode (`openOnContext`): the trigger is a region, not a menu button, so its\n   * element carries no `aria-haspopup`, `aria-expanded` or `aria-controls`. A cloned child and a\n   * wrapper span do not receive them from `triggerProps` (the state-ARIA move of the wrapper span\n   * is skipped too). A render-prop child still receives every trigger prop; when its element\n   * carries them after a commit, they are removed from it and a development warning is logged\n   * once (`<componentName>:context-state-aria`).\n   * @default false\n   */\n  omitStateAria?: boolean;\n}\n\ntype UnknownProps = Record<string, unknown>;\n\n/** Roles that make an element no widget of its own. */\nconst GENERIC_ROLES: ReadonlySet<string> = new Set(['generic', 'none', 'presentation']);\n\n/** Whether a `role` value (attribute or prop) names a role other than a generic one. */\nfunction isNonGenericRole(role: unknown): boolean {\n  if (typeof role !== 'string') return false;\n  const first = role.trim().split(/\\s+/)[0];\n  return first !== '' && !GENERIC_ROLES.has(first);\n}\n\n/** Whether a `tabIndex` prop puts its element in the tab order. */\nfunction isInTabOrder(tabIndex: unknown): boolean {\n  if (typeof tabIndex === 'number') return tabIndex >= 0;\n  return typeof tabIndex === 'string' && tabIndex.trim() !== '' && Number(tabIndex) >= 0;\n}\n\n/** Native controls, whose own role can carry the state ARIA. */\nconst NATIVE_CONTROL_SELECTOR = 'a[href], button, input, select, summary, textarea';\n\n/**\n * Whether `el` can carry the state ARIA: its `role` names a role other than a generic one, or it\n * has none and is a native control. A `<span>` or `<div>` without a role is generic, whatever its\n * `tabIndex` (axe `aria-allowed-attr`).\n */\nfunction isWidgetElement(el: Element): boolean {\n  const role = el.getAttribute('role');\n  if (role !== null && role.trim() !== '') return isNonGenericRole(role);\n  return el.matches(NATIVE_CONTROL_SELECTOR);\n}\n\n/**\n * The element that acts as the trigger rendered as `el` (a cloned child, or the wrapper `<span>`\n * of `asChild={false}`, of text children and of the automatic fallback): `el` itself when it is a\n * widget (a native control, or an element given a role other than a generic one) in the tab order\n * by markup (`tabIndex >= 0`: a button, a span given `role=\"button\"` and `tabIndex={0}`); else the\n * first element inside it in the tab order by markup; else `el` when it is a widget out of the tab\n * order (a span given only `role=\"button\"`, a `<button tabIndex={-1}>`); else `null`. `tabIndex`\n * alone never makes a generic element the trigger: it cannot carry the state ARIA. The trigger's\n * state ARIA belongs on it, and focus returns to it ({@link getTriggerFocusTarget}). Read from the\n * markup, not `getFirstTabbable`: that skips an `inert` subtree, and the page around a trigger is\n * inert while its modal dialog is open. Internal (not exported from the package entry).\n */\nexport function getTriggerTarget(el: HTMLElement): HTMLElement | null {\n  const widget = isWidgetElement(el);\n  if (widget && el.tabIndex >= 0) return el;\n  for (const candidate of el.querySelectorAll<HTMLElement>(FOCUSABLE_SELECTOR)) {\n    if (!isHiddenInput(candidate) && candidate.tabIndex >= 0) return candidate;\n  }\n  return widget ? el : null;\n}\n\n/**\n * The element that takes focus for the trigger rendered as `trigger`: the one rule of every focus\n * return of Menu, Popover, Dialog and Drawer (Escape, outside press, item activation, Tab and\n * Shift+Tab, the Close part). It is the {@link getTriggerTarget} element, which carries the state\n * ARIA, when that can take focus now (a `<button tabIndex={-1}>` child; the button inside a\n * `tabIndex={-1}` wrapper span, or inside a span given only a `role`); else the first tabbable\n * element inside `trigger` (a wrapper span whose first control is disabled or hidden, with another\n * one after it); else `trigger` itself when it can take focus (a span holding only text, given a\n * `tabIndex` but no widget role); else `null`. Internal (not exported from the package entry).\n */\nexport function getTriggerFocusTarget(trigger: HTMLElement | null): HTMLElement | null {\n  if (!trigger) return null;\n  const target = getTriggerTarget(trigger);\n  if (target && isFocusable(target)) return target;\n  return getFirstTabbable(trigger) ?? (isFocusable(trigger) ? trigger : null);\n}\n\n/**\n * A read-only ref for `useRestoreFocus`'s `triggerRef` and `useDismiss`'s `anchorRef` (Menu,\n * Popover; the anchor is where a surface opened from the popup restores focus once its opener is\n * gone): resolved when it is read, to {@link getTriggerFocusTarget} of the element in\n * `triggerRef`, or to that element itself when nothing in it can take focus (the restore then goes\n * to the element next to where it is, as for any opener that cannot take focus). Stable while\n * `triggerRef` is.\n */\nexport function useTriggerFocusRef(\n  triggerRef: React.RefObject<HTMLElement | null>,\n): React.RefObject<HTMLElement | null> {\n  return React.useMemo(() => createTriggerFocusRef(triggerRef), [triggerRef]);\n}\n\nfunction createTriggerFocusRef(\n  triggerRef: React.RefObject<HTMLElement | null>,\n): React.RefObject<HTMLElement | null> {\n  return {\n    get current() {\n      const trigger = triggerRef.current;\n      return trigger && (getTriggerFocusTarget(trigger) ?? trigger);\n    },\n  };\n}\n\nfunction isElementNode(value: unknown): value is Element {\n  return typeof value === 'object' && value !== null && (value as Node).nodeType === 1;\n}\n\ntype StateAriaValues = Partial<Record<(typeof STATE_ARIA)[number], unknown>>;\n\n/** `props` without the state ARIA keys (context-menu mode). */\nfunction withoutStateAria(props: UnknownProps): UnknownProps {\n  const rest = { ...props };\n  for (const key of STATE_ARIA) delete rest[key];\n  return rest;\n}\n\n/** The state ARIA keys present in `props` (a key given as `undefined` removes the attribute). */\nfunction pickStateAria(props: UnknownProps): StateAriaValues {\n  const values: StateAriaValues = {};\n  for (const key of STATE_ARIA) {\n    if (key in props) values[key] = props[key];\n  }\n  return values;\n}\n\n/** Writes `values` onto `target` and returns a cleanup that restores its own attributes. */\nfunction moveStateAria(target: Element, values: StateAriaValues): () => void {\n  const previous = Object.keys(values).map((key) => [key, target.getAttribute(key)] as const);\n  for (const [key, value] of Object.entries(values)) {\n    if (value === undefined || value === null) target.removeAttribute(key);\n    else target.setAttribute(key, String(value));\n  }\n  return () => {\n    for (const [key, value] of previous) {\n      if (value === null) target.removeAttribute(key);\n      else target.setAttribute(key, value);\n    }\n  };\n}\n\n/**\n * Renders a trigger (`Dialog.Trigger`, `Drawer.Trigger`, `Popover.Trigger`, `Menu.Trigger`,\n * `.Close`): puts `triggerProps` on the consumer's element.\n *\n * - **Single element child** (default): cloned with the trigger props merged in (`mergeProps`):\n *   handlers composed (the child's run first; `preventDefault()` skips the trigger's), classes and\n *   styles merged, the child's own `id` kept, and live `aria-expanded` / `aria-controls` /\n *   `aria-haspopup` always winning over the child's values. The trigger ref and the child's own ref\n *   are merged with {@link useMergedRefs}, so a ref that keeps its identity is attached once and\n *   the element is not detached and re-attached on every render (stable positioning anchor and\n *   focus-restore target). A Fragment around a single element (`<><Button /></>`) is unwrapped and\n *   its element cloned.\n * - **`triggerProps.ref`** does not have to be stable: an inline callback or a fresh `mergeRefs(…)`\n *   result is detached and re-attached after each commit (as React does for an inline ref), and a\n *   state-setting ref (`ref: setAnchor`) never loops. Pass a stable ref (an object ref, a\n *   `useCallback` or a state setter) so floating-ui's reference and restore targets are set once.\n * - **Render-prop child**: called with `triggerProps` (all of them, whatever `asChild` says).\n * - **`asChild={false}`**: the 0.4 wrapper `<span>` carrying the trigger props except the state\n *   ARIA, which moves as in the automatic fallback below (so a button inside is announced as\n *   opening the popup).\n * - **Text, a Fragment of several elements, several children**: a wrapper `<span>` (with a\n *   development warning from `renderTrigger`) carrying the trigger props except the state ARIA,\n *   which moves as in the automatic fallback below.\n * - **A wrapper span the consumer made the trigger** (a `role` such as `\"button\"` and\n *   `tabIndex={0}` passed to the trigger, e.g. `<Menu.Trigger asChild={false} role=\"button\"\n *   tabIndex={0}>Actions</Menu.Trigger>`): the span keeps the state ARIA, as the element that\n *   takes focus and is announced ({@link getTriggerTarget}). A span given only such a role gets\n *   it too (after mount) when nothing inside it is in the tab order; `tabIndex` alone leaves the\n *   span generic, so the state ARIA moves as below.\n * - **Automatic fallback**: when the cloned child has not attached its ref by the end of the mount\n *   layout effect (a custom component that neither forwards `ref` nor spreads props), the hook\n *   switches once to the wrapper span — whose click handler catches the bubbling click, so the\n *   trigger keeps working — and warns in development. The span keeps the other trigger props (`id`,\n *   handlers, ref), but the state ARIA (`aria-haspopup`, `aria-expanded`, `aria-controls`), which\n *   a generic span cannot carry, moves after each commit onto the first element inside it in the\n *   tab order (the child's own values restored when it stops being that element), or is dropped\n *   when there is none. A component that forwards `ref` but drops `onClick` cannot be detected.\n * - **Context-menu mode** (`omitStateAria`): a cloned child and a wrapper span get no\n *   `aria-haspopup`, `aria-expanded` or `aria-controls` (nothing moves inside the span either); a\n *   render-prop child receives them with the other props, and the ones it spreads are removed from\n *   its element after each commit, with a one-time development warning.\n *\n * @param children      The trigger's children.\n * @param triggerProps  Props for the trigger element (`id`, state ARIA, handlers, `ref`; the ref may\n *   change between renders, a stable one is attached once).\n * @param options       See {@link UseTriggerElementOptions}.\n */\nexport function useTriggerElement<P>(\n  children: TriggerChildren<P> | React.ReactNode,\n  triggerProps: P,\n  options: UseTriggerElementOptions,\n): React.ReactNode {\n  const { componentName, asChild = true, onResolvedId, omitStateAria = false } = options;\n  const [wrapperFallback, setWrapperFallback] = React.useState(false);\n\n  const isRenderProp = typeof children === 'function';\n  // A Fragment around one element is that element (children of a conditional expression).\n  const content = isRenderProp ? null : unwrapFragment(children as React.ReactNode);\n  const singleElement = isCloneableElement(content);\n  const cloneable = asChild && !wrapperFallback && singleElement;\n  const cloneTarget = cloneable ? (content as React.ReactElement<UnknownProps>) : null;\n  const allProps = triggerProps as UnknownProps;\n  const ourRef = allProps.ref as React.Ref<Element> | undefined;\n  // The props this hook puts on an element itself (a render-prop child receives `triggerProps`).\n  const ourProps = omitStateAria ? withoutStateAria(allProps) : allProps;\n  // The cloned child's own `ref` prop is read to merge it (React 19 keeps `ref` in props).\n  const childRef = cloneTarget\n    ? (cloneTarget.props.ref as React.Ref<Element> | undefined)\n    : undefined;\n\n  const attachedRef = React.useRef<Element | null>(null);\n  const detectAttach = React.useCallback((node: Element | null) => {\n    attachedRef.current = isElementNode(node) ? node : null;\n  }, []);\n  const mergedRef = useMergedRefs<Element>(ourRef, childRef, detectAttach);\n\n  React.useLayoutEffect(() => {\n    if (!cloneable || attachedRef.current) return;\n    warnOnce(\n      `trigger-ref:${componentName}`,\n      `${componentName}: its child did not attach the trigger ref (a component that neither forwards \\`ref\\` nor spreads its props). It is rendered inside a <span> wrapper instead; forward \\`ref\\` and spread props onto the element, or pass asChild={false}.`,\n    );\n    // C-HOOKS site 2: the child never attached its ref after mount; switch to the wrapper span once.\n    setWrapperFallback(true);\n  }, [cloneable, componentName]);\n\n  // A wrapper span: the explicit one of `asChild={false}`, the automatic fallback of a single\n  // element child, or children that cannot be cloned (text, several elements). The trigger is the\n  // element inside, so the state ARIA, which a generic span cannot carry, goes to the first element\n  // it rendered in the tab order — unless the consumer made the span itself the trigger (a widget\n  // `role` and `tabIndex={0}`, see getTriggerTarget): then the span keeps it from the first render.\n  // A span given only such a role gets it after mount when nothing inside it is in the tab order.\n  const autoWrapper = asChild && wrapperFallback && singleElement;\n  const wrapper = !isRenderProp && !cloneable;\n  const wrapperIsTrigger =\n    wrapper && isNonGenericRole(ourProps.role) && isInTabOrder(ourProps.tabIndex);\n  const movedAria = wrapper && !wrapperIsTrigger && !omitStateAria ? pickStateAria(ourProps) : null;\n  // No deps: runs after every commit of the trigger (which re-renders on every state change), so\n  // the attributes follow the live state and the child's current first tabbable element. A new\n  // target rendered by the child without a trigger commit is picked up at the next one.\n  React.useLayoutEffect(() => {\n    const span = attachedRef.current;\n    if (!movedAria || !span) return undefined;\n    const target = getTriggerTarget(span as HTMLElement);\n    return target ? moveStateAria(target, movedAria) : undefined;\n  });\n\n  // Context-menu mode: the state ARIA a render-prop child spread onto its element is removed after\n  // each commit (React writes it again only when a value changes). No deps: every commit.\n  React.useLayoutEffect(() => {\n    const el = attachedRef.current;\n    if (!omitStateAria || !isRenderProp || !el) return;\n    const spread = STATE_ARIA.filter((name) => el.hasAttribute(name));\n    if (spread.length === 0) return;\n    for (const name of spread) el.removeAttribute(name);\n    warnOnce(\n      `${componentName}:context-state-aria`,\n      `${componentName}: the trigger element is a context-menu region (openOnContext), which is not a menu button: do not spread aria-haspopup, aria-expanded and aria-controls onto it.`,\n    );\n  });\n\n  const ourId = typeof ourProps.id === 'string' ? ourProps.id : undefined;\n  const childId =\n    cloneTarget && typeof cloneTarget.props.id === 'string' ? cloneTarget.props.id : undefined;\n  const resolvedId = childId ?? ourId;\n  const reportId = useEventCallback(onResolvedId);\n  React.useEffect(() => {\n    if (resolvedId) reportId(resolvedId);\n  }, [resolvedId, reportId]);\n\n  if (cloneTarget) {\n    const { ref: _theirRef, ...theirProps } = cloneTarget.props;\n    const { ref: _ourRef, ...ourRest } = ourProps;\n    const merged = mergeProps(ourRest, theirProps, { oursWin: STATE_ARIA });\n    return React.cloneElement(cloneTarget, { ...merged, ref: mergedRef });\n  }\n\n  if (wrapper) {\n    const { ref: _ourRef, ...ourRest } = ourProps;\n    const wrapperProps: UnknownProps = { ...ourRest, ref: mergedRef };\n    if (!wrapperIsTrigger || omitStateAria) for (const key of STATE_ARIA) delete wrapperProps[key];\n    // The explicit 0.4 span renders the children as given. Otherwise `asChild` lets renderTrigger\n    // warn about children it cannot clone; the automatic fallback (a single element, never cloned\n    // again) warned above.\n    return asChild\n      ? renderTrigger(content, wrapperProps, { componentName, asChild: !autoWrapper })\n      : renderTrigger(children, wrapperProps, { componentName, asChild: false });\n  }\n\n  // A render-prop child. In context-menu mode its element is found through the merged ref, so the\n  // state ARIA it spreads can be removed.\n  const renderProps = omitStateAria ? ({ ...allProps, ref: mergedRef } as P) : triggerProps;\n  return renderTrigger(children, renderProps, { componentName, asChild: false });\n}\n"],"mappings":"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"}

package/dist/hooks/useTypeahead.cjs

@@ -0,0 +1,2 @@
+"use client";const e=require("./useEventCallback.cjs");let t=require("react");function n(e){return e.ctrlKey&&e.altKey&&e.key.length===1&&e.key!==` `}function r(e,t){return e.key.length!==1||e.metaKey||(e.ctrlKey||e.altKey)&&!n(e)?!1:e.key!==` `||t}function i(n){let{timeout:i=500}=n,a=e.useEventCallback(n.getItems),o=e.useEventCallback(n.onMatch),s=(0,t.useRef)(``),c=(0,t.useRef)(null),l=(0,t.useRef)(i);return(0,t.useEffect)(()=>{l.current=i},[i]),(0,t.useEffect)(()=>()=>{c.current!==null&&clearTimeout(c.current),c.current=null},[]),{onTypeahead:(0,t.useCallback)((e,t)=>{let n=s.current.length>0;if(!r(e,n))return!1;let i=s.current+e.key.toLowerCase();s.current=i,c.current!==null&&clearTimeout(c.current),c.current=setTimeout(()=>{s.current=``,c.current=null},l.current);let u=a().filter(e=>!e.disabled);if(u.length===0)return n;let d=i.length>1&&Array.from(i).every(e=>e===i[0])?i[0]:i,f=u.findIndex(e=>e.value===t),p=Math.max(f,0),m=[...u.slice(p),...u.slice(0,p)];d.length===1&&f!==-1&&(m=m.filter(e=>e.value!==t));let h=m.filter(e=>e.text.trim().toLowerCase().startsWith(d)).map(e=>e.value);return h.length===0?n:(o(h[0],h),!0)},[a,o]),isSearching:(0,t.useCallback)(()=>s.current.length>0,[])}}exports.isAltGraphCharacter=n,exports.useTypeahead=i;
+//# sourceMappingURL=useTypeahead.cjs.map

package/dist/hooks/useTypeahead.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"useTypeahead.cjs","names":["useEventCallback","useRef","useCallback","require_useEventCallback","react","isAltGraphCharacter","event","isTypeaheadKey","searching","useTypeahead","options","getItems","onMatch","bufferRef","timerRef","timeoutRef","timeout","search","items","item","prefix","c","currentIndex","currentValue","start","candidates","matches"],"sources":["../../src/hooks/useTypeahead.ts"],"sourcesContent":["import { useCallback, useEffect, useRef } from 'react';\nimport type * as React from 'react';\nimport { useEventCallback } from './useEventCallback';\n\n/** An item that typeahead can move to. */\nexport interface TypeaheadItem {\n  value: string;\n  /** Text matched against the typed characters (case-insensitive prefix match). */\n  text: string;\n  /** Disabled items are skipped. */\n  disabled?: boolean;\n}\n\n/** Options of {@link useTypeahead}. */\nexport interface UseTypeaheadOptions {\n  /** Returns the items in navigation order, read at key time. */\n  getItems: () => TypeaheadItem[];\n  /**\n   * Called with the value of the matched item, and with every item that matches the typed\n   * characters in search order (`value` first), for a caller that passes over an item it cannot\n   * move to.\n   */\n  onMatch: (value: string, matches: readonly string[]) => void;\n  /** Milliseconds after the last key press before the typed prefix resets. @default 500 */\n  timeout?: number;\n}\n\n/** Result of {@link useTypeahead}. */\nexport interface UseTypeaheadResult {\n  /**\n   * Handles a key press. Returns `true` when the key was consumed as typeahead: it matched an\n   * item, or it continued a search (see `isSearching`), even when nothing matches, a Space\n   * included. The caller should `preventDefault()`. Returns `false` for a key that is not\n   * typeahead, and for the first character of a search when it matches nothing (so a closed\n   * listbox can still open on it); that character still starts the search.\n   *\n   * @param event        The keydown event (DOM or React).\n   * @param currentValue The value of the focused or active item, or `null`.\n   */\n  onTypeahead: (event: KeyboardEvent | React.KeyboardEvent, currentValue: string | null) => boolean;\n  /**\n   * Whether a search is in progress: a printable key was typed less than `timeout` ms ago,\n   * whether or not it matched. A Space typed now continues the search.\n   */\n  isSearching: () => boolean;\n}\n\n/**\n * A character typed with AltGr, which Windows reports as Ctrl+Alt (Polish `ł`, Romanian `ș`): text\n * input for typeahead, not a shortcut. Ctrl+Alt with a named key (Ctrl+Alt+ArrowDown) or with\n * Space (AltGr types no plain space) is a shortcut. Internal (not exported from the package entry).\n */\nexport function isAltGraphCharacter(event: KeyboardEvent | React.KeyboardEvent): boolean {\n  return event.ctrlKey && event.altKey && event.key.length === 1 && event.key !== ' ';\n}\n\nfunction isTypeaheadKey(event: KeyboardEvent | React.KeyboardEvent, searching: boolean): boolean {\n  if (event.key.length !== 1 || event.metaKey) return false;\n  // Ctrl or Alt is a shortcut, except a character typed with AltGr.\n  if ((event.ctrlKey || event.altKey) && !isAltGraphCharacter(event)) return false;\n  // Space activates the focused item unless a search is in progress.\n  return event.key !== ' ' || searching;\n}\n\n/**\n * Typeahead for lists, menus and trees (APG): printable characters typed within `timeout` build a\n * prefix; the next enabled item whose text starts with it (wrapping around from the current item)\n * is matched. Repeating one character cycles through the items that start with it. Characters\n * typed with AltGr (Ctrl+Alt on Windows) count; Ctrl, Alt or Meta shortcuts do not.\n *\n * @example\n * const { onTypeahead } = useTypeahead({ getItems, onMatch: focusValue });\n * const onKeyDown = (e) => { if (onTypeahead(e, focusedValue)) e.preventDefault(); };\n */\nexport function useTypeahead(options: UseTypeaheadOptions): UseTypeaheadResult {\n  const { timeout = 500 } = options;\n  const getItems = useEventCallback(options.getItems);\n  const onMatch = useEventCallback(options.onMatch);\n  const bufferRef = useRef('');\n  const timerRef = useRef<ReturnType<typeof setTimeout> | null>(null);\n  const timeoutRef = useRef(timeout);\n\n  useEffect(() => {\n    timeoutRef.current = timeout;\n  }, [timeout]);\n\n  useEffect(\n    () => () => {\n      if (timerRef.current !== null) clearTimeout(timerRef.current);\n      timerRef.current = null;\n    },\n    [],\n  );\n\n  const onTypeahead = useCallback(\n    (event: KeyboardEvent | React.KeyboardEvent, currentValue: string | null): boolean => {\n      const searching = bufferRef.current.length > 0;\n      if (!isTypeaheadKey(event, searching)) return false;\n\n      const search = bufferRef.current + event.key.toLowerCase();\n      bufferRef.current = search;\n      if (timerRef.current !== null) clearTimeout(timerRef.current);\n      timerRef.current = setTimeout(() => {\n        bufferRef.current = '';\n        timerRef.current = null;\n      }, timeoutRef.current);\n\n      const items = getItems().filter((item) => !item.disabled);\n      // A search already in progress consumed this key even when nothing matches, so the caller\n      // must not activate or commit. The first unmatched character still returns false.\n      if (items.length === 0) return searching;\n\n      const repeated = search.length > 1 && Array.from(search).every((c) => c === search[0]);\n      const prefix = repeated ? search[0] : search;\n      const currentIndex = items.findIndex((item) => item.value === currentValue);\n      const start = Math.max(currentIndex, 0);\n      let candidates = [...items.slice(start), ...items.slice(0, start)];\n      // A single character moves on from the current item; a longer prefix may keep it.\n      if (prefix.length === 1 && currentIndex !== -1) {\n        candidates = candidates.filter((item) => item.value !== currentValue);\n      }\n      const matches = candidates\n        .filter((item) => item.text.trim().toLowerCase().startsWith(prefix))\n        .map((item) => item.value);\n      if (matches.length === 0) return searching;\n      onMatch(matches[0], matches);\n      return true;\n    },\n    [getItems, onMatch],\n  );\n\n  const isSearching = useCallback(() => bufferRef.current.length > 0, []);\n\n  return { onTypeahead, isSearching };\n}\n"],"mappings":"8EAoDA,SAAgBK,EAAoB,EAAqD,CACvF,OAAOC,EAAM,SAAWA,EAAM,QAAUA,EAAM,IAAI,SAAW,GAAKA,EAAM,MAAQ,GAClF,CAEA,SAASC,EAAe,EAA4C,EAA6B,CAK/F,OAJID,EAAM,IAAI,SAAW,GAAKA,EAAM,UAE/BA,EAAM,SAAWA,EAAM,SAAW,CAACD,EAAoBC,CAAK,EAAU,GAEpEA,EAAM,MAAQ,KAAOE,CAC9B,CAYA,SAAgBC,EAAa,EAAkD,CAC7E,GAAM,CAAE,UAAU,KAAQC,EACpBC,EAAWX,EAAAA,iBAAiBU,EAAQ,QAAQ,EAC5CE,EAAUZ,EAAAA,iBAAiBU,EAAQ,OAAO,EAC1CG,GAAA,EAAYZ,EAAAA,OAAAA,CAAO,EAAE,EACrBa,GAAA,EAAWb,EAAAA,OAAAA,CAA6C,IAAI,EAC5Dc,GAAA,EAAad,EAAAA,OAAAA,CAAOe,CAAO,EAqDjC,OAnDA,EAAAZ,EAAA,UAAA,KAAgB,CACd,EAAW,QAAUY,CACvB,EAAG,CAACA,CAAO,CAAC,GAEZ,EAAAZ,EAAA,UAAA,SACc,CACNU,EAAS,UAAY,MAAM,aAAaA,EAAS,OAAO,EAC5D,EAAS,QAAU,IACrB,EACA,CAAC,CACH,EAyCO,CAAE,aAAA,EAvCWZ,EAAAA,YAAAA,EACjB,EAA4C,IAAyC,CACpF,IAAMM,EAAYK,EAAU,QAAQ,OAAS,EAC7C,GAAI,CAACN,EAAeD,EAAOE,CAAS,EAAG,MAAO,GAE9C,IAAMS,EAASJ,EAAU,QAAUP,EAAM,IAAI,YAAY,EACzD,EAAU,QAAUW,EAChBH,EAAS,UAAY,MAAM,aAAaA,EAAS,OAAO,EAC5D,EAAS,QAAU,eAAiB,CAClC,EAAU,QAAU,GACpB,EAAS,QAAU,IACrB,EAAGC,EAAW,OAAO,EAErB,IAAMG,EAAQP,EAAS,CAAC,CAAC,OAAQ,GAAS,CAACQ,EAAK,QAAQ,EAGxD,GAAID,EAAM,SAAW,EAAG,OAAOV,EAG/B,IAAMY,EADWH,EAAO,OAAS,GAAK,MAAM,KAAKA,CAAM,CAAC,CAAC,MAAO,GAAMI,IAAMJ,EAAO,EAAE,EAC3DA,EAAO,GAAKA,EAChCK,EAAeJ,EAAM,UAAW,GAASC,EAAK,QAAUI,CAAY,EACpEC,EAAQ,KAAK,IAAIF,EAAc,CAAC,EAClCG,EAAa,CAAC,GAAGP,EAAM,MAAMM,CAAK,EAAG,GAAGN,EAAM,MAAM,EAAGM,CAAK,CAAC,EAE7DJ,EAAO,SAAW,GAAKE,IAAiB,KAC1C,EAAaG,EAAW,OAAQ,GAASN,EAAK,QAAUI,CAAY,GAEtE,IAAMG,EAAUD,EACb,OAAQ,GAASN,EAAK,KAAK,KAAK,CAAC,CAAC,YAAY,CAAC,CAAC,WAAWC,CAAM,CAAC,CAAC,CACnE,IAAK,GAASD,EAAK,KAAK,EAG3B,OAFIO,EAAQ,SAAW,EAAUlB,GACjCI,EAAQc,EAAQ,GAAIA,CAAO,EACpB,GACT,EACA,CAACf,EAAUC,CAAO,CAKX,EAAa,aAAA,EAFFV,EAAAA,YAAAA,KAAkBW,EAAU,QAAQ,OAAS,EAAG,CAAC,CAE/C,CAAY,CACpC"}

package/dist/hooks/useTypeahead.mjs

@@ -0,0 +1,38 @@
+"use client";
+import { useEventCallback as e } from "./useEventCallback.mjs";
+import { useCallback as t, useEffect as n, useRef as r } from "react";
+//#region src/hooks/useTypeahead.ts
+function i(e) {
+	return e.ctrlKey && e.altKey && e.key.length === 1 && e.key !== " ";
+}
+function a(e, t) {
+	return e.key.length !== 1 || e.metaKey || (e.ctrlKey || e.altKey) && !i(e) ? !1 : e.key !== " " || t;
+}
+function o(i) {
+	let { timeout: o = 500 } = i, s = e(i.getItems), c = e(i.onMatch), l = r(""), u = r(null), d = r(o);
+	return n(() => {
+		d.current = o;
+	}, [o]), n(() => () => {
+		u.current !== null && clearTimeout(u.current), u.current = null;
+	}, []), {
+		onTypeahead: t((e, t) => {
+			let n = l.current.length > 0;
+			if (!a(e, n)) return !1;
+			let r = l.current + e.key.toLowerCase();
+			l.current = r, u.current !== null && clearTimeout(u.current), u.current = setTimeout(() => {
+				l.current = "", u.current = null;
+			}, d.current);
+			let i = s().filter((e) => !e.disabled);
+			if (i.length === 0) return n;
+			let o = r.length > 1 && Array.from(r).every((e) => e === r[0]) ? r[0] : r, f = i.findIndex((e) => e.value === t), p = Math.max(f, 0), m = [...i.slice(p), ...i.slice(0, p)];
+			o.length === 1 && f !== -1 && (m = m.filter((e) => e.value !== t));
+			let h = m.filter((e) => e.text.trim().toLowerCase().startsWith(o)).map((e) => e.value);
+			return h.length === 0 ? n : (c(h[0], h), !0);
+		}, [s, c]),
+		isSearching: t(() => l.current.length > 0, [])
+	};
+}
+//#endregion
+export { i as isAltGraphCharacter, o as useTypeahead };
+
+//# sourceMappingURL=useTypeahead.mjs.map

package/dist/hooks/useTypeahead.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"useTypeahead.mjs","names":["isAltGraphCharacter","event","isTypeaheadKey","searching","useTypeahead","options","getItems","useEventCallback","onMatch","bufferRef","useRef","timerRef","timeoutRef","timeout","useEffect","useCallback","search","items","item","prefix","c","currentIndex","currentValue","start","candidates","matches"],"sources":["../../src/hooks/useTypeahead.ts"],"sourcesContent":["import { useCallback, useEffect, useRef } from 'react';\nimport type * as React from 'react';\nimport { useEventCallback } from './useEventCallback';\n\n/** An item that typeahead can move to. */\nexport interface TypeaheadItem {\n  value: string;\n  /** Text matched against the typed characters (case-insensitive prefix match). */\n  text: string;\n  /** Disabled items are skipped. */\n  disabled?: boolean;\n}\n\n/** Options of {@link useTypeahead}. */\nexport interface UseTypeaheadOptions {\n  /** Returns the items in navigation order, read at key time. */\n  getItems: () => TypeaheadItem[];\n  /**\n   * Called with the value of the matched item, and with every item that matches the typed\n   * characters in search order (`value` first), for a caller that passes over an item it cannot\n   * move to.\n   */\n  onMatch: (value: string, matches: readonly string[]) => void;\n  /** Milliseconds after the last key press before the typed prefix resets. @default 500 */\n  timeout?: number;\n}\n\n/** Result of {@link useTypeahead}. */\nexport interface UseTypeaheadResult {\n  /**\n   * Handles a key press. Returns `true` when the key was consumed as typeahead: it matched an\n   * item, or it continued a search (see `isSearching`), even when nothing matches, a Space\n   * included. The caller should `preventDefault()`. Returns `false` for a key that is not\n   * typeahead, and for the first character of a search when it matches nothing (so a closed\n   * listbox can still open on it); that character still starts the search.\n   *\n   * @param event        The keydown event (DOM or React).\n   * @param currentValue The value of the focused or active item, or `null`.\n   */\n  onTypeahead: (event: KeyboardEvent | React.KeyboardEvent, currentValue: string | null) => boolean;\n  /**\n   * Whether a search is in progress: a printable key was typed less than `timeout` ms ago,\n   * whether or not it matched. A Space typed now continues the search.\n   */\n  isSearching: () => boolean;\n}\n\n/**\n * A character typed with AltGr, which Windows reports as Ctrl+Alt (Polish `ł`, Romanian `ș`): text\n * input for typeahead, not a shortcut. Ctrl+Alt with a named key (Ctrl+Alt+ArrowDown) or with\n * Space (AltGr types no plain space) is a shortcut. Internal (not exported from the package entry).\n */\nexport function isAltGraphCharacter(event: KeyboardEvent | React.KeyboardEvent): boolean {\n  return event.ctrlKey && event.altKey && event.key.length === 1 && event.key !== ' ';\n}\n\nfunction isTypeaheadKey(event: KeyboardEvent | React.KeyboardEvent, searching: boolean): boolean {\n  if (event.key.length !== 1 || event.metaKey) return false;\n  // Ctrl or Alt is a shortcut, except a character typed with AltGr.\n  if ((event.ctrlKey || event.altKey) && !isAltGraphCharacter(event)) return false;\n  // Space activates the focused item unless a search is in progress.\n  return event.key !== ' ' || searching;\n}\n\n/**\n * Typeahead for lists, menus and trees (APG): printable characters typed within `timeout` build a\n * prefix; the next enabled item whose text starts with it (wrapping around from the current item)\n * is matched. Repeating one character cycles through the items that start with it. Characters\n * typed with AltGr (Ctrl+Alt on Windows) count; Ctrl, Alt or Meta shortcuts do not.\n *\n * @example\n * const { onTypeahead } = useTypeahead({ getItems, onMatch: focusValue });\n * const onKeyDown = (e) => { if (onTypeahead(e, focusedValue)) e.preventDefault(); };\n */\nexport function useTypeahead(options: UseTypeaheadOptions): UseTypeaheadResult {\n  const { timeout = 500 } = options;\n  const getItems = useEventCallback(options.getItems);\n  const onMatch = useEventCallback(options.onMatch);\n  const bufferRef = useRef('');\n  const timerRef = useRef<ReturnType<typeof setTimeout> | null>(null);\n  const timeoutRef = useRef(timeout);\n\n  useEffect(() => {\n    timeoutRef.current = timeout;\n  }, [timeout]);\n\n  useEffect(\n    () => () => {\n      if (timerRef.current !== null) clearTimeout(timerRef.current);\n      timerRef.current = null;\n    },\n    [],\n  );\n\n  const onTypeahead = useCallback(\n    (event: KeyboardEvent | React.KeyboardEvent, currentValue: string | null): boolean => {\n      const searching = bufferRef.current.length > 0;\n      if (!isTypeaheadKey(event, searching)) return false;\n\n      const search = bufferRef.current + event.key.toLowerCase();\n      bufferRef.current = search;\n      if (timerRef.current !== null) clearTimeout(timerRef.current);\n      timerRef.current = setTimeout(() => {\n        bufferRef.current = '';\n        timerRef.current = null;\n      }, timeoutRef.current);\n\n      const items = getItems().filter((item) => !item.disabled);\n      // A search already in progress consumed this key even when nothing matches, so the caller\n      // must not activate or commit. The first unmatched character still returns false.\n      if (items.length === 0) return searching;\n\n      const repeated = search.length > 1 && Array.from(search).every((c) => c === search[0]);\n      const prefix = repeated ? search[0] : search;\n      const currentIndex = items.findIndex((item) => item.value === currentValue);\n      const start = Math.max(currentIndex, 0);\n      let candidates = [...items.slice(start), ...items.slice(0, start)];\n      // A single character moves on from the current item; a longer prefix may keep it.\n      if (prefix.length === 1 && currentIndex !== -1) {\n        candidates = candidates.filter((item) => item.value !== currentValue);\n      }\n      const matches = candidates\n        .filter((item) => item.text.trim().toLowerCase().startsWith(prefix))\n        .map((item) => item.value);\n      if (matches.length === 0) return searching;\n      onMatch(matches[0], matches);\n      return true;\n    },\n    [getItems, onMatch],\n  );\n\n  const isSearching = useCallback(() => bufferRef.current.length > 0, []);\n\n  return { onTypeahead, isSearching };\n}\n"],"mappings":";;;;AAoDA,SAAgBA,EAAoB,GAAqD;CACvF,OAAOC,EAAM,WAAWA,EAAM,UAAUA,EAAM,IAAI,WAAW,KAAKA,EAAM,QAAQ;AAClF;AAEA,SAASC,EAAe,GAA4C,GAA6B;CAK/F,OAJID,EAAM,IAAI,WAAW,KAAKA,EAAM,YAE/BA,EAAM,WAAWA,EAAM,WAAW,CAACD,EAAoBC,CAAK,IAAU,KAEpEA,EAAM,QAAQ,OAAOE;AAC9B;AAYA,SAAgBC,EAAa,GAAkD;CAC7E,IAAM,EAAE,aAAU,QAAQC,GACpBC,IAAWC,EAAiBF,EAAQ,QAAQ,GAC5CG,IAAUD,EAAiBF,EAAQ,OAAO,GAC1CI,IAAYC,EAAO,EAAE,GACrBC,IAAWD,EAA6C,IAAI,GAC5DE,IAAaF,EAAOG,CAAO;CAqDjC,OAnDAC,QAAgB;EACd,EAAW,UAAUD;CACvB,GAAG,CAACA,CAAO,CAAC,GAEZC,cACc;EAEV,AADIH,EAAS,YAAY,QAAM,aAAaA,EAAS,OAAO,GAC5D,EAAS,UAAU;CACrB,GACA,CAAC,CACH,GAyCO;EAAE,aAvCWI,GACjB,GAA4C,MAAyC;GACpF,IAAMZ,IAAYM,EAAU,QAAQ,SAAS;GAC7C,IAAI,CAACP,EAAeD,GAAOE,CAAS,GAAG,OAAO;GAE9C,IAAMa,IAASP,EAAU,UAAUR,EAAM,IAAI,YAAY;GAGzD,AAFA,EAAU,UAAUe,GAChBL,EAAS,YAAY,QAAM,aAAaA,EAAS,OAAO,GAC5D,EAAS,UAAU,iBAAiB;IAElC,AADA,EAAU,UAAU,IACpB,EAAS,UAAU;GACrB,GAAGC,EAAW,OAAO;GAErB,IAAMK,IAAQX,EAAS,CAAC,CAAC,QAAQ,MAAS,CAACY,EAAK,QAAQ;GAGxD,IAAID,EAAM,WAAW,GAAG,OAAOd;GAG/B,IAAMgB,IADWH,EAAO,SAAS,KAAK,MAAM,KAAKA,CAAM,CAAC,CAAC,OAAO,MAAMI,MAAMJ,EAAO,EAAE,IAC3DA,EAAO,KAAKA,GAChCK,IAAeJ,EAAM,WAAW,MAASC,EAAK,UAAUI,CAAY,GACpEC,IAAQ,KAAK,IAAIF,GAAc,CAAC,GAClCG,IAAa,CAAC,GAAGP,EAAM,MAAMM,CAAK,GAAG,GAAGN,EAAM,MAAM,GAAGM,CAAK,CAAC;GAEjE,AAAIJ,EAAO,WAAW,KAAKE,MAAiB,OAC1C,IAAaG,EAAW,QAAQ,MAASN,EAAK,UAAUI,CAAY;GAEtE,IAAMG,IAAUD,EACb,QAAQ,MAASN,EAAK,KAAK,KAAK,CAAC,CAAC,YAAY,CAAC,CAAC,WAAWC,CAAM,CAAC,CAAC,CACnE,KAAK,MAASD,EAAK,KAAK;GAG3B,OAFIO,EAAQ,WAAW,IAAUtB,KACjCK,EAAQiB,EAAQ,IAAIA,CAAO,GACpB;EACT,GACA,CAACnB,GAAUE,CAAO,CAKX;EAAa,aAFFO,QAAkBN,EAAU,QAAQ,SAAS,GAAG,CAAC,CAE/C;CAAY;AACpC"}