@eifi1/ui-kit 0.4.0 → 0.5.0

package/src/components/numpad-sheet.tsx

@@ -0,0 +1,264 @@
+import { createPortal } from "react-dom";
+import { Delete } from "lucide-react";
+import { useMemo } from "react";
+import type { ReactNode } from "react";
+import { cn } from "../lib/cn";
+import { useEscapeKey } from "../hooks/use-dismiss";
+import { evaluateExpression, formatResult, sanitizeLive } from "../lib/calc";
+import {
+  DEFAULT_CALCULATOR_LABELS,
+  useKitLabels,
+  type CalculatorLabels,
+} from "../i18n/kit-labels";
+
+/**
+ * A full calculator keypad rendered as a bottom sheet — the mobile counterpart to
+ * the desktop {@link CalculatorButton} popover, and the replacement for the old
+ * under-the-field operator bar (`MathKeys`, feedback #334).
+ *
+ * A native app (YNAB) can swap the system keyboard for its own keypad; a PWA
+ * cannot — but it CAN suppress the OS keyboard with `inputMode="none"` on the
+ * host field and paint its own keypad in the freed space. So the host input keeps
+ * real focus/caret/selection + the existing value/commit contract, while this
+ * sheet drives it: digits + operators + a live `= …` preview, evaluated through
+ * the shared {@link evaluateExpression} engine. Desktop is untouched (it keeps the
+ * native keyboard and the calculator popover); the host gates this to mobile.
+ *
+ * Buttons commit through the host's `onChange`/blur, so the sheet is stateless —
+ * the field text is the single source of truth. `onPointerDown` preventDefault on
+ * the root keeps the host input focused (caret stays, keyboard stays hidden) as
+ * the user taps keys; the buttons' `onClick` still fires.
+ */
+/** Names for the pad itself and its four non-digit keys. The first four are
+ *  screen-reader names; `done` is the one string here that is READ OFF THE SCREEN —
+ *  the brand-filled primary button — and it was a hardcoded English literal while
+ *  its three neighbours each took an override, so a German phone showed "Done"
+ *  among German labels with no prop able to change it. */
+export interface NumberPadSheetLabels extends Partial<CalculatorLabels> {
+  /** The pad's own name — the `calculator.panel` key under its older name here. */
+  pad?: string;
+  backspace?: string;
+  clear?: string;
+  equals?: string;
+  /** Visible text on the primary key, not an `aria-label`. */
+  done?: string;
+}
+
+type PadKey =
+  | { kind: "ins"; label: string; ins: string; accent?: boolean; name?: PadKeyName }
+  | { kind: "back" };
+
+/** The {@link CalculatorLabels} key naming a non-digit key; digits are their glyph. */
+type PadKeyName = "plus" | "minus" | "times" | "divide" | "decimal";
+
+// Insert chars that survive `sanitizeLive` (it keeps `× ÷` and ASCII `+ - * /`
+// but strips the unicode minus `−`, so minus inserts an ASCII "-" while showing
+// the nicer glyph). The evaluator normalises `× ÷` back to `* /`.
+const PAD_KEYS: PadKey[] = [
+  { kind: "ins", label: "7", ins: "7" },
+  { kind: "ins", label: "8", ins: "8" },
+  { kind: "ins", label: "9", ins: "9" },
+  { kind: "ins", label: "÷", ins: "÷", accent: true, name: "divide" },
+  { kind: "ins", label: "4", ins: "4" },
+  { kind: "ins", label: "5", ins: "5" },
+  { kind: "ins", label: "6", ins: "6" },
+  { kind: "ins", label: "×", ins: "×", accent: true, name: "times" },
+  { kind: "ins", label: "1", ins: "1" },
+  { kind: "ins", label: "2", ins: "2" },
+  { kind: "ins", label: "3", ins: "3" },
+  { kind: "ins", label: "−", ins: "-", accent: true, name: "minus" },
+  { kind: "ins", label: ".", ins: ".", name: "decimal" },
+  { kind: "ins", label: "0", ins: "0" },
+  { kind: "back" },
+  { kind: "ins", label: "+", ins: "+", accent: true, name: "plus" },
+];
+
+/** Every key's shape — including the thing this pad used to delete without replacing.
+ *
+ *  `focus:outline-none` alone is not a style choice, it is the removal of the only
+ *  signal a keyboard user has; on a 4×4 grid of identical tiles it leaves no way at all
+ *  to tell which key Enter is about to press (the audit's §a11y, and the same defect as
+ *  the dropdown search box).
+ *
+ *  `focus-visible` and `ring-inset`, for the two reasons {@link ToggleGroup} already
+ *  writes down. This is a touch control first, and a plain `focus:` ring paints itself
+ *  on every TAP, because a tap focuses the button. And the keys sit 6px apart, which is
+ *  thinner than an outward ring plus the neighbour it would spill onto — inset keeps the
+ *  ring inside the key it describes.
+ *
+ *  --brand rather than --border-strong: the operator keys are filled with --border, and
+ *  a ring in the colour of the thing it surrounds is not an indicator. */
+const PAD_BTN =
+  "flex h-14 items-center justify-center rounded-lg text-lg font-medium transition-transform select-none focus:outline-none focus-visible:ring-2 focus-visible:ring-inset focus-visible:ring-[var(--brand)] active:scale-[0.97]";
+const PAD_DIGIT = "bg-[var(--bg-surface-2)] text-[var(--text-primary)] active:bg-[var(--border)]";
+const PAD_ACCENT = "bg-[var(--border)] text-[var(--text-primary)] active:bg-[var(--bg-surface-2)]";
+
+export function NumberPadSheet({
+  value,
+  onChange,
+  onDone,
+  label,
+  labels,
+}: {
+  value: string;
+  /** Fired with the raw (sanitised) field text on every key — same contract as
+   * the host field's own `onChange`. */
+  onChange: (value: string) => void;
+  /** Fired on "Done": the host blurs the input, which commits (evaluates) and
+   * unmounts the sheet via its existing blur handler. */
+  onDone: () => void;
+  /** Optional field label, echoed in the sheet header so the user still knows
+   * which field they're editing when the sheet covers it. */
+  label?: ReactNode;
+  /** Names for the pad itself and its non-digit keys — screen-reader names, except
+   * `done`, which is the visible text on the primary key. Merged over `calculator`
+   * from `<UiKitProvider labels>`: this is the same keypad as `CalculatorButton`'s,
+   * on a phone, and one translation covers both. Digits need no name — their glyph
+   * IS the name; the operators do (see {@link CalculatorLabels.plus}). */
+  labels?: NumberPadSheetLabels;
+}) {
+  // `pad` is this sheet's older spelling of `panel`, so it is folded in as that.
+  const fromProps = useMemo(() => {
+    if (!labels) return undefined;
+    const { pad, ...rest } = labels;
+    return pad === undefined ? rest : { ...rest, panel: pad };
+  }, [labels]);
+  const text = useKitLabels("calculator", DEFAULT_CALCULATOR_LABELS, fromProps);
+
+  // NO `useBodyScrollLock`, and that is the point of the control (Keksdose live
+  // #317: *"Background not scrollable when the amount input calculator field is
+  // open"*).
+  //
+  // This sheet is a KEYBOARD, not a dialog. It is opened by focusing a field and
+  // exists only because a PWA cannot swap the system keyboard for its own — so it
+  // suppresses the OS keyboard with `inputMode="none"` and paints itself in the
+  // freed space. An OS keyboard does not freeze the page behind it; it takes the
+  // bottom of the screen and leaves you free to scroll what is left, which is how
+  // you reach the field you are typing into when the keys cover it.
+  //
+  // Locking here made the page unreachable at exactly the moment it matters most:
+  // correcting a receipt total against the running line sum, where the figure you
+  // are comparing against sits below the keypad. The other four holders of that
+  // hook are all modal — `Modal`, `PickerSheet`, `FullBleedDialog`, the DataTable
+  // row dialog — and they stay locked, because for them the page behind is not
+  // part of the task.
+  //
+  // The pad still does not scroll ITSELF away under a stray drag: the root's
+  // `onPointerDown` preventDefault (below) keeps the host input focused and eats
+  // the gesture on the sheet, so a touch that starts on a key is not a page scroll.
+
+  // ── NO focus trap either, and for a harder reason than the scroll lock ────────
+  //
+  // Wave 3 put `useFocusTrap` on every overlay in this package. This one is the
+  // exception, and it is not an oversight to be tidied up later: a trap here would
+  // DELETE THE COMPONENT IT WAS PROTECTING. Both hosts render the pad with
+  // `showNumpad = isMobile && !disabled && focused`, where `focused` is the host
+  // input's own focus state. Moving focus into the pad blurs that input, the host
+  // sets `focused` false, and the pad unmounts — on mount, before a single key can be
+  // pressed. The blur also COMMITS, so the trap would evaluate a half-typed
+  // expression on the way out.
+  //
+  // That is the contract, not an accident of it. This sheet exists because a PWA
+  // cannot swap the system keyboard for its own: the host keeps real focus, caret and
+  // selection while `inputMode="none"` suppresses the OS keys, and the root's
+  // `onPointerDown` preventDefault below is there for the same reason. The pad is
+  // `role="group"`, not a dialog. A keyboard does not trap focus; it is what you type
+  // WITH.
+  //
+  // What was genuinely missing is a way OUT that is not a tap. `useEscapeKey` and not
+  // a handler on the sheet, because the sheet never has the focus a keydown would
+  // bubble from — the host does, and the host is not this component. Escape does what
+  // the Done key does rather than cancelling, because committing on blur is the
+  // host's contract and a cancel would have to be the host's to offer.
+  //
+  // The limit, since it is better written down than discovered: inside a `Modal` the
+  // dialog's own Escape handler sits on the focus path and stops the event before a
+  // document listener sees it, so there the press closes the dialog — which it did
+  // before this line existed too, and which takes the pad with it either way.
+  useEscapeKey(onDone);
+
+  const result = evaluateExpression(value);
+  const preview = result !== null && formatResult(result) !== value.trim() ? `= ${formatResult(result)}` : "";
+
+  const insert = (ch: string) => onChange(sanitizeLive(value + ch));
+  const backspace = () => onChange(value.slice(0, -1));
+  const clearAll = () => onChange("");
+  const equals = () => {
+    if (result !== null) onChange(formatResult(result));
+  };
+
+  const sheet = (
+    <div
+      role="group"
+      aria-label={text.panel}
+      // Keep the host input focused when tapping the pad: preventDefault on
+      // pointerdown blocks the focus/blur, while the buttons' click still fires.
+      onPointerDown={(e) => e.preventDefault()}
+      className="fixed inset-x-0 bottom-0 z-50 border-t border-[var(--border)] bg-[var(--bg-surface)] px-2 pt-2 shadow-[0_-4px_24px_rgba(0,0,0,0.12)]"
+      style={{ paddingBottom: "max(0.5rem, env(safe-area-inset-bottom))" }}
+    >
+      {/* Header display: which field + the running expression and live result, so
+          the value stays visible even when the sheet covers the field. */}
+      <div className="flex items-end justify-between gap-3 px-2 pb-2">
+        {label != null && (
+          <span className="truncate pb-1 text-xs font-medium text-[var(--money-neutral)]">{label}</span>
+        )}
+        <div className="ml-auto min-w-0 text-right">
+          <div className="truncate font-mono text-lg leading-tight text-[var(--text-primary)]">{value || "0"}</div>
+          <div className="h-4 font-mono text-xs text-[var(--money-neutral)]">{preview}</div>
+        </div>
+      </div>
+
+      <div className="grid grid-cols-4 gap-1.5">
+        {PAD_KEYS.map((key, i) =>
+          key.kind === "back" ? (
+            <button
+              key="back"
+              type="button"
+              aria-label={text.backspace}
+              onClick={backspace}
+              className={cn(PAD_BTN, PAD_ACCENT)}
+            >
+              <Delete className="size-5" />
+            </button>
+          ) : (
+            <button
+              key={`${key.ins}-${i}`}
+              type="button"
+              aria-label={key.name ? text[key.name] : key.label}
+              onClick={() => insert(key.ins)}
+              className={cn(PAD_BTN, key.accent ? PAD_ACCENT : PAD_DIGIT)}
+            >
+              {key.label}
+            </button>
+          ),
+        )}
+      </div>
+
+      <div className="mt-1.5 grid grid-cols-4 gap-1.5">
+        <button type="button" aria-label={text.clear} onClick={clearAll} className={cn(PAD_BTN, PAD_ACCENT)}>
+          C
+        </button>
+        <button type="button" aria-label={text.equals} onClick={equals} className={cn(PAD_BTN, PAD_ACCENT)}>
+          =
+        </button>
+        <button
+          type="button"
+          onClick={onDone}
+          // The one key whose own fill is --brand, so it rings in the colour that fill
+          // was chosen to be legible against instead (tailwind-merge keeps the later
+          // ring colour). A --brand ring here would be present in the DOM and invisible
+          // on screen, which is the defect this change exists to fix.
+          className={cn(
+            PAD_BTN,
+            "col-span-2 bg-[var(--brand)] text-[var(--brand-contrast)] focus-visible:ring-[var(--brand-contrast)] active:bg-[var(--brand-hover)]",
+          )}
+        >
+          {text.done}
+        </button>
+      </div>
+    </div>
+  );
+
+  return createPortal(sheet, document.body);
+}

