@eifi1/ui-kit 0.53.0 → 0.55.0

package/src/hooks/use-hotkey.ts

@@ -1,189 +0,0 @@
-import { useEffect, useRef } from "react";
-
-/**
- * A key combination: modifiers and one key, joined by "+", case-insensitive —
- * `"Ctrl+Shift+F"`, `"Mod+K"`, `"Alt+ArrowUp"`, `"Escape"`, `"?"`.
- *
- * Modifiers: `Ctrl` (`Control`), `Meta` (`Cmd`, `Command`), `Shift`, `Alt` (`Option`),
- * and `Mod` — Cmd on Apple platforms, Ctrl everywhere else, the one to use for an
- * app shortcut. The key is `KeyboardEvent.key` ("f", "Enter", "ArrowUp", "/"), or a
- * `KeyboardEvent.code` ("KeyF", "Digit1") when the physical key is what matters.
- * Several combos: pass an array.
- */
-export type Hotkey = string;
-
-export interface UseHotkeyOptions {
-  /** Off while `false` (default `true`). */
-  enabled?: boolean;
-  /** Call `preventDefault()` on a match (default `true`): Ctrl+Shift+F must not also
-   *  open the browser's own dialog. */
-  preventDefault?: boolean;
-  /** Where to listen. Default `document`. A ref, an element, or `window`. */
-  target?: EventTarget | null | { current: EventTarget | null };
-  /**
-   * Fire while the focus is in a text field, select or contenteditable too. Default
-   * `false`: a shortcut must not steal the letters someone is typing. A combo with Ctrl,
-   * Meta or Alt is not typing — those still fire unless this is `"never"`.
-   */
-  allowInInputs?: boolean | "never";
-  /** `keydown` (default) or `keyup`. */
-  event?: "keydown" | "keyup";
-}
-
-export interface ParsedHotkey {
-  ctrl: boolean;
-  meta: boolean;
-  shift: boolean;
-  alt: boolean;
-  key: string;
-}
-
-/** Whether this is an Apple platform, where `Mod` means Cmd. */
-export function isApplePlatform(): boolean {
-  if (typeof navigator === "undefined") return false;
-  const nav = navigator as Navigator & { userAgentData?: { platform?: string } };
-  return /mac|iphone|ipad|ipod/i.test(nav.userAgentData?.platform || nav.platform || nav.userAgent);
-}
-
-/** Parse one combo. `apple` decides what `Mod` is. Throws on an empty key. */
-export function parseHotkey(combo: Hotkey, apple = isApplePlatform()): ParsedHotkey {
-  const parts = combo
-    .split("+")
-    .map((p) => p.trim())
-    // "Ctrl++" is Ctrl and "+": an empty part after a "+" is the plus key itself.
-    .map((p, i, all) => (p === "" && i === all.length - 1 ? "+" : p))
-    .filter((p) => p !== "");
-  const out: ParsedHotkey = { ctrl: false, meta: false, shift: false, alt: false, key: "" };
-  for (const part of parts) {
-    switch (part.toLowerCase()) {
-      case "ctrl":
-      case "control":
-        out.ctrl = true;
-        break;
-      case "meta":
-      case "cmd":
-      case "command":
-        out.meta = true;
-        break;
-      case "mod":
-        if (apple) out.meta = true;
-        else out.ctrl = true;
-        break;
-      case "shift":
-        out.shift = true;
-        break;
-      case "alt":
-      case "option":
-        out.alt = true;
-        break;
-      default:
-        out.key = part;
-    }
-  }
-  if (!out.key) throw new Error(`useHotkey: "${combo}" names no key`);
-  return out;
-}
-
-const KEY_ALIASES: Record<string, string> = {
-  esc: "escape",
-  space: " ",
-  del: "delete",
-  up: "arrowup",
-  down: "arrowdown",
-  left: "arrowleft",
-  right: "arrowright",
-};
-
-/** One letter of a script other than Latin: what a Russian, Greek or Hebrew layout's letter keys type. */
-const NON_LATIN_LETTER = /^(?!\p{Script=Latin})\p{L}$/u;
-
-/** Whether `e` is `combo` — every modifier as named (no more, no fewer), and the key. */
-export function matchesHotkey(e: KeyboardEvent, combo: ParsedHotkey): boolean {
-  if (e.ctrlKey !== combo.ctrl || e.metaKey !== combo.meta || e.altKey !== combo.alt) return false;
-  const want = KEY_ALIASES[combo.key.toLowerCase()] ?? combo.key.toLowerCase();
-  const key = (e.key ?? "").toLowerCase();
-  const code = (e.code ?? "").toLowerCase();
-  // On a non-Latin layout `key` is the local letter — Ctrl+K types "л" on a Russian one —
-  // so a letter chord never fired there, ⌘K included (0.52 code review, use-hotkey.ts; the
-  // hand-written ⌘K listener before 0.52 compared `key` alone and missed it too). The
-  // physical key stands in for the letter there, and only there: a Latin layout's letter
-  // is wherever it types (Dvorak's K is on QWERTY's V).
-  const physical = /^[a-z]$/.test(want) && NON_LATIN_LETTER.test(e.key ?? "") && code === `key${want}`;
-  if (key !== want && code !== want && !physical) return false;
-  // Shift must match exactly for a letter or a named key; for a symbol it is how the
-  // symbol is typed ("?" is Shift+/ on a US layout, a plain key on others), so an
-  // unnamed Shift is not held against it. Space is a named key, not a symbol, though its
-  // alias is one character: "Space" fired on Shift+Space, the browser's page-up, and
-  // cancelled it (0.52 code review, use-hotkey.ts).
-  const symbol = want.length === 1 && !/[a-z0-9 ]/.test(want);
-  return symbol && !combo.shift ? true : e.shiftKey === combo.shift;
-}
-
-/** Is the focus somewhere that takes typed characters? */
-function isTypingTarget(target: EventTarget | null): boolean {
-  if (!(target instanceof HTMLElement)) return false;
-  if (target.isContentEditable) return true;
-  if (target instanceof HTMLTextAreaElement || target instanceof HTMLSelectElement) return true;
-  if (target instanceof HTMLInputElement) {
-    return !["button", "checkbox", "radio", "submit", "reset", "range", "color", "file", "image"].includes(target.type);
-  }
-  return false;
-}
-
-/**
- * Call `handler` when `combo` is pressed — kastlan's feedback button (Ctrl+Shift+F,
- * feedback-button:60) wired it by hand, and so will every next shortcut.
- *
- * - `Mod` is Cmd on a Mac and Ctrl elsewhere, read once per mount.
- * - Modifiers match EXACTLY: `"Ctrl+K"` does not fire on Ctrl+Shift+K.
- * - Typing in a field is left alone unless `allowInInputs`, except for a combo with
- *   Ctrl / Meta / Alt, which no one types as text.
- * - A key held down fires once, not on every repeat — and its repeats are cancelled as
- *   the first press was, or the browser acts on them.
- * - The newest `handler` is always called; changing it does not re-attach the listener.
- *
- * `useCommandKey` (the ⌘K palette hook) is this with `"Mod+K"` and `allowInInputs`
- * since 0.52, and FormActions' Ctrl/Cmd+Enter is {@link matchesHotkey} (refactor audit
- * 2026-10-30, DUP-12): one reading of a chord.
- */
-export function useHotkey(
-  combo: Hotkey | ReadonlyArray<Hotkey>,
-  handler: (event: KeyboardEvent) => void,
-  options: UseHotkeyOptions = {},
-): void {
-  const { enabled = true, preventDefault = true, target, allowInInputs = false, event = "keydown" } = options;
-  const handlerRef = useRef(handler);
-  useEffect(() => {
-    handlerRef.current = handler;
-  });
-  const key = typeof combo === "string" ? combo : combo.join("\u0000");
-  const targetEl = target && "current" in target ? undefined : target;
-  const targetRef = target && "current" in target ? target : undefined;
-
-  useEffect(() => {
-    if (!enabled) return;
-    const node: EventTarget | null =
-      targetRef?.current ?? targetEl ?? (typeof document === "undefined" ? null : document);
-    if (!node) return;
-    const apple = isApplePlatform();
-    const parsed = key.split("\u0000").map((c) => parseHotkey(c, apple));
-    const listener = (raw: Event) => {
-      const e = raw as KeyboardEvent;
-      const hit = parsed.find((p) => matchesHotkey(e, p));
-      if (!hit) return;
-      if (allowInInputs !== true && isTypingTarget(e.target)) {
-        const chorded = hit.ctrl || hit.meta || hit.alt;
-        if (allowInInputs === "never" || !chorded) return;
-      }
-      if (preventDefault) e.preventDefault();
-      // A held key's repeats are cancelled like its first press, and call nothing. They
-      // returned before the `preventDefault` once, so a held Ctrl+K's repeats reached the
-      // browser's own Ctrl+K and took the focus out of the palette ⌘K had just opened
-      // (0.52 code review, use-hotkey.ts; the hand-written ⌘K listener cancelled them).
-      if (e.repeat) return;
-      handlerRef.current(e);
-    };
-    node.addEventListener(event, listener);
-    return () => node.removeEventListener(event, listener);
-  }, [key, enabled, preventDefault, allowInInputs, event, targetEl, targetRef]);
-}

