@eifi1/ui-kit 0.5.1 → 0.6.1

package/src/components/danger-confirm.tsx

@@ -0,0 +1,286 @@
+import { useEffect, useId, useRef, useState } from "react";
+import type { ComponentPropsWithoutRef, FormEvent, ReactNode } from "react";
+import { cn } from "../lib/cn";
+import { useKitLabels } from "../i18n/kit-labels";
+import { Button, Input, Spinner } from "./ui";
+
+/**
+ * Every string the tile renders — the `dangerConfirm` namespace of
+ * `<UiKitProvider labels>`, overridable per instance through `labels`. The arm and
+ * confirm buttons are usually worded per action ("Delete budget"), which is what the
+ * `armLabel` / `confirmLabel` props are for; these are the fallbacks.
+ */
+export interface DangerConfirmLabels {
+  /** The button that arms the tile. */
+  arm: string;
+  /** The button that runs the action once the guards are satisfied. */
+  confirm: string;
+  cancel: string;
+  /** The warning above the fields, when no `prompt` is given. */
+  prompt: string;
+  /** Label of the password field (`requirePassword`). */
+  password: string;
+  /** Label of the type-to-confirm field, given the phrase to type. A FUNCTION, like
+   *  every message that carries a value: where the phrase sits in the sentence moves
+   *  with the language. */
+  phrase: (phrase: string) => string;
+}
+
+export const DEFAULT_DANGER_CONFIRM_LABELS: DangerConfirmLabels = {
+  arm: "Delete…",
+  confirm: "Delete",
+  cancel: "Cancel",
+  prompt: "This cannot be undone.",
+  password: "Password",
+  phrase: (phrase) => `Type “${phrase}” to confirm`,
+};
+
+export interface DangerConfirmProps extends Omit<ComponentPropsWithoutRef<"div">, "onChange"> {
+  /**
+   * Runs the action, with the entered password when `requirePassword` is on.
+   *
+   * Return a promise and the tile manages itself: busy until it settles, disarmed
+   * (fields wiped) when it resolves, still armed when it rejects — so the user can
+   * correct a wrong password and retry. The rejection is not swallowed for you to
+   * miss: handle it (and show why) in the caller, as with any mutation.
+   */
+  onConfirm: (password?: string) => void | Promise<unknown>;
+  /** Show a password field; confirm stays disabled until it is filled. */
+  requirePassword?: boolean;
+  /** Show a "type <phrase> to confirm" field; confirm stays disabled until the field
+   *  matches exactly (case-sensitive, surrounding spaces ignored). */
+  phrase?: string;
+  /** The warning above the fields. Defaults to `labels.prompt`. */
+  prompt?: ReactNode;
+  /** `"danger"` (default) for what cannot be undone; `"warning"` for what can, at a
+   *  cost (loading demo data over your own). Colours the prompt and the confirm. */
+  tone?: "danger" | "warning";
+  /** Visible text of the arm button; defaults to `labels.arm`. */
+  armLabel?: ReactNode;
+  /** Visible text of the confirm button; defaults to `labels.confirm`. */
+  confirmLabel?: ReactNode;
+  /** The action is running: confirm shows a spinner and nothing can be pressed. For a
+   *  caller that tracks the mutation itself (a `useMutation`'s `isPending`); a
+   *  promise returned from `onConfirm` does the same on its own. */
+  busy?: boolean;
+  /** The arm button is disabled. */
+  disabled?: boolean;
+  /**
+   * Why the action is not available — a read-only demo, a write lock, a missing
+   * permission. Disables the arm button like `disabled`, and SAYS so: the sentence is
+   * shown under the button and attached to it with `aria-describedby`, and the button
+   * stays focusable (`aria-disabled`) so a keyboard user can land on it and hear why.
+   *
+   * On the ARM button rather than the confirm: arming asks for a password, and asking
+   * for a password for a write that can never land is the worse of the two.
+   */
+  lockedReason?: ReactNode;
+  /** Controlled armed state. The parent can then collapse the tile from a mutation's
+   *  own `onSuccess` without returning a promise. */
+  armed?: boolean;
+  /** Called with the next armed state — on arm, cancel, and a resolved `onConfirm`. */
+  onArmedChange?: (armed: boolean) => void;
+  /** User-facing strings; see {@link DangerConfirmLabels}. */
+  labels?: Partial<DangerConfirmLabels>;
+}
+
+/**
+ * An "arm → confirm" tile for destructive actions: one button, which expands into a
+ * warning, an optional password field, an optional type-to-confirm field and a
+ * confirm that stays disabled until every guard is satisfied.
+ *
+ * Keksdose hand-rolled it three times (load demo data, wipe everything, reset a
+ * budget) and then as `shared/components/danger-confirm.tsx`; the only app-specific
+ * part was its write-lock hook, which is `lockedReason` here.
+ *
+ * The fields are a `<form>`, so Enter confirms once the guards allow it. They are
+ * wiped every time the tile disarms — a password must not sit in a collapsed tile.
+ * Arming moves focus to the first field (or Cancel, when there is none — never to the
+ * destructive button itself), and disarming moves it back to the arm button, so the
+ * keyboard user is never left on an element that just vanished.
+ */
+export function DangerConfirm({
+  onConfirm,
+  requirePassword,
+  phrase,
+  prompt,
+  tone = "danger",
+  armLabel,
+  confirmLabel,
+  busy: busyProp,
+  disabled,
+  lockedReason,
+  armed: armedProp,
+  onArmedChange,
+  labels: labelsProp,
+  className,
+  ...rest
+}: DangerConfirmProps) {
+  const labels = useKitLabels("dangerConfirm", DEFAULT_DANGER_CONFIRM_LABELS, labelsProp);
+  const [armedState, setArmedState] = useState(false);
+  const armed = armedProp ?? armedState;
+  const [password, setPassword] = useState("");
+  const [typed, setTyped] = useState("");
+  const [pending, setPending] = useState(false);
+  const busy = Boolean(busyProp) || pending;
+  // `readOnly` rather than `disabled` on the fields while busy: disabling the field
+  // that has focus (Enter was pressed in it) drops focus to <body>.
+  const promptId = useId();
+  const reasonId = useId();
+
+  // The kit's Button takes no ref, so the two buttons focus is moved to are found by id.
+  const armId = useId();
+  const cancelId = useId();
+  const firstFieldRef = useRef<HTMLInputElement>(null);
+  // Focus moves only after a transition — never on mount, so a tile that renders armed
+  // (controlled) does not take the page's focus merely by existing.
+  const moveFocus = useRef(false);
+  const mounted = useRef(true);
+  useEffect(() => {
+    mounted.current = true;
+    return () => {
+      mounted.current = false;
+    };
+  }, []);
+
+  // A disarm from anywhere (cancel, a resolved confirm, the parent) wipes the fields.
+  // During render, like NumberField's draft, so no frame shows a collapsed tile that
+  // still holds a password.
+  const [wasArmed, setWasArmed] = useState(armed);
+  if (wasArmed !== armed) {
+    setWasArmed(armed);
+    if (!armed) {
+      setPassword("");
+      setTyped("");
+    }
+  }
+
+  const prevArmed = useRef(armed);
+  useEffect(() => {
+    const changed = prevArmed.current !== armed;
+    prevArmed.current = armed;
+    const byUser = moveFocus.current;
+    moveFocus.current = false;
+    if (!changed) return;
+    if (armed) {
+      if (byUser) (firstFieldRef.current ?? document.getElementById(cancelId))?.focus();
+      return;
+    }
+    // A controlled parent collapsing the tile from its own `onSuccess` did not go
+    // through `setArmed`; if focus went down with the form, bring it back too.
+    const lost = document.activeElement === null || document.activeElement === document.body;
+    if (byUser || lost) document.getElementById(armId)?.focus();
+  }, [armed, armId, cancelId]);
+
+  const setArmed = (next: boolean) => {
+    moveFocus.current = true;
+    if (armedProp === undefined) setArmedState(next);
+    onArmedChange?.(next);
+  };
+
+  const locked = lockedReason !== undefined && lockedReason !== null && lockedReason !== false && lockedReason !== "";
+  const passwordOk = !requirePassword || password !== "";
+  const phraseOk = phrase === undefined || typed.trim() === phrase;
+  const canConfirm = passwordOk && phraseOk && !busy;
+
+  const submit = (e: FormEvent) => {
+    e.preventDefault();
+    if (!canConfirm) return;
+    const result = onConfirm(requirePassword ? password : undefined);
+    if (!result || typeof (result as Promise<unknown>).then !== "function") return;
+    setPending(true);
+    (result as Promise<unknown>).then(
+      () => {
+        if (!mounted.current) return;
+        setPending(false);
+        setArmed(false);
+      },
+      () => {
+        // Stays armed, fields kept: the caller shows why, the user retries.
+        if (mounted.current) setPending(false);
+      },
+    );
+  };
+
+  const toneText = tone === "warning" ? "text-[var(--warning)]" : "text-[var(--danger)]";
+
+  if (!armed) {
+    return (
+      <div {...rest} className={cn("space-y-1", className)}>
+        <Button
+          id={armId}
+          type="button"
+          variant={tone === "warning" ? "secondary" : "danger"}
+          disabled={disabled}
+          aria-disabled={locked || undefined}
+          aria-describedby={locked ? reasonId : undefined}
+          onClick={() => {
+            if (!locked) setArmed(true);
+          }}
+          className="aria-disabled:cursor-not-allowed aria-disabled:opacity-50"
+        >
+          {armLabel ?? labels.arm}
+        </Button>
+        {locked && (
+          <p id={reasonId} className="text-xs text-[var(--text-muted)]">
+            {lockedReason}
+          </p>
+        )}
+      </div>
+    );
+  }
+
+  return (
+    <div {...rest} className={cn("space-y-2", className)}>
+      <form
+        className="space-y-2"
+        aria-describedby={promptId}
+        aria-busy={busy || undefined}
+        onSubmit={submit}
+        noValidate
+      >
+        <p id={promptId} className={cn("text-xs font-medium", toneText)}>
+          {prompt ?? labels.prompt}
+        </p>
+        {phrase !== undefined && (
+          <Input
+            ref={firstFieldRef}
+            label={labels.phrase(phrase)}
+            value={typed}
+            autoComplete="off"
+            autoCapitalize="off"
+            spellCheck={false}
+            readOnly={busy}
+            onChange={(e) => setTyped(e.target.value)}
+          />
+        )}
+        {requirePassword && (
+          <Input
+            // The phrase field takes the ref when both are there — it comes first.
+            ref={phrase === undefined ? firstFieldRef : undefined}
+            type="password"
+            autoComplete="current-password"
+            label={labels.password}
+            value={password}
+            readOnly={busy}
+            onChange={(e) => setPassword(e.target.value)}
+          />
+        )}
+        <div className="flex flex-wrap gap-2">
+          <Button id={cancelId} type="button" variant="ghost" disabled={busy} onClick={() => setArmed(false)}>
+            {labels.cancel}
+          </Button>
+          <Button
+            type="submit"
+            variant={tone === "warning" ? "primary" : "danger"}
+            disabled={!canConfirm}
+            aria-busy={busy || undefined}
+          >
+            {busy && <Spinner label={null} className="h-4 w-4" />}
+            {confirmLabel ?? labels.confirm}
+          </Button>
+        </div>
+      </form>
+    </div>
+  );
+}

