@eifi1/ui-kit 0.4.1 → 0.5.0

package/dist/components/numpad-sheet.js.map

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

package/dist/components/page-contents.d.ts

@@ -0,0 +1,90 @@
+import * as react from 'react';
+import { ComponentPropsWithoutRef, ReactNode } from 'react';
+
+/**
+ * "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.
+ */
+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;
+}
+interface PageContentsLabels {
+    /** The heading above the list, and the landmark's accessible name. */
+    title: string;
+}
+declare const DEFAULT_PAGE_CONTENTS_LABELS: PageContentsLabels;
+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.
+ */
+declare function useScrollSpy(ids: readonly string[], options?: UseScrollSpyOptions): string | null;
+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.
+ */
+declare function PageContents({ items, activeId, hrefFor, variant, labels, className, ...rest }: PageContentsProps): react.JSX.Element | null;
+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>`.
+ */
+declare function PageContentsLayout({ contents, position, children, className, ...rest }: PageContentsLayoutProps): react.JSX.Element;
+
+export { DEFAULT_PAGE_CONTENTS_LABELS, PageContents, type PageContentsItem, type PageContentsLabels, PageContentsLayout, type PageContentsLayoutProps, type PageContentsProps, type UseScrollSpyOptions, useScrollSpy };

package/dist/components/page-contents.js

@@ -0,0 +1,170 @@
+"use client";
+import { jsx, jsxs } from "react/jsx-runtime";
+import { useEffect, useRef, useState } from "react";
+import { ChevronDown } from "lucide-react";
+import { cn } from "../lib/cn.js";
+import { useKitLabels } from "../i18n/kit-labels.js";
+const DEFAULT_PAGE_CONTENTS_LABELS = {
+  title: "On this page"
+};
+function useScrollSpy(ids, options = {}) {
+  const { root = null, line = 0.15 } = options;
+  const [current, setCurrent] = useState(null);
+  const key = ids.join("\0");
+  useEffect(() => {
+    if (ids.length === 0) return;
+    const scroller = 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;
+      }
+      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, root, line]);
+  return current;
+}
+function PageContents({
+  items,
+  activeId,
+  hrefFor = (id) => `#${id}`,
+  variant = "rail",
+  labels,
+  className,
+  ...rest
+}) {
+  const l = useKitLabels("pageContents", DEFAULT_PAGE_CONTENTS_LABELS, labels);
+  const listRef = useRef(null);
+  const [clicked, setClicked] = useState(null);
+  useEffect(() => {
+    if (!clicked) return;
+    const release = () => setClicked(null);
+    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;
+  useEffect(() => {
+    if (!shown || variant !== "rail") return;
+    listRef.current?.querySelector(`[data-entry="${CSS.escape(shown)}"]`)?.scrollIntoView?.({ block: "nearest" });
+  }, [shown, variant]);
+  if (items.length === 0) return null;
+  const list = /* @__PURE__ */ jsx(
+    "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]"
+      ),
+      children: items.map((item) => {
+        const current = item.id === shown;
+        return /* @__PURE__ */ jsx("li", { "data-entry": item.id, children: /* @__PURE__ */ jsx(
+          "a",
+          {
+            href: hrefFor(item.id),
+            title: variant === "rail" && typeof item.label === "string" ? item.label : void 0,
+            "aria-current": current ? "location" : void 0,
+            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)]"
+            ),
+            children: item.label
+          }
+        ) }, item.id);
+      })
+    }
+  );
+  if (variant === "disclosure") {
+    return /* @__PURE__ */ jsxs(
+      "details",
+      {
+        className: cn(
+          "group rounded-md border border-[var(--border)] bg-[var(--bg-surface)]",
+          className
+        ),
+        children: [
+          /* @__PURE__ */ jsxs("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", children: [
+            l.title,
+            /* @__PURE__ */ jsx(
+              ChevronDown,
+              {
+                "aria-hidden": true,
+                className: "size-4 transition-transform duration-200 group-open:rotate-180 motion-reduce:transition-none"
+              }
+            )
+          ] }),
+          /* @__PURE__ */ jsx("nav", { ...rest, "aria-label": l.title, className: "border-t border-[var(--border)] px-2 py-2", children: list })
+        ]
+      }
+    );
+  }
+  return /* @__PURE__ */ jsxs("nav", { ...rest, "aria-label": l.title, className, children: [
+    /* @__PURE__ */ jsx("p", { className: "mb-2 text-[11px] font-semibold uppercase tracking-wide text-[var(--text-muted)]", children: l.title }),
+    list
+  ] });
+}
+function PageContentsLayout({
+  contents,
+  position = "start",
+  children,
+  className,
+  ...rest
+}) {
+  const rail = /* @__PURE__ */ jsx("aside", { className: "hidden xl:block", children: /* @__PURE__ */ jsx("div", { className: "sticky top-6", children: contents }) });
+  return /* @__PURE__ */ jsxs(
+    "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
+      ),
+      children: [
+        position === "start" && rail,
+        /* @__PURE__ */ jsx("div", { className: "min-w-0", children }),
+        position === "end" && rail
+      ]
+    }
+  );
+}
+export {
+  DEFAULT_PAGE_CONTENTS_LABELS,
+  PageContents,
+  PageContentsLayout,
+  useScrollSpy
+};
+//# sourceMappingURL=page-contents.js.map