package/src/hooks/use-large-text.ts

@@ -1,41 +0,0 @@
-import { useTextSize } from "../theme/text-size";
-import { useMediaQuery } from "./use-media-query";
-
-/**
- * The two questions the kit's 0.32 behaviours ask (docs/text-size-harmonization.md §4,
- * §10.7–10.9), answered in one place so every part draws the line where the others do.
- *
- * Prefer CSS where it can: a class that differs at Large is a `large:` variant
- * (tokens.css), and a layout switch is a breakpoint, which already scales. These hooks
- * are for what CSS cannot decide — whether a tooltip is rendered at all, whether a label
- * becomes text, whether a row's actions collapse into a menu.
- */
-
-/** Large or Extra large is in force (`<html data-text-size>`) — the JS twin of the
- *  `large:` variant. */
-export function useLargeText(): boolean {
-  return useTextSize().size !== "normal";
-}
-
-/**
- * The primary pointer is a finger (`pointer: coarse`): a hover never happens, so a
- * tooltip opens only on the taps that do nothing else. A pointer query, so it stays
- * `useMediaQuery` (§10.4). `false` without `matchMedia` (SSR, jsdom).
- */
-export function useCoarsePointer(): boolean {
-  return useMediaQuery("(pointer: coarse)", false);
-}
-
-/**
- * Whether a fact may NOT live only in a tooltip here (§4 "No fact only in a tooltip"):
- * at Large and Extra large, where the reader is the one who asked for bigger type, and
- * on a touch screen at every size, where a tooltip cannot be hovered open. Where this
- * is true the kit draws the fact in the layout — a `disabledReason` as a line under its
- * control, a FieldHint as the field's caption, a StatTile hint as text — and keeps the
- * bubble only where there is no room (a top bar, a dense row's inline actions).
- */
-export function useInlineFacts(): boolean {
-  const large = useLargeText();
-  const coarse = useCoarsePointer();
-  return large || coarse;
-}

