@dowel-ui/react 0.4.0 → 0.5.0

package/src/components/secret-field/secret-field.tsx

@@ -0,0 +1,284 @@
+"use client";
+
+import {
+  useEffect,
+  useId,
+  useRef,
+  useState,
+  type ComponentPropsWithRef,
+  type ReactNode,
+} from "react";
+
+import { Button } from "@/components/button";
+import { Input } from "@/components/input";
+import { cn } from "@/lib/utils";
+
+/**
+ * An API key, token or signing secret, in the three states it actually has.
+ *
+ * Stripe, GitHub, OpenAI, Vercel and every developer product with a settings
+ * page draw this by hand, and the states are the same everywhere: shown once
+ * at creation and never again; hidden but revealable, for a secret the server
+ * can show again; and gone, where only a prefix and the last four remain and
+ * the only thing left to do is regenerate. No component library ships it —
+ * the nearest thing is a password input, which is a control for entering a
+ * secret you know, not for handling one you have just been given.
+ *
+ * "Shown once" is a first-class state rather than a toast, because it is the
+ * one that costs people money: the key is on screen, the tab closes, and the
+ * next hour is spent regenerating it and updating every client. So the field
+ * says it in a sentence beside the value, and the way out is a button that
+ * says what it means — "I have saved it" — rather than the value quietly
+ * vanishing on navigation.
+ *
+ * While hidden, the secret is not in the DOM. The preview is what is
+ * rendered, so a screenshot, an extension or a devtools pane sees the prefix
+ * and the last four, which is what the server itself keeps. Reveals are
+ * reported, since an audit log of who looked is the reason the hidden state
+ * exists. Copy works while hidden, because the point of the key is to be
+ * pasted, not read.
+ */
+
+export type SecretFieldState = "shown" | "hidden" | "revealed" | "gone";
+
+export interface SecretFieldProps extends Omit<ComponentPropsWithRef<"div">, "children"> {
+  label: string;
+  /** The secret. Omit once it can no longer be shown. */
+  value?: string;
+  /** What stands in for it while hidden or gone. Derived from the value when there is one. */
+  preview?: string;
+  /** This is the only time the value can be seen. */
+  once?: boolean;
+  /** The reader has saved a shown-once value. Drop `value` in response. */
+  onAcknowledge?: () => void;
+  /** Called each time the value is shown or hidden, so reveals can be logged. */
+  onRevealChange?: (revealed: boolean) => void;
+  /** Offers to regenerate. Confirmed inline first, because it revokes the current one. */
+  onRegenerate?: () => void;
+  /** Said before regenerating. */
+  regenerateWarning?: string;
+  /** Metadata — when it was created, when it was last used. */
+  children?: ReactNode;
+}
+
+/**
+ * A prefix and the last four, the way a server keeps a key it has hashed.
+ * The prefix is kept through the last underscore in the first twelve
+ * characters — `sk_live_`, `ghp_`, `whsec_` — so the reader can tell which
+ * key this is without being shown any of it.
+ */
+export function maskSecret(value: string, keepEnd = 4): string {
+  const underscore = value.slice(0, 12).lastIndexOf("_");
+  let prefix = underscore > 0 ? value.slice(0, underscore + 1) : value.slice(0, 4);
+  // Never show enough of a short secret to reconstruct it.
+  if (prefix.length + keepEnd + 4 > value.length) prefix = "";
+  if (value.length < keepEnd + 4) return "••••••••";
+  return `${prefix}…${value.slice(-keepEnd)}`;
+}
+
+export function SecretField({
+  className,
+  label,
+  value,
+  preview,
+  once = false,
+  onAcknowledge,
+  onRevealChange,
+  onRegenerate,
+  regenerateWarning = "Regenerating revokes this one immediately. Anything still using it stops working.",
+  children,
+  ...props
+}: SecretFieldProps) {
+  const id = useId();
+  const [revealed, setRevealed] = useState(false);
+  const [confirming, setConfirming] = useState(false);
+  const [copy, setCopy] = useState<"idle" | "copied" | "error">("idle");
+  const timer = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  useEffect(
+    () => () => {
+      if (timer.current) clearTimeout(timer.current);
+    },
+    [],
+  );
+
+  const state: SecretFieldState =
+    value === undefined ? "gone" : once ? "shown" : revealed ? "revealed" : "hidden";
+  const visible = state === "shown" || state === "revealed";
+  const masked = preview ?? (value !== undefined ? maskSecret(value) : "••••••••");
+
+  const copyValue = () => {
+    if (value === undefined) return;
+    const settle = (next: "copied" | "error") => {
+      setCopy(next);
+      if (timer.current) clearTimeout(timer.current);
+      timer.current = setTimeout(() => {
+        setCopy("idle");
+      }, 2000);
+    };
+    // Wrapped so a missing clipboard API throws into the same failure path
+    // as a refused one, rather than throwing out of the click handler.
+    Promise.resolve()
+      .then(() => navigator.clipboard.writeText(value))
+      .then(
+        () => {
+          settle("copied");
+        },
+        () => {
+          settle("error");
+        },
+      );
+  };
+
+  const setReveal = (next: boolean) => {
+    setRevealed(next);
+    onRevealChange?.(next);
+  };
+
+  const note =
+    state === "shown"
+      ? "Shown once. Copy it now — it cannot be shown again."
+      : state === "gone"
+        ? "Cannot be shown again."
+        : state === "hidden"
+          ? "Hidden. Copy works without revealing it."
+          : "Revealed.";
+
+  return (
+    <div
+      data-slot="secret-field"
+      data-state={state}
+      className={cn("flex flex-col gap-2", className)}
+      {...props}
+    >
+      <label htmlFor={`${id}-value`} className="text-xs font-medium">
+        {label}
+      </label>
+
+      <div className="flex flex-wrap items-center gap-2">
+        {/* Read-only rather than disabled, so it can be focused, selected and
+            read. While hidden the DOM holds the preview, not the secret. */}
+        <Input
+          id={`${id}-value`}
+          readOnly
+          inputSize="sm"
+          value={visible ? value : masked}
+          spellCheck={false}
+          autoComplete="off"
+          aria-describedby={`${id}-note`}
+          // Claims a readable width first; the buttons wrap under it when the
+          // row is short, rather than the key being squeezed to a fragment.
+          className="min-w-0 flex-1 basis-64 font-mono"
+          onFocus={(event) => {
+            if (visible) event.currentTarget.select();
+          }}
+        />
+
+        {value !== undefined && !once ? (
+          <Button
+            variant="outline"
+            size="sm"
+            aria-pressed={revealed}
+            aria-label={`${revealed ? "Hide" : "Reveal"} — ${label}`}
+            onClick={() => {
+              setReveal(!revealed);
+            }}
+          >
+            {revealed ? "Hide" : "Reveal"}
+          </Button>
+        ) : null}
+
+        {value !== undefined ? (
+          <Button
+            variant="outline"
+            size="sm"
+            data-state={copy}
+            aria-label={`Copy — ${label}`}
+            onClick={copyValue}
+          >
+            {copy === "copied" ? "Copied" : "Copy"}
+          </Button>
+        ) : null}
+
+        {state === "shown" && onAcknowledge ? (
+          <Button variant="primary" size="sm" onClick={onAcknowledge}>
+            I have saved it
+          </Button>
+        ) : null}
+
+        {onRegenerate && !confirming ? (
+          <Button
+            variant="outline"
+            size="sm"
+            aria-label={`Regenerate — ${label}`}
+            onClick={() => {
+              setConfirming(true);
+            }}
+          >
+            Regenerate…
+          </Button>
+        ) : null}
+      </div>
+
+      <p
+        id={`${id}-note`}
+        data-slot="secret-field-note"
+        className={cn("text-xs", state === "shown" ? "text-warning" : "text-muted-foreground")}
+      >
+        {note}
+      </p>
+
+      {/* Present from the start, so the first copy is heard. Failure is said
+          too: the clipboard can be refused, and a button that only ever says
+          "Copied" would be lying the one time it matters. */}
+      <span role="status" aria-live="polite" className="sr-only">
+        {copy === "copied"
+          ? "Copied to the clipboard"
+          : copy === "error"
+            ? "Could not copy. Select the value and copy it by hand."
+            : ""}
+      </span>
+      {copy === "error" ? (
+        <p data-slot="secret-field-copy-error" className="text-xs text-destructive">
+          Could not copy. Select the value and copy it by hand.
+        </p>
+      ) : null}
+
+      {children}
+
+      {confirming ? (
+        <div
+          data-slot="secret-field-confirm"
+          role="group"
+          aria-labelledby={`${id}-confirm`}
+          className="flex flex-col gap-2 rounded-md border border-destructive/40 bg-destructive/5 p-3"
+        >
+          <p id={`${id}-confirm`} className="text-xs text-destructive">
+            {regenerateWarning}
+          </p>
+          <div className="flex flex-wrap gap-2">
+            <Button
+              variant="destructive"
+              size="sm"
+              onClick={() => {
+                setConfirming(false);
+                onRegenerate?.();
+              }}
+            >
+              Regenerate
+            </Button>
+            <Button
+              variant="outline"
+              size="sm"
+              onClick={() => {
+                setConfirming(false);
+              }}
+            >
+              Cancel
+            </Button>
+          </div>
+        </div>
+      ) : null}
+    </div>
+  );
+}

