@tensor_1/react 2.48.0 → 2.49.0

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/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
+};