@tensor_1/react 2.47.0 → 2.49.0

package/dist/hooks/useChangeHighlight.js

@@ -0,0 +1,44 @@
+"use client";
+import { useEffect, useRef } from "react";
+import { announcePolite, ensureAnnouncer } from "../announce.js";
+function useChangeHighlight(value, { announce, disabled } = {}) {
+  const ref = useRef(null);
+  const previous = useRef(value);
+  const announces = announce !== void 0;
+  useEffect(() => {
+    if (announces) ensureAnnouncer(ref.current);
+  }, [announces]);
+  useEffect(() => {
+    if (Object.is(previous.current, value)) return;
+    previous.current = value;
+    const el = ref.current;
+    if (disabled || !el) return;
+    flashChanged(el);
+    if (announce) announcePolite(announce, el);
+  }, [value, announce, disabled]);
+  return ref;
+}
+const handlers = /* @__PURE__ */ new WeakMap();
+function flashChanged(el) {
+  if (el.hasAttribute("data-uix-changed")) {
+    el.removeAttribute("data-uix-changed");
+    void el.offsetWidth;
+  }
+  el.setAttribute("data-uix-changed", "");
+  const previous = handlers.get(el);
+  if (previous) el.removeEventListener("animationend", previous);
+  const done = (event) => {
+    const target = event.target;
+    if (!event.animationName.startsWith("uix-changed")) return;
+    if (target !== el && target?.parentNode !== el) return;
+    el.removeAttribute("data-uix-changed");
+    el.removeEventListener("animationend", done);
+    handlers.delete(el);
+  };
+  handlers.set(el, done);
+  el.addEventListener("animationend", done);
+}
+export {
+  flashChanged,
+  useChangeHighlight
+};

package/dist/hooks/useDeferredReorder.d.ts

@@ -0,0 +1,32 @@
+import { PointerEvent, FocusEvent } from 'react';
+
+type Key = string | number;
+interface UseDeferredReorderResult<T> {
+    /** The items to render: the new data, in the order that was showing while the list is held. */
+    items: T[];
+    /** A new order is waiting until the pointer and focus leave the list. Say so if it matters ("New order — move away to apply"). */
+    held: boolean;
+    /** Spread on the list element. */
+    listProps: {
+        onPointerEnter: (event: PointerEvent<HTMLElement>) => void;
+        onPointerLeave: (event: PointerEvent<HTMLElement>) => void;
+        onFocus: (event: FocusEvent<HTMLElement>) => void;
+        onBlur: (event: FocusEvent<HTMLElement>) => void;
+    };
+}
+/**
+ * Never re-sort under the pointer (HAR-2586, motion standard §2.5). While a mouse pointer is
+ * over the list, or keyboard focus is inside it, a new order from live data waits: rows keep
+ * their places (their content still updates), new rows join at the end, removed rows still go.
+ * When the pointer and keyboard focus leave, the new order applies — with `MotionList`, as a
+ * glide. A click alone does not hold the list (focus from a click is not keyboard focus), and
+ * a hold whose focused row disappeared lets go.
+ *
+ * ```tsx
+ * const queue = useDeferredReorder(liveRows, (row) => row.id);
+ * <MotionList {...queue.listProps} items={queue.items} getKey={(row) => row.id} renderItem={…} />
+ * ```
+ */
+declare function useDeferredReorder<T>(items: readonly T[], getKey: (item: T) => Key): UseDeferredReorderResult<T>;
+
+export { type UseDeferredReorderResult, useDeferredReorder };

package/dist/hooks/useDeferredReorder.js