package/dist/components/page-contents.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/components/page-contents.tsx"],"sourcesContent":["import { useEffect, useRef, useState } from \"react\";\nimport type { ComponentPropsWithoutRef, ReactNode } from \"react\";\nimport { ChevronDown } from \"lucide-react\";\nimport { cn } from \"../lib/cn\";\nimport { useKitLabels } from \"../i18n/kit-labels\";\n\n/**\n * \"On this page\": a page's own table of contents, with the section being read marked.\n *\n * Three parts, because an app needs them separately:\n *\n *   - {@link useScrollSpy} — which section is current, from the headings' positions in\n *     a scroll container. No markup; usable for anything that follows the reader.\n *   - {@link PageContents} — the list. `variant=\"rail\"` for beside the page,\n *     `variant=\"disclosure\"` for a collapsed block under the title on narrow screens.\n *   - {@link PageContentsLayout} — the page with the rail sticky on one side of it.\n *\n * Domain-free: the app supplies the entries and how an entry links (`hrefFor`), so it\n * works with any router, including a hash router where `#id` alone would be read as a\n * route.\n */\n\nexport interface PageContentsItem {\n  /** The id of the heading the entry jumps to. */\n  id: string;\n  label: ReactNode;\n  /** 2 indents the entry under the one before it. */\n  level?: 1 | 2;\n}\n\nexport interface PageContentsLabels {\n  /** The heading above the list, and the landmark's accessible name. */\n  title: string;\n}\n\nexport const DEFAULT_PAGE_CONTENTS_LABELS: PageContentsLabels = {\n  title: \"On this page\",\n};\n\nexport interface UseScrollSpyOptions {\n  /** The element that scrolls. Defaults to the viewport. In `AppShell`, pass its\n   *  `<main>` — it is the page's scroll container from `md` up. */\n  root?: Element | null;\n  /**\n   * How far down the scroller the \"reading line\" sits, as a fraction of its height.\n   * A section becomes current once its heading passes above it, and stays current\n   * until the next heading does — so a long section keeps its entry marked while it\n   * is being read, not only while its heading is on screen. Default 0.15: close to\n   * the top, so a short section followed by another does not hand its mark to the\n   * next one the moment it is scrolled to.\n   */\n  line?: number;\n}\n\n/**\n * The id of the section being read: the last of `ids` whose element has scrolled\n * above the reading line — or the first, before any has.\n */\nexport function useScrollSpy(ids: readonly string[], options: UseScrollSpyOptions = {}): string | null {\n  const { root = null, line = 0.15 } = options;\n  const [current, setCurrent] = useState<string | null>(null);\n  const key = ids.join(\"\\u0000\");\n\n  useEffect(() => {\n    if (ids.length === 0) return;\n    const scroller: Element | Window = root ?? window;\n    const measure = () => {\n      const top = root ? root.getBoundingClientRect().top : 0;\n      const height = root ? root.clientHeight : window.innerHeight;\n      const reading = top + height * line;\n      let next = ids[0];\n      for (const id of ids) {\n        const el = document.getElementById(id);\n        if (el && el.getBoundingClientRect().top <= reading) next = id;\n      }\n      // At the very bottom the last sections may never reach the line; the reader\n      // who scrolled to the end is reading the end.\n      const atEnd = root\n        ? root.scrollTop + root.clientHeight >= root.scrollHeight - 2\n        : window.scrollY + window.innerHeight >= document.documentElement.scrollHeight - 2;\n      const scrolled = root ? root.scrollTop : window.scrollY;\n      if (atEnd && scrolled > 0) next = ids[ids.length - 1];\n      setCurrent(next);\n    };\n    let frame = 0;\n    const onScroll = () => {\n      cancelAnimationFrame(frame);\n      frame = requestAnimationFrame(measure);\n    };\n    measure();\n    scroller.addEventListener(\"scroll\", onScroll, { passive: true });\n    window.addEventListener(\"resize\", onScroll);\n    return () => {\n      cancelAnimationFrame(frame);\n      scroller.removeEventListener(\"scroll\", onScroll);\n      window.removeEventListener(\"resize\", onScroll);\n    };\n    // `key` stands for `ids`: a new array with the same entries is the same list.\n    // eslint-disable-next-line react-hooks/exhaustive-deps\n  }, [key, root, line]);\n\n  return current;\n}\n\nexport interface PageContentsProps extends Omit<ComponentPropsWithoutRef<\"nav\">, \"children\"> {\n  items: PageContentsItem[];\n  /** The current entry — typically `useScrollSpy(items.map(i => i.id), …)`. */\n  activeId?: string | null;\n  /** The link for an entry. Default `#id`; under a hash router build it with the\n   *  router (react-router's `useHref({ hash: id })` gives `#/page#id`). */\n  hrefFor?: (id: string) => string;\n  /** `rail` — a list beside the page. `disclosure` — collapsed under a summary line,\n   *  for narrow screens where a rail has no room. */\n  variant?: \"rail\" | \"disclosure\";\n  labels?: Partial<PageContentsLabels>;\n}\n\n/**\n * The list itself. The current entry gets a brand bar on the list's rule, the brand\n * colour, and `aria-current=\"location\"` — the marker documentation sites use, and the\n * one a screen reader announces.\n */\nexport function PageContents({\n  items,\n  activeId,\n  hrefFor = (id) => `#${id}`,\n  variant = \"rail\",\n  labels,\n  className,\n  ...rest\n}: PageContentsProps) {\n  const l = useKitLabels(\"pageContents\", DEFAULT_PAGE_CONTENTS_LABELS, labels);\n  const listRef = useRef<HTMLUListElement>(null);\n  // The entry just clicked is the current one until the reader scrolls on their own.\n  // Without this, jumping to a short section near the end of a page marks whichever\n  // later section the jump also carried past the reading line — you click one entry\n  // and another lights up.\n  const [clicked, setClicked] = useState<string | null>(null);\n  useEffect(() => {\n    if (!clicked) return;\n    const release = () => setClicked(null);\n    // A user scroll — wheel, touch, keys — releases it; the programmatic scroll the\n    // jump itself causes does not fire these.\n    window.addEventListener(\"wheel\", release, { passive: true, once: true });\n    window.addEventListener(\"touchmove\", release, { passive: true, once: true });\n    window.addEventListener(\"keydown\", release, { once: true });\n    return () => {\n      window.removeEventListener(\"wheel\", release);\n      window.removeEventListener(\"touchmove\", release);\n      window.removeEventListener(\"keydown\", release);\n    };\n  }, [clicked]);\n  const shown = clicked ?? activeId;\n\n  // Keep the current entry in view when the list is taller than the window.\n  useEffect(() => {\n    if (!shown || variant !== \"rail\") return;\n    listRef.current\n      ?.querySelector<HTMLElement>(`[data-entry=\"${CSS.escape(shown)}\"]`)\n      ?.scrollIntoView?.({ block: \"nearest\" });\n  }, [shown, variant]);\n\n  if (items.length === 0) return null;\n\n  const list = (\n    <ul\n      ref={listRef}\n      className={cn(\n        \"space-y-0.5 border-s border-[var(--border)]\",\n        variant === \"rail\" && \"max-h-[calc(100dvh-10rem)] overflow-y-auto [scrollbar-width:thin]\",\n      )}\n    >\n      {items.map((item) => {\n        const current = item.id === shown;\n        return (\n          <li key={item.id} data-entry={item.id}>\n            <a\n              href={hrefFor(item.id)}\n              // One line per entry in the rail; past 22rem the ellipsis takes over and\n              // the full text is on hover. The disclosure has the page's width and wraps.\n              title={variant === \"rail\" && typeof item.label === \"string\" ? item.label : undefined}\n              aria-current={current ? \"location\" : undefined}\n              onClick={() => setClicked(item.id)}\n              className={cn(\n                \"-ms-px block border-s-2 py-1 pe-1 text-[13px] leading-snug transition-colors duration-150\",\n                variant === \"rail\" && \"truncate\",\n                item.level === 2 ? \"ps-6\" : \"ps-3\",\n                current\n                  ? \"border-[var(--brand)] font-medium text-[var(--brand)]\"\n                  : \"border-transparent text-[var(--text-muted)] hover:border-[var(--border-strong)] hover:text-[var(--text-primary)]\",\n              )}\n            >\n              {item.label}\n            </a>\n          </li>\n        );\n      })}\n    </ul>\n  );\n\n  if (variant === \"disclosure\") {\n    return (\n      <details\n        className={cn(\n          \"group rounded-md border border-[var(--border)] bg-[var(--bg-surface)]\",\n          className,\n        )}\n      >\n        <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\">\n          {l.title}\n          <ChevronDown\n            aria-hidden\n            className=\"size-4 transition-transform duration-200 group-open:rotate-180 motion-reduce:transition-none\"\n          />\n        </summary>\n        <nav {...rest} aria-label={l.title} className=\"border-t border-[var(--border)] px-2 py-2\">\n          {list}\n        </nav>\n      </details>\n    );\n  }\n\n  return (\n    <nav {...rest} aria-label={l.title} className={className}>\n      <p className=\"mb-2 text-[11px] font-semibold uppercase tracking-wide text-[var(--text-muted)]\">\n        {l.title}\n      </p>\n      {list}\n    </nav>\n  );\n}\n\nexport interface PageContentsLayoutProps extends ComponentPropsWithoutRef<\"div\"> {\n  /** What goes in the rail — typically a `<PageContents variant=\"rail\">`. */\n  contents: ReactNode;\n  /**\n   * Which side of the page the rail sits on: `start` is the left in a left-to-right\n   * language (next to the app's own sidebar, so both navigations are in one place),\n   * `end` the right (the documentation-site convention, clear of the sidebar). Logical,\n   * so both flip in a right-to-left UI.\n   */\n  position?: \"start\" | \"end\";\n  children: ReactNode;\n}\n\n/**\n * The page with a sticky contents rail beside it, from `xl` (1280px) up. Below that\n * the rail would squeeze the content, so it is not rendered there — pair it with a\n * `<PageContents variant=\"disclosure\" className=\"xl:hidden\">` in the page.\n *\n * The rail is `sticky top-6`, which sticks inside the nearest scroll container — the\n * viewport, or `AppShell`'s `<main>`.\n */\nexport function PageContentsLayout({\n  contents,\n  position = \"start\",\n  children,\n  className,\n  ...rest\n}: PageContentsLayoutProps) {\n  // In DOM order on its side, not moved there with `order`: Tab and a screen reader\n  // follow the source, and a rail painted on the left but read after the page would\n  // put the page's index at its end.\n  const rail = (\n    <aside className=\"hidden xl:block\">\n      <div className=\"sticky top-6\">{contents}</div>\n    </aside>\n  );\n  return (\n    <div\n      {...rest}\n      className={cn(\n        \"xl:grid xl:gap-10\",\n        // `fit-content(22rem)`: the rail is as wide as its longest entry, up to 22rem.\n        // A fixed 13rem broke \"Select — unlabelled, labelled, invalid, disabled\" over\n        // three lines beside a page with room to spare; an index you scan should read\n        // one entry per line.\n        position === \"start\"\n          ? \"xl:grid-cols-[fit-content(22rem)_minmax(0,1fr)]\"\n          : \"xl:grid-cols-[minmax(0,1fr)_fit-content(22rem)]\",\n        className,\n      )}\n    >\n      {position === \"start\" && rail}\n      <div className=\"min-w-0\">{children}</div>\n      {position === \"end\" && rail}\n    </div>\n  );\n}\n"],"mappings":";AAgLY,cAgCJ,YAhCI;AAhLZ,SAAS,WAAW,QAAQ,gBAAgB;AAE5C,SAAS,mBAAmB;AAC5B,SAAS,UAAU;AACnB,SAAS,oBAAoB;AA+BtB,MAAM,+BAAmD;AAAA,EAC9D,OAAO;AACT;AAqBO,SAAS,aAAa,KAAwB,UAA+B,CAAC,GAAkB;AACrG,QAAM,EAAE,OAAO,MAAM,OAAO,KAAK,IAAI;AACrC,QAAM,CAAC,SAAS,UAAU,IAAI,SAAwB,IAAI;AAC1D,QAAM,MAAM,IAAI,KAAK,IAAQ;AAE7B,YAAU,MAAM;AACd,QAAI,IAAI,WAAW,EAAG;AACtB,UAAM,WAA6B,QAAQ;AAC3C,UAAM,UAAU,MAAM;AACpB,YAAM,MAAM,OAAO,KAAK,sBAAsB,EAAE,MAAM;AACtD,YAAM,SAAS,OAAO,KAAK,eAAe,OAAO;AACjD,YAAM,UAAU,MAAM,SAAS;AAC/B,UAAI,OAAO,IAAI,CAAC;AAChB,iBAAW,MAAM,KAAK;AACpB,cAAM,KAAK,SAAS,eAAe,EAAE;AACrC,YAAI,MAAM,GAAG,sBAAsB,EAAE,OAAO,QAAS,QAAO;AAAA,MAC9D;AAGA,YAAM,QAAQ,OACV,KAAK,YAAY,KAAK,gBAAgB,KAAK,eAAe,IAC1D,OAAO,UAAU,OAAO,eAAe,SAAS,gBAAgB,eAAe;AACnF,YAAM,WAAW,OAAO,KAAK,YAAY,OAAO;AAChD,UAAI,SAAS,WAAW,EAAG,QAAO,IAAI,IAAI,SAAS,CAAC;AACpD,iBAAW,IAAI;AAAA,IACjB;AACA,QAAI,QAAQ;AACZ,UAAM,WAAW,MAAM;AACrB,2BAAqB,KAAK;AAC1B,cAAQ,sBAAsB,OAAO;AAAA,IACvC;AACA,YAAQ;AACR,aAAS,iBAAiB,UAAU,UAAU,EAAE,SAAS,KAAK,CAAC;AAC/D,WAAO,iBAAiB,UAAU,QAAQ;AAC1C,WAAO,MAAM;AACX,2BAAqB,KAAK;AAC1B,eAAS,oBAAoB,UAAU,QAAQ;AAC/C,aAAO,oBAAoB,UAAU,QAAQ;AAAA,IAC/C;AAAA,EAGF,GAAG,CAAC,KAAK,MAAM,IAAI,CAAC;AAEpB,SAAO;AACT;AAoBO,SAAS,aAAa;AAAA,EAC3B;AAAA,EACA;AAAA,EACA,UAAU,CAAC,OAAO,IAAI,EAAE;AAAA,EACxB,UAAU;AAAA,EACV;AAAA,EACA;AAAA,EACA,GAAG;AACL,GAAsB;AACpB,QAAM,IAAI,aAAa,gBAAgB,8BAA8B,MAAM;AAC3E,QAAM,UAAU,OAAyB,IAAI;AAK7C,QAAM,CAAC,SAAS,UAAU,IAAI,SAAwB,IAAI;AAC1D,YAAU,MAAM;AACd,QAAI,CAAC,QAAS;AACd,UAAM,UAAU,MAAM,WAAW,IAAI;AAGrC,WAAO,iBAAiB,SAAS,SAAS,EAAE,SAAS,MAAM,MAAM,KAAK,CAAC;AACvE,WAAO,iBAAiB,aAAa,SAAS,EAAE,SAAS,MAAM,MAAM,KAAK,CAAC;AAC3E,WAAO,iBAAiB,WAAW,SAAS,EAAE,MAAM,KAAK,CAAC;AAC1D,WAAO,MAAM;AACX,aAAO,oBAAoB,SAAS,OAAO;AAC3C,aAAO,oBAAoB,aAAa,OAAO;AAC/C,aAAO,oBAAoB,WAAW,OAAO;AAAA,IAC/C;AAAA,EACF,GAAG,CAAC,OAAO,CAAC;AACZ,QAAM,QAAQ,WAAW;AAGzB,YAAU,MAAM;AACd,QAAI,CAAC,SAAS,YAAY,OAAQ;AAClC,YAAQ,SACJ,cAA2B,gBAAgB,IAAI,OAAO,KAAK,CAAC,IAAI,GAChE,iBAAiB,EAAE,OAAO,UAAU,CAAC;AAAA,EAC3C,GAAG,CAAC,OAAO,OAAO,CAAC;AAEnB,MAAI,MAAM,WAAW,EAAG,QAAO;AAE/B,QAAM,OACJ;AAAA,IAAC;AAAA;AAAA,MACC,KAAK;AAAA,MACL,WAAW;AAAA,QACT;AAAA,QACA,YAAY,UAAU;AAAA,MACxB;AAAA,MAEC,gBAAM,IAAI,CAAC,SAAS;AACnB,cAAM,UAAU,KAAK,OAAO;AAC5B,eACE,oBAAC,QAAiB,cAAY,KAAK,IACjC;AAAA,UAAC;AAAA;AAAA,YACC,MAAM,QAAQ,KAAK,EAAE;AAAA,YAGrB,OAAO,YAAY,UAAU,OAAO,KAAK,UAAU,WAAW,KAAK,QAAQ;AAAA,YAC3E,gBAAc,UAAU,aAAa;AAAA,YACrC,SAAS,MAAM,WAAW,KAAK,EAAE;AAAA,YACjC,WAAW;AAAA,cACT;AAAA,cACA,YAAY,UAAU;AAAA,cACtB,KAAK,UAAU,IAAI,SAAS;AAAA,cAC5B,UACI,0DACA;AAAA,YACN;AAAA,YAEC,eAAK;AAAA;AAAA,QACR,KAlBO,KAAK,EAmBd;AAAA,MAEJ,CAAC;AAAA;AAAA,EACH;AAGF,MAAI,YAAY,cAAc;AAC5B,WACE;AAAA,MAAC;AAAA;AAAA,QACC,WAAW;AAAA,UACT;AAAA,UACA;AAAA,QACF;AAAA,QAEA;AAAA,+BAAC,aAAQ,WAAU,4JAChB;AAAA,cAAE;AAAA,YACH;AAAA,cAAC;AAAA;AAAA,gBACC,eAAW;AAAA,gBACX,WAAU;AAAA;AAAA,YACZ;AAAA,aACF;AAAA,UACA,oBAAC,SAAK,GAAG,MAAM,cAAY,EAAE,OAAO,WAAU,6CAC3C,gBACH;AAAA;AAAA;AAAA,IACF;AAAA,EAEJ;AAEA,SACE,qBAAC,SAAK,GAAG,MAAM,cAAY,EAAE,OAAO,WAClC;AAAA,wBAAC,OAAE,WAAU,mFACV,YAAE,OACL;AAAA,IACC;AAAA,KACH;AAEJ;AAuBO,SAAS,mBAAmB;AAAA,EACjC;AAAA,EACA,WAAW;AAAA,EACX;AAAA,EACA;AAAA,EACA,GAAG;AACL,GAA4B;AAI1B,QAAM,OACJ,oBAAC,WAAM,WAAU,mBACf,8BAAC,SAAI,WAAU,gBAAgB,oBAAS,GAC1C;AAEF,SACE;AAAA,IAAC;AAAA;AAAA,MACE,GAAG;AAAA,MACJ,WAAW;AAAA,QACT;AAAA;AAAA;AAAA;AAAA;AAAA,QAKA,aAAa,UACT,oDACA;AAAA,QACJ;AAAA,MACF;AAAA,MAEC;AAAA,qBAAa,WAAW;AAAA,QACzB,oBAAC,SAAI,WAAU,WAAW,UAAS;AAAA,QAClC,aAAa,SAAS;AAAA;AAAA;AAAA,EACzB;AAEJ;","names":[]}