package/src/components/session-expiry/index.ts

@@ -0,0 +1,9 @@
+export {
+  SessionExpiry,
+  describeCountdown,
+  formatCountdown,
+  secondsLeft,
+  sessionPhase,
+  type SessionExpiryProps,
+  type SessionPhase,
+} from "./session-expiry";

package/src/components/session-expiry/meta.ts

@@ -0,0 +1,23 @@
+import { defineMeta } from "@/registry/schema";
+
+export const meta = defineMeta({
+  name: "session-expiry",
+  title: "Session Expiry",
+  description:
+    "The idle-timeout warning WCAG 2.2.1 asks for: warned, extendable, and not dismissable by accident.",
+  category: "feedback",
+  status: "stable",
+  dependencies: [],
+  registryDependencies: ["button", "dialog"],
+  files: ["session-expiry.tsx"],
+  a11y:
+    "An alert dialog, named by its heading and described by the sentence that says how long is " +
+    "left. Escape and the backdrop do nothing, because dismissing a session warning without " +
+    "choosing is choosing nothing; the two buttons are the way out, and focus opens on the safe " +
+    "one. The visible countdown is not live — a number every second for two minutes drowns the " +
+    "question — and a separate status region speaks four times: when the warning opens, at one " +
+    "minute, thirty seconds and ten, still saying a threshold a slow tick skipped over. The " +
+    "clock is read in an effect, so the server renders nothing rather than a countdown from the " +
+    "wrong instant. This satisfies the warn-and-extend half of WCAG 2.2.1 Timing Adjustable; the " +
+    "twenty-second minimum is the default window's business and the application's.",
+});

