@tensor_1/react 2.41.0 → 2.43.0

package/README.md

@@ -762,6 +762,30 @@ The layout grid for dashboard widgets (HAR-1555; TENSOR's role dashboards). Pure
 - Refs reach the grid and item `<div>`s, and other props pass through. For an element you render yourself (a drag-and-drop library's sortable node, a server template), use `dashboardGridClassName(columns, gap)` and `dashboardGridItemClassName(span)`.
 - Plain HTML: `.uix-dashboard-grid` with `--cols-N` / `--{sm,md,lg,xl}-cols-N` and `--gap-sm|lg`, items `.uix-dashboard-grid__item` with `--span-2` / `--full`. Every direct child of the grid is a cell.
 
+### OrgChart
+
+Reporting lines as a top-down chart (HAR-1807; TENSOR's People directory). Managers sit above their direct reports, joined by lines; each person is a card with photo or initials, name, title, team, location and the number of direct reports, which is also the control that shows or hides them. Data fetching stays in the product: the chart asks for a person's reports through `loadChildren` the first time they are opened.
+
+```tsx
+<OrgChart
+  aria-label="Organisation"
+  nodes={roots}                       // OrgChartNode[]: { id, name, title?, team?, location?, photo?, badge?, reportCount?, children? }
+  loadChildren={(node) => api.reports(node.id)}
+  expanded={expanded} onToggle={(id, open) => setExpanded(next(expanded, id, open))}
+  selected={personId} onSelect={openPerson}
+  revealId={searchHit} onReveal={() => setSearchHit(null)}
+/>
+```
+
+- **Lazy reports:** a person with `reportCount > 0` and no `children` is expandable; on expand a loading row stands in for the reports, and a rejection shows an error row whose Enter, Space or click retries. Results are kept for the life of the chart. Expanding through a controlled `expanded` (a whole reporting line at once) loads each level as it appears.
+- **Search:** set `expanded` to the person's reporting line and `revealId` to the person; once their card exists the chart scrolls it into view, focuses it and calls `onReveal`. Set `revealId` back to null there, so the same person can be revealed again.
+- **Stacked rows:** a row of people without reports of their own is a column under their manager (`stackLeaves`, default true), so a team of eight takes one card width.
+- **Frame:** zoom out / in (25–150 %, around the frame's centre), Fit (the chart's width into the frame), the level button resets to 100 %; drag the background to pan (mouse and pen; touch scrolls). Opening a manager keeps their card where it was while their reports appear. Until the reader moves the view, a chart wider than the frame stays centred on its top, and `defaultZoom={'fit'}` keeps fitting as reports load. `--org-chart-max-height` (default 70vh) caps the frame. The root is an inline-size container: give it a width (a block, or `flex: 1` in a flex row).
+- **Narrow:** below 48rem of the chart's **own** width (a container query: a side panel counts as much as a phone) it is an indented vertical tree with guide lines; the toolbar steps aside.
+- **Keyboard:** one tab stop (roving tabindex). In the chart ↑ is the manager, ↓ the first report (↓ on a closed manager opens them first), ← → the previous and next person on the same level across teams; in a stacked column ↑ ↓ move along it. In the list the tree keys apply (↑ ↓ visible order, → open / first report, ← close / manager). From a stacked column, ← → go to the next column. Home / End, a letter jumps to the next visible person whose name starts with it, Enter opens the person (`onSelect`), Space shows or hides their reports. A failed load is announced.
+- **Words:** `labels` or `UixLabelsProvider` `orgChart` (`DEFAULT_ORG_CHART_LABELS`): the tree's default name (`chart`), loading, error, retry, `reportsOne` / `reportsMany` (`{count}`), expand / collapse, the toolbar and its buttons, `zoomLevel` / `resetZoom` (`{percent}`).
+- Plain HTML: `.uix-org-chart` > `__toolbar`, `__viewport` > `__canvas` > `ul.__tree[role=tree]` > `li.__item[role=treeitem]` > `.__node` (+ `ul.__group[role=group]`, `[data-stack]` for a column). The ARIA state on the item drives the styling.
+
 ### Select draws its own list
 
 `Select` (HAR-1572) no longer opens the browser's dropdown. It is the WAI-ARIA select-only combobox: a `<button role="combobox">` trigger and a UIx-drawn listbox in the top layer (a bottom sheet on phones). The props did not change, so existing call sites keep working:

package/dist/components/Button.d.ts

@@ -1,6 +1,7 @@
 import * as react from 'react';
 import { ButtonHTMLAttributes, ReactNode, AnchorHTMLAttributes } from 'react';
 import { UixRenderLink } from '../link.js';
+import { KeyShortcut } from './Kbd.js';
 
 type ButtonVariant = 'primary' | 'secondary' | 'outline' | 'ghost' | 'danger' | 'link';
 /** `xs` is 24 px: the smallest hit area WCAG 2.5.8 allows, for dense tool rows (HAR-1348). */
@@ -10,6 +11,21 @@ interface ButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
     size?: ButtonSize;
     icon?: boolean;
     loading?: boolean;
+    /**
+     * Let a long label wrap onto more lines: the size becomes a minimum height instead of a fixed
+     * one (HAR-1813, WCAG 1.4.10 reflow). For human-language labels on public or narrow screens;
+     * dense staff rows keep the one-line default. Ignored with `icon`.
+     */
+    wrap?: boolean;
+    /**
+     * The button's keyboard shortcut, in `KbdCombo` key names: `['A']`, `['Mod', 'Enter']`
+     * (HAR-2031). Hover or focus shows the keys in a hint above the button (an icon button's
+     * `aria-label` before them), and the button gets `aria-keyshortcuts` for the viewer's platform
+     * (⌘ / Meta on Apple, Ctrl / Control elsewhere), unless you pass `aria-keyshortcuts` yourself.
+     * Inside a `Tooltip` the Tooltip shows the keys in its own bubble. The kit only shows the
+     * shortcut: the product binds the key.
+     */
+    shortcut?: KeyShortcut;
     children?: ReactNode;
 }
 declare const Button: react.ForwardRefExoticComponent<ButtonProps & react.RefAttributes<HTMLButtonElement>>;
@@ -19,6 +35,8 @@ interface ButtonLinkProps extends AnchorHTMLAttributes<HTMLAnchorElement> {
     size?: ButtonSize;
     /** Icon-only link: square, and needs `aria-label`. */
     icon?: boolean;
+    /** Let a long label wrap (see `ButtonProps.wrap`, HAR-1813). Ignored with `icon`. */
+    wrap?: boolean;
     /**
      * Renders the link without `href`, with `aria-disabled="true"`, so it is announced
      * as an unavailable link and cannot be followed or focused.
@@ -32,7 +50,7 @@ interface ButtonLinkProps extends AnchorHTMLAttributes<HTMLAnchorElement> {
  * A link that looks like a `Button` (HAR-1348; TENSOR A4/B5, MOTUS C-3). Use it when the
  * action navigates; use `Button` when it acts in place.
  */
-declare function ButtonLink({ href, variant, size, icon, disabled, renderLink, className, children, onClick, ...props }: ButtonLinkProps): react.JSX.Element;
+declare function ButtonLink({ href, variant, size, icon, wrap, disabled, renderLink, className, children, onClick, ...props }: ButtonLinkProps): react.JSX.Element;
 interface ButtonGroupProps {
     children?: ReactNode;
     className?: string;

package/dist/components/Button.js

@@ -1,26 +1,28 @@
-import { Fragment, jsx } from "react/jsx-runtime";
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
 import { forwardRef } from "react";
 import { cx } from "../cx.js";
 import { renderUixLink } from "../link.js";
-const buttonClasses = (variant, size, icon, className) => cx(
+import { ShortcutHint } from "./ShortcutHint.js";
+const buttonClasses = (variant, size, icon, wrap, className) => cx(
   "uix-btn",
   `uix-btn--${variant}`,
   size !== "md" && `uix-btn--${size}`,
   icon && "uix-btn--icon",
+  wrap && !icon && "uix-btn--wrap",
   className
 );
 let warnedIconButton = false;
 const Button = forwardRef(
-  ({ variant = "secondary", size = "md", icon = false, loading = false, className, children, disabled, onClick, ...props }, ref) => {
+  ({ variant = "secondary", size = "md", icon = false, loading = false, wrap = false, shortcut, className, children, disabled, onClick, ...props }, ref) => {
     if (!warnedIconButton && icon && children == null && !props["aria-label"] && !props["aria-labelledby"] && typeof process !== "undefined" && process.env.NODE_ENV !== "production") {
       warnedIconButton = true;
       console.warn("uix: icon-only <Button> has no accessible name \u2014 pass aria-label or aria-labelledby.");
     }
-    return /* @__PURE__ */ jsx(
+    return /* @__PURE__ */ jsxs(
       "button",
       {
         ref,
-        className: buttonClasses(variant, size, icon, className),
+        className: buttonClasses(variant, size, icon, wrap, className),
         disabled,
         "aria-disabled": loading || void 0,
         "aria-busy": loading || void 0,
@@ -33,14 +35,17 @@ const Button = forwardRef(
           onClick?.(e);
         } : void 0,
         ...props,
-        children
+        children: [
+          children,
+          shortcut && shortcut.length > 0 && /* @__PURE__ */ jsx(ShortcutHint, { keys: shortcut, label: icon ? props["aria-label"] : void 0, ownsAria: props["aria-keyshortcuts"] === void 0 })
+        ]
       }
     );
   }
 );
 Button.displayName = "Button";
-function ButtonLink({ href, variant = "secondary", size = "md", icon = false, disabled = false, renderLink, className, children, onClick, ...props }) {
-  const classes = buttonClasses(variant, size, icon, className);
+function ButtonLink({ href, variant = "secondary", size = "md", icon = false, wrap = false, disabled = false, renderLink, className, children, onClick, ...props }) {
+  const classes = buttonClasses(variant, size, icon, wrap, className);
   if (disabled) {
     return /* @__PURE__ */ jsx("a", { ...props, className: classes, role: "link", "aria-disabled": "true", children });
   }

package/dist/components/DescriptionList.d.ts

@@ -20,6 +20,17 @@ import { ReactNode, HTMLAttributes } from 'react';
  * Use `items` for data-driven lists (the common case) or the `DescriptionItem`
  * compound child for hand-authored content. Both render `<dt>`/`<dd>` pairs as
  * direct children of the grid `<dl>`, so they align into the same columns.
+ *
+ * Below 22rem of its own width (a phone, a side rail, a narrow column) each label
+ * sits above its value and both take the full width (HAR-2032), so a long label
+ * never squeezes the value. A `DetailLayout` side column always stacks.
+ *
+ * The list is an inline-size container for this, so its content no longer sizes
+ * it: in a box sized by its content (a flex row, a `Popover` or hover card, a
+ * `max-content` tooltip, an auto-layout table cell, inline-block, a float) it is
+ * 12rem wide, and stacked, unless you size it (`flex: 1`, a width). And an
+ * unnamed `@container` query or a `cqi` unit inside a value now measures the
+ * list: name the container you mean (`@container/card`).
  */
 interface DescriptionListItem {
     /** Stable identity for the row; falls back to the list index when omitted. */

package/dist/components/DiscardPrompt.d.ts

@@ -0,0 +1,54 @@
+import * as react from 'react';
+import { RefObject, KeyboardEvent, ReactNode } from 'react';
+import { ButtonProps } from './Button.js';
+import '../link.js';
+import './Kbd.js';
+
+/** The words of the "Discard changes?" step a `dirty` Drawer or Modal asks before it closes (HAR-2029). */
+interface DiscardPromptLabels {
+    /** The question, e.g. "Discard changes?". It names the step. */
+    title: string;
+    /** What discarding means, under the question. */
+    description: string;
+    /** The safe choice. It has focus when the step opens. */
+    keepEditing: string;
+    /** Close and throw the input away. */
+    discard: string;
+}
+type DialogCloseProps = ButtonProps;
+/**
+ * A button that closes the surrounding `Drawer` or `Modal` the way its × does (HAR-2029): at once
+ * when the form is clean, through the "Discard changes?" step (placed against this button) when
+ * the dialog is `dirty`, and not at all while it is `pending`. Use it for the footer's Cancel.
+ * Its own `onClick` runs first; `event.preventDefault()` there keeps the dialog open.
+ */
+declare const DialogClose: react.ForwardRefExoticComponent<ButtonProps & react.RefAttributes<HTMLButtonElement>>;
+interface GuardedDialogOptions {
+    open: boolean;
+    onClose?: () => void;
+    dirty?: boolean;
+    pending?: boolean;
+    labels?: Partial<DiscardPromptLabels>;
+    /** The dialog's own × button: the step is placed against it unless a DialogClose asked. */
+    closeRef: RefObject<HTMLButtonElement | null>;
+}
+/**
+ * `useDialog` with the dismissal guard of a form dialog (HAR-2029). Every way out (Escape, the
+ * ×, a backdrop click, a `DialogClose`) goes through `requestClose`: a clean dialog closes at
+ * once, a `dirty` one opens the anchored "Discard changes?" step, a `pending` one does nothing.
+ *
+ * Escape is taken on the dialog's own keydown, after the controls inside it had their turn (a
+ * Select closing its list cancels the event first), and cancelling that keydown is what keeps the
+ * browser from closing the dialog. A close request that was not a keydown (the Android back
+ * gesture) arrives as `cancel`. If the browser still closes a guarded dialog by force (it may
+ * ignore a cancelled `cancel` without user activation), the dialog reopens at once and asks.
+ */
+declare function useGuardedDialog({ open, onClose, dirty, pending, labels: labelsProp, closeRef }: GuardedDialogOptions): {
+    ref: RefObject<HTMLDialogElement>;
+    requestClose: (anchor?: HTMLElement | null) => void;
+    onKeyDown: (event: KeyboardEvent<HTMLDialogElement>) => void;
+    prompt: react.JSX.Element | null;
+    provide: (children: ReactNode) => react.JSX.Element;
+};
+
+export { DialogClose, type DialogCloseProps, type DiscardPromptLabels, type GuardedDialogOptions, useGuardedDialog };

package/dist/components/DiscardPrompt.js

@@ -0,0 +1,245 @@
+"use client";
+import { jsx, jsxs } from "react/jsx-runtime";
+import { createContext, forwardRef, useCallback, useContext, useEffect, useId, useLayoutEffect, useRef, useState } from "react";
+import { Button } from "./Button.js";
+import { Popover } from "./Popover.js";
+import { useUixLabels } from "../labels-context.js";
+import { useDialog } from "../hooks/useDialog.js";
+const useIsomorphicLayoutEffect = typeof document !== "undefined" ? useLayoutEffect : useEffect;
+const anyAutoPopoverOpen = () => {
+  try {
+    return !!document.querySelector('[popover]:not([popover="manual"]):popover-open');
+  } catch {
+    return false;
+  }
+};
+const DEFAULT_DISCARD_LABELS = {
+  title: "Discard changes?",
+  description: "What you entered here will be lost.",
+  keepEditing: "Keep editing",
+  discard: "Discard"
+};
+const DialogCloseContext = createContext(null);
+const DialogClose = forwardRef(({ onClick, type = "button", ...props }, ref) => {
+  const dialog = useContext(DialogCloseContext);
+  const pending = !!dialog?.pending;
+  return /* @__PURE__ */ jsx(
+    Button,
+    {
+      ref,
+      type,
+      ...props,
+      ...pending ? { "aria-disabled": true } : {},
+      onClick: (event) => {
+        if (pending) {
+          event.preventDefault();
+          return;
+        }
+        onClick?.(event);
+        if (event.defaultPrevented) return;
+        dialog?.requestClose(event.currentTarget);
+      }
+    }
+  );
+});
+DialogClose.displayName = "DialogClose";
+function useGuardedDialog({ open, onClose, dirty = false, pending = false, labels: labelsProp, closeRef }) {
+  const uixLabels = useUixLabels();
+  const labels = { ...DEFAULT_DISCARD_LABELS, ...uixLabels.discardPrompt, ...labelsProp };
+  const panelId = `${useId()}-discard`;
+  const [prompt, setPromptState] = useState(null);
+  const latest = useRef({ open, onClose, dirty, pending, prompt });
+  useIsomorphicLayoutEffect(() => {
+    latest.current = { ...latest.current, open, onClose, dirty, pending };
+  });
+  const setPrompt = useCallback((next) => {
+    latest.current.prompt = next;
+    setPromptState(next);
+  }, []);
+  const guarded = () => !!latest.current.onClose && (latest.current.dirty || latest.current.pending);
+  const requestClose = useCallback((anchor) => {
+    const { open: isOpen, onClose: close, dirty: isDirty, pending: isPending, prompt: asking } = latest.current;
+    if (!isOpen || !close || isPending || asking) return;
+    if (!isDirty) {
+      close();
+      return;
+    }
+    const active = document.activeElement;
+    setPrompt({ anchor: anchor ?? closeRef.current, returnTo: active instanceof HTMLElement ? active : null });
+  }, [closeRef, setPrompt]);
+  const dialogRef = useRef(null);
+  const backOut = useRef({ focus: null, forced: false });
+  const keepEditing = useCallback(() => {
+    const asked = latest.current.prompt;
+    setPrompt(null);
+    const target = asked?.returnTo;
+    const dialog = dialogRef.current;
+    const back = target && target !== dialog && target.isConnected && dialog?.contains(target) ? target : asked?.anchor ?? closeRef.current;
+    backOut.current.focus = back ?? null;
+    back?.focus();
+  }, [closeRef, setPrompt]);
+  const ref = useDialog(open, onClose, () => {
+    if (!guarded()) return false;
+    if (backOut.current.forced) {
+      backOut.current.forced = false;
+      const field = backOut.current.focus;
+      queueMicrotask(() => field?.focus());
+    } else if (latest.current.prompt) keepEditing();
+    else requestClose();
+    return true;
+  });
+  dialogRef.current = ref.current;
+  const discard = useCallback(() => {
+    setPrompt(null);
+    latest.current.onClose?.();
+  }, [setPrompt]);
+  useEffect(() => {
+    if (open && dirty && !pending) return;
+    if (!latest.current.prompt) return;
+    if (open && document.getElementById(panelId)?.contains(document.activeElement)) keepEditing();
+    else setPrompt(null);
+  }, [open, dirty, pending, panelId, keepEditing, setPrompt]);
+  useEffect(() => {
+    const el = ref.current;
+    dialogRef.current = el;
+    if (!el || !open) return;
+    const ours = (event) => event.target?.closest?.("dialog") === el;
+    const onCancel = (event) => {
+      if (!guarded()) return;
+      event.preventDefault();
+      if (latest.current.prompt) {
+        keepEditing();
+        backOut.current.forced = !event.cancelable;
+      } else requestClose();
+    };
+    const outside = (event) => !document.getElementById(panelId)?.contains(event.target);
+    let swallow = null;
+    const forget = () => {
+      swallow = null;
+    };
+    const onPointerDownCapture = (event) => {
+      swallow = latest.current.prompt && ours(event) && outside(event) ? event.target : null;
+      if (swallow) setPrompt(null);
+    };
+    const onPointerUpCapture = () => {
+      window.setTimeout(forget, 0);
+    };
+    const onClickCapture = (event) => {
+      const pressed = swallow != null && swallow === event.target;
+      swallow = null;
+      if (!pressed && !(latest.current.prompt && ours(event) && outside(event))) return;
+      event.preventDefault();
+      event.stopPropagation();
+      setPrompt(null);
+    };
+    el.addEventListener("cancel", onCancel);
+    el.addEventListener("pointerdown", onPointerDownCapture, true);
+    el.addEventListener("pointerup", onPointerUpCapture, true);
+    el.addEventListener("pointercancel", forget, true);
+    el.addEventListener("contextmenu", forget, true);
+    el.addEventListener("click", onClickCapture, true);
+    el.addEventListener("keydown", forget, true);
+    return () => {
+      el.removeEventListener("cancel", onCancel);
+      el.removeEventListener("pointerdown", onPointerDownCapture, true);
+      el.removeEventListener("pointerup", onPointerUpCapture, true);
+      el.removeEventListener("pointercancel", forget, true);
+      el.removeEventListener("contextmenu", forget, true);
+      el.removeEventListener("click", onClickCapture, true);
+      el.removeEventListener("keydown", forget, true);
+    };
+  }, [open, ref, requestClose, keepEditing, setPrompt, panelId]);
+  const onKeyDown = (event) => {
+    if (event.key !== "Escape" || event.defaultPrevented) return;
+    if (event.target.closest("dialog") !== event.currentTarget || anyAutoPopoverOpen()) return;
+    if (latest.current.prompt) {
+      event.preventDefault();
+      keepEditing();
+      return;
+    }
+    if (!guarded()) return;
+    event.preventDefault();
+    requestClose();
+  };
+  const element = dirty || prompt ? /* @__PURE__ */ jsx(
+    DiscardPrompt,
+    {
+      id: panelId,
+      prompt,
+      labels,
+      onKeepEditing: keepEditing,
+      onDismiss: () => setPrompt(null),
+      onDiscard: discard
+    }
+  ) : null;
+  const provide = (children) => /* @__PURE__ */ jsx(DialogCloseContext.Provider, { value: { requestClose, pending }, children });
+  return { ref, requestClose, onKeyDown, prompt: element, provide };
+}
+function DiscardPrompt({ id, prompt, labels, onKeepEditing, onDismiss, onDiscard }) {
+  const keepRef = useRef(null);
+  const open = prompt != null;
+  useEffect(() => {
+    const panel = document.getElementById(id);
+    if (!panel) return;
+    const shown = () => {
+      try {
+        return panel.matches(":popover-open");
+      } catch {
+        return false;
+      }
+    };
+    if (!open) {
+      if (shown()) {
+        try {
+          panel.hidePopover();
+        } catch {
+        }
+      }
+      return;
+    }
+    if (!shown()) {
+      try {
+        panel.showPopover();
+      } catch {
+      }
+    }
+    keepRef.current?.focus();
+  }, [open, id]);
+  return /* @__PURE__ */ jsxs(
+    Popover,
+    {
+      id,
+      popover: "manual",
+      anchor: prompt?.anchor ?? null,
+      placement: "bottom-end",
+      role: "alertdialog",
+      "aria-labelledby": `${id}-title`,
+      "aria-describedby": `${id}-body`,
+      className: "uix-popconfirm",
+      "data-uix-discard-prompt": "",
+      tabIndex: -1,
+      onKeyDown: (event) => {
+        if (event.key !== "Escape") return;
+        event.preventDefault();
+        event.stopPropagation();
+        onKeepEditing();
+      },
+      onBlur: (event) => {
+        const next = event.relatedTarget;
+        if (open && next && !event.currentTarget.contains(next)) onDismiss();
+      },
+      children: [
+        /* @__PURE__ */ jsx("div", { id: `${id}-title`, className: "uix-popconfirm__title", children: labels.title }),
+        /* @__PURE__ */ jsx("div", { id: `${id}-body`, className: "uix-popconfirm__body", children: labels.description }),
+        /* @__PURE__ */ jsxs("div", { className: "uix-popconfirm__actions", children: [
+          /* @__PURE__ */ jsx(Button, { ref: keepRef, type: "button", size: "sm", onClick: onKeepEditing, children: labels.keepEditing }),
+          /* @__PURE__ */ jsx(Button, { type: "button", size: "sm", variant: "danger", onClick: onDiscard, children: labels.discard })
+        ] })
+      ]
+    }
+  );
+}
+export {
+  DialogClose,
+  useGuardedDialog
+};

package/dist/components/Drawer.d.ts

@@ -1,15 +1,31 @@
 import * as react from 'react';
 import { HTMLAttributes, ReactNode } from 'react';
+import { DiscardPromptLabels } from './DiscardPrompt.js';
+import './Button.js';
+import '../link.js';
+import './Kbd.js';
 
 interface DrawerProps extends Omit<HTMLAttributes<HTMLDialogElement>, 'title'> {
     /** TENSOR RX-125 (UIX-04): translatable; English default. */
     closeLabel?: string;
     open: boolean;
     onClose?: () => void;
+    /**
+     * The drawer holds input that is not saved (HAR-2029), e.g. react-hook-form's
+     * `formState.isDirty`. Escape, the close button, a backdrop click and a `DialogClose` then open
+     * an anchored "Discard changes?" step with focus on "Keep editing" instead of calling `onClose`;
+     * "Discard" calls it. A clean drawer closes at once. A `<form method="dialog">` submit counts
+     * as a way out too: save with your own handler instead.
+     */
+    dirty?: boolean;
+    /** A save is in flight: Escape, the close button, a backdrop click and a `DialogClose` do nothing. */
+    pending?: boolean;
+    /** The words of the discard step. Default: `UixLabelsProvider` `discardPrompt`, then English. */
+    discardLabels?: Partial<DiscardPromptLabels>;
     /**
      * A click on the dimmed backdrop calls `onClose`, like Escape and the close button
-     * (TENSOR HAR-547). Pass `false` on a drawer that holds unsaved form input, so a stray click
-     * can't discard it; Escape and the close button still close. Default `true`.
+     * (TENSOR HAR-547), or asks first when the drawer is `dirty`. `false` ignores backdrop clicks
+     * altogether. Default `true`.
      */
     dismissOnBackdrop?: boolean;
     /**
@@ -21,6 +37,6 @@ interface DrawerProps extends Omit<HTMLAttributes<HTMLDialogElement>, 'title'> {
     children?: ReactNode;
     footer?: ReactNode;
 }
-declare function Drawer({ open, onClose, dismissOnBackdrop, side, title, children, footer, closeLabel: closeLabelProp, className, onClick, ...rest }: DrawerProps): react.JSX.Element;
+declare function Drawer({ open, onClose, dirty, pending, discardLabels, dismissOnBackdrop, side, title, children, footer, closeLabel: closeLabelProp, className, onClick, onKeyDown, ...rest }: DrawerProps): react.JSX.Element;
 
 export { Drawer, type DrawerProps };

package/dist/components/Drawer.js

@@ -1,32 +1,71 @@
 "use client";
-import { jsx, jsxs } from "react/jsx-runtime";
-import { useId } from "react";
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+import { useId, useRef } from "react";
 import { cx } from "../cx.js";
 import { useUixLabels } from "../labels-context.js";
-import { useDialog } from "../hooks/useDialog.js";
 import { backdropDismiss } from "../hooks/backdropDismiss.js";
+import { useGuardedDialog } from "./DiscardPrompt.js";
 const CloseIcon = () => /* @__PURE__ */ jsx("svg", { width: "16", height: "16", viewBox: "0 0 16 16", fill: "none", stroke: "currentColor", strokeWidth: 1.5, strokeLinecap: "round", "aria-hidden": "true", children: /* @__PURE__ */ jsx("path", { d: "M4 4l8 8M12 4l-8 8" }) });
-function Drawer({ open, onClose, dismissOnBackdrop = true, side = "end", title, children, footer, closeLabel: closeLabelProp, className, onClick, ...rest }) {
+function Drawer({
+  open,
+  onClose,
+  dirty = false,
+  pending = false,
+  discardLabels,
+  dismissOnBackdrop = true,
+  side = "end",
+  title,
+  children,
+  footer,
+  closeLabel: closeLabelProp,
+  className,
+  onClick,
+  onKeyDown,
+  ...rest
+}) {
   const uixLabels = useUixLabels();
   const closeLabel = closeLabelProp ?? uixLabels.drawer?.close ?? "Close drawer";
-  const ref = useDialog(open, onClose);
+  const closeRef = useRef(null);
+  const guard = useGuardedDialog({ open, onClose, dirty, pending, labels: discardLabels, closeRef });
   const titleId = useId();
-  return /* @__PURE__ */ jsxs("dialog", { ref, className: cx("uix-drawer", side !== "end" && `uix-drawer--${side}`, className), "aria-labelledby": title ? titleId : void 0, ...rest, onClick: backdropDismiss(onClose, onClick, dismissOnBackdrop), children: [
-    (title != null || onClose) && /* @__PURE__ */ jsxs("div", { className: "uix-drawer__header", children: [
-      title && /* @__PURE__ */ jsx("h2", { id: titleId, style: { fontWeight: 600, fontSize: "var(--uix-text-h3)", fontFamily: "inherit", letterSpacing: "inherit", lineHeight: "inherit" }, children: title }),
-      onClose && /* @__PURE__ */ jsx(
-        "button",
-        {
-          style: { marginLeft: "auto", border: 0, background: "transparent", color: "var(--uix-text-muted)", cursor: "pointer", width: 30, height: 30, display: "grid", placeItems: "center", borderRadius: "var(--uix-radius-sm)" },
-          onClick: onClose,
-          "aria-label": closeLabel,
-          children: /* @__PURE__ */ jsx(CloseIcon, {})
-        }
-      )
-    ] }),
-    children != null && /* @__PURE__ */ jsx("div", { className: "uix-drawer__body", children }),
-    footer != null && /* @__PURE__ */ jsx("div", { className: "uix-drawer__footer", children: footer })
-  ] });
+  return /* @__PURE__ */ jsxs(
+    "dialog",
+    {
+      ref: guard.ref,
+      className: cx("uix-drawer", side !== "end" && `uix-drawer--${side}`, className),
+      "aria-labelledby": title ? titleId : void 0,
+      ...rest,
+      onClick: backdropDismiss(onClose && (() => guard.requestClose()), onClick, dismissOnBackdrop),
+      onKeyDown: (event) => {
+        onKeyDown?.(event);
+        guard.onKeyDown(event);
+      },
+      children: [
+        guard.provide(
+          /* @__PURE__ */ jsxs(Fragment, { children: [
+            (title != null || onClose) && /* @__PURE__ */ jsxs("div", { className: "uix-drawer__header", children: [
+              title && /* @__PURE__ */ jsx("h2", { id: titleId, style: { fontWeight: 600, fontSize: "var(--uix-text-h3)", fontFamily: "inherit", letterSpacing: "inherit", lineHeight: "inherit" }, children: title }),
+              onClose && /* @__PURE__ */ jsx(
+                "button",
+                {
+                  ref: closeRef,
+                  type: "button",
+                  className: "uix-drawer__close",
+                  onClick: () => guard.requestClose(),
+                  "aria-label": closeLabel,
+                  "aria-disabled": pending || void 0,
+                  children: /* @__PURE__ */ jsx(CloseIcon, {})
+                }
+              )
+            ] }),
+            children != null && /* @__PURE__ */ jsx("div", { className: "uix-drawer__body", children }),
+            footer != null && /* @__PURE__ */ jsx("div", { className: "uix-drawer__footer", children: footer })
+          ] })
+        ),
+        guard.prompt
+      ]
+    }
+  );
 }
 export {
   Drawer

package/dist/components/EditorialHome.d.ts

@@ -9,7 +9,7 @@ interface PageIntroProps extends Omit<HTMLAttributes<HTMLElement>, 'title'> {
     lede?: ReactNode;
     /** Label shown above the search well. */
     searchLabel?: ReactNode;
-    /** The search well itself (form + `.uix-searchbar` markup, or `SearchBar`-style composition). */
+    /** The search well itself: a `SearchBar size="lg"` (HAR-2030), or `.uix-searchbar` markup. */
     search?: ReactNode;
     /** Shortcut buttons; rendered inside the `.uix-shortcut-grid` full-width row. */
     shortcuts?: ReactNode;

package/dist/components/Field.d.ts

@@ -5,6 +5,12 @@ interface FieldProps {
     label?: string;
     hint?: string;
     error?: string;
+    /**
+     * A value to check, not an error (HAR-1814): shown under the control in the warning colour,
+     * announced politely, and marks the control `data-warning`. `error` wins over it; it wins
+     * over `success` and `hint`.
+     */
+    warning?: string;
     success?: string;
     required?: boolean;
     /**
@@ -19,6 +25,6 @@ interface FieldProps {
     className?: string;
     htmlFor?: string;
 }
-declare function Field({ label, hint, error, success, required, help, helpLabel, children, className, htmlFor }: FieldProps): react.JSX.Element;
+declare function Field({ label, hint, error, warning, success, required, help, helpLabel, children, className, htmlFor }: FieldProps): react.JSX.Element;
 
 export { Field, type FieldProps };

package/dist/components/Field.js

@@ -3,16 +3,17 @@ import { cloneElement, isValidElement, useId } from "react";
 import { cx } from "../cx.js";
 import { InfoTip } from "./InfoTip.js";
 import { hasHelp, helpLabelFor } from "../info-tip-model.js";
-function Field({ label, hint, error, success, required, help, helpLabel, children, className, htmlFor }) {
+function Field({ label, hint, error, warning, success, required, help, helpLabel, children, className, htmlFor }) {
   const uid = useId();
   const msgId = `${uid}-msg`;
-  const describedBy = error || success || hint ? msgId : void 0;
+  const describedBy = error || warning || success || hint ? msgId : void 0;
   const controlId = isValidElement(children) ? children.props.id ?? `${uid}-ctl` : void 0;
   const control = isValidElement(children) ? cloneElement(children, {
     id: controlId,
     "aria-describedby": [children.props["aria-describedby"], describedBy].filter(Boolean).join(" ") || void 0,
     "aria-invalid": error ? true : children.props["aria-invalid"],
-    "aria-required": children.props["aria-required"] ?? (required || void 0)
+    "aria-required": children.props["aria-required"] ?? (required || void 0),
+    "data-warning": children.props["data-warning"] ?? (warning && !error || void 0)
   }) : children;
   return /* @__PURE__ */ jsxs("div", { className: cx("uix-field", className), children: [
     label && hasHelp(help) ? /* @__PURE__ */ jsxs("div", { className: "uix-field__label-row", children: [
@@ -21,7 +22,7 @@ function Field({ label, hint, error, success, required, help, helpLabel, childre
       required && /* @__PURE__ */ jsx("span", { className: "uix-field__required", "aria-hidden": "true", children: "*" })
     ] }) : label && /* @__PURE__ */ jsx("label", { className: "uix-field__label", htmlFor: htmlFor ?? controlId, "data-required": required || void 0, children: label }),
     control,
-    /* @__PURE__ */ jsx("div", { className: "uix-field__msg", id: msgId, children: error ? /* @__PURE__ */ jsx("span", { className: "uix-field__error", role: "alert", children: error }) : success ? /* @__PURE__ */ jsx("span", { className: "uix-field__success", role: "status", children: success }) : hint ? /* @__PURE__ */ jsx("span", { className: "uix-field__hint", children: hint }) : null })
+    /* @__PURE__ */ jsx("div", { className: "uix-field__msg", id: msgId, children: error ? /* @__PURE__ */ jsx("span", { className: "uix-field__error", role: "alert", children: error }) : warning ? /* @__PURE__ */ jsx("span", { className: "uix-field__warning", role: "status", children: warning }) : success ? /* @__PURE__ */ jsx("span", { className: "uix-field__success", role: "status", children: success }) : hint ? /* @__PURE__ */ jsx("span", { className: "uix-field__hint", children: hint }) : null })
   ] });
 }
 export {