@eifi1/ui-kit 0.4.0 → 0.5.0

package/src/components/password-strength.tsx

@@ -0,0 +1,258 @@
+import { useEffect, useRef } from "react";
+import type { ComponentPropsWithoutRef } from "react";
+import { cn } from "../lib/cn";
+import { useAnnounce } from "../hooks/use-announce";
+import { useKitLabels } from "../i18n/kit-labels";
+
+/**
+ * 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.
+ */
+
+/* ── The scorer ──────────────────────────────────────────────────────────── */
+
+/** 0 = too short (or empty), 4 = strong. */
+export type PasswordStrengthScore = 0 | 1 | 2 | 3 | 4;
+
+export type PasswordRuleId = "length" | "case" | "digit" | "symbol";
+
+export interface PasswordRule {
+  id: PasswordRuleId;
+  met: boolean;
+  /** Only `length` is required; the rest are suggestions. */
+  required: boolean;
+}
+
+export 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;
+}
+
+const DEFAULT_MIN_LENGTH = 8;
+
+/** The checklist's rules, evaluated. Pure; the order is the order they are shown in. */
+export function passwordRules(value: string, { minLength = DEFAULT_MIN_LENGTH }: PasswordScoreOptions = {}): PasswordRule[] {
+  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 },
+  ];
+}
+
+/**
+ * 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.
+ */
+export function scorePassword(value: string, options: PasswordScoreOptions = {}): PasswordStrengthScore {
+  const minLength = options.minLength ?? DEFAULT_MIN_LENGTH;
+  const chars = [...value];
+  // Under the minimum is never anything but "too short", however varied.
+  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) as PasswordStrengthScore;
+}
+
+/** UTF-8 byte length — what a bcrypt-style ceiling counts. "ü" is two, an emoji four. */
+export function passwordByteLength(value: string): number {
+  return new TextEncoder().encode(value).length;
+}
+
+/* ── Labels ──────────────────────────────────────────────────────────────── */
+
+/** Every string the meter renders or speaks. */
+export 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;
+}
+
+export const DEFAULT_PASSWORD_STRENGTH_LABELS: PasswordStrengthLabels = {
+  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"] as const;
+
+/* ── The meter ───────────────────────────────────────────────────────────── */
+
+// The filled segments' colour per score. "Good" sits between the warning and the
+// success hue rather than borrowing either, so 3 and 4 differ in colour as well as in
+// segment count. Index 0 is never drawn — a too-short secret fills no segment.
+const FILL: Record<PasswordStrengthScore, string> = {
+  0: "",
+  1: "bg-[var(--danger)]",
+  2: "bg-[var(--warning)]",
+  3: "bg-[color-mix(in_oklab,var(--success)_60%,var(--warning))]",
+  4: "bg-[var(--success)]",
+};
+
+export 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.
+ */
+export function PasswordStrengthMeter({
+  value,
+  score: scoreProp,
+  minLength = DEFAULT_MIN_LENGTH,
+  showRequirements = true,
+  maxBytes,
+  labels: labelsProp,
+  className,
+  ...rest
+}: PasswordStrengthMeterProps) {
+  // Prop > <UiKitProvider> > English, like every labelled component in the kit.
+  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]];
+
+  // Speak on a CHANGE of level only — not on every keystroke, and not on mount (a
+  // prefilled field has not changed anything). Clearing the field says nothing: the
+  // user did that on purpose and the meter disappearing is the whole news.
+  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: Record<PasswordRuleId, string> = {
+    length: labels.ruleLength(minLength),
+    case: labels.ruleCase,
+    digit: labels.ruleDigit,
+    symbol: labels.ruleSymbol,
+  };
+  const tooLong = maxBytes !== undefined && passwordByteLength(value) > maxBytes;
+
+  return (
+    <div {...rest} className={cn("mt-1.5 space-y-1", className)}>
+      {/* Rendered from the start and never unmounted — see useAnnounce. */}
+      <div {...regionProps} />
+      {!empty && (
+        <>
+          <div className="flex items-center gap-2">
+            <div className="flex flex-1 gap-1" aria-hidden="true" data-score={score}>
+              {[1, 2, 3, 4].map((step) => (
+                <div
+                  key={step}
+                  className={cn(
+                    "h-1 flex-1 rounded-full",
+                    step <= score ? FILL[score] : "bg-[var(--border)]",
+                  )}
+                />
+              ))}
+            </div>
+            <p className="min-w-[4.5rem] text-end text-xs text-[var(--text-secondary)]">{level}</p>
+          </div>
+          {showRequirements && (
+            <ul className="flex flex-wrap gap-x-3 gap-y-0.5 text-xs">
+              {rules.map((r) => (
+                <li
+                  key={r.id}
+                  // `relative`: the sr-only state needs a local containing block.
+                  className={cn(
+                    "relative",
+                    r.met ? "text-[var(--success)]" : "text-[var(--text-muted)]",
+                  )}
+                  data-met={r.met}
+                >
+                  <span className="sr-only">{r.met ? labels.met : labels.notMet} </span>
+                  <span aria-hidden="true">{r.met ? "✓" : "○"}</span>{" "}
+                  {r.required ? ruleText[r.id] : labels.optional(ruleText[r.id])}
+                </li>
+              ))}
+            </ul>
+          )}
+          {tooLong && <p className="text-xs text-[var(--danger)]">{labels.tooLong(maxBytes)}</p>}
+        </>
+      )}
+    </div>
+  );
+}