package/src/components/session-expiry/session-expiry.tsx

@@ -0,0 +1,321 @@
+"use client";
+
+import {
+  memo,
+  useEffect,
+  useId,
+  useRef,
+  useState,
+  useSyncExternalStore,
+  type ReactNode,
+} from "react";
+
+import { Button } from "@/components/button";
+import {
+  Dialog,
+  DialogContent,
+  DialogDescription,
+  DialogFooter,
+  DialogHeader,
+  DialogTitle,
+} from "@/components/dialog";
+import { cn } from "@/lib/utils";
+
+/**
+ * "Your session ends in two minutes. Stay signed in?"
+ *
+ * Every product with an idle timeout builds this, and WCAG 2.2.1 (Timing
+ * Adjustable) says what it has to do: warn before the time runs out, and
+ * give at least twenty seconds to extend it with a simple action. Most
+ * implementations get the first half — a toast, a modal — and fail the
+ * second in one of two ways: the warning can be dismissed without choosing,
+ * so a reader who closed it to see the page underneath is signed out with
+ * no further word; or the countdown is a live region, so a screen reader
+ * user hears a number every second for two minutes and cannot hear the
+ * choice they are being asked to make.
+ *
+ * So this is an alert dialog that cannot be waved away. Escape and the
+ * backdrop do nothing, because dismissing a session warning without
+ * choosing is choosing nothing, and the two buttons are the two things a
+ * person can actually do. The countdown ticks on screen and is announced at
+ * four moments — when the warning opens, at one minute, thirty seconds and
+ * ten — which is enough to know how long is left and quiet enough to hear
+ * the question.
+ *
+ * When time runs out, `onExpire` fires once and the dialog says so, with a
+ * slot for whatever the application offers next. It does not sign anyone
+ * out; the server did that, and this is the part that tells the person.
+ */
+
+export type SessionPhase = "active" | "warning" | "expired";
+
+/** Where a session stands, given the clock. Pure, for tests and for the server. */
+export function sessionPhase(expiresAt: Date, now: Date, warnBefore: number): SessionPhase {
+  const remaining = expiresAt.getTime() - now.getTime();
+  if (remaining <= 0) return "expired";
+  if (remaining <= warnBefore) return "warning";
+  return "active";
+}
+
+/** Whole seconds left, never negative. */
+export function secondsLeft(expiresAt: Date, now: Date): number {
+  return Math.max(0, Math.ceil((expiresAt.getTime() - now.getTime()) / 1000));
+}
+
+/** "1:59" for the screen. */
+export function formatCountdown(seconds: number): string {
+  const minutes = Math.floor(seconds / 60);
+  const rest = seconds % 60;
+  return `${String(minutes)}:${String(rest).padStart(2, "0")}`;
+}
+
+/** "1 minute 59 seconds" for the ear. */
+export function describeCountdown(seconds: number): string {
+  const minutes = Math.floor(seconds / 60);
+  const rest = seconds % 60;
+  const parts: string[] = [];
+  if (minutes > 0) parts.push(`${String(minutes)} ${minutes === 1 ? "minute" : "minutes"}`);
+  if (rest > 0 || minutes === 0)
+    parts.push(`${String(rest)} ${rest === 1 ? "second" : "seconds"}`);
+  return parts.join(" ");
+}
+
+/** The seconds-left values at which the countdown is said aloud. */
+const ANNOUNCE_AT = [60, 30, 10];
+
+function subscribeToClock(callback: () => void) {
+  const timer = setInterval(callback, 1000);
+  return () => {
+    clearInterval(timer);
+  };
+}
+/** Whole seconds, so the snapshot is stable within a second and React does not re-render for nothing. */
+const readClockSeconds = () => Math.floor(Date.now() / 1000);
+const readNoClock = () => null;
+
+export interface SessionExpiryProps {
+  /** When the session ends. Move it forward after a successful extend. */
+  expiresAt: Date;
+  /** How long before the end to warn, in milliseconds. Two minutes by default. */
+  warnBefore?: number;
+  /**
+   * The clock. Supply it to drive the countdown yourself, or in tests; omit
+   * and the component ticks once a second while mounted.
+   */
+  now?: Date;
+  /** Keep the session going. May return a promise; the button waits for it. */
+  onExtend: () => void | Promise<void>;
+  /** Called once when the time runs out. */
+  onExpire?: () => void;
+  /** Offered as the other choice. Omit to offer only staying signed in. */
+  onSignOut?: () => void;
+  /** The warning's heading. */
+  heading?: string;
+  /** What is at stake, in the reader's language: "Unsaved edits will be lost." */
+  children?: ReactNode;
+  /** What to offer once the session has ended: a sign-in link, usually. */
+  expiredAction?: ReactNode;
+  className?: string;
+}
+
+export function SessionExpiry({
+  expiresAt,
+  warnBefore = 120_000,
+  now: nowProp,
+  onExtend,
+  onExpire,
+  onSignOut,
+  heading = "Your session is about to end",
+  children,
+  expiredAction,
+  className,
+}: SessionExpiryProps) {
+  const id = useId();
+
+  // The clock as an external store that ticks once a second. The server
+  // snapshot is null, so the server and the first client render agree on
+  // showing nothing; the real instant arrives in the re-render after.
+  const tickSeconds = useSyncExternalStore(subscribeToClock, readClockSeconds, readNoClock);
+  const tick = tickSeconds === null ? null : new Date(tickSeconds * 1000);
+
+  const now = nowProp ?? tick;
+  const phase = now ? sessionPhase(expiresAt, now, warnBefore) : "active";
+  const seconds = now ? secondsLeft(expiresAt, now) : 0;
+
+  const [announcement, setAnnouncement] = useState("");
+
+  // Announced at the moments that matter, not every second. Tracked as the
+  // last threshold spoken so a tick that skips a value still says it once.
+  const [spoken, setSpoken] = useState<number | null>(null);
+  const [endedFor, setEndedFor] = useState<number | null>(null);
+
+  if (phase === "warning") {
+    if (spoken === null) {
+      setSpoken(Number.POSITIVE_INFINITY);
+      setAnnouncement(`${heading}. ${describeCountdown(seconds)} left.`);
+    } else {
+      const due = ANNOUNCE_AT.find((at) => seconds <= at && at < spoken);
+      if (due !== undefined) {
+        setSpoken(due);
+        setAnnouncement(`${describeCountdown(seconds)} left.`);
+      }
+    }
+  } else if (spoken !== null && phase === "active") {
+    // Extended. The next warning starts its announcements afresh.
+    setSpoken(null);
+    setAnnouncement("");
+  } else if (phase === "expired" && endedFor !== expiresAt.getTime()) {
+    setEndedFor(expiresAt.getTime());
+    setAnnouncement("Your session has ended.");
+  }
+
+  // The one side effect: telling the application, once per expiry. A ref
+  // rather than state, because nothing rendered depends on it.
+  const firedFor = useRef<number | null>(null);
+  useEffect(() => {
+    if (phase !== "expired" || firedFor.current === expiresAt.getTime()) return;
+    firedFor.current = expiresAt.getTime();
+    onExpire?.();
+  }, [phase, expiresAt, onExpire]);
+
+  const open = phase !== "active";
+
+  // Once told to close, the dialog is left alone: the countdown it shows is
+  // frozen and its props stop changing, so the clock's ticks no longer
+  // re-render a surface that is mid-exit. A dialog re-rendered every second
+  // while closing never finishes closing.
+  const [shown, setShown] = useState(seconds);
+  if (open && shown !== seconds) setShown(seconds);
+
+  return (
+    <ExpiryDialog
+      id={id}
+      open={open}
+      phase={phase}
+      seconds={shown}
+      heading={heading}
+      announcement={announcement}
+      onExtend={onExtend}
+      onSignOut={onSignOut}
+      expiredAction={expiredAction}
+      className={className}
+    >
+      {children}
+    </ExpiryDialog>
+  );
+}
+
+interface ExpiryDialogProps {
+  id: string;
+  open: boolean;
+  phase: SessionPhase;
+  seconds: number;
+  heading: string;
+  announcement: string;
+  onExtend: () => void | Promise<void>;
+  onSignOut?: () => void;
+  expiredAction?: ReactNode;
+  className?: string;
+  children?: ReactNode;
+}
+
+const ExpiryDialog = memo(function ExpiryDialog({
+  id,
+  open,
+  phase,
+  seconds,
+  heading,
+  announcement,
+  onExtend,
+  onSignOut,
+  expiredAction,
+  className,
+  children,
+}: ExpiryDialogProps) {
+  const stayRef = useRef<HTMLButtonElement>(null);
+  const [extending, setExtending] = useState(false);
+
+  const extend = () => {
+    const result = onExtend();
+    if (result instanceof Promise) {
+      setExtending(true);
+      void result.finally(() => {
+        setExtending(false);
+      });
+    }
+  };
+
+  return (
+    <Dialog open={open}>
+      <DialogContent
+        role="alertdialog"
+        showCloseButton={false}
+        aria-describedby={`${id}-description`}
+        data-slot="session-expiry"
+        data-phase={phase}
+        className={cn("max-w-sm", className)}
+        // Dismissing a session warning without choosing is choosing nothing,
+        // so the gestures that dismiss a dialog do nothing here. The buttons
+        // are the way out, and there are two of them.
+        onEscapeKeyDown={(event) => {
+          event.preventDefault();
+        }}
+        onPointerDownOutside={(event) => {
+          event.preventDefault();
+        }}
+        onInteractOutside={(event) => {
+          event.preventDefault();
+        }}
+        // Focus lands on the safe choice. The first tabbable would be "Sign
+        // out now", and a reflexive Enter on that is the outcome the whole
+        // dialog exists to prevent.
+        onOpenAutoFocus={(event) => {
+          event.preventDefault();
+          stayRef.current?.focus();
+        }}
+      >
+        <DialogHeader>
+          <DialogTitle>{phase === "expired" ? "Your session has ended" : heading}</DialogTitle>
+          <DialogDescription id={`${id}-description`}>
+            {phase === "expired" ? (
+              "You were signed out after a period of inactivity."
+            ) : (
+              <>
+                You will be signed out in{" "}
+                <span data-slot="session-expiry-countdown" className="font-medium tabular-nums">
+                  <span aria-hidden="true">{formatCountdown(seconds)}</span>
+                  <span className="sr-only">{describeCountdown(seconds)}</span>
+                </span>
+                .
+              </>
+            )}
+          </DialogDescription>
+        </DialogHeader>
+
+        {children ? <div className="text-sm text-muted-foreground">{children}</div> : null}
+
+        {/* The countdown above is not live. This is, and it speaks four times. */}
+        <span role="status" aria-live="polite" className="sr-only">
+          {announcement}
+        </span>
+
+        <DialogFooter>
+          {phase === "expired" ? (
+            expiredAction
+          ) : (
+            <>
+              {onSignOut ? (
+                <Button variant="outline" onClick={onSignOut}>
+                  Sign out now
+                </Button>
+              ) : null}
+              <Button ref={stayRef} loading={extending} onClick={extend}>
+                Stay signed in
+              </Button>
+            </>
+          )}
+        </DialogFooter>
+      </DialogContent>
+    </Dialog>
+  );
+});

