@t007/utils 0.0.24 → 0.0.26

package/dist/hooks/react.cjs

@@ -0,0 +1,466 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/hooks/react.ts
+var react_exports = {};
+__export(react_exports, {
+  useArrowNavigation: () => useArrowNavigation,
+  useFocusTrap: () => useFocusTrap,
+  useHighlight: () => useHighlight,
+  useOutsideClick: () => useOutsideClick,
+  useRipple: () => useRipple,
+  useScrollAssist: () => useScrollAssist
+});
+module.exports = __toCommonJS(react_exports);
+
+// src/hooks/react/useScrollAssist.ts
+var import_react = require("react");
+
+// src/core/num.ts
+var import_utils = require("sia-reactor/utils");
+
+// src/core/dom.ts
+var import_utils2 = require("sia-reactor/utils");
+var INTERACTIVE_SELECTOR = 'button,[href],input,label,select,textarea,details>summary,[contenteditable],iframe,audio[controls],video[controls],[tabindex]:not([tabindex="-1"])';
+var isInteractive = (target) => target instanceof HTMLElement && target.matches(INTERACTIVE_SELECTOR);
+function getActiveElement(root = document) {
+  const activeEl = root.activeElement;
+  return !activeEl ? null : activeEl.shadowRoot ? getActiveElement(activeEl.shadowRoot) : activeEl;
+}
+
+// src/hooks/react/useScrollAssist.ts
+var import_sia_reactor = require("sia-reactor");
+function useScrollAssist(ref, { enabled = true, pxPerSecond = 80, assistClassName = "t007-scroll-assist", vertical = true, horizontal = true } = import_sia_reactor.NIL) {
+  const scrollId = (0, import_react.useRef)(null), last = (0, import_react.useRef)(performance.now()), assists = (0, import_react.useRef)({}), assistWidth = (0, import_react.useRef)(20), assistHeight = (0, import_react.useRef)(20);
+  const update = (0, import_react.useCallback)(() => {
+    const el = ref.current;
+    if (!el) return;
+    const hasInteractive = !!el.querySelector(INTERACTIVE_SELECTOR);
+    if (horizontal) {
+      const w = assists.current.left?.offsetWidth || assistWidth.current;
+      const check = hasInteractive ? el.clientWidth < w * 2 : false;
+      assists.current.left.style.display = check ? "none" : el.scrollLeft > 0 ? "block" : "none";
+      assists.current.right.style.display = check ? "none" : el.scrollLeft + el.clientWidth < el.scrollWidth - 1 ? "block" : "none";
+      assistWidth.current = w;
+    }
+    if (vertical) {
+      const h = assists.current.up?.offsetHeight || assistHeight.current;
+      const check = hasInteractive ? el.clientHeight < h * 2 : false;
+      assists.current.up.style.display = check ? "none" : el.scrollTop > 0 ? "block" : "none";
+      assists.current.down.style.display = check ? "none" : el.scrollTop + el.clientHeight < el.scrollHeight - 1 ? "block" : "none";
+      assistHeight.current = h;
+    }
+  }, [ref, horizontal, vertical]);
+  const scroll = (0, import_react.useCallback)(
+    (dir) => {
+      const el = ref.current;
+      if (!el) return;
+      const loop = () => {
+        const now = performance.now(), dt = now - last.current;
+        last.current = now;
+        const d = pxPerSecond * dt / 1e3;
+        if (dir === "left") el.scrollLeft = Math.max(0, el.scrollLeft - d);
+        if (dir === "right") el.scrollLeft = Math.min(el.scrollWidth - el.clientWidth, el.scrollLeft + d);
+        if (dir === "up") el.scrollTop = Math.max(0, el.scrollTop - d);
+        if (dir === "down") el.scrollTop = Math.min(el.scrollHeight - el.clientHeight, el.scrollTop + d);
+        scrollId.current = requestAnimationFrame(loop);
+      };
+      last.current = performance.now();
+      loop();
+    },
+    [ref, pxPerSecond]
+  );
+  const stop = (0, import_react.useCallback)(() => void (cancelAnimationFrame(scrollId.current ?? 0), scrollId.current = null), []);
+  const createAssist = (0, import_react.useCallback)(
+    (dir) => {
+      const el = document.createElement("div");
+      el.className = assistClassName;
+      el.dataset.scrollDirection = dir;
+      el.style.display = "none";
+      for (const evt of ["pointerenter", "dragenter"]) el.addEventListener(evt, () => scroll(dir));
+      for (const evt of ["pointerleave", "pointerup", "pointercancel", "dragleave", "dragend"]) el.addEventListener(evt, stop);
+      return el;
+    },
+    [assistClassName, scroll, stop]
+  );
+  (0, import_react.useEffect)(() => {
+    if (!enabled) return;
+    const el = ref.current;
+    if (!el || !el.parentElement) return;
+    const parent = el.parentElement;
+    const dirs = [...horizontal ? ["left", "right"] : [], ...vertical ? ["up", "down"] : []];
+    for (const dir of dirs) {
+      const div = createAssist(dir);
+      assists.current[dir] = div;
+      (dir === "left" || dir === "up" ? parent.insertBefore : parent.appendChild).call(parent, div, el);
+    }
+    const observer = new ResizeObserver(update), mObserver = new MutationObserver(update);
+    update(), el.addEventListener("scroll", update);
+    observer.observe(el), mObserver.observe(el, { childList: true, subtree: true, characterData: true });
+    const allAssists = assists.current;
+    return () => {
+      stop(), el.removeEventListener("scroll", update);
+      observer.disconnect(), mObserver.disconnect();
+      for (const a of Object.values(allAssists)) a?.remove();
+    };
+  }, [ref, enabled, assistClassName, vertical, horizontal, createAssist, update, stop]);
+  return { update };
+}
+
+// src/hooks/react/useOutsideClick.ts
+var import_react2 = require("react");
+
+// src/hooks/vanilla/outsideClick.ts
+var import_sia_reactor2 = require("sia-reactor");
+var stacks = /* @__PURE__ */ new WeakMap();
+function initOutsideClick(el, { enabled = false, onOutsideClick = import_sia_reactor2.NOOP, clickOnClick = true, clickOnEscape = true, clickOnFocusOut = false, allowInputs = true, root = window, scoped = true, capture = true } = import_sia_reactor2.NIL) {
+  const existing = (t007._outsiders ??= /* @__PURE__ */ new WeakMap()).get(el);
+  if (!enabled || existing) return existing ? existing : void 0;
+  scoped = scoped && root instanceof HTMLElement, root = scoped ? root : root === document ? document : window;
+  const stack = stacks.get(root) ?? [], onScopedOut = (e, t, p = e.touches?.[0] || e, rect = el.getBoundingClientRect()) => {
+    if (stack.at(-1) !== el || p.clientX >= rect.left && p.clientX <= rect.right && p.clientY >= rect.top && p.clientY <= rect.bottom) return false;
+    return (!scoped ? true : root.contains(t)) && onOutsideClick(e);
+  }, handleClick = ((e) => clickOnClick && !(allowInputs && isInteractive(e.target)) && onScopedOut(e, e.target)), handleEscape = ((e) => clickOnEscape && e.key === "Escape" && !e.ctrlKey && !e.shiftKey && !e.altKey && !e.metaKey && stack.at(-1) === el && onOutsideClick(e)), handleFocusOut = (e) => clickOnFocusOut && onScopedOut(e, e.relatedTarget);
+  root.addEventListener("mousedown", handleClick, capture), root.addEventListener("touchstart", handleClick, { passive: true, capture });
+  root.addEventListener("keydown", handleEscape, capture), el.addEventListener("focusout", handleFocusOut, capture);
+  if (!stack.includes(el)) stack.push(el), stacks.set(root, stack);
+  const destroy = () => {
+    root.removeEventListener("mousedown", handleClick, capture), root.removeEventListener("touchstart", handleClick, capture);
+    root.removeEventListener("keydown", handleEscape, capture);
+    el.removeEventListener("focusout", handleFocusOut, capture);
+    t007._outsiders.delete(el), stack.splice(stack.indexOf(el), 1);
+  };
+  return t007._outsiders.set(el, destroy), destroy;
+}
+
+// src/hooks/react/useOutsideClick.ts
+var import_sia_reactor3 = require("sia-reactor");
+function useOutsideClick(ref, config = import_sia_reactor3.NIL) {
+  (0, import_react2.useEffect)(() => ref.current ? initOutsideClick(ref.current, config) : void 0, [ref, config.enabled, config.onOutsideClick, config.clickOnEscape, config.clickOnClick, config.clickOnFocusOut, config.allowInputs, config.root, config.scoped, config.capture]);
+}
+
+// src/hooks/react/useArrowNavigation/index.ts
+var import_react3 = require("react");
+
+// src/hooks/react/useArrowNavigation/utils.ts
+var getTargetIndex = ({ key, currIndex, length, gridX, gridY, vGridY, loop, ctrlKey = false, rtl }) => {
+  const rowStart = currIndex - currIndex % gridX, rowEnd = Math.min(rowStart + gridX - 1, length - 1), colStart = currIndex % gridX, colEnd = Math.min(colStart + gridX * (gridY - 1), length - 1), canX = gridX > 1, canY = gridY > 1, horizontalMove = rtl ? { ArrowRight: canX ? -1 : 0, ArrowLeft: canX ? 1 : 0 } : { ArrowRight: canX ? 1 : 0, ArrowLeft: canX ? -1 : 0 }, move = { ...horizontalMove, ArrowDown: canY ? gridX : 0, ArrowUp: canY ? -gridX : 0, Home: ctrlKey ? 0 : rowStart, End: ctrlKey ? length - 1 : rowEnd, PageDown: (vGridY - 1) * gridX, PageUp: -(vGridY - 1) * gridX }[key] ?? 0;
+  let targetIndex = key === "Home" || key === "End" ? move : currIndex + move;
+  if (key === "ArrowDown") {
+    if (!loop && targetIndex >= length) targetIndex -= move;
+  } else if (key === "ArrowUp") {
+    if (!loop && targetIndex < 0) targetIndex += Math.abs(move);
+  } else if (key === "PageDown") {
+    if (!loop && targetIndex >= length) targetIndex = colEnd;
+  } else if (key === "PageUp") {
+    if (!loop && targetIndex < 0) targetIndex = colStart;
+  }
+  return loop ? (targetIndex + length) % length : (0, import_utils.clamp)(0, targetIndex, length - 1);
+};
+var getCommonAncestor = (first, second) => {
+  if (!first) return null;
+  if (!second) return first.parentElement;
+  const ancestors = /* @__PURE__ */ new Set();
+  let current = first;
+  while (current) ancestors.add(current), current = current.parentElement;
+  current = second;
+  while (current) {
+    if (ancestors.has(current)) return current;
+    current = current.parentElement;
+  }
+  return null;
+};
+var getGrid = (all, x = true, y = true, vY = true) => {
+  const len = all.length, grid = {};
+  if (!len) return grid;
+  let cols = all.findIndex((el) => el.offsetTop !== all[0].offsetTop);
+  cols = cols > 0 ? cols : len;
+  if (x) grid.x = cols;
+  let rows = Math.ceil(len / cols);
+  if (y) grid.y = rows;
+  if (vY) {
+    const itemHeight = all[0].offsetHeight ?? 0, containerHeight = getCommonAncestor(all[0], all[1])?.clientHeight ?? 0;
+    rows = (0, import_utils.clamp)(1, Math.floor(containerHeight / itemHeight), rows) || rows;
+    grid.vY = rows;
+  }
+  return grid;
+};
+
+// src/hooks/react/useArrowNavigation/consts.ts
+var import_sia_reactor4 = require("sia-reactor");
+var H_NAV_KEYS = ["ArrowRight", "ArrowLeft", "Home", "End"];
+var V_NAV_KEYS = ["ArrowUp", "ArrowDown", "PageDown", "PageUp"];
+var NAV_KEYS = [...H_NAV_KEYS, ...V_NAV_KEYS];
+var DEFAULT_CONFIG = {
+  enabled: null,
+  selector: "[data-arrow-item]",
+  focusOnHover: true,
+  loop: true,
+  virtual: false,
+  typeahead: false,
+  rovingTab: null,
+  defaultTabbableIndex: null,
+  baseTabIndex: "0",
+  resetMs: 500,
+  rtl: null,
+  grid: {},
+  activeClass: "focus-outlined",
+  inputSelector: "input,textarea,[contenteditable='true']",
+  focusOptions: { preventScroll: false },
+  scrollIntoView: { block: "nearest", inline: "nearest" },
+  onSelect: import_sia_reactor4.NOOP,
+  onFocusOut: import_sia_reactor4.NOOP
+};
+
+// src/hooks/react/useArrowNavigation/index.ts
+function useArrowNavigation(containerRef, config = {}) {
+  const { enabled: isEnabled, selector, focusOnHover, loop, virtual, typeahead, rovingTab, resetMs, activeClass, inputSelector, defaultTabbableIndex, baseTabIndex, grid, rtl: isRtl, focusOptions, scrollIntoView, onSelect, onFocusOut } = { ...DEFAULT_CONFIG, ...config }, [gridX, setGridX] = (0, import_react3.useState)(grid.x || 1), [gridY, setGridY] = (0, import_react3.useState)(grid.y || 1), [vGridY, setVGridY] = (0, import_react3.useState)(grid.vY || 1), [activeIndex, setActiveIndex] = (0, import_react3.useState)(-1), buffer = (0, import_react3.useRef)(""), timeout = (0, import_react3.useRef)(null), itemsRef = (0, import_react3.useRef)([]), enabled = isEnabled ?? virtual, roving = rovingTab ?? !virtual, rtl = (0, import_react3.useMemo)(() => isRtl !== null ? isRtl : getComputedStyle(containerRef.current || document.body).direction === "rtl", [containerRef, isRtl]), mutationObserverRef = (0, import_react3.useRef)(null), shouldSnub = (0, import_react3.useCallback)(() => !enabled || !containerRef.current, [enabled, containerRef]), isItemDisabled = (0, import_react3.useCallback)((el) => !el ? true : el.hasAttribute("disabled") || el.hasAttribute("aria-disabled"), []), getItems = (0, import_react3.useCallback)(() => itemsRef.current = Array.from(containerRef.current?.querySelectorAll(selector) || []), [containerRef, selector]);
+  const getAbleIndex = (0, import_react3.useCallback)(
+    (targetIndex, e = { key: "ArrowRight", ctrlKey: false }) => {
+      if (shouldSnub()) return;
+      const all = itemsRef.current;
+      if (!all.length) return null;
+      let index = targetIndex;
+      let attempts = 0;
+      while (attempts < all.length) {
+        if (!isItemDisabled(all[index])) return index;
+        index = getTargetIndex({ key: e.key, currIndex: index, gridX, gridY, vGridY, length: all.length, loop, ctrlKey: e.ctrlKey, rtl });
+        attempts++;
+      }
+      return null;
+    },
+    [shouldSnub, isItemDisabled, gridX, gridY, vGridY, loop, rtl]
+  );
+  const goToIndex = (0, import_react3.useCallback)(
+    (targetIndex, e = { key: "ArrowRight" }) => {
+      if (shouldSnub()) return;
+      const all = itemsRef.current, index = getAbleIndex(targetIndex, e);
+      if (index === null) return;
+      setActiveIndex(index), onSelect(all[index], e);
+      if (virtual) {
+        all[index]?.scrollIntoView(scrollIntoView);
+        containerRef.current?.setAttribute("aria-activedescendant", all[index].id || "");
+      } else all[index]?.focus(focusOptions);
+    },
+    [shouldSnub, virtual, onSelect, scrollIntoView, focusOptions, getAbleIndex, containerRef]
+  );
+  const updateDOM = (0, import_react3.useCallback)(() => {
+    if (shouldSnub() || !virtual && !roving) return;
+    const all = itemsRef.current;
+    if (!all.length) return;
+    const tabbableIndex = defaultTabbableIndex !== null && !isItemDisabled(all[defaultTabbableIndex]) ? defaultTabbableIndex : getAbleIndex(0);
+    for (let i = 0, len = all.length; i < len; i++) {
+      const el = all[i], isActive = i === activeIndex;
+      if (roving) el.setAttribute("tabindex", i === activeIndex || activeIndex === -1 && i === tabbableIndex ? baseTabIndex : "-1");
+      else if (virtual && activeIndex > 0) el.setAttribute("tabindex", i > activeIndex ? baseTabIndex : "-1");
+      else el.setAttribute("tabindex", baseTabIndex);
+      if (virtual) el.setAttribute("aria-selected", String(isActive)), el.classList.toggle(activeClass, isActive);
+    }
+  }, [shouldSnub, activeIndex, virtual, activeClass, roving, defaultTabbableIndex, getAbleIndex, isItemDisabled, baseTabIndex]);
+  const typeAhead = (0, import_react3.useCallback)(
+    (key) => {
+      if (shouldSnub() || !typeahead) return;
+      const all = itemsRef.current;
+      buffer.current += key.toLowerCase();
+      if (timeout.current) clearTimeout(timeout.current);
+      timeout.current = setTimeout(() => buffer.current = "", resetMs);
+      const start = activeIndex >= 0 ? activeIndex + 1 : 0;
+      for (let i = 0; i < all.length; i++) {
+        const idx = (start + i) % all.length, label = (all[idx].getAttribute("data-label") || all[idx].innerText || "").trim().toLowerCase();
+        if (label.startsWith(buffer.current)) return goToIndex(idx);
+      }
+    },
+    [shouldSnub, typeahead, resetMs, goToIndex, activeIndex]
+  );
+  const simulateKey = (0, import_react3.useCallback)(
+    (e) => {
+      if (shouldSnub() || getActiveElement()?.matches("option")) return;
+      const all = itemsRef.current, { key } = e;
+      if (!all.length) return;
+      if (virtual && (key === " " || key === "Enter")) return all[activeIndex]?.click();
+      if (e.target?.matches(DEFAULT_CONFIG.inputSelector) && !virtual) return;
+      if (typeahead && key.length === 1 && /^[a-z0-9]$/i.test(key)) return typeAhead(key);
+      if (!NAV_KEYS.includes(key)) return;
+      if (!(e.currentTarget?.matches(DEFAULT_CONFIG.inputSelector) && gridX <= 1 && H_NAV_KEYS.includes(key))) e.preventDefault?.(), e.stopPropagation?.();
+      const currIndex = virtual ? activeIndex : all.indexOf(getActiveElement()), targetIndex = getTargetIndex({ currIndex, gridX, gridY, vGridY, length: all.length, loop, rtl, key, ctrlKey: e.ctrlKey });
+      goToIndex(targetIndex, e);
+    },
+    [shouldSnub, virtual, activeIndex, gridX, gridY, vGridY, loop, rtl, goToIndex, typeahead, typeAhead]
+  );
+  const latest = (0, import_react3.useRef)({ getItems, updateDOM, activeIndex });
+  (0, import_react3.useEffect)(() => void (latest.current = { getItems, updateDOM, activeIndex }), [getItems, updateDOM, activeIndex]);
+  (0, import_react3.useEffect)(() => void getItems(), [getItems, enabled]);
+  (0, import_react3.useEffect)(() => void (!enabled && setActiveIndex(-1)), [enabled]);
+  (0, import_react3.useEffect)(() => updateDOM(), [activeIndex, updateDOM]);
+  (0, import_react3.useEffect)(() => {
+    if (shouldSnub()) return;
+    const container = containerRef.current, handleKeyDown = simulateKey, interactiveEls = !virtual ? [container] : [container.querySelector(inputSelector)];
+    for (const el of interactiveEls) el?.addEventListener("keydown", handleKeyDown);
+    return () => {
+      for (const el of interactiveEls) el?.removeEventListener("keydown", handleKeyDown);
+    };
+  }, [shouldSnub, containerRef, virtual, inputSelector, simulateKey]);
+  (0, import_react3.useEffect)(() => {
+    if (shouldSnub()) return;
+    const container = containerRef.current;
+    const handleFocusOut = (e) => {
+      if (!container.contains(e.relatedTarget)) return setActiveIndex(-1), onFocusOut(e);
+      const among = itemsRef.current.includes(e.relatedTarget);
+      if (!among && (defaultTabbableIndex ?? -1) >= 0) return setActiveIndex(-1);
+      if (virtual) setActiveIndex(-1);
+    };
+    container.addEventListener("focusout", handleFocusOut);
+    return () => container.removeEventListener("focusout", handleFocusOut);
+  }, [shouldSnub, containerRef, onFocusOut, defaultTabbableIndex, virtual]);
+  (0, import_react3.useEffect)(() => {
+    if (!enabled || !focusOnHover) return;
+    const all = itemsRef.current;
+    const handleHover = (e) => {
+      if (!focusOnHover) return;
+      const el = e.currentTarget;
+      const i = itemsRef.current?.indexOf(el);
+      if (i !== -1) goToIndex(i);
+    };
+    for (const el of all) el.addEventListener("mouseenter", handleHover);
+    return () => {
+      for (const el of all) el.removeEventListener("mouseenter", handleHover);
+    };
+  }, [enabled, focusOnHover, goToIndex]);
+  (0, import_react3.useEffect)(() => {
+    if (shouldSnub()) return;
+    const observer = mutationObserverRef.current = new MutationObserver(() => {
+      const { getItems: getItems2, updateDOM: updateDOM2, activeIndex: activeIndex2 } = latest.current;
+      const oldEl = itemsRef.current[activeIndex2];
+      getItems2();
+      const newEl = itemsRef.current[activeIndex2];
+      updateDOM2();
+      if (oldEl && newEl && oldEl === newEl) return;
+      setActiveIndex(-1);
+    });
+    observer.observe(containerRef.current, { childList: true, subtree: true });
+    return () => observer.disconnect();
+  }, [shouldSnub, containerRef]);
+  (0, import_react3.useEffect)(() => {
+    if (shouldSnub()) return;
+    const all = itemsRef.current;
+    const setGrid = (g) => {
+      if (g.x) setGridX(g.x);
+      if (g.y) setGridY(g.y);
+      if (g.vY) setVGridY(g.vY);
+    };
+    setGrid(grid);
+    if (grid.x && grid.y && grid.vY) return;
+    const calcGrid = () => setGrid(getGrid(all, !grid.x, !grid.y, !grid.vY));
+    calcGrid();
+    const resizeObserver = new ResizeObserver(() => calcGrid());
+    resizeObserver.observe(getCommonAncestor(all[0], all[1]) ?? containerRef.current);
+    return () => resizeObserver.disconnect();
+  }, [shouldSnub, containerRef, grid]);
+  (0, import_react3.useEffect)(() => void (timeout.current && clearTimeout(timeout.current)), []);
+  return { gridX, gridY, vGridY, activeIndex, activeItem: (0, import_react3.useCallback)(() => itemsRef.current[activeIndex] ?? null, [activeIndex]), items: (0, import_react3.useCallback)(() => itemsRef.current, []), getAbleIndex, typeAhead, goToIndex, simulateKey };
+}
+
+// src/hooks/react/useFocusTrap.ts
+var import_react4 = require("react");
+
+// src/hooks/vanilla/focusTrap.ts
+var import_sia_reactor5 = require("sia-reactor");
+var stacks2 = /* @__PURE__ */ new WeakMap();
+function initFocusTrap(el, { enabled = false, initialSelector = "[data-autofocus]", ringClassName = "focus-outline", root = window, scoped = true, capture = true } = import_sia_reactor5.NIL) {
+  const existing = (t007._ftrappers ??= /* @__PURE__ */ new WeakMap()).get(el);
+  if (!enabled || existing) return existing ? existing : void 0;
+  scoped = scoped && root instanceof HTMLElement, root = scoped ? root : root === document ? document : window;
+  const stack = stacks2.get(root) ?? [], focused = document.querySelector(":focus"), initial = el.querySelector(initialSelector), first = (0, import_utils2.createEl)("span", { tabIndex: 0 }, { focusGuard: "start" }, { position: "absolute", width: "0", height: "0", pointerEvents: "none" }), last = (0, import_utils2.createEl)("span", { tabIndex: 0 }, { focusGuard: "end" }, { position: "absolute", width: "0", height: "0", pointerEvents: "none" }), getFocusable = (c = el) => Array.prototype.filter.call(c.querySelectorAll(INTERACTIVE_SELECTOR), (el2) => !el2.hasAttribute("disabled") && !el2.hasAttribute("aria-hidden") && !el2.hasAttribute("data-focus-guard")), resetFocus = (i = 0, els = getFocusable()) => els?.length ? els.at(i).focus() : (!el.hasAttribute("tabindex") && (el.tabIndex = -1), el.focus()), edgeFocus = (pre = false) => {
+    if (!scoped) return resetFocus(pre ? -1 : 0);
+    else if (root.hasAttribute("tabindex")) return root.focus();
+    const items = getFocusable();
+    if (!items.length) return resetFocus(0, null);
+    const all = getFocusable(root.parentElement?.closest(`:has(${INTERACTIVE_SELECTOR})`) || document.body);
+    for (let target, len = all.length, i = all.indexOf(items[pre ? 0 : items.length - 1]) + (pre ? -1 : 1); pre ? i >= 0 : i < len; pre ? i-- : i++) if (!root.contains(target = all[i])) return target.focus();
+    (pre ? first : last).blur();
+  }, handleFocusIn = () => stack.at(-1) === el && getActiveElement() !== root && !el.contains(getActiveElement()) && setTimeout(resetFocus, 0, 0), handleInitialBlur = () => initial.classList.remove(ringClassName);
+  first.addEventListener("focus", (e) => el.contains(e.relatedTarget) ? edgeFocus(true) : resetFocus(), capture), el.prepend(first);
+  last.addEventListener("focus", (e) => el.contains(e.relatedTarget) ? edgeFocus() : resetFocus(-1), capture), el.append(last);
+  root.addEventListener("focusin", handleFocusIn, capture);
+  if (!el.querySelector(":focus")) !initial ? resetFocus() : setTimeout(() => (initial.classList.add(ringClassName), initial.focus(), initial.addEventListener("blur", handleInitialBlur, capture)));
+  if (!stack.includes(el)) stack.push(el), stacks2.set(root, stack);
+  const destroy = () => {
+    focused?.isConnected && focused.focus(), first.remove(), last.remove();
+    root.removeEventListener("focusin", handleFocusIn, capture);
+    initial?.removeEventListener("blur", handleInitialBlur, capture);
+    t007._ftrappers.delete(el), stack.splice(stack.indexOf(el), 1);
+  };
+  return t007._ftrappers.set(el, destroy), destroy;
+}
+
+// src/hooks/react/useFocusTrap.ts
+var import_sia_reactor6 = require("sia-reactor");
+function useFocusTrap(ref, config = import_sia_reactor6.NIL) {
+  (0, import_react4.useEffect)(() => ref.current ? initFocusTrap(ref.current, config) : void 0, [ref, config.enabled, config.initialSelector, config.ringClassName, config.root, config.scoped, config.capture]);
+}
+
+// src/hooks/react/useHighlight.ts
+var import_react5 = require("react");
+function useHighlight(text, query, ignoreCase = true, options) {
+  const { trimQuery = true, wholeWord = false } = options ?? {};
+  return (0, import_react5.useMemo)(() => {
+    if (!query) return [{ text, match: false }];
+    const queries = (Array.isArray(query) ? query : [query]).sort((a, b) => b.length - a.length).map((q) => (trimQuery ? q.trim() : q)?.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")).filter(Boolean);
+    if (!queries.length) return [{ text, match: false }];
+    const boundary = wholeWord ? "\\b" : "", regex = new RegExp(`(${queries.map((q) => boundary + q + boundary).join("|")})`, ignoreCase ? "gi" : "g"), parts = text.split(regex);
+    return parts.map((part) => ({ text: part, match: !!part.match(regex) }));
+  }, [text, query, ignoreCase, trimQuery, wholeWord]);
+}
+
+// src/hooks/react/useRipple.ts
+var import_react6 = require("react");
+
+// src/hooks/vanilla/ripple.ts
+var import_sia_reactor7 = require("sia-reactor");
+function rippleHandler(e, { target, forceCenter = false, wrapperClassName = "t007-ripple-wrapper", className = "t007-ripple", holdClassName = "t007-ripple-hold", fadeClassName = "t007-ripple-fade" } = import_sia_reactor7.NIL) {
+  const el = target || e.currentTarget;
+  if (!el || e.target !== e.currentTarget && isInteractive(e.target) || el.hasAttribute("disabled") || e.pointerType === "mouse" && e.button !== 0) return;
+  e.stopPropagation?.();
+  const { offsetWidth: rW, offsetHeight: rH } = el, { width: w, height: h, left: l, top: t } = el.getBoundingClientRect(), size = Math.max(rW, rH), x = forceCenter ? rW / 2 - size / 2 : (e.clientX - l) * rW / w - size / 2, y = forceCenter ? rH / 2 - size / 2 : (e.clientY - t) * rH / h - size / 2, wrapper = (0, import_utils2.createEl)("span", { className: wrapperClassName }), ripple = (0, import_utils2.createEl)("span", { className: className + " " + holdClassName }, {}, { cssText: `width:${size}px;height:${size}px;left:${x}px;top:${y}px;` });
+  let canRelease = false;
+  ripple.addEventListener("animationend", () => canRelease = true, { once: true });
+  el.append(wrapper.appendChild(ripple).parentElement);
+  const release = () => {
+    if (!canRelease) return ripple.addEventListener("animationend", release, { once: true });
+    ripple.classList.replace(holdClassName, fadeClassName);
+    ripple.addEventListener("animationend", () => setTimeout(() => wrapper.remove()));
+    for (const evt of ["pointerup", "pointercancel"]) (el.ownerDocument?.defaultView || window).removeEventListener(evt, release);
+  };
+  for (const evt of ["pointerup", "pointercancel"]) (el.ownerDocument?.defaultView || window).addEventListener(evt, release);
+}
+
+// src/hooks/react/useRipple.ts
+var import_sia_reactor8 = require("sia-reactor");
+function useRipple() {
+  return (0, import_react6.useCallback)((e, config = import_sia_reactor8.NIL) => rippleHandler(e.nativeEvent, config), []);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  useArrowNavigation,
+  useFocusTrap,
+  useHighlight,
+  useOutsideClick,
+  useRipple,
+  useScrollAssist
+});