package/src/hooks/use-long-press.ts

@@ -1,140 +0,0 @@
-import { useCallback, useEffect, useRef, type PointerEvent as ReactPointerEvent } from "react";
-
-// The press-and-hold that puts DataTable's phone cards into selection mode (0.40,
-// keksdose live #421). Taken over from keksdose's register list
-// (frontend/src/shared/hooks/use-long-press.ts, its feedback #153) so the kit's cards
-// and kk's register answer the same gesture the same way: 500 ms, an 8 px dead zone,
-// cancelled by a scroll, the trailing click swallowed. Public since 0.52 (DUP-8, refactor
-// audit 2026-10-30): private, it left keksdose keeping the original beside the copy.
-
-const LONG_PRESS_MS = 500;
-/** The same 8 px dead zone `useRowSwipe` locks its axis at: the press is dead by the
- *  time the swipe hook takes pointer capture on its (ancestor) layer. */
-const SLOP_PX = 8;
-
-const movedBeyondSlop = (from: { x: number; y: number }, x: number, y: number) =>
-  Math.hypot(x - from.x, y - from.y) > SLOP_PX;
-
-export interface LongPressOptions {
-  /** Default `true`. Off, a press does nothing and the context menu is the browser's. */
-  enabled?: boolean;
-  /** How long a press is held, in ms. Default 500. */
-  delay?: number;
-}
-
-export interface LongPressResult {
-  handlers: {
-    onPointerDown: (e: ReactPointerEvent) => void;
-    onPointerMove: (e: ReactPointerEvent) => void;
-    onContextMenu: (e: { preventDefault: () => void }) => void;
-  };
-  /** True exactly once after a long press fired: call it from an `onClickCapture` to
-   *  swallow the click the browser still sends when the finger lifts. */
-  consumeClick: () => boolean;
-}
-
-/**
- * A press-and-hold on a touch row that may ALSO be swipeable.
- *
- *  - The cancel listeners live on `window`: `useRowSwipe` captures the pointer on an
- *    ancestor once a drag resolves to the x axis, after which the pressed element's
- *    own pointer handlers stop firing, and a timer cancelled only there would fire
- *    mid-swipe.
- *  - A scroll cancels too (`touch-action: pan-y` hands vertical panning to the
- *    browser, which sends `pointercancel`; the capture-phase `scroll` is the backstop).
- *  - `contextmenu` is suppressed while enabled — Android fires it at ~500 ms. Pair it
- *    with `select-none [-webkit-touch-callout:none]` on the element: iOS's callout
- *    only yields to that CSS.
- */
-export function useLongPress(
-  onLongPress: () => void,
-  { enabled = true, delay = LONG_PRESS_MS }: LongPressOptions = {},
-): LongPressResult {
-  const timer = useRef<number | null>(null);
-  const start = useRef({ x: 0, y: 0 });
-  const fired = useRef(false);
-  const teardown = useRef<(() => void) | null>(null);
-  const cbRef = useRef(onLongPress);
-  useEffect(() => {
-    cbRef.current = onLongPress;
-  });
-
-  const cancel = useCallback(() => {
-    if (timer.current !== null) {
-      window.clearTimeout(timer.current);
-      timer.current = null;
-    }
-    teardown.current?.();
-    teardown.current = null;
-  }, []);
-
-  const onPointerDown = useCallback(
-    (e: ReactPointerEvent) => {
-      // Cleared above every early return: a press whose trailing click never arrives
-      // (the finger lifted over another row) would otherwise leave the latch armed,
-      // and it would eat the next real tap once the card has switched modes.
-      fired.current = false;
-      if (!enabled) return;
-      if (e.pointerType === "mouse" && e.button !== 0) return;
-      cancel();
-      start.current = { x: e.clientX, y: e.clientY };
-
-      const onEnd = () => cancel();
-      const onMove = (ev: PointerEvent) => {
-        if (movedBeyondSlop(start.current, ev.clientX, ev.clientY)) cancel();
-      };
-      window.addEventListener("pointerup", onEnd);
-      window.addEventListener("pointercancel", onEnd);
-      window.addEventListener("pointermove", onMove);
-      window.addEventListener("scroll", onEnd, { capture: true, passive: true });
-      teardown.current = () => {
-        window.removeEventListener("pointerup", onEnd);
-        window.removeEventListener("pointercancel", onEnd);
-        window.removeEventListener("pointermove", onMove);
-        window.removeEventListener("scroll", onEnd, { capture: true });
-      };
-
-      timer.current = window.setTimeout(() => {
-        cancel();
-        fired.current = true;
-        // The swipe stages' haptic vocabulary; absent on iOS Safari.
-        navigator.vibrate?.(20);
-        cbRef.current();
-      }, delay);
-    },
-    [cancel, delay, enabled],
-  );
-
-  // Also on the element: it still cancels if an ancestor stops the native event
-  // before it reaches `window`.
-  const onPointerMove = useCallback(
-    (e: ReactPointerEvent) => {
-      if (timer.current === null) return;
-      if (movedBeyondSlop(start.current, e.clientX, e.clientY)) cancel();
-    },
-    [cancel],
-  );
-
-  const onContextMenu = useCallback(
-    (e: { preventDefault: () => void }) => {
-      if (enabled) e.preventDefault();
-    },
-    [enabled],
-  );
-
-  const consumeClick = useCallback(() => {
-    if (!fired.current) return false;
-    fired.current = false;
-    return true;
-  }, []);
-
-  // Turned off mid-press: the armed timer still fired, entering selection mode against the
-  // caller's wish and arming `consumeClick` for the next click (0.52 code review).
-  useEffect(() => {
-    if (!enabled) cancel();
-  }, [enabled, cancel]);
-
-  useEffect(() => cancel, [cancel]);
-
-  return { handlers: { onPointerDown, onPointerMove, onContextMenu }, consumeClick };
-}