@@ -0,0 +1,47 @@
+"use client";
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+function useDeferredReorder(items, getKey) {
+  const [pointer, setPointer] = useState(false);
+  const [focus, setFocus] = useState(false);
+  const holding = pointer || focus;
+  const keyOf = useRef(getKey);
+  keyOf.current = getKey;
+  const shownOrder = useRef(items.map(getKey));
+  const list = useRef(null);
+  const shown = useMemo(() => {
+    const key = keyOf.current;
+    if (!holding) return [...items];
+    const byKey = new Map(items.map((item) => [key(item), item]));
+    const kept = shownOrder.current.filter((k) => byKey.has(k)).map((k) => byKey.get(k));
+    const keptKeys = new Set(shownOrder.current);
+    const added = items.filter((item) => !keptKeys.has(key(item)));
+    return [...kept, ...added];
+  }, [items, holding]);
+  shownOrder.current = shown.map((item) => keyOf.current(item));
+  const held = holding && shown.some((item, i) => keyOf.current(item) !== keyOf.current(items[i]));
+  useEffect(() => {
+    if (focus && list.current && !list.current.contains(document.activeElement)) setFocus(false);
+  }, [items, focus]);
+  const onPointerEnter = useCallback((event) => {
+    list.current = event.currentTarget;
+    if (event.pointerType === "mouse" || event.pointerType === "pen") setPointer(true);
+  }, []);
+  const onPointerLeave = useCallback(() => setPointer(false), []);
+  const onFocus = useCallback((event) => {
+    list.current = event.currentTarget;
+    const target = event.target;
+    let keyboard = true;
+    try {
+      keyboard = target.matches(":focus-visible");
+    } catch {
+    }
+    if (keyboard) setFocus(true);
+  }, []);
+  const onBlur = useCallback((event) => {
+    if (!event.currentTarget.contains(event.relatedTarget)) setFocus(false);
+  }, []);
+  return { items: shown, held, listProps: { onPointerEnter, onPointerLeave, onFocus, onBlur } };
+}
+export {
+  useDeferredReorder
+};

package/dist/hooks/useDialog.d.ts

@@ -2,6 +2,11 @@
  * `keepOpen` is asked when the browser closed the dialog on its own (Escape or a close request
  * nobody cancelled, a `method="dialog"` form). Returning `true` reopens it instead of calling
  * `onClose`: a form dialog with unsaved input or a save in flight (HAR-2029).
+ *
+ * The dialog opens and closes in a layout effect (HAR-1831). A dialog its caller unmounts while
+ * open (`{open && <ConfirmDialog …/>}`, or a page that navigates away) is closed in the commit,
+ * while it is still in the document, so the browser returns focus to the control that opened it;
+ * a passive cleanup ran after the element was removed, and focus fell to `<body>`.
  */
 declare function useDialog(open: boolean, onClose?: () => void, keepOpen?: () => boolean): React.RefObject<HTMLDialogElement>;
 

package/dist/hooks/useDialog.js

@@ -1,5 +1,7 @@
 "use client";
