@eifi1/ui-kit 0.54.0 → 0.55.0

package/src/components/one-time-code-input.tsx

@@ -1,270 +0,0 @@
-import { useId, useState } from "react";
-import type { ChangeEvent, ClipboardEvent, FocusEvent, InputHTMLAttributes, ReactNode, Ref } from "react";
-import { cn } from "../lib/cn";
-import { EndHintRow, FieldCaption, useFieldError, useFieldHint, type FieldHelpProps } from "./field-parts";
-import { FIELD_BASE, FIELD_INVALID, FIELD_WRITABLE_LOOK, FLOATING_INPUT_CLASS, FloatingField } from "./field-base";
-
-/**
- * The field for a verification code — the six digits an authenticator app shows, or the
- * ones a sign-in mail or SMS carries.
- *
- * Asked for by kastlan (input audit, item 3) and keksdose (K8) for the sign-in
- * verification step, and already written twice by hand inside {@link TwoFactorSetting}.
- * The three copies agreed on `inputMode="numeric"` and `autoComplete="one-time-code"`
- * and on nothing else: kastlan's login stripped non-digits and capped at six, keksdose's
- * capped at eight and kept whatever was typed, and the settings card kept everything,
- * spaces included — so "123 456" pasted from an authenticator that groups its digits
- * reached the server with the space in it.
- *
- * ONE FIELD, NOT SIX BOXES. The six-box look is the fashionable one, and every part of
- * it works against the two ways a code actually arrives. A paste lands in ONE input,
- * so the boxes need a paste handler that spreads it; the platform's own code autofill
- * (iOS and macOS offer the code from Messages and Mail above the keyboard, Android's
- * keyboards do the same) fills the ONE field marked `one-time-code`, so the boxes need
- * that field to exist anyway, hidden; and a screen reader hears six unlabelled inputs
- * of one character each. One text field gets all three right for free.
- *
- * WHAT IT DOES TO THE TEXT:
- *  - **Digits only**, as a STRING. A code may start with 0, and a number field would
- *    drop it ("012345" → 12345) — kastlan's login says as much in a comment. Every
- *    character that is not a digit is dropped as it arrives, so the spaces and dashes
- *    of "123 456" and "123-456" go, whether typed or pasted. Full-width digits (what a
- *    Chinese input method types: "１２３") are folded to ASCII first (NFKC).
- *  - **No `maxLength` attribute.** The browser applies it BEFORE the change event, so
- *    pasting "123 456" into a `maxLength={6}` field kept "123 45" and the cleaning saw
- *    one digit short. The length is enforced here instead, after the cleaning: a field
- *    that is full refuses another digit, as `maxLength` would.
- *  - **A paste that is a whole code replaces the field**, wherever the caret is: a
- *    person pasting six digits means "this is the code", not "insert these into the
- *    stale one".
- *  - **The caret stays put** when a character is dropped, rather than jumping to the
- *    end as a controlled input does when its value is put back.
- *
- * `onComplete` fires when an edit — a keystroke, a paste, the platform's autofill —
- * makes the code `length` digits long. It is a notification, nothing more: the field
- * never submits a form on its own. Whether a full code verifies at once is the app's
- * call (a sign-in step may; a "turn off two-factor" form that also wants a password
- * should not). It does not fire for a value set from outside.
- *
- * `label`, `hint` and `error` read as on every kit field: a floating label, a text hint
- * as a caption under the field (a {@link FieldHint} "?" rides the label line instead),
- * the error under that, both attached through `aria-describedby` after the caller's own.
- */
-export interface OneTimeCodeInputProps
-  extends
-    Omit<
-      InputHTMLAttributes<HTMLInputElement>,
-      "value" | "defaultValue" | "onChange" | "type" | "inputMode" | "autoComplete" | "maxLength" | "pattern"
-    >,
-    FieldHelpProps {
-  /** The digits so far — a string, so leading zeros survive. */
-  value: string;
-  /** The cleaned code after every edit: digits only, never longer than `length`. */
-  onChange: (code: string) => void;
-  /** How many digits the code has. Default 6. The field refuses digits past it. */
-  length?: number;
-  /** Called with the code when an edit makes it `length` digits long. Never submits
-   *  anything itself. */
-  onComplete?: (code: string) => void;
-  /** The floating label, as on {@link Input}. Without one, name the field with
-   *  `aria-label` or `aria-labelledby` (kastlan's login points it at its prompt). */
-  label?: ReactNode;
-  /** Plain text: a caption under the field, attached with `aria-describedby`. Anything
-   *  else (a {@link FieldHint}): on the label line — or at the field's end edge when
-   *  there is no label. The rule {@link Select}'s `hint` follows. */
-  hint?: ReactNode;
-  /** What is wrong ("That code has expired"). Rendered under the field, attached with
-   *  `aria-describedby`, and implies `invalid`. */
-  error?: ReactNode;
-  /** Paint the field invalid and set `aria-invalid` without a message of its own. */
-  invalid?: boolean;
-  /** Classes for the `<input>`; `className` styles the field's wrapper once it has a
-   *  label, the `<input>` itself when it has none — as on {@link Input}. */
-  inputClassName?: string;
-  /**
-   * Keep the field `readOnly` until it first takes focus.
-   *
-   * A browser that has a login saved for the site fills it in on load — and on a page
-   * where the code field is the only text field near a password field, it can take the
-   * code field for the username and write the address into it. A read-only field is
-   * never autofilled, and focus is the moment a person (or the platform's code
-   * suggestion, which needs a focused field anyway) starts to use it. So the field
-   * stays read-only until then, and only until then.
-   *
-   * It keeps the LOOK of an editable field throughout ({@link FIELD_WRITABLE_LOOK}):
-   * this is the one place where read-only does not mean "you may not type here", and
-   * without the opt-out the field would sit there greyed until it is clicked.
-   *
-   * {@link TwoFactorSetting} has always done this — its code fields share a page with
-   * the current-password field of the disable form — and keeps doing it through this
-   * prop. Off by default, because it is a trade: a field that is read-only at the
-   * moment focus lands can be announced as read-only by a screen reader, and on some
-   * mobile browsers it does not raise the keyboard until a second tap. Turn it on where
-   * a saved login actually lands in the field.
-   */
-  readOnlyUntilFocus?: boolean;
-  /** The `<input>`. A React 19 ref prop since 0.34 (MOD-4, refactor audit 2026-10); it
-   *  was `forwardRef`. */
-  ref?: Ref<HTMLInputElement>;
-}
-
-// Equal-width digits, spaced a little apart, so a code reads — and compares against the
-// authenticator's screen — digit by digit.
-const CODE_TYPE = "tabular-nums tracking-widest";
-
-/** The ASCII digits in `text`, in order. NFKC folds full-width digits ("１") to "1". */
-function digitsOf(text: string): string {
-  return text.normalize("NFKC").replace(/\D/g, "");
-}
-
-export function OneTimeCodeInput(props: OneTimeCodeInputProps) {
-  const {
-    ref,
-    value,
-    onChange,
-    length = 6,
-    onComplete,
-    label,
-    hint,
-    help,
-    error,
-    invalid: invalidProp,
-    className,
-    inputClassName,
-    readOnlyUntilFocus = false,
-    readOnly,
-    id,
-    placeholder,
-    onFocus,
-    onPaste,
-    "aria-describedby": ariaDescribedBy,
-    "aria-invalid": ariaInvalid,
-    ...rest
-  } = props;
-  // A length below one is no code at all; a fractional one is a typo.
-  const size = Math.max(1, Math.floor(length) || 1);
-  const generatedId = useId();
-  const fieldId = id ?? generatedId;
-  // Text is a caption under the field; a FieldHint rides the label line, and is that
-  // caption at Large and on touch (§4). See `hint`. Through useFieldHint and
-  // useFieldError since 0.34, not copies of their rules (DUP-2, DUP-8).
-  const hintParts = useFieldHint(hint, ariaDescribedBy, { help, name: label ?? rest["aria-label"] });
-  const {
-    isInvalid: invalid,
-    describedBy,
-    errorEl,
-  } = useFieldError(error, invalidProp, hintParts.describedBy, ariaInvalid);
-  // Passed at all — even as `undefined` — the field keeps its box, so the `<input>` is
-  // never re-parented (and never loses focus) when a message comes or goes. See
-  // `FieldGroup` in field-base.tsx.
-  const reserve = "error" in props || "hint" in props;
-  const labelled = label !== undefined;
-
-  // Focused once = in use; the guard is down for good from then on (see the prop).
-  const [focusedOnce, setFocusedOnce] = useState(false);
-  const guarding = readOnlyUntilFocus && !focusedOnce;
-
-  const commit = (next: string) => {
-    if (next === value) return;
-    onChange(next);
-    if (next.length === size) onComplete?.(next);
-  };
-
-  const handleChange = (e: ChangeEvent<HTMLInputElement>) => {
-    const input = e.currentTarget;
-    const raw = input.value;
-    const cleaned = digitsOf(raw);
-    // Past the length: a full field refuses the digit (what `maxLength` does), a
-    // partial one keeps the first `size` — a paste longer than the room left.
-    const refused = cleaned.length > size && value.length >= size;
-    const next = refused ? value : cleaned.slice(0, size);
-    if (next !== raw) {
-      // Write the cleaned text back NOW, with the caret where the typist left it.
-      // React would otherwise put its value back after this handler, and setting an
-      // input's value moves the caret to the end — so a space typed mid-code threw
-      // the caret to the last digit. React finds the DOM already agreeing and leaves
-      // it alone.
-      const caret = input.selectionStart ?? raw.length;
-      const at = refused
-        ? Math.max(0, caret - (raw.length - value.length))
-        : Math.min(digitsOf(raw.slice(0, caret)).length, next.length);
-      input.value = next;
-      try {
-        input.setSelectionRange(at, at);
-      } catch {
-        /* not every input type has a selection; a text field does */
-      }
-    }
-    commit(next);
-  };
-
-  const handlePaste = (e: ClipboardEvent<HTMLInputElement>) => {
-    onPaste?.(e);
-    // A read-only field still receives the event; it must not take the code.
-    if (e.defaultPrevented || readOnly || guarding || rest.disabled) return;
-    const pasted = digitsOf(e.clipboardData.getData("text"));
-    // Anything else — a few digits into a partial code — is an ordinary insertion,
-    // and the change handler cleans it.
-    if (pasted.length !== size) return;
-    e.preventDefault();
-    commit(pasted);
-  };
-
-  const handleFocus = (e: FocusEvent<HTMLInputElement>) => {
-    if (guarding) setFocusedOnce(true);
-    onFocus?.(e);
-  };
-
-  const input = (
-    <input
-      ref={ref}
-      id={labelled ? fieldId : id}
-      {...rest}
-      type="text"
-      inputMode="numeric"
-      autoComplete="one-time-code"
-      // The numeric keypad's older cue, for the browsers that predate `inputMode`.
-      // The value is digits only, so it can never fail the pattern.
-      pattern="[0-9]*"
-      // A labelled field's placeholder is a single space: it drives the floating
-      // label's `placeholder-shown` trick. Unlabelled, the caller's ("000000") shows.
-      placeholder={labelled ? " " : placeholder}
-      value={value}
-      readOnly={readOnly || guarding}
-      onChange={handleChange}
-      onPaste={handlePaste}
-      onFocus={handleFocus}
-      aria-invalid={invalid || undefined}
-      aria-describedby={describedBy}
-      className={cn(
-        labelled ? FLOATING_INPUT_CLASS : FIELD_BASE,
-        CODE_TYPE,
-        // Read-only for the guard's sake only: keep the editable look. A caller's
-        // own `readOnly` keeps FIELD_BASE's settled grey, as everywhere else.
-        guarding && !readOnly && FIELD_WRITABLE_LOOK,
-        !labelled && className,
-        inputClassName,
-        invalid && FIELD_INVALID,
-      )}
-    />
-  );
-
-  const field: ReactNode = labelled ? (
-    <FloatingField className={className} htmlFor={fieldId} label={label} hint={hintParts.labelHint}>
-      {input}
-    </FloatingField>
-  ) : (
-    // No label line to ride: a "?" goes at the field's end edge, outside the box —
-    // where an unlabelled Select puts it.
-    <EndHintRow hint={hintParts.labelHint}>{input}</EndHintRow>
-  );
-
-  if (hintParts.captionText === undefined && errorEl === null && !reserve) return field;
-  return (
-    <div>
-      {field}
-      <FieldCaption parts={hintParts} />
-      {errorEl}
-    </div>
-  );
-}

