@runtypelabs/persona 4.17.1 → 4.18.0

package/src/components/header-parts.ts

@@ -4,6 +4,229 @@ import { AgentWidgetConfig } from "../types";
 import { attachTooltip } from "../utils/tooltip";
 import { HEADER_THEME_CSS } from "./header-builder";
 
+/**
+ * Class hook for the shared header control box. The stylesheet sizes it from
+ * `--persona-header-control-size` (theme `components.header.controlSize`).
+ */
+export const HEADER_CONTROL_CLASS = "persona-header-control";
+/** Adds `--persona-header-control-icon-size` sizing to the control's glyph. */
+export const HEADER_CONTROL_GLYPH_CLASS = "persona-header-control--glyph";
+/** Scales the glyph up for icons whose paths under-fill the 24x24 viewBox. */
+export const HEADER_CONTROL_SPARSE_CLASS = "persona-header-control--sparse";
+/**
+ * Icon-size token default in CSS pixels. Only derives the SVG attributes when a
+ * per-control size is unset; the box itself is owned by the stylesheet.
+ */
+const ICON_FALLBACK_PX = 20;
+
+/**
+ * Icons whose Lucide paths occupy only the middle of the 24x24 viewBox (X spans
+ * 6,6 to 18,18; siblings such as refresh-cw span ~75%). Rendering them larger
+ * brings their visible extent into parity; the stroke is thinned by the same
+ * factor so the weight still matches. Keep the scale in sync with the
+ * `.persona-header-control--sparse` multiplier in widget.css.
+ */
+const SPARSE_GLYPHS: Record<string, [number, number]> = { x: [1.4, 1.05] };
+
+// Flex, not block: an inline-flex button in a block wrapper reserves baseline
+// slack and rides high inside it.
+const DEFAULT_WRAPPER_CLASS =
+  "persona-relative persona-ml-auto persona-inline-flex persona-items-center persona-justify-center";
+
+const DEFAULT_CLEAR_CHAT_WRAPPER_CLASS =
+  "persona-relative persona-ml-auto persona-clear-chat-button-wrapper";
+
+export interface HeaderControlGlyphOptions {
+  /**
+   * Explicit nominal glyph size. Unset hands the box to
+   * `--persona-header-control-icon-size` via the glyph class hook.
+   */
+  iconSize?: string;
+  /** Text glyph rendered when the icon name is not in the registry. */
+  iconText?: string;
+}
+
+/**
+ * Render (or re-render) a header control's glyph with the shared optical
+ * compensation, syncing the class hooks that let the stylesheet own the box.
+ * Both the factory and the live `update()` restyle path go through it so a
+ * config change can never repaint a control at a different size or weight.
+ */
+export const applyHeaderControlGlyph = (
+  button: HTMLButtonElement,
+  iconName: string,
+  options: HeaderControlGlyphOptions = {},
+): void => {
+  const { iconSize, iconText } = options;
+  // [glyph scale, stroke width]; dense glyphs take the standard pair.
+  const [scale, stroke] = SPARSE_GLYPHS[iconName] ?? [1, 1.5];
+  // Without an explicit size the stylesheet owns the glyph box, so the sparse
+  // multiplier has to live there too.
+  const tokenGlyph = !iconSize;
+  button.classList.toggle(HEADER_CONTROL_GLYPH_CLASS, tokenGlyph);
+  button.classList.toggle(HEADER_CONTROL_SPARSE_CLASS, tokenGlyph && scale !== 1);
+
+  // Attribute sizing only decides the glyph when the stylesheet is not driving
+  // it; with the glyph class the CSS width/height wins over these attributes.
+  const nominalPx = parseFloat(iconSize ?? "") || ICON_FALLBACK_PX;
+  const icon = renderLucideIcon(
+    iconName,
+    `${Math.round(nominalPx * scale)}px`,
+    "currentColor",
+    stroke,
+  );
+  if (icon) {
+    // Inline SVG baseline spacing pushes the glyph a fractional pixel
+    // off-center inside the button.
+    icon.style.display = "block";
+    if (!tokenGlyph) {
+      // Explicit sizing detaches the glyph classes, so the stroke token has to
+      // ride inline; the attribute stroke stays as the no-token fallback.
+      icon.style.strokeWidth = `calc(var(--persona-components-header-controlStrokeWidth, 1.5) * ${Number((stroke / 1.5).toFixed(4))})`;
+    }
+    button.replaceChildren(icon);
+  } else if (iconText) {
+    button.textContent = iconText;
+  }
+  // Unrenderable glyph with no text fallback keeps whatever was mounted; an
+  // empty button is worse than a stale one.
+};
+
+export interface HeaderIconButtonParts {
+  button: HTMLButtonElement;
+  wrapper: HTMLElement;
+}
+
+export interface CreateHeaderIconButtonOptions {
+  /** Required: also the default tooltip text. */
+  ariaLabel: string;
+  /**
+   * Attach the shared styled tooltip, reading the button's live `aria-label`
+   * so a relabel (e.g. Messages while busy) stays accurate. `false` opts out;
+   * default true.
+   */
+  tooltip?: boolean;
+  /** Muted chip after the tooltip label, e.g. a keyboard shortcut. */
+  tooltipHint?: string | (() => string);
+  /** Lucide icon name; falls back to `iconText` when it is not in the registry. */
+  iconName?: string;
+  /** Text glyph rendered when no icon resolves. */
+  iconText?: string;
+  /** Wrapper className. Always flex so the button can never ride off-center. */
+  wrapperClassName?: string;
+  /**
+   * Explicit box size. Unset leaves `--persona-header-control-size` in charge;
+   * set, it writes an inline box that overrides the token.
+   */
+  size?: string;
+  /**
+   * Explicit nominal glyph size. Unset leaves `--persona-header-control-icon-size`
+   * in charge. Sparse-viewBox compensation applies on top either way.
+   */
+  iconSize?: string;
+  /** Falls back to the header zone's action-icon color. */
+  color?: string;
+  /** Set, it replaces the transparent + hover-fill default classes. */
+  backgroundColor?: string;
+  borderWidth?: string;
+  borderColor?: string;
+  borderRadius?: string;
+  paddingX?: string;
+  paddingY?: string;
+  /** Renders `display: none` without removing the control. */
+  hidden?: boolean;
+  /** Appended to the button's class list (e.g. a stable selector hook). */
+  extraClassName?: string;
+  /** Extra attributes, applied after `type` and `aria-label`. */
+  attrs?: Record<string, string>;
+}
+
+/**
+ * The one header icon-button recipe: close, clear chat, trailing actions, and
+ * the Messages control all build through it so their box, glyph, and stroke
+ * can never drift apart. Config keys stay inline styles, which win over the
+ * token-driven stylesheet rules.
+ */
+export const createHeaderIconButton = (
+  options: CreateHeaderIconButtonOptions,
+): HeaderIconButtonParts => {
+  const {
+    ariaLabel,
+    tooltip = true,
+    tooltipHint,
+    iconName,
+    iconText,
+    wrapperClassName = DEFAULT_WRAPPER_CLASS,
+    size,
+    iconSize,
+    color,
+    backgroundColor,
+    borderWidth,
+    borderColor,
+    borderRadius,
+    paddingX,
+    paddingY,
+    hidden,
+    extraClassName,
+    attrs,
+  } = options;
+
+  const wrapper = createElement("div", wrapperClassName);
+
+  const hasBorder = Boolean(borderWidth || borderColor);
+
+  // hover-bg / border-none / rounded-full are default utility classes that
+  // apply only when the matching style override is absent; an override sets
+  // the inline style instead (cx omits the class).
+  const button = createNode("button", {
+    className: cx(
+      HEADER_CONTROL_CLASS,
+      "persona-inline-flex persona-items-center persona-justify-center persona-cursor-pointer",
+      !backgroundColor && "persona-bg-transparent hover:persona-bg-gray-100",
+      !hasBorder && "persona-border-none",
+      !borderRadius && "persona-rounded-full",
+      extraClassName,
+    ),
+    attrs: { type: "button", "aria-label": ariaLabel, ...attrs },
+    style: {
+      width: size,
+      height: size,
+      minWidth: size,
+      minHeight: size,
+      display: hidden ? "none" : undefined,
+      color: color || HEADER_THEME_CSS.actionIconColor,
+      // Empty strings are a no-op on a fresh element, so they need no guard.
+      backgroundColor,
+      border: hasBorder
+        ? `${borderWidth || "0px"} solid ${borderColor || "transparent"}`
+        : undefined,
+      borderRadius,
+      paddingLeft: paddingX,
+      paddingRight: paddingX,
+      paddingTop: paddingY,
+      paddingBottom: paddingY,
+    },
+  });
+
+  if (iconName) {
+    applyHeaderControlGlyph(button, iconName, { iconSize, iconText });
+  } else if (iconText) {
+    button.textContent = iconText;
+  }
+
+  wrapper.appendChild(button);
+  // attachTooltip is per-anchor idempotent, and a disabled attach replaces any
+  // previous enabled one, so update() rebuilds stay safe.
+  attachTooltip({
+    anchor: button,
+    trigger: wrapper,
+    text: () => button.getAttribute("aria-label") ?? ariaLabel,
+    hint: tooltipHint,
+    enabled: tooltip,
+  });
+  return { button, wrapper };
+};
+
 export interface CloseButtonParts {
   button: HTMLButtonElement;
   wrapper: HTMLElement;
@@ -31,9 +254,8 @@ export interface CreateCloseButtonOptions {
    */
   buttonSize?: string;
   /**
-   * Override the rendered icon size (default: "28px"). Pair with
-   * `buttonSize` when scaling the whole control down: otherwise the
-   * 28px icon will overflow a smaller button.
+   * Explicit nominal icon size. Unset means the header control icon-size token
+   * owns the glyph. Pair with `buttonSize` when scaling the whole control down.
    */
   iconSize?: string;
 }
@@ -48,22 +270,17 @@ export interface CreateClearChatButtonOptions {
   /**
    * Explicit button-size override that wins over `launcher.clearChat.size`.
    * Composer-bar mode uses this so the clear icon visually matches the
-   * shrunken close button (16px) and doesn't render at the floating
-   * launcher's 32px default.
+   * shrunken close button and doesn't inherit the header control size.
    */
   buttonSize?: string;
-  /** Override the rendered icon size (default: "20px"). */
+  /** Explicit icon size; unset leaves the header control icon-size token. */
   iconSize?: string;
 }
 
-const DEFAULT_WRAPPER_CLASS =
-  "persona-relative persona-ml-auto persona-inline-flex persona-items-center persona-justify-center";
-
 /**
- * Build the close (×) button + tooltip used in the panel header. Lifted
- * verbatim from header-builder.ts so composer-bar mode can render just a
- * close button (no full header strip) without duplicating the tooltip
- * + config-driven styling logic.
+ * Build the close (×) button + tooltip used in the panel header. Every header
+ * layout routes through this so composer-bar mode can render just a close
+ * button (no full header strip) without duplicating the config-driven styling.
  */
 export const createCloseButton = (
   config: AgentWidgetConfig | undefined,
@@ -73,87 +290,37 @@ export const createCloseButton = (
     showClose = true,
     wrapperClassName = DEFAULT_WRAPPER_CLASS,
     buttonSize,
-    iconSize = "28px",
+    iconSize,
   } = options;
   const launcher = config?.launcher ?? {};
-  // Call-site `buttonSize` (if provided) wins over launcher config. The
-  // launcher's `closeButtonSize` is set in DEFAULT_WIDGET_CONFIG so it's
-  // never undefined, which means the call-site override is the only way
-  // to opt a specific render path (like composer-bar's minimal close) into
-  // a different size.
-  const closeButtonSize = buttonSize ?? launcher.closeButtonSize ?? "32px";
-
-  const wrapper = createElement("div", wrapperClassName);
-
   const closeButtonTooltipText = launcher.closeButtonTooltipText ?? "Close chat";
   const closeButtonShowTooltip = launcher.closeButtonShowTooltip ?? true;
-  const closeButtonIconName = launcher.closeButtonIconName ?? "x";
-  const closeButtonIconText = launcher.closeButtonIconText ?? "×";
-  // hover-bg / border-none / rounded-full are default utility classes that
-  // apply only when the matching style override is absent; an override sets
-  // the inline style instead (cx omits the class).
-  const hasCloseBorder = Boolean(
-    launcher.closeButtonBorderWidth || launcher.closeButtonBorderColor
-  );
-
-  const button = createNode("button", {
-    className: cx(
-      "persona-inline-flex persona-items-center persona-justify-center persona-cursor-pointer",
-      !launcher.closeButtonBackgroundColor && "hover:persona-bg-gray-100",
-      !hasCloseBorder && "persona-border-none",
-      !launcher.closeButtonBorderRadius && "persona-rounded-full"
-    ),
-    attrs: { type: "button", "aria-label": closeButtonTooltipText },
-    style: {
-      height: closeButtonSize,
-      width: closeButtonSize,
-      display: showClose ? undefined : "none",
-      color: launcher.closeButtonColor || HEADER_THEME_CSS.actionIconColor,
-      backgroundColor: launcher.closeButtonBackgroundColor || undefined,
-      border: hasCloseBorder
-        ? `${launcher.closeButtonBorderWidth || "0px"} solid ${launcher.closeButtonBorderColor || "transparent"}`
-        : undefined,
-      borderRadius: launcher.closeButtonBorderRadius || undefined,
-      paddingLeft: launcher.closeButtonPaddingX || undefined,
-      paddingRight: launcher.closeButtonPaddingX || undefined,
-      paddingTop: launcher.closeButtonPaddingY || undefined,
-      paddingBottom: launcher.closeButtonPaddingY || undefined,
-    },
-  });
 
-  // The X glyph's paths occupy only the middle 50% of its 24x24 viewBox
-  // (from 6,6 to 18,18), while other header icons (e.g. refresh-cw) span
-  // ~75% of the viewBox. Rendering X at a larger intrinsic size brings
-  // its visible extent into parity with sibling icons in the header.
-  // display:block eliminates inline-baseline spacing that can push the
-  // icon a fractional pixel off-center inside the button.
-  const closeIconSvg = renderLucideIcon(closeButtonIconName, iconSize, "currentColor", 1);
-  if (closeIconSvg) {
-    closeIconSvg.style.display = "block";
-    button.appendChild(closeIconSvg);
-  } else {
-    button.textContent = closeButtonIconText;
-  }
-
-  wrapper.appendChild(button);
-  attachTooltip({
-    anchor: button,
-    trigger: wrapper,
-    text: () => button.getAttribute("aria-label") ?? closeButtonTooltipText,
-    enabled: closeButtonShowTooltip,
+  const { button, wrapper } = createHeaderIconButton({
+    ariaLabel: closeButtonTooltipText,
+    tooltip: closeButtonShowTooltip,
+    iconName: launcher.closeButtonIconName ?? "x",
+    iconText: launcher.closeButtonIconText ?? "×",
+    wrapperClassName,
+    // Call-site `buttonSize` wins over launcher config; both unset means the
+    // header control-size token owns the box.
+    size: buttonSize ?? launcher.closeButtonSize,
+    iconSize,
+    color: launcher.closeButtonColor,
+    backgroundColor: launcher.closeButtonBackgroundColor,
+    borderWidth: launcher.closeButtonBorderWidth,
+    borderColor: launcher.closeButtonBorderColor,
+    borderRadius: launcher.closeButtonBorderRadius,
+    paddingX: launcher.closeButtonPaddingX,
+    paddingY: launcher.closeButtonPaddingY,
+    hidden: !showClose,
   });
 
   return { button, wrapper };
 };
 
-const DEFAULT_CLEAR_CHAT_WRAPPER_CLASS =
-  "persona-relative persona-ml-auto persona-clear-chat-button-wrapper";
-
 /**
  * Build the clear-chat (refresh) button + tooltip used in the panel header.
- * Extracted from `header-builder.ts` so composer-bar mode can render a
- * "start over" button alongside its close icon without duplicating the
- * tooltip + config-driven styling logic.
  *
  * The factory only handles construction. Wiring the click to the
  * clear-history handler is owned by `setupClearChatButton()` in `ui.ts`,
@@ -166,69 +333,30 @@ export const createClearChatButton = (
   const {
     wrapperClassName = DEFAULT_CLEAR_CHAT_WRAPPER_CLASS,
     buttonSize,
-    iconSize = "20px",
+    iconSize,
   } = options;
 
   const launcher = config?.launcher ?? {};
   const clearChatConfig = launcher.clearChat ?? {};
-  // Call-site `buttonSize` (when provided) wins over launcher.clearChat.size.
-  // Same precedence rule as createCloseButton: callers like composer-bar
-  // intentionally override the inherited launcher default to fit their UX.
-  const clearChatSize = buttonSize ?? clearChatConfig.size ?? "32px";
-  const clearChatIconName = clearChatConfig.iconName ?? "refresh-cw";
-  const clearChatIconColor = clearChatConfig.iconColor ?? "";
-  const clearChatBgColor = clearChatConfig.backgroundColor ?? "";
-  const clearChatBorderWidth = clearChatConfig.borderWidth ?? "";
-  const clearChatBorderColor = clearChatConfig.borderColor ?? "";
-  const clearChatBorderRadius = clearChatConfig.borderRadius ?? "";
-  const clearChatPaddingX = clearChatConfig.paddingX ?? "";
-  const clearChatPaddingY = clearChatConfig.paddingY ?? "";
   const clearChatTooltipText = clearChatConfig.tooltipText ?? "Clear chat";
   const clearChatShowTooltip = clearChatConfig.showTooltip ?? true;
 
-  const wrapper = createElement("div", wrapperClassName);
-
-  // hover-bg / border-none / rounded-full are default utility classes that
-  // apply only when the matching style override is absent; an override sets
-  // the inline style instead (cx omits the class).
-  const hasClearChatBorder = Boolean(clearChatBorderWidth || clearChatBorderColor);
-
-  const button = createNode("button", {
-    className: cx(
-      "persona-inline-flex persona-items-center persona-justify-center persona-cursor-pointer",
-      !clearChatBgColor && "hover:persona-bg-gray-100",
-      !hasClearChatBorder && "persona-border-none",
-      !clearChatBorderRadius && "persona-rounded-full"
-    ),
-    attrs: { type: "button", "aria-label": clearChatTooltipText },
-    style: {
-      height: clearChatSize,
-      width: clearChatSize,
-      color: clearChatIconColor || HEADER_THEME_CSS.actionIconColor,
-      backgroundColor: clearChatBgColor || undefined,
-      border: hasClearChatBorder
-        ? `${clearChatBorderWidth || "0px"} solid ${clearChatBorderColor || "transparent"}`
-        : undefined,
-      borderRadius: clearChatBorderRadius || undefined,
-      paddingLeft: clearChatPaddingX || undefined,
-      paddingRight: clearChatPaddingX || undefined,
-      paddingTop: clearChatPaddingY || undefined,
-      paddingBottom: clearChatPaddingY || undefined,
-    },
-  });
-
-  const iconSvg = renderLucideIcon(clearChatIconName, iconSize, "currentColor", 1);
-  if (iconSvg) {
-    iconSvg.style.display = "block";
-    button.appendChild(iconSvg);
-  }
-
-  wrapper.appendChild(button);
-  attachTooltip({
-    anchor: button,
-    trigger: wrapper,
-    text: () => button.getAttribute("aria-label") ?? clearChatTooltipText,
-    enabled: clearChatShowTooltip,
+  const { button, wrapper } = createHeaderIconButton({
+    ariaLabel: clearChatTooltipText,
+    tooltip: clearChatShowTooltip,
+    iconName: clearChatConfig.iconName ?? "refresh-cw",
+    wrapperClassName,
+    // Call-site `buttonSize` wins over `launcher.clearChat.size`; both unset
+    // means the header control-size token owns the box.
+    size: buttonSize ?? clearChatConfig.size,
+    iconSize,
+    color: clearChatConfig.iconColor,
+    backgroundColor: clearChatConfig.backgroundColor,
+    borderWidth: clearChatConfig.borderWidth,
+    borderColor: clearChatConfig.borderColor,
+    borderRadius: clearChatConfig.borderRadius,
+    paddingX: clearChatConfig.paddingX,
+    paddingY: clearChatConfig.paddingY,
   });
 
   return { button, wrapper };

package/src/components/history-confirm-dialog.ts

@@ -0,0 +1,177 @@
+/**
+ * Shell-owned destructive confirmation for history actions
+ * (`docs/visitor-history-implementation-plan.md` D7, accessibility contract).
+ *
+ * An alert dialog: labelled and described, focus-trapped, least-destructive
+ * action focused first, Escape resolves `false`, and focus returns to whatever
+ * was focused when it opened. Styling is inline so the dialog costs no bytes in
+ * `widget.css`; colors come from the same theme variables the panel uses.
+ */
+
+import { createNode } from "../utils/dom";
+
+export interface HistoryConfirmOptions {
+  title: string;
+  description: string;
+  confirmLabel: string;
+  cancelLabel: string;
+  /** Where the modal mounts. Normally the widget container. */
+  host: HTMLElement;
+}
+
+const FOCUSABLE = "button:not([disabled])";
+
+/** Resolves `true` only for the confirming action. */
+export function showHistoryConfirm(
+  options: HistoryConfirmOptions
+): Promise<boolean> {
+  const previouslyFocused =
+    document.activeElement instanceof HTMLElement ? document.activeElement : null;
+  const id = Math.random().toString(36).slice(2, 8);
+  const titleId = `persona-history-confirm-title-${id}`;
+  const descriptionId = `persona-history-confirm-desc-${id}`;
+
+  const cancel = createNode("button", {
+    className: "persona-history-confirm__cancel",
+    text: options.cancelLabel,
+    attrs: { type: "button" },
+  });
+  const confirm = createNode("button", {
+    className: "persona-history-confirm__confirm",
+    text: options.confirmLabel,
+    attrs: { type: "button", "data-persona-destructive": "true" },
+  });
+
+  const dialog = createNode(
+    "div",
+    {
+      className: "persona-history-confirm__dialog",
+      attrs: {
+        role: "alertdialog",
+        "aria-modal": "true",
+        "aria-labelledby": titleId,
+        "aria-describedby": descriptionId,
+      },
+      style: {
+        maxWidth: "22rem",
+        width: "100%",
+        borderRadius: "var(--persona-radius-lg, 0.75rem)",
+        background: "var(--persona-surface, #ffffff)",
+        // The real text token, never `inherit`: the host is the panel in
+        // split layouts, whose cascaded color is the page's, not the theme's.
+        color: "var(--persona-text, #111827)",
+        boxShadow:
+          "var(--persona-history-confirm-shadow, 0 20px 40px -12px rgba(0, 0, 0, 0.35))",
+        padding: "20px",
+        display: "flex",
+        flexDirection: "column",
+        gap: "12px",
+      },
+    },
+    createNode("h2", {
+      className: "persona-history-confirm__title",
+      text: options.title,
+      attrs: { id: titleId },
+      style: { margin: "0", fontSize: "1rem", fontWeight: "600" },
+    }),
+    createNode("p", {
+      className: "persona-history-confirm__description",
+      text: options.description,
+      attrs: { id: descriptionId },
+      style: { margin: "0", fontSize: "0.875rem", lineHeight: "1.4" },
+    }),
+    createNode(
+      "div",
+      {
+        className: "persona-history-confirm__actions",
+        style: {
+          display: "flex",
+          gap: "8px",
+          justifyContent: "flex-end",
+          flexWrap: "wrap",
+        },
+      },
+      cancel,
+      confirm
+    )
+  );
+
+  for (const button of [cancel, confirm]) {
+    button.style.minHeight = "44px";
+    button.style.minWidth = "88px";
+    button.style.padding = "0 16px";
+    button.style.borderRadius = "var(--persona-radius-md, 0.5rem)";
+    button.style.cursor = "pointer";
+    button.style.font = "inherit";
+  }
+  cancel.style.border = "1px solid var(--persona-border, rgba(0,0,0,0.12))";
+  cancel.style.background = "transparent";
+  cancel.style.color = "inherit";
+  confirm.style.border = "none";
+  confirm.style.background = "var(--persona-danger, #b42318)";
+  confirm.style.color = "var(--persona-danger-fg, #ffffff)";
+
+  const overlay = createNode(
+    "div",
+    {
+      className: "persona-history-confirm",
+      style: {
+        position: "absolute",
+        inset: "0",
+        zIndex: "40",
+        display: "flex",
+        alignItems: "center",
+        justifyContent: "center",
+        padding: "16px",
+        background: "var(--persona-history-confirm-scrim, rgba(15, 23, 42, 0.45))",
+      },
+    },
+    dialog
+  );
+
+  return new Promise<boolean>((resolve) => {
+    let settled = false;
+    const close = (result: boolean): void => {
+      if (settled) return;
+      settled = true;
+      overlay.removeEventListener("keydown", onKeydown, true);
+      overlay.remove();
+      previouslyFocused?.focus();
+      resolve(result);
+    };
+
+    function onKeydown(event: KeyboardEvent): void {
+      if (event.key === "Escape") {
+        event.preventDefault();
+        event.stopPropagation();
+        close(false);
+        return;
+      }
+      if (event.key !== "Tab") return;
+      // Trap: only the two actions are reachable while the alert is open.
+      const focusable = Array.from(dialog.querySelectorAll<HTMLElement>(FOCUSABLE));
+      if (focusable.length === 0) return;
+      const first = focusable[0]!;
+      const last = focusable[focusable.length - 1]!;
+      const active = document.activeElement;
+      if (event.shiftKey && (active === first || !dialog.contains(active))) {
+        event.preventDefault();
+        last.focus();
+      } else if (!event.shiftKey && active === last) {
+        event.preventDefault();
+        first.focus();
+      }
+    }
+
+    overlay.addEventListener("keydown", onKeydown, true);
+    // A click on the scrim is not a destructive confirmation.
+    overlay.addEventListener("pointerdown", (event) => {
+      if (event.target === overlay) close(false);
+    });
+    cancel.addEventListener("click", () => close(false));
+    confirm.addEventListener("click", () => close(true));
+
+    options.host.appendChild(overlay);
+    cancel.focus();
+  });
+}