package/src/components/shortcut-recorder/index.ts

@@ -0,0 +1,19 @@
+export {
+  ShortcutRecorder,
+  type ShortcutRecorderProps,
+  type TakenShortcut,
+} from "./shortcut-recorder";
+export {
+  RESERVED_KEYS,
+  describeShortcut,
+  detectPlatform,
+  formatShortcut,
+  needsModifier,
+  parseShortcut,
+  serializeShortcut,
+  shortcutFromKey,
+  shortcutParts,
+  shortcutsEqual,
+  type Platform,
+  type Shortcut,
+} from "./shortcut-model";

package/src/components/shortcut-recorder/meta.ts

@@ -0,0 +1,22 @@
+import { defineMeta } from "@/registry/schema";
+
+export const meta = defineMeta({
+  name: "shortcut-recorder",
+  title: "Shortcut Recorder",
+  description:
+    "Press the keys you want: records a chord, platform-aware, and says when it clashes.",
+  category: "form",
+  status: "stable",
+  dependencies: [],
+  registryDependencies: [],
+  files: ["shortcut-model.ts", "shortcut-recorder.tsx"],
+  a11y:
+    "The recorder is a button named by what the shortcut does and described by its value in " +
+    "words — Command Shift K — while the key caps on it are hidden from assistive technology, " +
+    "since ⌘⇧K read aloud is noise. While recording it is aria-pressed and its description " +
+    "says what to do; Tab always leaves and Escape always cancels, so it is never a keyboard " +
+    "trap. Every outcome is announced through a status region present from the start: recorded, " +
+    "refused with the reason, clashing with which command, cancelled, cleared. Symbols are shown " +
+    "on a Mac and words elsewhere, and the description uses the platform's own names for its " +
+    "keys.",
+});