-import { useRef, useEffect } from "react";
+import { useRef, useEffect, useLayoutEffect } from "react";
+import { markKeyOpened, watchInputModality } from "../motion.js";
+const useIsomorphicLayoutEffect = typeof document !== "undefined" ? useLayoutEffect : useEffect;
 let lockCount = 0;
 let saved = null;
 function lockBodyScroll() {
@@ -37,12 +39,21 @@ function useDialog(open, onClose, keepOpen) {
   const keepOpenRef = useRef(keepOpen);
   keepOpenRef.current = keepOpen;
   useEffect(() => {
+    watchInputModality();
+  }, []);
+  useIsomorphicLayoutEffect(() => {
     const el = ref.current;
     if (!el || !open) {
-      if (el && el.open) el.close();
+      if (el && el.open) {
+        markKeyOpened(el);
+        el.close();
+      }
       return;
     }
-    if (!el.open) el.showModal();
+    if (!el.open) {
+      markKeyOpened(el);
+      el.showModal();
+    }
     lockBodyScroll();
     let locked = true;
     const handleClose = () => {
@@ -60,9 +71,12 @@ function useDialog(open, onClose, keepOpen) {
       }
       onCloseRef.current?.();
     };
+    const handleCancel = () => markKeyOpened(el);
     el.addEventListener("close", handleClose);
+    el.addEventListener("cancel", handleCancel);
     return () => {
       el.removeEventListener("close", handleClose);
+      el.removeEventListener("cancel", handleCancel);
       if (locked) {
         locked = false;
         unlockBodyScroll();

package/dist/hooks/useKeyboardGrab.d.ts

@@ -0,0 +1,58 @@
+import { KeyboardEvent, FocusEvent } from 'react';
+
+type KeyboardGrabDirection = 'up' | 'down' | 'left' | 'right';
+/** The words `useKeyboardGrab` says. `{label}` is the item's name. */
+interface KeyboardGrabLabels {
+    grabbed: string;
+    dropped: string;
+    cancelled: string;
+}
+declare const DEFAULT_KEYBOARD_GRAB_LABELS: KeyboardGrabLabels;
+interface UseKeyboardGrabOptions {
+    /**
+     * The item's stable id. The picked-up state follows the id, so an item that a move puts in
+     * another list (a kanban card going to the next column) is still picked up, and focused, when
+     * it mounts there.
+     */
+    id: string;
+    /** The item's name in what is said. */
+    label: string;
+    /** Move the picked-up item one step; return what to say (e.g. "Position 3 of 8"), or nothing. */
+    onMove: (direction: KeyboardGrabDirection) => string | void;
+    /** The item was put down where it is now. */
+    onDrop?: () => void;
+    /** Escape, or focus leaving the item: put it back where it was picked up. */
+    onCancel?: () => void;
+    /** Overrides `UixLabelsProvider` `keyboardGrab`, then English. */
+    labels?: Partial<KeyboardGrabLabels>;
+}
+interface UseKeyboardGrabResult {
+    grabbed: boolean;
+    /** Spread on the focusable item: its ref, the key handling, and `data-uix-drag="grabbed"` while it is picked up. */
+    itemProps: {
+        ref: (el: HTMLElement | null) => void;
+        onKeyDown: (event: KeyboardEvent<HTMLElement>) => void;
+        onBlur: (event: FocusEvent<HTMLElement>) => void;
+        'data-uix-drag'?: 'grabbed';
+    };
+}
+/**
+ * The keyboard path for anything a person drags (HAR-2590, WCAG 2.1.1 and 2.5.7): Space or Enter on
+ * the focused item picks it up (a dashed ring, `data-uix-drag="grabbed"`), the arrow keys move it
+ * one step at a time, Space or Enter puts it down, Escape or focus leaving puts it back. Each step
+ * is said through the polite live region. Moves from the keyboard are instant: no glide (§2.2).
+ * A held key does not toggle; keys on a control inside the item are left to it.
+ *
+ * The kit's own lists already have a keyboard path (SortableList's Move up / Move down and
+ * Alt+arrows, KanbanCard `onMove`, DashboardCanvas handles); this is for a draggable thing a
+ * product builds itself.
+ */
+declare function useKeyboardGrab({ id, label, onMove, onDrop, onCancel, labels }: UseKeyboardGrabOptions): UseKeyboardGrabResult;
+/**
+ * Let a dropped item land (HAR-2590): `data-uix-settle` for one short ease-out from the lifted
+ * scale to rest. Call it on the item's element once it is in its new place (after the commit
+ * that moved it). Under reduced motion there is no landing and nothing is left behind.
+ */
+declare function settleDrop(el: HTMLElement | null | undefined): void;
+
+export { DEFAULT_KEYBOARD_GRAB_LABELS, type KeyboardGrabDirection, type KeyboardGrabLabels, type UseKeyboardGrabOptions, type UseKeyboardGrabResult, settleDrop, useKeyboardGrab };

package/dist/hooks/useKeyboardGrab.js

@@ -0,0 +1,118 @@
+"use client";
+import { useCallback, useEffect, useRef, useSyncExternalStore } from "react";
+import { announcePolite } from "../announce.js";
+import { fillLabel } from "../fill-label.js";
+import { useUixLabels } from "../labels-context.js";
+const DEFAULT_KEYBOARD_GRAB_LABELS = {
+  grabbed: "{label} picked up. Use the arrow keys to move it, Space to drop it, Escape to cancel.",
+  dropped: "{label} dropped.",
+  cancelled: "Move cancelled. {label} is back where it was."
+};
+let grabbedId = null;
+let refocusId = null;
+const listeners = /* @__PURE__ */ new Set();
+const setGrabbedId = (id) => {
+  grabbedId = id;
+  listeners.forEach((l) => l());
+};
+const subscribe = (l) => {
+  listeners.add(l);
+  return () => {
+    listeners.delete(l);
+  };
+};
+const DIRECTIONS = { ArrowUp: "up", ArrowDown: "down", ArrowLeft: "left", ArrowRight: "right" };
+function useKeyboardGrab({ id, label, onMove, onDrop, onCancel, labels }) {
+  const grabbed = useSyncExternalStore(subscribe, () => grabbedId === id, () => false);
+  const words = { ...DEFAULT_KEYBOARD_GRAB_LABELS, ...useUixLabels().keyboardGrab, ...labels };
+  const live = useRef({ onMove, onDrop, onCancel, words, label, id });
+  live.current = { onMove, onDrop, onCancel, words, label, id };
+  const element = useRef(null);
+  const say = (template) => announcePolite(fillLabel(template, { label: live.current.label }), element.current);
+  const cancel = useCallback(() => {
+    if (grabbedId !== live.current.id) return;
+    setGrabbedId(null);
+    live.current.onCancel?.();
+    announcePolite(fillLabel(live.current.words.cancelled, { label: live.current.label }), element.current);
+  }, []);
+  useEffect(() => {
+    if (!grabbed) return void 0;
+    const escape = (event) => {
+      if (event.key !== "Escape") return;
+      event.preventDefault();
+      event.stopPropagation();
+      cancel();
+    };
+    window.addEventListener("keydown", escape, true);
+    return () => window.removeEventListener("keydown", escape, true);
+  }, [grabbed, cancel]);
+  const ref = useCallback((el) => {
+    element.current = el;
+    if (el && refocusId === live.current.id) {
+      refocusId = null;
+      el.focus({ preventScroll: false });
+    }
+  }, []);
+  const onKeyDown = (event) => {
+    if (event.target !== event.currentTarget || event.defaultPrevented || event.altKey || event.ctrlKey || event.metaKey) return;
+    if (event.key === " " || event.key === "Enter") {
+      event.preventDefault();
+      if (event.repeat) return;
+      if (grabbed) {
+        setGrabbedId(null);
+        say(live.current.words.dropped);
+        live.current.onDrop?.();
+      } else {
+        setGrabbedId(live.current.id);
+        say(live.current.words.grabbed);
+      }
+      return;
+    }
+    if (!grabbed) return;
+    const direction = DIRECTIONS[event.key];
+    if (!direction) return;
+    event.preventDefault();
+    refocusId = live.current.id;
+    const said = live.current.onMove(direction);
+    if (said) announcePolite(said, element.current);
+    queueMicrotask(() => {
+      if (refocusId === live.current.id && element.current?.isConnected) refocusId = null;
+    });
+  };
+  const onBlur = (event) => {
+    if (!grabbed) return;
+    const to = event.relatedTarget;
+    if (to && event.currentTarget.contains(to)) return;
+    if (refocusId === live.current.id) return;
+    cancel();
+  };
+  return {
+    grabbed,
+    itemProps: { ref, onKeyDown, onBlur, ...grabbed ? { "data-uix-drag": "grabbed" } : {} }
+  };
+}
+function settleDrop(el) {
+  if (!el) return;
+  if (el.hasAttribute("data-uix-settle")) {
+    el.removeAttribute("data-uix-settle");
+    void el.offsetWidth;
+  }
+  el.setAttribute("data-uix-settle", "");
+  if (typeof getComputedStyle === "function" && getComputedStyle(el).animationName === "none") {
+    el.removeAttribute("data-uix-settle");
+    return;
+  }
+  const done = (event) => {
+    if (event.target !== el) return;
+    el.removeAttribute("data-uix-settle");
+    el.removeEventListener("animationend", done);
+    el.removeEventListener("animationcancel", done);
+  };
+  el.addEventListener("animationend", done);
+  el.addEventListener("animationcancel", done);
+}
+export {
+  DEFAULT_KEYBOARD_GRAB_LABELS,
+  settleDrop,
+  useKeyboardGrab
+};

package/dist/hooks/useOptimisticValue.d.ts

@@ -0,0 +1,51 @@
+interface OptimisticRollback<T> {
+    /** The value the person asked for. */
+    attempted: T;
+    /** The value shown again. */
+    restored: T;
+    error: unknown;
+}
+interface UseOptimisticValueOptions<T> {
+    /** Called when a change fails and the value is put back, e.g. to show a toast that says what was restored. */
+    onRollback?: (rollback: OptimisticRollback<T>) => void;
+}
+interface UseOptimisticValueResult<T> {
+    /** What to show: the person's change at once, the server's value otherwise. */
+    value: T;
+    /** Show `next` now and save it; resolves when the save settles (it never rejects). */
+    set: (next: T) => Promise<void>;
+    /** A save is in flight. */
+    pending: boolean;
+    /** The last rollback, until the next change; `null` when the last change saved. */
+    rollback: OptimisticRollback<T> | null;
+    /**
+     * Counts rollbacks. Pass it to `ChangeHighlight value={rollbacks}` (or `useChangeHighlight`)
+     * so the restored element flashes; the person's own change does not.
+     */
+    rollbacks: number;
+}
+/**
+ * An optimistic value with a visible rollback (HAR-2583, motion standard §2.6). Only for
+ * reversible, personal, nearly-always-successful actions: star, pin, a reaction, mark read, a
+ * display preference, the order of one's own saved views. Never for anything the server can
+ * refuse or an auditor reads (a state transition, an assignment, an approval, a priority):
+ * those stay pessimistic, with `Button loading` and `result`.
+ *
+ * `set(next)` shows `next` at once and calls `commit(next)`. If the commit fails, the last
+ * confirmed value comes back, `rollbacks` counts up (flash the element with it), `rollback`
+ * says what happened, and `onRollback` runs so the product can say it in words. When changes
+ * overlap, only the latest one's outcome counts. While nothing is pending, `value` follows
+ * `serverValue` when it changes; a change that saved stays shown until then.
+ *
+ * ```tsx
+ * const star = useOptimisticValue(view.starred, (next) => api.star(view.id, next), {
+ *   onRollback: () => toast.error(t('starNotSaved')),
+ * });
+ * <ChangeHighlight value={star.rollbacks} variant="ring" announce={star.rollback ? t('starRestored') : undefined}>
+ *   <StarButton starred={star.value} onToggle={() => star.set(!star.value)} />
+ * </ChangeHighlight>
+ * ```
+ */
+declare function useOptimisticValue<T>(serverValue: T, commit: (next: T) => Promise<unknown>, { onRollback }?: UseOptimisticValueOptions<T>): UseOptimisticValueResult<T>;
+
+export { type OptimisticRollback, type UseOptimisticValueOptions, type UseOptimisticValueResult, useOptimisticValue };

package/dist/hooks/useOptimisticValue.js

@@ -0,0 +1,61 @@
+"use client";
+import { useCallback, useEffect, useRef, useState } from "react";
+function useOptimisticValue(serverValue, commit, { onRollback } = {}) {
+  const [shown, setShown] = useState(serverValue);
+  const [pending, setPending] = useState(false);
+  const [rollback, setRollback] = useState(null);
+  const [rollbacks, setRollbacks] = useState(0);
+  const confirmed = useRef(serverValue);
+  const latest = useRef(0);
+  const confirmedId = useRef(0);
+  const mounted = useRef(true);
+  const commitRef = useRef(commit);
+  const onRollbackRef = useRef(onRollback);
+  commitRef.current = commit;
+  onRollbackRef.current = onRollback;
+  useEffect(() => {
+    mounted.current = true;
+    return () => {
+      mounted.current = false;
+    };
+  }, []);
+  const pendingRef = useRef(false);
+  pendingRef.current = pending;
+  const firstServer = useRef(true);
+  useEffect(() => {
+    if (firstServer.current) {
+      firstServer.current = false;
+      return;
+    }
+    confirmed.current = serverValue;
+    if (!pendingRef.current) setShown(serverValue);
+  }, [serverValue]);
+  const set = useCallback(async (next) => {
+    const id = ++latest.current;
+    setShown(next);
+    setPending(true);
+    setRollback(null);
+    try {
+      await commitRef.current(next);
+      if (id > confirmedId.current) {
+        confirmedId.current = id;
+        confirmed.current = next;
+      }
+      if (!mounted.current || id !== latest.current) return;
+      setPending(false);
+    } catch (error) {
+      if (!mounted.current || id !== latest.current) return;
+      const restored = confirmed.current;
+      const event = { attempted: next, restored, error };
+      setShown(restored);
+      setPending(false);
+      setRollback(event);
+      setRollbacks((n) => n + 1);
+      onRollbackRef.current?.(event);
+    }
+  }, []);
+  return { value: shown, set, pending, rollback, rollbacks };
+}
+export {
+  useOptimisticValue
+};

package/dist/hooks/useReducedMotion.d.ts

@@ -1,4 +1,7 @@
-/** Non-hook read for event handlers and effects. `false` where there is no `matchMedia` (SSR, tests). */
+/**
+ * Non-hook read for event handlers and effects: the OS setting, or the in-app preference
+ * `<html data-motion="reduce">` (HAR-1372). `false` where there is no `matchMedia` (SSR, tests).
+ */
 declare function prefersReducedMotion(): boolean;
 /** True while the user asks for reduced motion; re-renders when the setting changes. `false` on the server. */
 declare function useReducedMotion(): boolean;

package/dist/hooks/useReducedMotion.js

@@ -6,9 +6,15 @@ function subscribe(onChange) {
   };
   const mql = matchMedia(QUERY);
   mql.addEventListener("change", onChange);
-  return () => mql.removeEventListener("change", onChange);
+  const observer = typeof MutationObserver === "function" && typeof document !== "undefined" ? new MutationObserver(onChange) : null;
+  observer?.observe(document.documentElement, { attributes: true, attributeFilter: ["data-motion"] });
+  return () => {
+    mql.removeEventListener("change", onChange);
+    observer?.disconnect();
+  };
 }
 function prefersReducedMotion() {
+  if (typeof document !== "undefined" && document.documentElement.getAttribute("data-motion") === "reduce") return true;
   return typeof matchMedia !== "undefined" && matchMedia(QUERY).matches;
 }
 function useReducedMotion() {

package/dist/hooks/useResolvedFilterLabels.d.ts

@@ -0,0 +1,15 @@
+import { FilterField, FilterValue } from '../filter-model.js';
+
+/**
+ * A filter chip's field and value with the labels of ids restored from a URL or a saved view
+ * (PR #168 review: a chip read "Assignee: usr_8f3a"). A `reference` value's choices without a
+ * label, and an `enum` value's ids that are not among `field.options`, are looked up once with
+ * `field.resolveLabels`. Until the answer arrives, and when the lookup fails, the ids show.
+ * Internal: DataWorkspace and AuditLog summarise their chips through it.
+ */
+declare function useResolvedFilterLabels(field: FilterField, value: FilterValue | undefined): {
+    field: FilterField;
+    value: FilterValue | undefined;
+};
+
+export { useResolvedFilterLabels };

package/dist/hooks/useResolvedFilterLabels.js

@@ -0,0 +1,34 @@
+"use client";
+import { useEffect, useRef, useState } from "react";
+import { isUnresolvedChoice } from "../filter-model.js";
+function useResolvedFilterLabels(field, value) {
+  const [known, setKnown] = useState(() => /* @__PURE__ */ new Map());
+  const asked = useRef(/* @__PURE__ */ new Set());
+  const resolver = useRef(field.resolveLabels);
+  resolver.current = field.resolveLabels;
+  const optionIds = new Set((field.options ?? []).map((o) => o.value));
+  const missing = value?.kind === "reference" ? value.values.filter(isUnresolvedChoice).map((v) => v.value) : value?.kind === "enum" ? value.values.filter((v) => !optionIds.has(v)) : [];
+  const key = missing.filter((id) => !known.has(id) && !asked.current.has(id)).join("\0");
+  useEffect(() => {
+    if (!key || !resolver.current) return;
+    const ids = key.split("\0");
+    for (const id of ids) asked.current.add(id);
+    resolver.current(ids).then(
+      (choices) => setKnown((prev) => new Map([...prev, ...choices.map((c) => [c.value, c.label])])),
+      () => {
+      }
+    );
+  }, [key]);
+  if (known.size === 0 || !value) return { field, value };
+  if (value.kind === "reference") {
+    return { field, value: { kind: "reference", values: value.values.map((v) => isUnresolvedChoice(v) && known.has(v.value) ? { value: v.value, label: known.get(v.value) } : v) } };
+  }
+  if (value.kind === "enum") {
+    const extra = value.values.filter((v) => !optionIds.has(v) && known.has(v)).map((v) => ({ value: v, label: known.get(v) }));
+    if (extra.length) return { field: { ...field, options: [...field.options ?? [], ...extra] }, value };
+  }
+  return { field, value };
+}
+export {
+  useResolvedFilterLabels
+};

package/dist/hooks/useSlidingIndicator.d.ts

@@ -0,0 +1,18 @@
+import { RefObject } from 'react';
+
+/**
+ * Slides the selection mark from the old item to the new one when a pointer changes it
+ * (HAR-2589): the selected tab's underline, the pill, the lifted segment. At rest every item
+ * keeps its own selected look (server HTML, forced colours, wrapped rows: nothing to keep in
+ * place); only during the slide does one indicator (`indicatorRef`, a child of `containerRef`)
+ * carry the mark — the container has `data-uix-indicator` and the new item's own mark steps
+ * aside — and at the end of the slide it hands the mark back and hides. The indicator is sized
+ * to the new item and played back from the old one with a transform (FLIP): nothing animates
+ * width or position.
+ *
+ * - A change from the keyboard jumps: arrow keys are the 100×-a-day path (§2.2).
+ * - Reduced motion jumps.
+ */
+declare function useSlidingIndicator(containerRef: RefObject<HTMLElement | null>, indicatorRef: RefObject<HTMLElement | null>, selectedSelector: string): void;
+
+export { useSlidingIndicator };

package/dist/hooks/useSlidingIndicator.js

@@ -0,0 +1,80 @@
+"use client";
+import { useEffect, useLayoutEffect, useRef } from "react";
+import { prefersReducedMotion } from "./useReducedMotion.js";
+const useIsomorphicLayoutEffect = typeof document !== "undefined" ? useLayoutEffect : useEffect;
+const SLIDE_FALLBACK_MS = 1e3;
+let lastInput = "pointer";
+let listening = false;
+function trackInput() {
+  if (listening || typeof document === "undefined") return;
+  listening = true;
+  document.addEventListener("keydown", () => {
+    lastInput = "keyboard";
+  }, true);
+  document.addEventListener("pointerdown", () => {
+    lastInput = "pointer";
+  }, true);
+}
+function useSlidingIndicator(containerRef, indicatorRef, selectedSelector) {
+  const last = useRef(null);
+  const finish = useRef(null);
+  useEffect(() => () => finish.current?.(), []);
+  useIsomorphicLayoutEffect(() => {
+    trackInput();
+    const container = containerRef.current;
+    const indicator = indicatorRef.current;
+    const selected = container?.querySelector(selectedSelector) ?? null;
+    if (!container || !selected || selected.offsetParent !== container) {
+      finish.current?.();
+      last.current = null;
+      return;
+    }
+    const box = { x: selected.offsetLeft, y: selected.offsetTop, w: selected.offsetWidth, h: selected.offsetHeight };
+    const before = last.current;
+    last.current = { el: selected, box };
+    if (!before || before.el === selected) return;
+    finish.current?.();
+    if (!indicator || lastInput !== "pointer" || prefersReducedMotion() || !box.w || !box.h) return;
+    slide(container, indicator, selected, before.box, box, finish);
+  });
+}
+function slide(container, indicator, target, from, to, finish) {
+  indicator.hidden = false;
+  indicator.style.inlineSize = `${to.w}px`;
+  indicator.style.blockSize = `${to.h}px`;
+  indicator.style.left = "0";
+  indicator.style.top = "0";
+  indicator.style.translate = `${to.x}px ${to.y}px`;
+  indicator.style.transform = `translate(${from.x - to.x}px, ${from.y - to.y}px) scale(${from.w / to.w}, ${from.h / to.h})`;
+  container.setAttribute("data-uix-indicator", "");
+  void indicator.offsetWidth;
+  indicator.setAttribute("data-moving", "");
+  indicator.style.transform = "";
+  let timer;
+  const size = () => `${container.offsetWidth} ${container.offsetHeight} ${target.offsetWidth} ${target.offsetHeight}`;
+  const startSize = size();
+  const resized = typeof ResizeObserver === "undefined" ? null : new ResizeObserver(() => {
+    if (size() !== startSize) end();
+  });
+  resized?.observe(container);
+  resized?.observe(target);
+  const end = () => {
+    clearTimeout(timer);
+    resized?.disconnect();
+    indicator.removeEventListener("transitionend", onEnd);
+    indicator.getAnimations?.().forEach((a) => a.cancel());
+    indicator.removeAttribute("data-moving");
+    indicator.hidden = true;
+    container.removeAttribute("data-uix-indicator");
+    if (finish.current === end) finish.current = null;
+  };
+  const onEnd = (event) => {
+    if (event.target === indicator && event.propertyName === "transform") end();
+  };
+  indicator.addEventListener("transitionend", onEnd);
+  timer = setTimeout(end, SLIDE_FALLBACK_MS);
+  finish.current = end;
+}
+export {
+  useSlidingIndicator
+};