package/dist/components/password-strength.d.ts

@@ -0,0 +1,106 @@
+import * as react from 'react';
+import { ComponentPropsWithoutRef } from 'react';
+
+/**
+ * The bar, the word and the advisory checklist under a field where someone is
+ * CHOOSING a secret.
+ *
+ * Ported from Keksdose (`features/auth/password-strength-meter.tsx`), where one meter
+ * sits under the sign-in password and the encryption passphrase alike — a copy per
+ * form is what had let the passphrase dialogs ship with no meter at all. Three things
+ * changed on the way in:
+ *
+ *  1. **Tokens, not palette.** The four fills were red/amber/lime/emerald utilities;
+ *     they are `--danger` → `--warning` → `--success` now, so a consumer re-pointing
+ *     those families re-skins the meter with them.
+ *  2. **Not colour alone.** The level is always written out beside the bar, and each
+ *     checklist item says "met" / "not met" to a screen reader — the ✓/○ glyphs are
+ *     decoration and hidden.
+ *  3. **Announced.** A level change is spoken through a polite live region
+ *     ({@link useAnnounce}); the bar itself is `aria-hidden`, because four coloured
+ *     strips read out as four empty groups.
+ *
+ * Advisory only, as in Keksdose: nothing here blocks a submit. The caller decides what
+ * is required — {@link passwordRules} marks `length` as the one rule that usually is,
+ * so a form can gate on it with the same function the checklist draws from.
+ *
+ * Dependency-free on purpose. zxcvbn is ~400 kB of dictionaries, and neither consumer
+ * ships it; a host that does can pass its scorer as `score` and keep the rest.
+ */
+/** 0 = too short (or empty), 4 = strong. */
+type PasswordStrengthScore = 0 | 1 | 2 | 3 | 4;
+type PasswordRuleId = "length" | "case" | "digit" | "symbol";
+interface PasswordRule {
+    id: PasswordRuleId;
+    met: boolean;
+    /** Only `length` is required; the rest are suggestions. */
+    required: boolean;
+}
+interface PasswordScoreOptions {
+    /** The length below which a secret is "too short", whatever else it has. Keep it
+     *  in step with the server's own minimum. Default 8. */
+    minLength?: number;
+}
+/** The checklist's rules, evaluated. Pure; the order is the order they are shown in. */
+declare function passwordRules(value: string, { minLength }?: PasswordScoreOptions): PasswordRule[];
+/**
+ * A 0–4 strength bucket. Length dominates, because it genuinely dominates real-world
+ * guessing cost: one step each at `minLength`, `minLength + 4` and `minLength + 8`,
+ * and one more for at least two of the three variety rules.
+ *
+ * One addition over Keksdose's curve: a secret with fewer than four DISTINCT
+ * characters caps at 1. Sixteen `a`s are long, and nothing about them is strong.
+ */
+declare function scorePassword(value: string, options?: PasswordScoreOptions): PasswordStrengthScore;
+/** UTF-8 byte length — what a bcrypt-style ceiling counts. "ü" is two, an emoji four. */
+declare function passwordByteLength(value: string): number;
+/** Every string the meter renders or speaks. */
+interface PasswordStrengthLabels {
+    /** The five level names, shown beside the bar. Score 0 … 4. */
+    tooShort: string;
+    weak: string;
+    fair: string;
+    good: string;
+    strong: string;
+    /** What the live region says when the level changes, given the level's name. */
+    announcement: (level: string) => string;
+    /** The length rule, given the minimum. */
+    ruleLength: (minLength: number) => string;
+    ruleCase: string;
+    ruleDigit: string;
+    ruleSymbol: string;
+    /** A suggestion rather than a requirement, given the rule's text. */
+    optional: (rule: string) => string;
+    /** Screen-reader-only state before each checklist item — the ✓/○ are hidden. */
+    met: string;
+    notMet: string;
+    /** Shown when the value is over `maxBytes`, given that ceiling. */
+    tooLong: (maxBytes: number) => string;
+}
+declare const DEFAULT_PASSWORD_STRENGTH_LABELS: PasswordStrengthLabels;
+interface PasswordStrengthMeterProps extends ComponentPropsWithoutRef<"div"> {
+    /** The secret being chosen. Nothing visible renders while it is empty. */
+    value: string;
+    /** Replace the built-in scorer (e.g. with zxcvbn's `score`). Must be pure. */
+    score?: (value: string) => PasswordStrengthScore;
+    /** See {@link PasswordScoreOptions.minLength}. Drives the built-in scorer and the
+     *  length rule's text. */
+    minLength?: number;
+    /** Show the checklist under the bar. Default `true`. */
+    showRequirements?: boolean;
+    /**
+     * A byte ceiling to warn about, if the secret has one — bcrypt reads at most 72
+     * BYTES. Leave it unset for a secret that has none (a passphrase stretched in the
+     * browser): inventing one talks people out of the long passphrase they chose.
+     */
+    maxBytes?: number;
+    /** User-facing strings; see {@link PasswordStrengthLabels}. */
+    labels?: Partial<PasswordStrengthLabels>;
+}
+/**
+ * Render directly under the password field. To have the field itself describe its
+ * strength, give this an `id` and point the input's `aria-describedby` at it.
+ */
+declare function PasswordStrengthMeter({ value, score: scoreProp, minLength, showRequirements, maxBytes, labels: labelsProp, className, ...rest }: PasswordStrengthMeterProps): react.JSX.Element;
+
+export { DEFAULT_PASSWORD_STRENGTH_LABELS, type PasswordRule, type PasswordRuleId, type PasswordScoreOptions, type PasswordStrengthLabels, PasswordStrengthMeter, type PasswordStrengthMeterProps, type PasswordStrengthScore, passwordByteLength, passwordRules, scorePassword };