package/src/components/dialog-frame.tsx

@@ -0,0 +1,179 @@
+import { useContext, useId } from "react";
+import type { ReactNode } from "react";
+import { X } from "lucide-react";
+
+import { cn } from "../lib/cn";
+import { Modal, ModalCloseContext } from "./modal";
+import type { ModalProps } from "./modal";
+import { useKitLabels } from "../i18n/kit-labels";
+
+export interface DialogFrameLabels {
+  /** Accessible name of the header's X, when {@link DialogFrameProps.closeButton} shows it. */
+  close: string;
+}
+
+export const DEFAULT_DIALOG_FRAME_LABELS: DialogFrameLabels = { close: "Close" };
+
+/**
+ * `ModalProps` minus the three this component owns: the NAME (`labelledBy` — the
+ * heading's id is generated inside and never reaches the caller), the content
+ * (`children` is the body here, not the whole panel) and `title`, which is the dialog's
+ * HEADING and a ReactNode rather than the browser's tooltip string — the collision
+ * `PickerSheet` met first. Everything else, `size`, `draggable`, `fullBleed`,
+ * `onKeyDown`, a `data-tour` anchor, still reaches the `Modal`.
+ */
+export interface DialogFrameProps extends Omit<ModalProps, "labelledBy" | "children" | "title"> {
+  /** The heading, and therefore the dialog's accessible name (`aria-labelledby`). */
+  title: ReactNode;
+  /** The smaller line under the heading; wired to `aria-describedby`. */
+  description?: ReactNode;
+  /**
+   * The heading's level. `h2` by default, which is what every dialog in both apps
+   * writes; a prop for a page that nests its demos under a real heading.
+   */
+  headingAs?: "h1" | "h2" | "h3" | "h4";
+  /**
+   * The row under the body — buttons, in the caller's own order and variants (the two
+   * apps disagree about the cancel button's variant, so the frame has no opinion on
+   * it). Stays put while the body scrolls.
+   *
+   * A FUNCTION receives the panel's animated close: `(close) => <Button
+   * onClick={close}>Cancel</Button>` lowers the panel the way Escape does, where
+   * calling `onClose` directly unmounts it at once.
+   */
+  actions?: ReactNode | ((close: () => void) => ReactNode);
+  /**
+   * Show an X in the header. Off by default: a centred dialog has a backdrop and
+   * Escape, and a form dialog has a Cancel. On for a dialog that commits as it goes
+   * and has no actions row, where the X is the only visible way out.
+   */
+  closeButton?: boolean;
+  /** Default: `dialogFrame.close` from the {@link UiKitProvider}, else "Close". */
+  closeLabel?: string;
+  /** Extra classes for the scrolling body (default spacing `space-y-3`). */
+  bodyClassName?: string;
+  /** The body. */
+  children: ReactNode;
+}
+
+/**
+ * A {@link Modal} with the frame every caller was writing by hand: a heading, an
+ * optional description, an optional X, a body that scrolls, and an actions row that
+ * does not.
+ *
+ * 34 dialogs across the two apps framed themselves — a heading with an id invented per
+ * file (and spelt three ways), four visible type sizes for one thing, ten spellings of
+ * one right-aligned button row — and the package's own feedback dialog shipped with no
+ * accessible name at all. This makes the name unforgettable: the heading's id comes
+ * from `useId()` and goes straight to `Modal`'s `labelledBy`, so a framed dialog cannot
+ * announce as just "dialog", and two open instances cannot share an id.
+ *
+ * ## It wraps, it does not change `Modal`
+ *
+ * `Modal` keeps `labelledBy` and every existing caller compiles untouched. What the
+ * frame changes is inside the panel: the panel becomes a flex column with no padding
+ * of its own, and only the BODY scrolls. The panel's `max-h-full` is still the outer
+ * bound, so a tall form keeps its heading and its Save button on screen instead of
+ * scrolling them away with the fields. A caller's own `className` still wins (it is
+ * tailwind-merged last), which is how a full-screen phone sheet is spelt:
+ * `fullBleed className="h-[100dvh] max-w-full rounded-none md:h-auto md:rounded-lg"`.
+ *
+ * ## What it is not
+ *
+ * Not `FullBleedDialog`: that is the phone's full-screen editor with its own `open`,
+ * Back handling and a required X, and it already draws a frame of its own. And not a
+ * form: submit handling, a pending label and close-on-success stay the caller's.
+ * Focus lands on the panel, as `Modal` decides — not on the first field, so opening
+ * does not pop a phone's keyboard; an `autoFocus` in the body overrides that from the
+ * caller's side, and should be a decision rather than a habit.
+ */
+export function DialogFrame({
+  title,
+  description,
+  headingAs: Heading = "h2",
+  actions,
+  closeButton = false,
+  closeLabel,
+  bodyClassName,
+  className,
+  children,
+  "aria-describedby": describedBy,
+  ...modal
+}: DialogFrameProps) {
+  const titleId = useId();
+  const descriptionId = useId();
+  const hasDescription = description !== undefined && description !== null;
+
+  return (
+    <Modal
+      {...modal}
+      labelledBy={titleId}
+      // The caller's own description (a warning inside the body, say) is ADDED to the
+      // frame's, not traded for it: both are the dialog's.
+      aria-describedby={[hasDescription ? descriptionId : undefined, describedBy].filter(Boolean).join(" ") || undefined}
+      // `overflow-hidden` replaces the panel's own `overflow-y-auto` (tailwind-merge
+      // treats them as one group), `p-0` its `p-4`: the scroller and the padding move
+      // to the body, which is the only part that should move.
+      className={cn("flex flex-col overflow-hidden p-0", className)}
+    >
+      <div className="flex shrink-0 items-start justify-between gap-2 px-4 pt-4 pb-3">
+        <div className="min-w-0">
+          <Heading id={titleId} className="text-lg font-semibold leading-snug text-[var(--text-primary)]">
+            {title}
+          </Heading>
+          {hasDescription && (
+            <p id={descriptionId} className="mt-0.5 text-sm text-[var(--text-muted)]">
+              {description}
+            </p>
+          )}
+        </div>
+        {closeButton && <FrameClose label={closeLabel} onClose={modal.onClose} />}
+      </div>
+      <div
+        className={cn(
+          // `min-h-0` is what lets a flex child shrink below its content and scroll;
+          // `last:pb-4` closes a frame that has no actions row under it.
+          "min-h-0 flex-1 space-y-3 overflow-y-auto overscroll-contain px-4 pb-3 last:pb-4",
+          bodyClassName,
+        )}
+      >
+        {children}
+      </div>
+      {actions !== undefined && actions !== null && <FrameActions actions={actions} onClose={modal.onClose} />}
+    </Modal>
+  );
+}
+
+/** The X. A component of its own so it can read the panel's animated close, which
+ *  only exists INSIDE the `Modal` (the frame's own body runs outside it). */
+function FrameClose({ label, onClose }: { label?: string; onClose: () => void }) {
+  const close = useContext(ModalCloseContext) ?? onClose;
+  const labels = useKitLabels("dialogFrame", DEFAULT_DIALOG_FRAME_LABELS, label === undefined ? undefined : { close: label });
+  return (
+    <button
+      type="button"
+      onClick={close}
+      aria-label={labels.close}
+      className="-me-1.5 -mt-1 shrink-0 rounded p-1.5 text-[var(--text-muted)] outline-none hover:bg-[var(--bg-hover)] hover:text-[var(--text-secondary)] focus-visible:ring-2 focus-visible:ring-[var(--brand)]"
+    >
+      <X aria-hidden className="size-5" />
+    </button>
+  );
+}
+
+function FrameActions({
+  actions,
+  onClose,
+}: {
+  actions: NonNullable<DialogFrameProps["actions"]>;
+  onClose: () => void;
+}) {
+  const close = useContext(ModalCloseContext) ?? onClose;
+  return (
+    // The border marks where the scrolling stops; `flex-wrap` keeps three long
+    // translated labels on a phone from pushing the row wider than the sheet.
+    <div className="flex shrink-0 flex-wrap items-center justify-end gap-2 border-t border-[var(--border)] px-4 py-3">
+      {typeof actions === "function" ? actions(close) : actions}
+    </div>
+  );
+}