@tensor_1/react 2.47.0 → 2.48.0

package/dist/components/InlineEdit.js

@@ -1,9 +1,10 @@
 "use client";
-import { jsx, jsxs } from "react/jsx-runtime";
-import { useEffect, useId, useRef, useState } from "react";
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+import { useEffect, useId, useLayoutEffect, useRef, useState } from "react";
 import { cx } from "../cx.js";
 import { fillLabel } from "../fill-label.js";
 import { useUixLabels } from "../labels-context.js";
+import { useDelayedPending } from "../hooks/useDelayedPending.js";
 import { PencilIcon } from "../icons/components.js";
 import { Button } from "./Button.js";
 import { Input } from "./Input.js";
@@ -15,8 +16,10 @@ const DEFAULT_INLINE_EDIT_LABELS = {
   saving: "Saving\u2026",
   saved: "Saved",
   failed: "Could not save.",
-  empty: "Not set"
+  empty: "Not set",
+  readOnly: "Read-only:"
 };
+const defaultEmpty = (value) => value == null || value === "";
 function InlineEdit({
   value,
   onSave,
@@ -25,22 +28,45 @@ function InlineEdit({
   renderEditor,
   multiline = false,
   validate,
+  equals = Object.is,
+  isEmpty = defaultEmpty,
+  commit = "explicit",
   placeholder,
   disabled = false,
+  readOnlyReason,
+  trigger = "value",
+  editing: editingProp,
+  onEditingChange,
+  draft: draftProp,
+  onDraftChange,
+  renderError,
+  onStateChange,
   labels: labelOverrides,
   className
 }) {
   const labels = { ...DEFAULT_INLINE_EDIT_LABELS, ...useUixLabels().inlineEdit, ...labelOverrides };
   const id = useId();
   const errorId = `${id}-error`;
-  const [editing, setEditing] = useState(false);
-  const [draft, setDraft] = useState(value);
+  const reasonId = `${id}-reason`;
+  const [editingState, setEditingState] = useState(false);
+  const isEditing = editingProp ?? editingState;
+  const [draftState, setDraftState] = useState(value);
+  const draft = draftProp !== void 0 ? draftProp : draftState;
   const [pending, setPending] = useState(false);
+  const pendingVisible = useDelayedPending(pending) && pending;
   const [error, setError] = useState();
   const [status, setStatus] = useState("");
+  const [saved, setSaved] = useState(false);
+  const [accepted, setAccepted] = useState(null);
   const viewRef = useRef(null);
   const editorRef = useRef(null);
-  const focusNext = useRef(null);
+  const focusView = useRef(false);
+  const editingRef = useRef(isEditing);
+  editingRef.current = isEditing;
+  const inFlight = useRef(false);
+  const lastSent = useRef(null);
+  const session = useRef(0);
+  const pressInside = useRef(false);
   const mounted = useRef(true);
   useEffect(() => {
     mounted.current = true;
@@ -48,83 +74,143 @@ function InlineEdit({
       mounted.current = false;
     };
   }, []);
+  const lastValue = useRef(value);
+  useLayoutEffect(() => {
+    if (equals(lastValue.current, value)) return;
+    lastValue.current = value;
+    setAccepted(null);
+  });
+  const shown = accepted ? accepted.value : value;
   useEffect(() => {
-    const target = focusNext.current;
-    if (!target) return;
-    focusNext.current = null;
-    if (target === "view") {
-      viewRef.current?.focus();
+    if (pendingVisible && pending) setStatus(labels.saving);
+  }, [pendingVisible, pending]);
+  const state = pending ? "saving" : error?.failure ? "error" : isEditing ? "editing" : saved ? "saved" : "idle";
+  const onStateChangeRef = useRef(onStateChange);
+  onStateChangeRef.current = onStateChange;
+  const reported = useRef("idle");
+  useEffect(() => {
+    if (reported.current === state) return;
+    reported.current = state;
+    onStateChangeRef.current?.(state);
+  }, [state]);
+  const setEditing = (next) => {
+    editingRef.current = next;
+    if (editingProp === void 0) setEditingState(next);
+    onEditingChange?.(next);
+  };
+  const setDraft = (next) => {
+    if (draftProp === void 0) setDraftState(next);
+    onDraftChange?.(next);
+  };
+  useEffect(() => {
+    if (isEditing) {
+      const control = editorRef.current?.querySelector("input, textarea, select, button, [tabindex]");
+      control?.focus();
+      if (control instanceof HTMLInputElement || control instanceof HTMLTextAreaElement) control.select();
       return;
     }
-    const control = editorRef.current?.querySelector("input, textarea, select, button, [tabindex]");
-    control?.focus();
-    if (control instanceof HTMLInputElement || control instanceof HTMLTextAreaElement) control.select();
-  }, [editing]);
-  const start = () => {
-    setDraft(value);
+    if (focusView.current) {
+      focusView.current = false;
+      viewRef.current?.focus();
+    }
+  }, [isEditing]);
+  const wasEditing = useRef(isEditing);
+  useLayoutEffect(() => {
+    if (isEditing && !wasEditing.current && editingProp !== void 0) resetForOpen();
+    wasEditing.current = isEditing;
+  });
+  function resetForOpen() {
+    setDraft(shown);
     setError(void 0);
     setStatus("");
-    focusNext.current = "editor";
+    setSaved(false);
+    lastSent.current = null;
+  }
+  const start = () => {
+    session.current += 1;
+    resetForOpen();
     setEditing(true);
   };
-  const close = () => {
-    focusNext.current = "view";
+  const close = (returnFocus) => {
+    focusView.current = returnFocus;
+    inFlight.current = false;
     setEditing(false);
   };
   const cancel = () => {
-    if (pending) return;
+    if (inFlight.current) return;
     setError(void 0);
-    close();
+    setDraft(shown);
+    close(true);
   };
-  const save = () => {
-    if (pending) return;
-    const issue = validate?.(draft);
+  const failureMessage = (reason) => typeof reason === "string" && reason ? reason : reason instanceof Error && reason.message ? reason.message : labels.failed;
+  const send = (next, explicit) => {
+    if (!editingRef.current || inFlight.current) return;
+    if (!explicit && error?.failure && lastSent.current && equals(lastSent.current.value, next)) return;
+    const issue = validate?.(next);
     if (issue != null) {
-      setError(issue);
+      setError({ message: issue });
       return;
     }
-    if (draft === value) {
-      close();
+    if (equals(next, shown)) {
+      setError(void 0);
+      close(explicit);
       return;
     }
     setError(void 0);
+    lastSent.current = { value: next };
+    const mine = session.current;
     let result;
     try {
-      result = onSave(draft);
+      result = onSave(next);
     } catch (thrown) {
-      setError(thrown instanceof Error && thrown.message ? thrown.message : labels.failed);
+      setError({ message: failureMessage(thrown), failure: { reason: thrown } });
       return;
     }
-    if (!result || typeof result.then !== "function") {
+    const done = () => {
+      setAccepted({ value: next });
       setStatus(labels.saved);
-      close();
+      setSaved(true);
+      if (editingRef.current && session.current === mine) close(explicit);
+    };
+    if (!result || typeof result.then !== "function") {
+      done();
       return;
     }
+    inFlight.current = true;
     setPending(true);
-    setStatus(labels.saving);
     result.then(
       () => {
         if (!mounted.current) return;
+        inFlight.current = false;
         setPending(false);
-        setStatus(labels.saved);
-        close();
+        done();
       },
       (reason) => {
         if (!mounted.current) return;
+        inFlight.current = false;
         setPending(false);
+        if (session.current !== mine) return;
         setStatus("");
-        setError(typeof reason === "string" && reason ? reason : reason instanceof Error && reason.message ? reason.message : labels.failed);
-        focusNext.current = null;
+        setError({ message: failureMessage(reason), failure: { reason } });
         editorRef.current?.querySelector("input, textarea, select")?.focus();
       }
     );
   };
+  const save = (next) => send(next === void 0 ? draft : next, true);
+  const retry = () => send(lastSent.current && equals(lastSent.current.value, draft) ? lastSent.current.value : draft, true);
+  const change = (next) => {
+    if (inFlight.current) return;
+    setDraft(next);
+    if (error && !error.failure) setError(void 0);
+    if (commit === "change") send(next, true);
+  };
   const onEditorKeyDown = (event) => {
     if (event.key === "Escape") {
+      if (event.defaultPrevented || event.target.closest?.('[aria-expanded="true"]')) return;
       event.preventDefault();
       event.stopPropagation();
       cancel();
-    } else if (event.key === "Enter" && !event.defaultPrevented) {
+    } else if (event.key === "Enter" && !event.defaultPrevented && commit !== "change") {
       const inField = event.target.matches("input, textarea");
       if (!inField) return;
       const isTextarea = event.target.tagName === "TEXTAREA";
@@ -133,15 +219,56 @@ function InlineEdit({
       save();
     }
   };
+  const onEditorBlur = (event) => {
+    if (commit === "explicit") return;
+    const next = event.relatedTarget;
+    if (next && event.currentTarget.contains(next)) return;
+    if (pressInside.current) return;
+    if (next) {
+      send(draft, false);
+      return;
+    }
+    const draftNow = draft;
+    setTimeout(() => {
+      if (!editingRef.current || pressInside.current) return;
+      if (editorRef.current?.contains(document.activeElement)) return;
+      send(draftNow, false);
+    }, 0);
+  };
+  const onEditorPointerDown = () => {
+    pressInside.current = true;
+    const release = () => {
+      setTimeout(() => {
+        pressInside.current = false;
+      }, 0);
+      window.removeEventListener("pointerup", release, true);
+      window.removeEventListener("pointercancel", release, true);
+    };
+    window.addEventListener("pointerup", release, true);
+    window.addEventListener("pointercancel", release, true);
+  };
   const liveRegion = /* @__PURE__ */ jsx("span", { className: "uix-visually-hidden", role: "status", "aria-live": "polite", children: status });
-  const shown = value === "" ? /* @__PURE__ */ jsx("span", { className: "uix-inline-edit__placeholder", children: placeholder ?? labels.empty }) : renderView?.(value) ?? value;
-  if (disabled) {
-    return /* @__PURE__ */ jsx("span", { className: cx("uix-inline-edit", "uix-inline-edit--readonly", className), children: /* @__PURE__ */ jsx("span", { className: "uix-inline-edit__value", children: shown }) });
+  const empty = isEmpty(shown);
+  const display = empty ? /* @__PURE__ */ jsx("span", { className: "uix-inline-edit__placeholder", children: placeholder ?? labels.empty }) : renderView?.(shown) ?? String(shown);
+  if (disabled || readOnlyReason != null) {
+    return /* @__PURE__ */ jsxs("span", { className: cx("uix-inline-edit", "uix-inline-edit--readonly", readOnlyReason != null && "uix-inline-edit--reason", className), children: [
+      /* @__PURE__ */ jsx("span", { className: "uix-inline-edit__value", "aria-describedby": readOnlyReason != null ? reasonId : void 0, children: display }),
+      readOnlyReason != null && /* @__PURE__ */ jsxs("span", { id: reasonId, className: "uix-inline-edit__reason", children: [
+        /* @__PURE__ */ jsxs("span", { className: "uix-visually-hidden", children: [
+          labels.readOnly,
+          " "
+        ] }),
+        readOnlyReason
+      ] })
+    ] });
   }
-  if (!editing) {
-    return /* @__PURE__ */ jsxs("span", { className: cx("uix-inline-edit", className), children: [
-      /* @__PURE__ */ jsxs("button", { ref: viewRef, type: "button", className: "uix-inline-edit__view", onClick: start, children: [
-        /* @__PURE__ */ jsx("span", { className: "uix-inline-edit__value", children: shown }),
+  if (!isEditing) {
+    return /* @__PURE__ */ jsxs("span", { className: cx("uix-inline-edit", trigger === "icon" && "uix-inline-edit--icon-trigger", className), children: [
+      trigger === "icon" ? /* @__PURE__ */ jsxs(Fragment, { children: [
+        /* @__PURE__ */ jsx("span", { className: "uix-inline-edit__value", children: display }),
+        /* @__PURE__ */ jsx("button", { ref: viewRef, type: "button", className: "uix-inline-edit__trigger", "aria-label": fillLabel(labels.edit, { label }), onClick: start, children: /* @__PURE__ */ jsx(PencilIcon, { size: "sm" }) })
+      ] }) : /* @__PURE__ */ jsxs("button", { ref: viewRef, type: "button", className: "uix-inline-edit__view", onClick: start, children: [
+        /* @__PURE__ */ jsx("span", { className: "uix-inline-edit__value", children: display }),
         /* @__PURE__ */ jsxs("span", { className: "uix-visually-hidden", children: [
           ", ",
           fillLabel(labels.edit, { label })
@@ -156,17 +283,33 @@ function InlineEdit({
     "aria-label": label,
     "aria-describedby": error != null ? errorId : void 0,
     "aria-invalid": error != null ? true : void 0,
-    disabled: pending
+    disabled: pendingVisible,
+    readOnly: pendingVisible
   };
+  const textDraft = typeof draft === "string" ? draft : String(draft ?? "");
+  const errorBody = error && (error.failure && renderError ? renderError(error.failure.reason, { message: error.message, draft, retry, cancel }) : error.message);
   return /* @__PURE__ */ jsxs("span", { className: cx("uix-inline-edit", "uix-inline-edit--editing", className), children: [
-    /* @__PURE__ */ jsxs("div", { ref: editorRef, className: "uix-inline-edit__editor", role: "group", "aria-label": fillLabel(labels.edit, { label }), "aria-busy": pending || void 0, onKeyDown: onEditorKeyDown, children: [
-      /* @__PURE__ */ jsx("div", { className: "uix-inline-edit__control", children: renderEditor ? renderEditor({ value: draft, onChange: setDraft, save, cancel, field }) : multiline ? /* @__PURE__ */ jsx(Textarea, { ...field, rows: 3, value: draft, invalid: error != null, onChange: (event) => setDraft(event.currentTarget.value) }) : /* @__PURE__ */ jsx(Input, { ...field, size: "sm", value: draft, invalid: error != null, onChange: (event) => setDraft(event.currentTarget.value) }) }),
-      /* @__PURE__ */ jsxs("span", { className: "uix-inline-edit__actions", children: [
-        /* @__PURE__ */ jsx(Button, { type: "button", size: "sm", variant: "primary", loading: pending, onClick: save, children: labels.save }),
-        /* @__PURE__ */ jsx(Button, { type: "button", size: "sm", disabled: pending, onClick: cancel, children: labels.cancel })
-      ] }),
-      error != null && /* @__PURE__ */ jsx("div", { id: errorId, className: "uix-field__error uix-inline-edit__error", role: "alert", children: error })
-    ] }),
+    /* @__PURE__ */ jsxs(
+      "div",
+      {
+        ref: editorRef,
+        className: "uix-inline-edit__editor",
+        role: "group",
+        "aria-label": fillLabel(labels.edit, { label }),
+        "aria-busy": pending || void 0,
+        onKeyDown: onEditorKeyDown,
+        onBlur: onEditorBlur,
+        onPointerDownCapture: onEditorPointerDown,
+        children: [
+          /* @__PURE__ */ jsx("div", { className: "uix-inline-edit__control", children: renderEditor ? renderEditor({ value: draft, onChange: change, save, cancel, field }) : multiline ? /* @__PURE__ */ jsx(Textarea, { ...field, disabled: false, rows: 3, value: textDraft, invalid: error != null, onChange: (event) => change(event.currentTarget.value) }) : /* @__PURE__ */ jsx(Input, { ...field, disabled: false, size: "sm", value: textDraft, invalid: error != null, onChange: (event) => change(event.currentTarget.value) }) }),
+          /* @__PURE__ */ jsxs("span", { className: "uix-inline-edit__actions", children: [
+            commit !== "change" && /* @__PURE__ */ jsx(Button, { type: "button", size: "sm", variant: "primary", loading: pending, onMouseDown: (event) => event.preventDefault(), onClick: () => save(), children: labels.save }),
+            /* @__PURE__ */ jsx(Button, { type: "button", size: "sm", disabled: pendingVisible, onMouseDown: (event) => event.preventDefault(), onClick: cancel, children: labels.cancel })
+          ] }),
+          errorBody != null && /* @__PURE__ */ jsx("div", { id: errorId, className: "uix-field__error uix-inline-edit__error", role: "alert", children: errorBody })
+        ]
+      }
+    ),
     liveRegion
   ] });
 }

package/dist/components/Input.d.ts

@@ -2,7 +2,11 @@ import * as react from 'react';
 import { InputHTMLAttributes, ReactNode, AriaAttributes } from 'react';
 
 interface InputProps extends Omit<InputHTMLAttributes<HTMLInputElement>, 'size'> {
-    size?: 'sm' | 'md';
+    /**
+     * `sm` 28 px, `md` 36 px (default), `lg` 44 px: the touch-target floor of a public page, the
+     * same height as `Button size="lg"` (HAR-1812).
+     */
+    size?: 'sm' | 'md' | 'lg';
     invalid?: boolean;
     valid?: boolean;
     /**
@@ -16,6 +20,12 @@ interface InputGroupProps {
     children: ReactNode;
     leadingIcon?: ReactNode;
     trailingIcon?: ReactNode;
+    /**
+     * A control at the end of the field, inside its border: a reveal toggle, a clear or a copy
+     * button (HAR-1376). Give it the class `uix-input-group__action` (an icon button sized to the
+     * field) and an accessible name. It takes the place of `trailingIcon`.
+     */
+    trailingAction?: ReactNode;
     className?: string;
     /** Injected by `<Field>` when it wraps the group; forwarded onto the child control. */
     id?: string;
@@ -29,6 +39,6 @@ interface InputGroupProps {
  * single child element (the child's own props win) so label/message association survives
  * the extra div (UIX-A11Y-3).
  */
-declare function InputGroup({ children, leadingIcon, trailingIcon, className, id, 'aria-describedby': describedBy, 'aria-invalid': invalid, 'aria-required': required, }: InputGroupProps): react.JSX.Element;
+declare function InputGroup({ children, leadingIcon, trailingIcon, trailingAction, className, id, 'aria-describedby': describedBy, 'aria-invalid': invalid, 'aria-required': required, }: InputGroupProps): react.JSX.Element;
 
 export { Input, InputGroup, type InputGroupProps, type InputProps };

package/dist/components/Input.js

@@ -6,7 +6,7 @@ const Input = forwardRef(
     "input",
     {
       ref,
-      className: cx("uix-input", size === "sm" && "uix-input--sm", className),
+      className: cx("uix-input", size !== "md" && `uix-input--${size}`, className),
       "aria-invalid": invalid || void 0,
       "data-valid": valid || void 0,
       "data-warning": warning || void 0,
@@ -19,6 +19,7 @@ function InputGroup({
   children,
   leadingIcon,
   trailingIcon,
+  trailingAction,
   className,
   id,
   "aria-describedby": describedBy,
@@ -37,13 +38,14 @@ function InputGroup({
       className: cx(
         "uix-input-group",
         leadingIcon && "uix-input-group--has-leading",
-        trailingIcon && "uix-input-group--has-trailing",
+        (trailingIcon || trailingAction) && "uix-input-group--has-trailing",
+        trailingAction && "uix-input-group--has-action",
         className
       ),
       children: [
         leadingIcon && /* @__PURE__ */ jsx("span", { className: "uix-input-group__icon", "aria-hidden": "true", children: leadingIcon }),
         control,
-        trailingIcon && /* @__PURE__ */ jsx("span", { className: "uix-input-group__icon uix-input-group__icon--trailing", "aria-hidden": "true", children: trailingIcon })
+        trailingAction ?? (trailingIcon && /* @__PURE__ */ jsx("span", { className: "uix-input-group__icon uix-input-group__icon--trailing", "aria-hidden": "true", children: trailingIcon }))
       ]
     }
   );

package/dist/components/Kbd.d.ts

@@ -26,6 +26,11 @@ type KeyShortcut = readonly string[];
 declare function ariaKeyShortcuts(keys: KeyShortcut, platform: KbdPlatform): string;
 /** A `shortcut` prop that is key names rather than a node (HAR-2031). */
 declare const isKeyShortcut: (value: unknown) => value is KeyShortcut;
+/**
+ * What a screen reader should hear for a shortcut: the key names joined with "+", e.g.
+ * "Control+K" or "Command+K" (HAR-2416). The same text `KbdCombo` speaks. Internal.
+ */
+declare function spokenKeys(keys: KeyShortcut, platform: KbdPlatform, keyLabels?: Partial<Record<string, string>>): string;
 interface KbdComboProps extends Omit<HTMLAttributes<HTMLSpanElement>, 'children'> {
     /**
      * Keys in order, e.g. `['Mod', 'K']`. `Mod` is ⌘ on Apple and Ctrl elsewhere; `Shift`,
@@ -43,4 +48,4 @@ interface KbdComboProps extends Omit<HTMLAttributes<HTMLSpanElement>, 'children'
  */
 declare function KbdCombo({ keys, platform, keyLabels, className, ...props }: KbdComboProps): react.JSX.Element;
 
-export { Kbd, KbdCombo, type KbdComboProps, type KbdPlatform, type KbdProps, type KeyShortcut, ariaKeyShortcuts, isKeyShortcut, useKbdPlatform };
+export { Kbd, KbdCombo, type KbdComboProps, type KbdPlatform, type KbdProps, type KeyShortcut, ariaKeyShortcuts, isKeyShortcut, spokenKeys, useKbdPlatform };

package/dist/components/Kbd.js

@@ -48,15 +48,14 @@ function ariaKeyShortcuts(keys, platform) {
   return keys.map((key) => ARIA_KEYS[key]?.[platform] ?? (key.length === 1 ? key.toUpperCase() : key)).join("+");
 }
 const isKeyShortcut = (value) => Array.isArray(value) && value.length > 0 && value.every((key) => typeof key === "string");
+function spokenKeys(keys, platform, keyLabels) {
+  return keys.map((key) => keyLabels?.[key] ?? KEYS[key]?.[platform]?.[1] ?? key).join("+");
+}
 function KbdCombo({ keys, platform, keyLabels, className, ...props }) {
   const active = useKbdPlatform(platform);
-  const parts = keys.map((key) => {
-    const known = KEYS[key]?.[active];
-    return { glyph: known?.[0] ?? key, spoken: keyLabels?.[key] ?? known?.[1] ?? key };
-  });
   return /* @__PURE__ */ jsxs("span", { className: cx("uix-kbd-combo", className), ...props, children: [
-    /* @__PURE__ */ jsx("span", { className: "uix-visually-hidden", children: parts.map((p) => p.spoken).join("+") }),
-    /* @__PURE__ */ jsx("span", { className: "uix-kbd-combo__keys", "aria-hidden": "true", children: parts.map((p, i) => /* @__PURE__ */ jsx("kbd", { className: "uix-kbd", children: p.glyph }, `${keys[i]}-${i}`)) })
+    /* @__PURE__ */ jsx("span", { className: "uix-visually-hidden", children: spokenKeys(keys, active, keyLabels) }),
+    /* @__PURE__ */ jsx("span", { className: "uix-kbd-combo__keys", "aria-hidden": "true", children: keys.map((key, i) => /* @__PURE__ */ jsx("kbd", { className: "uix-kbd", children: KEYS[key]?.[active]?.[0] ?? key }, `${key}-${i}`)) })
   ] });
 }
 export {
@@ -64,5 +63,6 @@ export {
   KbdCombo,
   ariaKeyShortcuts,
   isKeyShortcut,
+  spokenKeys,
   useKbdPlatform
 };

package/dist/components/Lightbox.d.ts

@@ -1,5 +1,5 @@
 import * as react from 'react';
-import { ReactNode } from 'react';
+import { ReactNode, KeyboardEvent } from 'react';
 
 interface LightboxItem {
     src: string;
@@ -22,6 +22,21 @@ interface LightboxLabels {
     zoomOut: string;
 }
 declare const DEFAULT_LIGHTBOX_LABELS: LightboxLabels;
+/** What `renderOverlay` receives (HAR-1826). */
+interface LightboxOverlayContext {
+    /** The item on show (0-based) and the item itself. */
+    index: number;
+    item: LightboxItem;
+    /** The rendered `<img>` or `<video>`; `naturalWidth` / `videoWidth` give the bitmap size. */
+    media: HTMLImageElement | HTMLVideoElement | null;
+    /**
+     * The overlay's size in CSS pixels. The overlay covers exactly the picture (not the letterbox
+     * around a fitted one), so a point at `(x, y)` in it is bitmap pixel
+     * `(x / width * naturalWidth, y / height * naturalHeight)`. 0 until the media has loaded.
+     */
+    width: number;
+    height: number;
+}
 interface LightboxProps {
     items: readonly LightboxItem[];
     /** The item on show (0-based). */
@@ -33,13 +48,34 @@ interface LightboxProps {
     loop?: boolean;
     labels?: Partial<LightboxLabels>;
     className?: string;
+    /**
+     * Buttons for the toolbar beside Close (HAR-1826), e.g. "Hide area" and "Undo" on a viewer
+     * that redacts a screenshot. Tab order: these, then Close. They sit inside the dialog.
+     */
+    actions?: ReactNode;
+    /**
+     * Content laid over the picture, in the picture's own box: it moves and scales with the
+     * fit / actual-size toggle. Pointer events on it never swipe or page, so it can draw. Each
+     * child positions itself (`position: absolute` in `%`, or px of `width` / `height`).
+     */
+    renderOverlay?: (context: LightboxOverlayContext) => ReactNode;
+    /**
+     * Runs first for every key in the viewer. Call `event.preventDefault()` to claim the key:
+     * the viewer then neither pages (arrows, Home, End) nor closes (Escape). For a draft that
+     * arrow keys move and Escape cancels.
+     */
+    onKeyDown?: (event: KeyboardEvent<HTMLDialogElement>) => void;
+    /** Escape only: `event.preventDefault()` keeps the viewer open. */
+    onEscapeKeyDown?: (event: KeyboardEvent<HTMLDialogElement>) => void;
 }
 /**
  * A full-screen media viewer over `.uix-lightbox` (HAR-1367; TENSOR C12 `capture-viewer.tsx`,
  * MOTUS C-8 programme gallery): previous/next buttons, ←/→ and Home/End, swipe on touch, an
- * announced "n of total" counter, a caption, and a fit/actual-size toggle. Native `<dialog>`,
- * so focus stays inside and Escape closes; focus returns to the control that opened it.
+ * announced "n of total" counter (not for a single item), a caption, and a fit/actual-size
+ * toggle. Native `<dialog>`, so focus stays inside and Escape closes; focus returns to the
+ * control that opened it. An annotating viewer (HAR-1826) adds toolbar `actions`, draws in
+ * `renderOverlay`, and claims Escape and the arrows with `onKeyDown` while a draft is open.
  */
-declare function Lightbox({ items, index, onIndexChange, open, onClose, loop, labels: labelOverrides, className }: LightboxProps): react.JSX.Element;
+declare function Lightbox({ items, index, onIndexChange, open, onClose, loop, labels: labelOverrides, className, actions, renderOverlay, onKeyDown: onKeyDownProp, onEscapeKeyDown, }: LightboxProps): react.JSX.Element;
 
-export { DEFAULT_LIGHTBOX_LABELS, Lightbox, type LightboxItem, type LightboxLabels, type LightboxProps };
+export { DEFAULT_LIGHTBOX_LABELS, Lightbox, type LightboxItem, type LightboxLabels, type LightboxOverlayContext, type LightboxProps };