package/dist/components/password-strength.js

@@ -0,0 +1,132 @@
+"use client";
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+import { useEffect, useRef } from "react";
+import { cn } from "../lib/cn.js";
+import { useAnnounce } from "../hooks/use-announce.js";
+import { useKitLabels } from "../i18n/kit-labels.js";
+const DEFAULT_MIN_LENGTH = 8;
+function passwordRules(value, { minLength = DEFAULT_MIN_LENGTH } = {}) {
+  return [
+    // Code points, not UTF-16 units: an emoji is one character to the person typing it.
+    { id: "length", met: [...value].length >= minLength, required: true },
+    { id: "case", met: /\p{Ll}/u.test(value) && /\p{Lu}/u.test(value), required: false },
+    { id: "digit", met: /\p{Nd}/u.test(value), required: false },
+    { id: "symbol", met: /[^\p{L}\p{N}\s]/u.test(value), required: false }
+  ];
+}
+function scorePassword(value, options = {}) {
+  const minLength = options.minLength ?? DEFAULT_MIN_LENGTH;
+  const chars = [...value];
+  if (chars.length === 0 || chars.length < minLength) return 0;
+  let score = 1;
+  if (chars.length >= minLength + 4) score += 1;
+  if (chars.length >= minLength + 8) score += 1;
+  const variety = passwordRules(value, { minLength }).filter((r) => !r.required && r.met).length;
+  if (variety >= 2) score += 1;
+  if (new Set(chars).size < 4) score = 1;
+  return Math.min(score, 4);
+}
+function passwordByteLength(value) {
+  return new TextEncoder().encode(value).length;
+}
+const DEFAULT_PASSWORD_STRENGTH_LABELS = {
+  tooShort: "Too short",
+  weak: "Weak",
+  fair: "Fair",
+  good: "Good",
+  strong: "Strong",
+  announcement: (level) => `Password strength: ${level}`,
+  ruleLength: (minLength) => `At least ${minLength} characters`,
+  ruleCase: "Upper and lower case",
+  ruleDigit: "A number",
+  ruleSymbol: "A symbol",
+  optional: (rule) => `${rule} (optional)`,
+  met: "Met:",
+  notMet: "Not met:",
+  tooLong: (maxBytes) => `At most ${maxBytes} characters (accents and emoji count for more than one).`
+};
+const LEVEL_KEYS = ["tooShort", "weak", "fair", "good", "strong"];
+const FILL = {
+  0: "",
+  1: "bg-[var(--danger)]",
+  2: "bg-[var(--warning)]",
+  3: "bg-[color-mix(in_oklab,var(--success)_60%,var(--warning))]",
+  4: "bg-[var(--success)]"
+};
+function PasswordStrengthMeter({
+  value,
+  score: scoreProp,
+  minLength = DEFAULT_MIN_LENGTH,
+  showRequirements = true,
+  maxBytes,
+  labels: labelsProp,
+  className,
+  ...rest
+}) {
+  const labels = useKitLabels("passwordStrength", DEFAULT_PASSWORD_STRENGTH_LABELS, labelsProp);
+  const { announce, regionProps } = useAnnounce();
+  const empty = value.length === 0;
+  const score = empty ? 0 : scoreProp ? scoreProp(value) : scorePassword(value, { minLength });
+  const level = labels[LEVEL_KEYS[score]];
+  const previous = useRef(score);
+  useEffect(() => {
+    if (previous.current === score) return;
+    previous.current = score;
+    if (!empty) announce(labels.announcement(level));
+  }, [score, empty, level, labels, announce]);
+  const rules = passwordRules(value, { minLength });
+  const ruleText = {
+    length: labels.ruleLength(minLength),
+    case: labels.ruleCase,
+    digit: labels.ruleDigit,
+    symbol: labels.ruleSymbol
+  };
+  const tooLong = maxBytes !== void 0 && passwordByteLength(value) > maxBytes;
+  return /* @__PURE__ */ jsxs("div", { ...rest, className: cn("mt-1.5 space-y-1", className), children: [
+    /* @__PURE__ */ jsx("div", { ...regionProps }),
+    !empty && /* @__PURE__ */ jsxs(Fragment, { children: [
+      /* @__PURE__ */ jsxs("div", { className: "flex items-center gap-2", children: [
+        /* @__PURE__ */ jsx("div", { className: "flex flex-1 gap-1", "aria-hidden": "true", "data-score": score, children: [1, 2, 3, 4].map((step) => /* @__PURE__ */ jsx(
+          "div",
+          {
+            className: cn(
+              "h-1 flex-1 rounded-full",
+              step <= score ? FILL[score] : "bg-[var(--border)]"
+            )
+          },
+          step
+        )) }),
+        /* @__PURE__ */ jsx("p", { className: "min-w-[4.5rem] text-end text-xs text-[var(--text-secondary)]", children: level })
+      ] }),
+      showRequirements && /* @__PURE__ */ jsx("ul", { className: "flex flex-wrap gap-x-3 gap-y-0.5 text-xs", children: rules.map((r) => /* @__PURE__ */ jsxs(
+        "li",
+        {
+          className: cn(
+            "relative",
+            r.met ? "text-[var(--success)]" : "text-[var(--text-muted)]"
+          ),
+          "data-met": r.met,
+          children: [
+            /* @__PURE__ */ jsxs("span", { className: "sr-only", children: [
+              r.met ? labels.met : labels.notMet,
+              " "
+            ] }),
+            /* @__PURE__ */ jsx("span", { "aria-hidden": "true", children: r.met ? "\u2713" : "\u25CB" }),
+            " ",
+            r.required ? ruleText[r.id] : labels.optional(ruleText[r.id])
+          ]
+        },
+        r.id
+      )) }),
+      tooLong && /* @__PURE__ */ jsx("p", { className: "text-xs text-[var(--danger)]", children: labels.tooLong(maxBytes) })
+    ] })
+  ] });
+}
+export {
+  DEFAULT_PASSWORD_STRENGTH_LABELS,
+  PasswordStrengthMeter,
+  passwordByteLength,
+  passwordRules,
+  scorePassword
+};
+//# sourceMappingURL=password-strength.js.map