package/src/components/page-contents-labels.ts

@@ -1,9 +0,0 @@
-// The English words of ./page-contents, in a module with no component code: the English
-// catalogue (src/i18n/defaults.ts) imports them without the component, so `en` loads as one
-// chunk like the other languages (0.34, KS U8). ./page-contents re-exports them.
-
-import type { PageContentsLabels } from "./page-contents";
-
-export const DEFAULT_PAGE_CONTENTS_LABELS: PageContentsLabels = {
-  title: "On this page",
-};

package/src/components/page-contents.tsx

@@ -1,282 +0,0 @@
-import { useEffect, useRef, useState } from "react";
-import type { ComponentPropsWithRef, ReactNode } from "react";
-import { ChevronDown } from "lucide-react";
-import { cn } from "../lib/cn";
-import { useKitLabels, type LabelOverride } from "../i18n/kit-labels";
-import { DEFAULT_PAGE_CONTENTS_LABELS } from "./page-contents-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;
-}
-
-// Defined in ./page-contents-labels, which holds no component code (0.34, KS U8).
-export { DEFAULT_PAGE_CONTENTS_LABELS };
-
-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<ComponentPropsWithRef<"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?: LabelOverride<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-subtle",
-        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)}
-              // Entries WRAP in the rail rather than truncate: a cut-off heading needed a
-              // native `title` to be read at all, which a keyboard never sees and which
-              // broke keksdose's one-tooltip rule (dev#523).
-              aria-current={current ? "location" : undefined}
-              onClick={() => setClicked(item.id)}
-              className={cn(
-                "-ms-px block border-s-2 py-1 pe-1 text-[0.8125rem] leading-snug transition-colors duration-150",
-                variant === "rail" && "[overflow-wrap:anywhere]",
-                item.level === 2 ? "ps-6" : "ps-3",
-                current
-                  ? "border-brand font-medium text-brand"
-                  : "border-transparent text-muted hover:border-strong hover:text-primary",
-              )}
-            >
-              {item.label}
-            </a>
-          </li>
-        );
-      })}
-    </ul>
-  );
-
-  if (variant === "disclosure") {
-    return (
-      <details className={cn("group rounded-md border border-subtle bg-surface", className)}>
-        <summary className="flex cursor-pointer list-none items-center justify-between px-3 py-2 text-sm font-medium 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-subtle px-2 py-2">
-          {list}
-        </nav>
-      </details>
-    );
-  }
-
-  return (
-    <nav {...rest} aria-label={l.title} className={className}>
-      <p className="mb-2 text-caption font-semibold uppercase tracking-wide text-muted">{l.title}</p>
-      {list}
-    </nav>
-  );
-}
-
-export interface PageContentsLayoutProps extends ComponentPropsWithRef<"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>
-  );
-}

package/src/components/page-header-context.ts

@@ -1,8 +0,0 @@
-import { createContext } from "react";
-
-/**
- * Set by `PageHeader` around its `breadcrumbs` (0.49 KIT-9), so a `Breadcrumbs` there
- * knows the page's title is already on screen: it hides its current entry by default
- * (`hideCurrent`) and draws nothing when only the home entry would remain. Internal.
- */
-export const PageHeaderTrailContext = createContext<{ titled: boolean } | null>(null);