package/dist/hooks/react.d.cts

@@ -0,0 +1,46 @@
+import { RefObject } from 'react';
+import { a as ScrollAssistConfig, C as Config, K as KeyEvent } from '../scrollAssist-y9wFmYgt.cjs';
+import { O as OutsideClickConfig, F as FocusTrapConfig, R as RippleConfig } from '../ripple-DcMWw_AP.cjs';
+export { H as HighlightOptions, u as useHighlight } from '../useHighlight-DMpDCILK.cjs';
+
+/** Configuration options for the `useScrollAssist` hook. */
+interface UseScrollAssistConfig extends ScrollAssistConfig {
+    /** Enables or disables the scroll assist. Defaults to `true`. */
+    enabled?: boolean;
+}
+/** React hook to add edge-scrolling assist to an element. It creates invisible "hot zones" at the edges of the element that, when hovered or dragged into, will scroll the element in that direction.
+ * The assist is automatically disabled when the element is too small or contains interactive elements near the edges to prevent interference.
+ * @param ref Ref of Scrollable element to enhance.
+ * @param options Scroll assist configuration.
+ * @returns An object with a method to manually update scroll assist visibility.
+ */
+declare function useScrollAssist(ref: RefObject<HTMLElement>, { enabled, pxPerSecond, assistClassName, vertical, horizontal }?: UseScrollAssistConfig): {
+    update: () => void;
+};
+
+/** React hook to attach outside-click, escape, and optional focus-out handling to an element. */
+declare function useOutsideClick<T extends HTMLElement>(ref: RefObject<T>, config?: OutsideClickConfig): void;
+
+/** A React hook for managing robustarrow-key roving focus navigation. */
+declare function useArrowNavigation(containerRef: React.RefObject<HTMLElement>, config?: Config): {
+    gridX: number;
+    gridY: number;
+    vGridY: number;
+    activeIndex: number;
+    activeItem: () => HTMLElement;
+    items: () => HTMLElement[];
+    getAbleIndex: (targetIndex: number, e?: KeyEvent) => number | null | undefined;
+    typeAhead: (key: string) => void;
+    goToIndex: (targetIndex: number, e?: KeyEvent) => void;
+    simulateKey: (e: KeyEvent) => void;
+};
+
+/** React hook  to keep focus trapped inside an element until disabled. */
+declare function useFocusTrap(ref: RefObject<HTMLElement>, config?: FocusTrapConfig): void;
+
+/** React hook to render and control a material-style ripple animation on an element.
+ * @returns Stable pointer handler for clickable UI surfaces.
+ */
+declare function useRipple(): (e: React.PointerEvent<HTMLElement>, config?: RippleConfig) => void;
+
+export { useArrowNavigation, useFocusTrap, useOutsideClick, useRipple, useScrollAssist };