package/dist/components/password-strength.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/components/password-strength.tsx"],"sourcesContent":["import { useEffect, useRef } from \"react\";\nimport type { ComponentPropsWithoutRef } from \"react\";\nimport { cn } from \"../lib/cn\";\nimport { useAnnounce } from \"../hooks/use-announce\";\nimport { useKitLabels } from \"../i18n/kit-labels\";\n\n/**\n * The bar, the word and the advisory checklist under a field where someone is\n * CHOOSING a secret.\n *\n * Ported from Keksdose (`features/auth/password-strength-meter.tsx`), where one meter\n * sits under the sign-in password and the encryption passphrase alike — a copy per\n * form is what had let the passphrase dialogs ship with no meter at all. Three things\n * changed on the way in:\n *\n *  1. **Tokens, not palette.** The four fills were red/amber/lime/emerald utilities;\n *     they are `--danger` → `--warning` → `--success` now, so a consumer re-pointing\n *     those families re-skins the meter with them.\n *  2. **Not colour alone.** The level is always written out beside the bar, and each\n *     checklist item says \"met\" / \"not met\" to a screen reader — the ✓/○ glyphs are\n *     decoration and hidden.\n *  3. **Announced.** A level change is spoken through a polite live region\n *     ({@link useAnnounce}); the bar itself is `aria-hidden`, because four coloured\n *     strips read out as four empty groups.\n *\n * Advisory only, as in Keksdose: nothing here blocks a submit. The caller decides what\n * is required — {@link passwordRules} marks `length` as the one rule that usually is,\n * so a form can gate on it with the same function the checklist draws from.\n *\n * Dependency-free on purpose. zxcvbn is ~400 kB of dictionaries, and neither consumer\n * ships it; a host that does can pass its scorer as `score` and keep the rest.\n */\n\n/* ── The scorer ──────────────────────────────────────────────────────────── */\n\n/** 0 = too short (or empty), 4 = strong. */\nexport type PasswordStrengthScore = 0 | 1 | 2 | 3 | 4;\n\nexport type PasswordRuleId = \"length\" | \"case\" | \"digit\" | \"symbol\";\n\nexport interface PasswordRule {\n  id: PasswordRuleId;\n  met: boolean;\n  /** Only `length` is required; the rest are suggestions. */\n  required: boolean;\n}\n\nexport interface PasswordScoreOptions {\n  /** The length below which a secret is \"too short\", whatever else it has. Keep it\n   *  in step with the server's own minimum. Default 8. */\n  minLength?: number;\n}\n\nconst DEFAULT_MIN_LENGTH = 8;\n\n/** The checklist's rules, evaluated. Pure; the order is the order they are shown in. */\nexport function passwordRules(value: string, { minLength = DEFAULT_MIN_LENGTH }: PasswordScoreOptions = {}): PasswordRule[] {\n  return [\n    // Code points, not UTF-16 units: an emoji is one character to the person typing it.\n    { id: \"length\", met: [...value].length >= minLength, required: true },\n    { id: \"case\", met: /\\p{Ll}/u.test(value) && /\\p{Lu}/u.test(value), required: false },\n    { id: \"digit\", met: /\\p{Nd}/u.test(value), required: false },\n    { id: \"symbol\", met: /[^\\p{L}\\p{N}\\s]/u.test(value), required: false },\n  ];\n}\n\n/**\n * A 0–4 strength bucket. Length dominates, because it genuinely dominates real-world\n * guessing cost: one step each at `minLength`, `minLength + 4` and `minLength + 8`,\n * and one more for at least two of the three variety rules.\n *\n * One addition over Keksdose's curve: a secret with fewer than four DISTINCT\n * characters caps at 1. Sixteen `a`s are long, and nothing about them is strong.\n */\nexport function scorePassword(value: string, options: PasswordScoreOptions = {}): PasswordStrengthScore {\n  const minLength = options.minLength ?? DEFAULT_MIN_LENGTH;\n  const chars = [...value];\n  // Under the minimum is never anything but \"too short\", however varied.\n  if (chars.length === 0 || chars.length < minLength) return 0;\n  let score = 1;\n  if (chars.length >= minLength + 4) score += 1;\n  if (chars.length >= minLength + 8) score += 1;\n  const variety = passwordRules(value, { minLength }).filter((r) => !r.required && r.met).length;\n  if (variety >= 2) score += 1;\n  if (new Set(chars).size < 4) score = 1;\n  return Math.min(score, 4) as PasswordStrengthScore;\n}\n\n/** UTF-8 byte length — what a bcrypt-style ceiling counts. \"ü\" is two, an emoji four. */\nexport function passwordByteLength(value: string): number {\n  return new TextEncoder().encode(value).length;\n}\n\n/* ── Labels ──────────────────────────────────────────────────────────────── */\n\n/** Every string the meter renders or speaks. */\nexport interface PasswordStrengthLabels {\n  /** The five level names, shown beside the bar. Score 0 … 4. */\n  tooShort: string;\n  weak: string;\n  fair: string;\n  good: string;\n  strong: string;\n  /** What the live region says when the level changes, given the level's name. */\n  announcement: (level: string) => string;\n  /** The length rule, given the minimum. */\n  ruleLength: (minLength: number) => string;\n  ruleCase: string;\n  ruleDigit: string;\n  ruleSymbol: string;\n  /** A suggestion rather than a requirement, given the rule's text. */\n  optional: (rule: string) => string;\n  /** Screen-reader-only state before each checklist item — the ✓/○ are hidden. */\n  met: string;\n  notMet: string;\n  /** Shown when the value is over `maxBytes`, given that ceiling. */\n  tooLong: (maxBytes: number) => string;\n}\n\nexport const DEFAULT_PASSWORD_STRENGTH_LABELS: PasswordStrengthLabels = {\n  tooShort: \"Too short\",\n  weak: \"Weak\",\n  fair: \"Fair\",\n  good: \"Good\",\n  strong: \"Strong\",\n  announcement: (level) => `Password strength: ${level}`,\n  ruleLength: (minLength) => `At least ${minLength} characters`,\n  ruleCase: \"Upper and lower case\",\n  ruleDigit: \"A number\",\n  ruleSymbol: \"A symbol\",\n  optional: (rule) => `${rule} (optional)`,\n  met: \"Met:\",\n  notMet: \"Not met:\",\n  tooLong: (maxBytes) =>\n    `At most ${maxBytes} characters (accents and emoji count for more than one).`,\n};\n\nconst LEVEL_KEYS = [\"tooShort\", \"weak\", \"fair\", \"good\", \"strong\"] as const;\n\n/* ── The meter ───────────────────────────────────────────────────────────── */\n\n// The filled segments' colour per score. \"Good\" sits between the warning and the\n// success hue rather than borrowing either, so 3 and 4 differ in colour as well as in\n// segment count. Index 0 is never drawn — a too-short secret fills no segment.\nconst FILL: Record<PasswordStrengthScore, string> = {\n  0: \"\",\n  1: \"bg-[var(--danger)]\",\n  2: \"bg-[var(--warning)]\",\n  3: \"bg-[color-mix(in_oklab,var(--success)_60%,var(--warning))]\",\n  4: \"bg-[var(--success)]\",\n};\n\nexport interface PasswordStrengthMeterProps extends ComponentPropsWithoutRef<\"div\"> {\n  /** The secret being chosen. Nothing visible renders while it is empty. */\n  value: string;\n  /** Replace the built-in scorer (e.g. with zxcvbn's `score`). Must be pure. */\n  score?: (value: string) => PasswordStrengthScore;\n  /** See {@link PasswordScoreOptions.minLength}. Drives the built-in scorer and the\n   *  length rule's text. */\n  minLength?: number;\n  /** Show the checklist under the bar. Default `true`. */\n  showRequirements?: boolean;\n  /**\n   * A byte ceiling to warn about, if the secret has one — bcrypt reads at most 72\n   * BYTES. Leave it unset for a secret that has none (a passphrase stretched in the\n   * browser): inventing one talks people out of the long passphrase they chose.\n   */\n  maxBytes?: number;\n  /** User-facing strings; see {@link PasswordStrengthLabels}. */\n  labels?: Partial<PasswordStrengthLabels>;\n}\n\n/**\n * Render directly under the password field. To have the field itself describe its\n * strength, give this an `id` and point the input's `aria-describedby` at it.\n */\nexport function PasswordStrengthMeter({\n  value,\n  score: scoreProp,\n  minLength = DEFAULT_MIN_LENGTH,\n  showRequirements = true,\n  maxBytes,\n  labels: labelsProp,\n  className,\n  ...rest\n}: PasswordStrengthMeterProps) {\n  // Prop > <UiKitProvider> > English, like every labelled component in the kit.\n  const labels = useKitLabels(\"passwordStrength\", DEFAULT_PASSWORD_STRENGTH_LABELS, labelsProp);\n  const { announce, regionProps } = useAnnounce();\n\n  const empty = value.length === 0;\n  const score = empty ? 0 : scoreProp ? scoreProp(value) : scorePassword(value, { minLength });\n  const level = labels[LEVEL_KEYS[score]];\n\n  // Speak on a CHANGE of level only — not on every keystroke, and not on mount (a\n  // prefilled field has not changed anything). Clearing the field says nothing: the\n  // user did that on purpose and the meter disappearing is the whole news.\n  const previous = useRef(score);\n  useEffect(() => {\n    if (previous.current === score) return;\n    previous.current = score;\n    if (!empty) announce(labels.announcement(level));\n  }, [score, empty, level, labels, announce]);\n\n  const rules = passwordRules(value, { minLength });\n  const ruleText: Record<PasswordRuleId, string> = {\n    length: labels.ruleLength(minLength),\n    case: labels.ruleCase,\n    digit: labels.ruleDigit,\n    symbol: labels.ruleSymbol,\n  };\n  const tooLong = maxBytes !== undefined && passwordByteLength(value) > maxBytes;\n\n  return (\n    <div {...rest} className={cn(\"mt-1.5 space-y-1\", className)}>\n      {/* Rendered from the start and never unmounted — see useAnnounce. */}\n      <div {...regionProps} />\n      {!empty && (\n        <>\n          <div className=\"flex items-center gap-2\">\n            <div className=\"flex flex-1 gap-1\" aria-hidden=\"true\" data-score={score}>\n              {[1, 2, 3, 4].map((step) => (\n                <div\n                  key={step}\n                  className={cn(\n                    \"h-1 flex-1 rounded-full\",\n                    step <= score ? FILL[score] : \"bg-[var(--border)]\",\n                  )}\n                />\n              ))}\n            </div>\n            <p className=\"min-w-[4.5rem] text-end text-xs text-[var(--text-secondary)]\">{level}</p>\n          </div>\n          {showRequirements && (\n            <ul className=\"flex flex-wrap gap-x-3 gap-y-0.5 text-xs\">\n              {rules.map((r) => (\n                <li\n                  key={r.id}\n                  // `relative`: the sr-only state needs a local containing block.\n                  className={cn(\n                    \"relative\",\n                    r.met ? \"text-[var(--success)]\" : \"text-[var(--text-muted)]\",\n                  )}\n                  data-met={r.met}\n                >\n                  <span className=\"sr-only\">{r.met ? labels.met : labels.notMet} </span>\n                  <span aria-hidden=\"true\">{r.met ? \"✓\" : \"○\"}</span>{\" \"}\n                  {r.required ? ruleText[r.id] : labels.optional(ruleText[r.id])}\n                </li>\n              ))}\n            </ul>\n          )}\n          {tooLong && <p className=\"text-xs text-[var(--danger)]\">{labels.tooLong(maxBytes)}</p>}\n        </>\n      )}\n    </div>\n  );\n}\n"],"mappings":"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","names":[]}