package/src/hooks/use-media-query.ts

@@ -1,39 +0,0 @@
-import { useEffect, useEffectEvent, useState } from "react";
-
-/**
- * Subscribe to a CSS media query, returning whether it currently matches and
- * re-rendering when it changes. `fallback` is the value used during SSR / when
- * `window.matchMedia` is unavailable.
- */
-export function useMediaQuery(query: string, fallback: boolean): boolean {
-  const get = () =>
-    typeof window !== "undefined" && typeof window.matchMedia === "function"
-      ? window.matchMedia(query).matches
-      : fallback;
-  // The answer is kept with the query it answers, and a new query is asked during the
-  // render that brings it. Read at mount only, the first commit after a new query still
-  // answered the OLD one, until the effect corrected it: `useBreakpoint` asks a new query
-  // when the text size changes, and at Large in a 700 px window the tour card was drawn
-  // un-docked for a frame before it docked (0.52 code review, use-breakpoint.ts).
-  const [state, setState] = useState(() => ({ query, matches: get() }));
-  let matches = state.matches;
-  if (state.query !== query) {
-    matches = get();
-    setState({ query, matches });
-  }
-  const answered = useEffectEvent(() => matches);
-  useEffect(() => {
-    if (typeof window === "undefined" || typeof window.matchMedia !== "function") return;
-    const mql = window.matchMedia(query);
-    const update = () =>
-      setState((prev) =>
-        prev.query === query && prev.matches === mql.matches ? prev : { query, matches: mql.matches },
-      );
-    // A change between the render and this subscription. Only then: an update that
-    // changes nothing still costs a render (and a commit) right after a new query.
-    if (mql.matches !== answered()) update();
-    mql.addEventListener("change", update);
-    return () => mql.removeEventListener("change", update);
-  }, [query]);
-  return matches;
-}