package/dist/hooks/react.d.ts

@@ -0,0 +1,46 @@
+import { RefObject } from 'react';
+import { a as ScrollAssistConfig, C as Config, K as KeyEvent } from '../scrollAssist-y9wFmYgt.js';
+import { O as OutsideClickConfig, F as FocusTrapConfig, R as RippleConfig } from '../ripple-DcMWw_AP.js';
+export { H as HighlightOptions, u as useHighlight } from '../useHighlight-DMpDCILK.js';
+
+/** Configuration options for the `useScrollAssist` hook. */
+interface UseScrollAssistConfig extends ScrollAssistConfig {
+    /** Enables or disables the scroll assist. Defaults to `true`. */
+    enabled?: boolean;
+}
+/** React hook to add edge-scrolling assist to an element. It creates invisible "hot zones" at the edges of the element that, when hovered or dragged into, will scroll the element in that direction.
+ * The assist is automatically disabled when the element is too small or contains interactive elements near the edges to prevent interference.
+ * @param ref Ref of Scrollable element to enhance.
+ * @param options Scroll assist configuration.
+ * @returns An object with a method to manually update scroll assist visibility.
+ */
+declare function useScrollAssist(ref: RefObject<HTMLElement>, { enabled, pxPerSecond, assistClassName, vertical, horizontal }?: UseScrollAssistConfig): {
+    update: () => void;
+};
+
+/** React hook to attach outside-click, escape, and optional focus-out handling to an element. */
+declare function useOutsideClick<T extends HTMLElement>(ref: RefObject<T>, config?: OutsideClickConfig): void;
+
+/** A React hook for managing robustarrow-key roving focus navigation. */
+declare function useArrowNavigation(containerRef: React.RefObject<HTMLElement>, config?: Config): {
+    gridX: number;
+    gridY: number;
+    vGridY: number;
+    activeIndex: number;
+    activeItem: () => HTMLElement;
+    items: () => HTMLElement[];
+    getAbleIndex: (targetIndex: number, e?: KeyEvent) => number | null | undefined;
+    typeAhead: (key: string) => void;
+    goToIndex: (targetIndex: number, e?: KeyEvent) => void;
+    simulateKey: (e: KeyEvent) => void;
+};
+
+/** React hook  to keep focus trapped inside an element until disabled. */
+declare function useFocusTrap(ref: RefObject<HTMLElement>, config?: FocusTrapConfig): void;
+
+/** React hook to render and control a material-style ripple animation on an element.
+ * @returns Stable pointer handler for clickable UI surfaces.
+ */
+declare function useRipple(): (e: React.PointerEvent<HTMLElement>, config?: RippleConfig) => void;
+
+export { useArrowNavigation, useFocusTrap, useOutsideClick, useRipple, useScrollAssist };