package/src/components/picker-sheet.tsx

@@ -0,0 +1,251 @@
+import { useRef } from "react";
+import { createPortal } from "react-dom";
+import { X } from "lucide-react";
+import type { ComponentPropsWithoutRef, KeyboardEvent, ReactNode, RefObject } from "react";
+import { cn } from "../lib/cn";
+import { DropdownSearchHeader } from "./dropdown";
+import { useBodyScrollLock } from "../hooks/use-body-scroll-lock";
+import { useOverlayHistory } from "../hooks/use-overlay-history";
+import { useFocusTrap } from "../hooks/use-focus-trap";
+import { useVisualViewport } from "../hooks/use-anchored-panel";
+import { DEFAULT_PICKER_SHEET_LABELS, useKitLabels } from "../i18n/kit-labels";
+
+/**
+ * Two of the div's own attributes are omitted because this component already owns
+ * the name: `title` here is the sheet's HEADING (and a ReactNode), not the browser's
+ * tooltip string, and `onClose` is "the sheet was dismissed", not the DOM's
+ * `<dialog>` close event. Everything else a caller can pass reaches the sheet.
+ */
+export interface PickerSheetProps
+  extends Omit<ComponentPropsWithoutRef<"div">, "title" | "onClose"> {
+  open: boolean;
+  onClose: () => void;
+  /** The field's own label — a sheet that fills the screen has to say what it is
+   *  asking for, which the anchored panel got for free by sitting under it. */
+  title?: ReactNode;
+  query: string;
+  onQueryChange: (value: string) => void;
+  searchPlaceholder?: string;
+  inputRef?: RefObject<HTMLInputElement | null>;
+  /** Default: `pickerSheet.close` from the {@link UiKitProvider}, else "Close". */
+  closeLabel?: string;
+  children: ReactNode;
+}
+
+/**
+ * The PHONE presentation of a picker: a full-screen dialog with a search box at
+ * the top and the list filling everything below it (Keksdose live #200).
+ *
+ * *"Paid as full screen dialog with input. Similar to the account select that
+ * already appears as full screen."* The account field is a native `<select>`, and
+ * a phone browser renders that as a full-screen list — so the app's own pickers,
+ * which are anchored dropdown panels, were the odd ones out: a 320px-tall panel
+ * squeezed between the field and the keyboard, showing three or four rows of a
+ * list that might have two hundred entries.
+ *
+ * What this fixes beyond size: the panel had to be *placed* (above/below, tracking
+ * the visual viewport as the keyboard opened — see `useAnchoredPanel`), and every
+ * one of those decisions is a chance to be wrong on a screen this small. A sheet
+ * has no placement. It also gives the search input somewhere unambiguous to live,
+ * which is the other half of the request: *"add filler possibility to the account
+ * select or even better right to the hoc the account select is derived from"* —
+ * so this lives in the shared picker, not in one form's copy of it.
+ *
+ * Rows are `min-h-11` (44px): the touch target the rest of the app uses. The list
+ * scrolls, the header does not, and the body behind it is scroll-locked so a drag
+ * that overshoots the list does not move the page underneath.
+ */
+export function PickerSheet({
+  open,
+  onClose,
+  title,
+  query,
+  onQueryChange,
+  searchPlaceholder,
+  inputRef,
+  closeLabel,
+  children,
+  "aria-label": ariaLabel,
+  className,
+  style,
+  ...rest
+}: PickerSheetProps) {
+  // Every picker in the kit opens one of these on a phone, and most of them pass
+  // their own `closeLabel` through as `undefined` — so this lookup is what makes the
+  // one way out of a full-screen sheet speak the app's language without each of
+  // them having to (see the prop's note in `EntityCombobox`).
+  const labels = useKitLabels("pickerSheet", DEFAULT_PICKER_SHEET_LABELS, { close: closeLabel });
+  useBodyScrollLock(open);
+  /**
+   * Back closes THE SHEET, not the dialog it was opened from (Keksdose live #309:
+   * *"Mouse Back does not only close the select but also the whole edit or create
+   * dialog which is cumbersome."*).
+   *
+   * The sheet is a full-screen overlay over whatever opened it, and on a phone that
+   * is almost always the row editor — which DOES push a history entry
+   * (`data-table.tsx`). So the sheet was invisible to Back: one press popped the
+   * editor's entry and took the whole dialog with it, discarding an edit in progress
+   * in order to dismiss a list.
+   *
+   * `useOverlayHistory` was built for exactly this nesting — its stack unwinds
+   * last-in-first-out, and the U-12 regression test in its own suite is written
+   * around "a Modal and a PickerSheet inside it". The sheet simply never called it.
+   *
+   * Nothing else has to change: the hook is a no-op while `open` is false, and it
+   * pops its own entry when the sheet closes some other way (the X, a row, the
+   * backdrop) so history does not accumulate husks.
+   */
+  useOverlayHistory(open, onClose);
+  // The visible region, while the sheet is up — see the `style` below for why a
+  // full-screen sheet cannot simply be `inset-0` on a phone (live #328).
+  const vv = useVisualViewport(open);
+  // A fallback ref so a caller that does not need the handle still gets the opening
+  // focus, rather than the behaviour depending on whether a prop was passed. What that
+  // focus is FOR is on the trap below.
+  const ownRef = useRef<HTMLInputElement | null>(null);
+  const searchRef = inputRef ?? ownRef;
+
+  const sheetRef = useRef<HTMLDivElement>(null);
+  /**
+   * The sheet said `aria-modal="true"` and then left focus on the field behind it, so
+   * a screen reader was told to hide the page the user's cursor was still standing in
+   * (the audit's *"Only Modal manages focus"*). Through the shared hook rather than
+   * the bare `.focus()` that used to live here: the hook re-reads the tabbable list on
+   * every Tab, which this panel needs more than most — its list is filtered as you
+   * type, so the rows a trap captured at open time are gone by the second keystroke.
+   *
+   * **`initialFocus` is the search box**, not the container, and this is the one place
+   * in the package that overrides `Modal`'s rule. The sheet exists in order to be typed
+   * into (live #212: *"make the text input filter active on select click"*), and the
+   * callers cannot do it themselves — `Combobox`'s field runs
+   * `setOpen(true); sheetInputRef.current?.focus()` in a single `onFocus`, so the focus
+   * call happens while this sheet is still unmounted and the ref is null. Only the
+   * sheet knows when its own input exists. Popping the keyboard is the POINT here,
+   * where in a form dialog it is the cost.
+   *
+   * **`restoreFocus` is off**, which is the uncomfortable half. Every caller in this
+   * kit opens the sheet from the field's own `onFocus` handler, so handing focus back
+   * to that field on close re-opens the sheet the user has just dismissed — a row tap
+   * would select a value and immediately put the list back over it. The field that
+   * opened it is the only thing that knows whether re-focusing it means "open"; a sheet
+   * that cannot tell must not guess. The cost is that focus lands on `<body>` after a
+   * dismissal, which on the phone this shape is for costs nothing, and on a pointer
+   * device is what happened before this change too.
+   */
+  useFocusTrap(sheetRef, {
+    active: open,
+    restoreFocus: false,
+    initialFocus: () => searchRef.current,
+  });
+
+  const handleKeyDown = (e: KeyboardEvent<HTMLDivElement>) => {
+    if (e.key !== "Escape") return;
+    // The sheet is almost always the INNERMOST overlay — it opens from a field inside a
+    // `Modal` or a `FullBleedDialog`, both of which take Escape on their own panel. A
+    // React portal's events still travel up the React tree, so without stopping it here
+    // one press would dismiss this list and the dialog underneath with it: Keksdose
+    // live #309 (*"Mouse Back does not only close the select but also the whole edit or
+    // create dialog which is cumbersome"*), which the Back gesture already learned, on
+    // the key a desktop user reaches for instead.
+    e.stopPropagation();
+    onClose();
+  };
+
+  if (!open || typeof document === "undefined") return null;
+  return createPortal(
+    <div
+      // Spread FIRST, and every attribute below it deliberately wins: `style`,
+      // `onMouseDown` and `onKeyDown` here are not styling choices, they are live
+      // #328, dev#477 and live #309 respectively, and a caller who passed one by
+      // accident would re-open a bug three apps have already paid for. `style` is
+      // MERGED rather than won outright (see below), which is the one case where a
+      // caller has something to add.
+      {...rest}
+      ref={sheetRef}
+      role="dialog"
+      aria-modal="true"
+      // Without it the container cannot take focus, and `useFocusTrap` has nothing to
+      // fall back to when the list is empty and the search box is the only thing in
+      // here — see the hook's "nothing tabbable" branch.
+      tabIndex={-1}
+      onKeyDown={handleKeyDown}
+      // The caller's own name wins over the heading: a sheet titled "Account" in a
+      // form with two of them needs to say WHICH, and `title` is what the user reads
+      // rather than what a reader announces.
+      aria-label={ariaLabel ?? (typeof title === "string" ? title : undefined)}
+      // The sheet is PORTALLED to <body>, so it is not inside the field's own
+      // wrapper — and `useDropdown` closes on any document mousedown landing
+      // outside that wrapper. Tapping a row therefore unmounted the row (open →
+      // false) before its CLICK could fire, so the tap selected nothing at all and
+      // the sheet just vanished (Keksdose dev#477).
+      //
+      // It bit whichever sheet commits on `onClick` — the payee field's, since live
+      // #200, where it hid behind the free-text value the search box was already
+      // setting; and the account field's the moment dev#477 moved it onto the inline
+      // picker. `ComboboxPanel`'s rows happen to commit on `onMouseDown`, so they
+      // beat the document listener and were never affected — which is luck, not a
+      // design, and exactly why the fix belongs to the sheet.
+      //
+      // Stopping the mousedown here rather than teaching every caller about the
+      // portal: the sheet is modal and full-screen, so "a click in here is not an
+      // outside click" is a property of the sheet, not of whoever opened it.
+      onMouseDown={(e) => e.stopPropagation()}
+      // ⚠️ `inset-0` was the whole of Keksdose live #328: *"When the keyboard overlays
+      // the entries I cannot scroll past them … to see also the last entries. Happens
+      // when browsing the account select."*
+      //
+      // This sheet FOCUSES ITS OWN SEARCH BOX on open (see above), so the keyboard is
+      // up every single time it is used on a phone. On Android that shrinks the visual
+      // viewport and leaves the LAYOUT viewport alone — `inset-0` is the layout
+      // viewport — so the sheet kept its full height with its bottom third behind the
+      // keyboard. The list below is `flex-1 overflow-y-auto`, so it sized itself to
+      // that hidden height too: it scrolled to ITS end while the last rows were still
+      // under the keys, and no gesture could bring them out. Nothing was clipped and
+      // nothing looked broken, which is why it reads as "I cannot scroll past them".
+      //
+      // `visualViewport` is the API that answers rather than hints (the live #292
+      // lesson): it reports the region actually on screen, keyboard and pinch-pan
+      // included, and it fires on the keyboard opening and closing. Pinned to that box,
+      // the sheet ends where the keys begin and the list's own scroll covers the rest.
+      // `useVisualViewport` returns null when there is nothing to correct, and then
+      // this is character-for-character the sheet that was here before.
+      // A caller's `style` is kept and the correction laid OVER it: the three values
+      // below are the whole of live #328, so they are not negotiable, but a z-index
+      // or a transition from outside has nothing to do with them. Without a visual
+      // viewport to correct for this is character-for-character what the caller passed.
+      style={vv ? { ...style, top: vv.top, height: vv.height, bottom: "auto" } : style}
+      className={cn("fixed inset-0 z-50 flex flex-col bg-[var(--bg-surface)] outline-none", className)}
+    >
+      <div className="flex items-center gap-2 border-b border-[var(--border)] px-3 py-2">
+        <span className="min-w-0 flex-1 truncate text-sm font-semibold text-[var(--text-primary)]">
+          {title}
+        </span>
+        <button
+          type="button"
+          aria-label={labels.close}
+          onClick={onClose}
+          className="rounded p-1.5 text-[var(--text-muted)] hover:bg-[var(--bg-hover)]"
+        >
+          <X className="size-5" />
+        </button>
+      </div>
+      <DropdownSearchHeader
+        query={query}
+        onQueryChange={onQueryChange}
+        inputRef={searchRef}
+        placeholder={searchPlaceholder}
+      />
+      {/* min-h-0 so the LIST scrolls rather than the dialog growing past the
+          viewport — a flex child defaults to min-height:auto. */}
+      <div className="min-h-0 flex-1 overflow-y-auto overscroll-contain">{children}</div>
+    </div>,
+    document.body,
+  );
+}
+
+/** A row inside a {@link PickerSheet} — the phone-sized version of a dropdown row,
+ *  so a list is comfortable to hit with a thumb rather than merely legible. */
+export const SHEET_ROW_CLASS = cn(
+  "flex min-h-11 w-full items-center gap-2 px-4 py-2 text-left text-base",
+  "text-[var(--text-primary)] hover:bg-[var(--bg-hover)]",
+);