package/src/hooks/use-mounted.ts

@@ -1,39 +0,0 @@
-import { useEffect, useRef } from "react";
-
-/**
- * A mounted guard and a callback-to-promise bridge, for a card that awaits an app's
- * callback and must not set state after the page moved on.
- *
- * Written for the account settings parts (0.34) and then imported by seven notifications
- * modules out of `account/account-parts.ts`: a generic helper living in a feature folder
- * that the folder beside it reached into sideways (refactor audit 2026-10-30, MOD-6).
- * `account-parts.ts` re-exports both, so nothing that imported them there moved, and
- * `admin/admin-parts.ts` re-exports `settle` in place of its own copy (0.52 code review).
- *
- * @internal Not part of the barrel.
- */
-
-/** Whether the component is still mounted — a late answer after the app navigated away
- *  (the deletion signs out) must not set state. */
-export function useMounted(): { readonly current: boolean } {
-  const mounted = useRef(true);
-  useEffect(() => {
-    mounted.current = true;
-    return () => {
-      mounted.current = false;
-    };
-  }, []);
-  return mounted;
-}
-
-/** Call `call` and hand back a promise, a throw included — a callback may return
- *  nothing (done at once), a promise, or throw before it returns one. Typed by what it
- *  answers, so the admin parts' copy, which kept the type, could go (0.52 code review,
- *  admin/admin-parts.ts). */
-export function settle<R>(call: () => R): Promise<Awaited<R>> {
-  try {
-    return Promise.resolve(call());
-  } catch (error) {
-    return Promise.reject(error);
-  }
-}

package/src/hooks/use-noindex.ts

@@ -1,37 +0,0 @@
-import { useEffect } from "react";
-
-/**
- * Marks the current page as not for search engines: a `<meta name="robots"
- * content="noindex">` in the document head while the calling component is mounted.
- *
- * keksdose's hook (shared/hooks/use-noindex.ts, feedback #97 and #129), for every app:
- * the contract puts it on the three legal pages and on every auth page
- * (docs/legal-harmonization.md §3.2). {@link LegalPage} calls it itself.
- *
- * It is the best-effort, client-side half. The authoritative half is the web server's
- * `X-Robots-Tag: noindex` on those routes (keksdose's Caddy `@noindex`), which a crawler
- * reads without running any script; this covers the dev server and any setup without
- * that header.
- *
- * The cleanup is the point of a hook rather than a tag in `index.html`: in a single-page
- * app the head outlives the page, so without it a visitor's navigation from a legal page
- * into the app would carry the marker onto pages that should be indexed. Each call adds
- * its OWN element and removes exactly that one, so two mounted callers (a page and a
- * dialog on it) never take each other's marker away.
- *
- * `active = false` adds nothing — for a page component that is also rendered as a
- * preview inside another page (the showcase), where the host page's indexing is not its
- * business. Hooks cannot be called conditionally, so the switch is an argument.
- */
-export function useNoIndex(active: boolean = true): void {
-  useEffect(() => {
-    if (!active) return;
-    const meta = document.createElement("meta");
-    meta.name = "robots";
-    meta.content = "noindex";
-    document.head.appendChild(meta);
-    return () => {
-      meta.remove();
-    };
-  }, [active]);
-}