package/src/components/page-contents.tsx

@@ -0,0 +1,289 @@
+import { useEffect, useRef, useState } from "react";
+import type { ComponentPropsWithoutRef, ReactNode } from "react";
+import { ChevronDown } from "lucide-react";
+import { cn } from "../lib/cn";
+import { useKitLabels } from "../i18n/kit-labels";
+
+/**
+ * "On this page": a page's own table of contents, with the section being read marked.
+ *
+ * Three parts, because an app needs them separately:
+ *
+ *   - {@link useScrollSpy} — which section is current, from the headings' positions in
+ *     a scroll container. No markup; usable for anything that follows the reader.
+ *   - {@link PageContents} — the list. `variant="rail"` for beside the page,
+ *     `variant="disclosure"` for a collapsed block under the title on narrow screens.
+ *   - {@link PageContentsLayout} — the page with the rail sticky on one side of it.
+ *
+ * Domain-free: the app supplies the entries and how an entry links (`hrefFor`), so it
+ * works with any router, including a hash router where `#id` alone would be read as a
+ * route.
+ */
+
+export interface PageContentsItem {
+  /** The id of the heading the entry jumps to. */
+  id: string;
+  label: ReactNode;
+  /** 2 indents the entry under the one before it. */
+  level?: 1 | 2;
+}
+
+export interface PageContentsLabels {
+  /** The heading above the list, and the landmark's accessible name. */
+  title: string;
+}
+
+export const DEFAULT_PAGE_CONTENTS_LABELS: PageContentsLabels = {
+  title: "On this page",
+};
+
+export interface UseScrollSpyOptions {
+  /** The element that scrolls. Defaults to the viewport. In `AppShell`, pass its
+   *  `<main>` — it is the page's scroll container from `md` up. */
+  root?: Element | null;
+  /**
+   * How far down the scroller the "reading line" sits, as a fraction of its height.
+   * A section becomes current once its heading passes above it, and stays current
+   * until the next heading does — so a long section keeps its entry marked while it
+   * is being read, not only while its heading is on screen. Default 0.15: close to
+   * the top, so a short section followed by another does not hand its mark to the
+   * next one the moment it is scrolled to.
+   */
+  line?: number;
+}
+
+/**
+ * The id of the section being read: the last of `ids` whose element has scrolled
+ * above the reading line — or the first, before any has.
+ */
+export function useScrollSpy(ids: readonly string[], options: UseScrollSpyOptions = {}): string | null {
+  const { root = null, line = 0.15 } = options;
+  const [current, setCurrent] = useState<string | null>(null);
+  const key = ids.join("\u0000");
+
+  useEffect(() => {
+    if (ids.length === 0) return;
+    const scroller: Element | Window = root ?? window;
+    const measure = () => {
+      const top = root ? root.getBoundingClientRect().top : 0;
+      const height = root ? root.clientHeight : window.innerHeight;
+      const reading = top + height * line;
+      let next = ids[0];
+      for (const id of ids) {
+        const el = document.getElementById(id);
+        if (el && el.getBoundingClientRect().top <= reading) next = id;
+      }
+      // At the very bottom the last sections may never reach the line; the reader
+      // who scrolled to the end is reading the end.
+      const atEnd = root
+        ? root.scrollTop + root.clientHeight >= root.scrollHeight - 2
+        : window.scrollY + window.innerHeight >= document.documentElement.scrollHeight - 2;
+      const scrolled = root ? root.scrollTop : window.scrollY;
+      if (atEnd && scrolled > 0) next = ids[ids.length - 1];
+      setCurrent(next);
+    };
+    let frame = 0;
+    const onScroll = () => {
+      cancelAnimationFrame(frame);
+      frame = requestAnimationFrame(measure);
+    };
+    measure();
+    scroller.addEventListener("scroll", onScroll, { passive: true });
+    window.addEventListener("resize", onScroll);
+    return () => {
+      cancelAnimationFrame(frame);
+      scroller.removeEventListener("scroll", onScroll);
+      window.removeEventListener("resize", onScroll);
+    };
+    // `key` stands for `ids`: a new array with the same entries is the same list.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [key, root, line]);
+
+  return current;
+}
+
+export interface PageContentsProps extends Omit<ComponentPropsWithoutRef<"nav">, "children"> {
+  items: PageContentsItem[];
+  /** The current entry — typically `useScrollSpy(items.map(i => i.id), …)`. */
+  activeId?: string | null;
+  /** The link for an entry. Default `#id`; under a hash router build it with the
+   *  router (react-router's `useHref({ hash: id })` gives `#/page#id`). */
+  hrefFor?: (id: string) => string;
+  /** `rail` — a list beside the page. `disclosure` — collapsed under a summary line,
+   *  for narrow screens where a rail has no room. */
+  variant?: "rail" | "disclosure";
+  labels?: Partial<PageContentsLabels>;
+}
+
+/**
+ * The list itself. The current entry gets a brand bar on the list's rule, the brand
+ * colour, and `aria-current="location"` — the marker documentation sites use, and the
+ * one a screen reader announces.
+ */
+export function PageContents({
+  items,
+  activeId,
+  hrefFor = (id) => `#${id}`,
+  variant = "rail",
+  labels,
+  className,
+  ...rest
+}: PageContentsProps) {
+  const l = useKitLabels("pageContents", DEFAULT_PAGE_CONTENTS_LABELS, labels);
+  const listRef = useRef<HTMLUListElement>(null);
+  // The entry just clicked is the current one until the reader scrolls on their own.
+  // Without this, jumping to a short section near the end of a page marks whichever
+  // later section the jump also carried past the reading line — you click one entry
+  // and another lights up.
+  const [clicked, setClicked] = useState<string | null>(null);
+  useEffect(() => {
+    if (!clicked) return;
+    const release = () => setClicked(null);
+    // A user scroll — wheel, touch, keys — releases it; the programmatic scroll the
+    // jump itself causes does not fire these.
+    window.addEventListener("wheel", release, { passive: true, once: true });
+    window.addEventListener("touchmove", release, { passive: true, once: true });
+    window.addEventListener("keydown", release, { once: true });
+    return () => {
+      window.removeEventListener("wheel", release);
+      window.removeEventListener("touchmove", release);
+      window.removeEventListener("keydown", release);
+    };
+  }, [clicked]);
+  const shown = clicked ?? activeId;
+
+  // Keep the current entry in view when the list is taller than the window.
+  useEffect(() => {
+    if (!shown || variant !== "rail") return;
+    listRef.current
+      ?.querySelector<HTMLElement>(`[data-entry="${CSS.escape(shown)}"]`)
+      ?.scrollIntoView?.({ block: "nearest" });
+  }, [shown, variant]);
+
+  if (items.length === 0) return null;
+
+  const list = (
+    <ul
+      ref={listRef}
+      className={cn(
+        "space-y-0.5 border-s border-[var(--border)]",
+        variant === "rail" && "max-h-[calc(100dvh-10rem)] overflow-y-auto [scrollbar-width:thin]",
+      )}
+    >
+      {items.map((item) => {
+        const current = item.id === shown;
+        return (
+          <li key={item.id} data-entry={item.id}>
+            <a
+              href={hrefFor(item.id)}
+              // One line per entry in the rail; past 22rem the ellipsis takes over and
+              // the full text is on hover. The disclosure has the page's width and wraps.
+              title={variant === "rail" && typeof item.label === "string" ? item.label : undefined}
+              aria-current={current ? "location" : undefined}
+              onClick={() => setClicked(item.id)}
+              className={cn(
+                "-ms-px block border-s-2 py-1 pe-1 text-[13px] leading-snug transition-colors duration-150",
+                variant === "rail" && "truncate",
+                item.level === 2 ? "ps-6" : "ps-3",
+                current
+                  ? "border-[var(--brand)] font-medium text-[var(--brand)]"
+                  : "border-transparent text-[var(--text-muted)] hover:border-[var(--border-strong)] hover:text-[var(--text-primary)]",
+              )}
+            >
+              {item.label}
+            </a>
+          </li>
+        );
+      })}
+    </ul>
+  );
+
+  if (variant === "disclosure") {
+    return (
+      <details
+        className={cn(
+          "group rounded-md border border-[var(--border)] bg-[var(--bg-surface)]",
+          className,
+        )}
+      >
+        <summary className="flex cursor-pointer list-none items-center justify-between px-3 py-2 text-sm font-medium text-[var(--text-secondary)] [&::-webkit-details-marker]:hidden">
+          {l.title}
+          <ChevronDown
+            aria-hidden
+            className="size-4 transition-transform duration-200 group-open:rotate-180 motion-reduce:transition-none"
+          />
+        </summary>
+        <nav {...rest} aria-label={l.title} className="border-t border-[var(--border)] px-2 py-2">
+          {list}
+        </nav>
+      </details>
+    );
+  }
+
+  return (
+    <nav {...rest} aria-label={l.title} className={className}>
+      <p className="mb-2 text-[11px] font-semibold uppercase tracking-wide text-[var(--text-muted)]">
+        {l.title}
+      </p>
+      {list}
+    </nav>
+  );
+}
+
+export interface PageContentsLayoutProps extends ComponentPropsWithoutRef<"div"> {
+  /** What goes in the rail — typically a `<PageContents variant="rail">`. */
+  contents: ReactNode;
+  /**
+   * Which side of the page the rail sits on: `start` is the left in a left-to-right
+   * language (next to the app's own sidebar, so both navigations are in one place),
+   * `end` the right (the documentation-site convention, clear of the sidebar). Logical,
+   * so both flip in a right-to-left UI.
+   */
+  position?: "start" | "end";
+  children: ReactNode;
+}
+
+/**
+ * The page with a sticky contents rail beside it, from `xl` (1280px) up. Below that
+ * the rail would squeeze the content, so it is not rendered there — pair it with a
+ * `<PageContents variant="disclosure" className="xl:hidden">` in the page.
+ *
+ * The rail is `sticky top-6`, which sticks inside the nearest scroll container — the
+ * viewport, or `AppShell`'s `<main>`.
+ */
+export function PageContentsLayout({
+  contents,
+  position = "start",
+  children,
+  className,
+  ...rest
+}: PageContentsLayoutProps) {
+  // In DOM order on its side, not moved there with `order`: Tab and a screen reader
+  // follow the source, and a rail painted on the left but read after the page would
+  // put the page's index at its end.
+  const rail = (
+    <aside className="hidden xl:block">
+      <div className="sticky top-6">{contents}</div>
+    </aside>
+  );
+  return (
+    <div
+      {...rest}
+      className={cn(
+        "xl:grid xl:gap-10",
+        // `fit-content(22rem)`: the rail is as wide as its longest entry, up to 22rem.
+        // A fixed 13rem broke "Select — unlabelled, labelled, invalid, disabled" over
+        // three lines beside a page with room to spare; an index you scan should read
+        // one entry per line.
+        position === "start"
+          ? "xl:grid-cols-[fit-content(22rem)_minmax(0,1fr)]"
+          : "xl:grid-cols-[minmax(0,1fr)_fit-content(22rem)]",
+        className,
+      )}
+    >
+      {position === "start" && rail}
+      <div className="min-w-0">{children}</div>
+      {position === "end" && rail}
+    </div>
+  );
+}