@eifi1/ui-kit 0.51.6 → 0.52.0

package/src/components/autocomplete.tsx

@@ -1,7 +1,8 @@
-import { Fragment, useId, useRef, useState } from "react";
+import { useId, useRef, useState } from "react";
 import type { ComponentPropsWithoutRef, ReactNode, Ref } from "react";
 import { createPortal } from "react-dom";
 import { cn } from "../lib/cn";
+import { hasContent } from "../lib/presence";
 import { FIELD_BASE, FIELD_FLOATING_PAD, FIELD_INVALID } from "./field-base";
 import { Spinner } from "./spinner";
 import { useAnchoredPanel } from "../hooks/use-anchored-panel";
@@ -10,10 +11,12 @@ import { isImeEnter } from "../lib/ime";
 import { isQuietFocus } from "../lib/quiet-focus";
 import { useAnchorDir } from "./use-anchor-dir";
 import {
+  anchoredHeadingClass,
   ComboboxFieldLabel,
   DISABLED_ROW_CLASS,
   endHintRowProps,
-  GROUP_HEADING_STICKY,
+  GroupedOptions,
+  groupRuns,
   isOptionEnabled,
   stepEnabled,
   SUGGESTION_LIST_CLASS,
@@ -293,7 +296,7 @@ export function Autocomplete<V extends string | number = string>(props: Autocomp
     active: live,
   });
 
-  const hasStatus = status !== undefined && status !== null && status !== false && status !== "";
+  const hasStatus = hasContent(status);
   // The visible line under the rows. Nothing below `minChars` unless the caller has
   // something to say — an empty field opening a box that says "type more" is noise.
   const statusLine: ReactNode = hasStatus
@@ -559,75 +562,66 @@ export function Autocomplete<V extends string | number = string>(props: Autocomp
                 aria-labelledby={labelledBy}
                 className="min-h-0 flex-1 overflow-y-auto py-1"
               >
-                {results.map((o, i) => {
-                  const startsGroup = o.group != null && o.group !== results[i - 1]?.group;
-                  return (
-                    // Keyed by group AND value, as in the core panel: an option may
-                    // appear once per group.
-                    <Fragment key={`${o.group ?? ""}|${String(o.value)}`}>
-                      {startsGroup && (
-                        <li
-                          role="presentation"
-                          className={cn(
-                            GROUP_HEADING_STICKY,
-                            "px-3 pb-0.5 pt-2 text-caption font-semibold uppercase tracking-wide text-muted first:pt-1",
-                          )}
-                        >
-                          {o.group}
-                        </li>
-                      )}
-                      <li role="presentation">
-                        <button
-                          type="button"
-                          id={optionId(i)}
-                          role="option"
-                          // CHOSEN, never "highlighted" — the family's rule. This
-                          // field holds no value, so the only row that can be chosen
-                          // is the one whose label the text already is.
-                          aria-selected={fillOnSelect && o.label === value}
-                          // Listed, announced as unavailable, never taken: `take`
-                          // refuses it and the arrows pass it over.
-                          aria-disabled={o.disabled || undefined}
-                          tabIndex={-1}
-                          onClick={() => take(o)}
-                          onMouseEnter={() => {
-                            if (!o.disabled) setActive(i);
-                          }}
-                          className={cn(
-                            // The family's suggestion row (DUP-4): it hand-rolled its
-                            // own with a plain `truncate`, so a long address was cut at
-                            // Large, where Combobox's rows wrap (text size §10.17, T1).
-                            // A flex row here, for the icon and the two lines.
-                            suggestionRowClass(i === active && !o.disabled),
-                            "flex items-center gap-2",
-                            small && "py-1 text-xs",
-                            o.disabled && DISABLED_ROW_CLASS,
-                            o.group != null && "ps-6",
-                          )}
-                        >
-                          {o.icon && (
-                            <span aria-hidden className="shrink-0 text-muted">
-                              {o.icon}
+                {/* One heading per group, a `role="group"` it names, as in the core panel
+                    (refactor audit 2026-10-30, INP-8), drawn by the same renderer: an
+                    option may appear once per group. */}
+                <GroupedOptions
+                  runs={groupRuns(results, (o) => o.group)}
+                  listboxId={listboxId}
+                  rowKey={(o) => String(o.value)}
+                  headingClassName={(run) => anchoredHeadingClass(run)}
+                  row={(o, i) => (
+                    <li role="presentation">
+                      <button
+                        type="button"
+                        id={optionId(i)}
+                        role="option"
+                        // CHOSEN, never "highlighted" — the family's rule. This
+                        // field holds no value, so the only row that can be chosen
+                        // is the one whose label the text already is.
+                        aria-selected={fillOnSelect && o.label === value}
+                        // Listed, announced as unavailable, never taken: `take`
+                        // refuses it and the arrows pass it over.
+                        aria-disabled={o.disabled || undefined}
+                        tabIndex={-1}
+                        onClick={() => take(o)}
+                        onMouseEnter={() => {
+                          if (!o.disabled) setActive(i);
+                        }}
+                        className={cn(
+                          // The family's suggestion row (DUP-4): it hand-rolled its
+                          // own with a plain `truncate`, so a long address was cut at
+                          // Large, where Combobox's rows wrap (text size §10.17, T1).
+                          // A flex row here, for the icon and the two lines.
+                          suggestionRowClass(i === active && !o.disabled),
+                          "flex items-center gap-2",
+                          small && "py-1 text-xs",
+                          o.disabled && DISABLED_ROW_CLASS,
+                          o.group && "ps-6",
+                        )}
+                      >
+                        {o.icon && (
+                          <span aria-hidden className="shrink-0 text-muted">
+                            {o.icon}
+                          </span>
+                        )}
+                        <span className="min-w-0 flex-1">
+                          <span className="block truncate-until-large text-primary">{o.label}</span>
+                          {o.sublabel && (
+                            <span
+                              className={cn(
+                                "block truncate-until-large text-placeholder",
+                                small ? "text-caption" : "text-xs",
+                              )}
+                            >
+                              {o.sublabel}
                             </span>
                           )}
-                          <span className="min-w-0 flex-1">
-                            <span className="block truncate-until-large text-primary">{o.label}</span>
-                            {o.sublabel && (
-                              <span
-                                className={cn(
-                                  "block truncate-until-large text-placeholder",
-                                  small ? "text-caption" : "text-xs",
-                                )}
-                              >
-                                {o.sublabel}
-                              </span>
-                            )}
-                          </span>
-                        </button>
-                      </li>
-                    </Fragment>
-                  );
-                })}
+                        </span>
+                      </button>
+                    </li>
+                  )}
+                />
               </ul>
             )}
             {statusLine !== null && (

package/src/components/bulk-action-bar.tsx

@@ -1,5 +1,5 @@
 import { useEffect, useLayoutEffect, useRef, useState } from "react";
-import type { ComponentPropsWithRef, CSSProperties, KeyboardEvent, ReactNode } from "react";
+import type { ComponentPropsWithRef, CSSProperties, FocusEvent, KeyboardEvent, ReactNode, RefObject } from "react";
 import { X } from "lucide-react";
 
 import { cn } from "../lib/cn";
@@ -8,6 +8,8 @@ import { useKitLabels, type LabelOverride } from "../i18n/kit-labels";
 import { useAnnounce } from "../hooks/use-announce";
 import { useBreakpoint } from "../hooks/use-breakpoint";
 import { OVERLAY_EXIT_MS, skipsExitAnimation } from "../hooks/use-close-transition";
+import { focusFirst, focusIsLost, whenFocusLeftForNothing } from "../lib/focus-left";
+import { hasContent } from "../lib/presence";
 import { Button } from "./button";
 import { IconButton } from "./icon-button";
 import { DEFAULT_BULK_ACTION_BAR_LABELS } from "./bulk-action-bar-labels";
@@ -124,6 +126,16 @@ export interface BulkActionBarProps extends Omit<ComponentPropsWithRef<"div">, "
   panel?: ReactNode;
   /** Default: `bulkActionBar` from the {@link UiKitProvider}, else English. */
   labels?: LabelOverride<BulkActionBarLabels>;
+  /**
+   * Where the focus goes when the bar leaves while it holds it — after Clear, or an action
+   * that empties the selection (0.52, refactor audit 2026-10-30, DSP-15). Without it, the
+   * control the focus came into the bar from (the row's box, say), if that is still on the
+   * page; with it, this first. Pass one where the selection takes that control with it — a
+   * bulk delete removes the rows whose boxes were ticked: the table, the list's heading,
+   * the "Select" button that entered selection mode. A bar that leaves without the focus
+   * in it moves nothing.
+   */
+  returnFocusRef?: RefObject<HTMLElement | null>;
 }
 
 /** Where the floating bar sits: clear of the phone nav and of the home indicator,
@@ -192,10 +204,12 @@ export function BulkActionBar({
   open,
   panel,
   labels: labelsProp,
+  returnFocusRef,
   className,
   style,
   onKeyDown,
   onFocus,
+  onBlur,
   ...rest
 }: BulkActionBarProps) {
   const labels = useKitLabels("bulkActionBar", DEFAULT_BULK_ACTION_BAR_LABELS, labelsProp);
@@ -245,6 +259,51 @@ export function BulkActionBar({
     rove(barRef.current, active);
   });
 
+  // Leaving with the focus in it (refactor audit 2026-10-30, DSP-15): the bar goes `inert`,
+  // which blurs the control it holds, then unmounts — and the focus fell to <body>; on a
+  // phone VoiceOver's cursor jumped to the top of the page (keksdose's register). Noted on
+  // the bar's outermost element, so the `panel`'s fields count: where the focus came in
+  // from (the first entry since the bar showed, replaced once that control is gone), and
+  // whether it is in the bar. Focus that leaves for nothing because the page took it —
+  // inert, a removal — still counts as in it; a real element elsewhere takes it out, and
+  // so does a click on the page that left it nowhere (0.52 code review,
+  // bulk-action-bar.tsx: the note outlived it, and the bar's hide long after — the last row
+  // unticked with the pointer — pulled the focus and the scroll back to the row's box).
+  const cameFrom = useRef<HTMLElement | null>(null);
+  const holdsFocus = useRef(false);
+  const trackFocus = {
+    onFocus: (e: FocusEvent<HTMLDivElement>) => {
+      holdsFocus.current = true;
+      const from = e.relatedTarget;
+      if (from instanceof HTMLElement && !e.currentTarget.contains(from) && !cameFrom.current?.isConnected)
+        cameFrom.current = from;
+    },
+    onBlur: (e: FocusEvent<HTMLDivElement>) => {
+      onBlur?.(e);
+      const to = e.relatedTarget;
+      if (to instanceof Element && !e.currentTarget.contains(to)) holdsFocus.current = false;
+      whenFocusLeftForNothing(e, () => {
+        holdsFocus.current = false;
+      });
+    },
+  };
+  // The commit that hides the bar: the focus goes back while the control holding it is
+  // still in place — before `inert` takes it, or, with no exit to play, before <body> does.
+  const wasShown = useRef(shown);
+  useLayoutEffect(() => {
+    if (wasShown.current === shown) return;
+    wasShown.current = shown;
+    const from = cameFrom.current;
+    const held = holdsFocus.current;
+    cameFrom.current = null;
+    holdsFocus.current = false;
+    if (shown) return;
+    // The outermost element: the toolbar, or with a `panel` the surface round both.
+    const surface = barRef.current?.closest("[data-bulk-action-bar]");
+    const inBar = !!surface && surface.contains(document.activeElement);
+    if (inBar || (held && focusIsLost())) focusFirst([returnFocusRef?.current, from]);
+  }, [shown, returnFocusRef]);
+
   const handleKeyDown = (e: KeyboardEvent<HTMLDivElement>) => {
     onKeyDown?.(e);
     if (e.defaultPrevented || ownsArrows(e.target as Element)) return;
@@ -279,7 +338,9 @@ export function BulkActionBar({
     </Button>
   );
 
-  const hasPanel = panel !== undefined && panel !== null && panel !== false;
+  // `hasContent` (refactor audit 2026-10-30, DUP-14): an empty-string panel drew an empty
+  // bordered strip under the bar.
+  const hasPanel = hasContent(panel);
   // The surface — where the bar sits and what it looks like — and the toolbar row's
   // own layout. Without a panel they are one element, exactly as before 0.11.0; with
   // one the surface wraps the row and the panel, so both share its tint and position.
@@ -314,6 +375,7 @@ export function BulkActionBar({
       onKeyDown={handleKeyDown}
       onFocus={(e) => {
         onFocus?.(e);
+        if (!hasPanel) trackFocus.onFocus(e);
         // Clicking a control is using it: the stop follows the pointer too.
         const hit = itemsOf(barRef.current).find((el) => el === e.target);
         if (hit) {
@@ -321,6 +383,7 @@ export function BulkActionBar({
           rove(barRef.current, active);
         }
       }}
+      onBlur={hasPanel ? undefined : trackFocus.onBlur}
       style={hasPanel ? undefined : surfaceStyle}
       className={hasPanel ? rowClass : cn(rowClass, surfaceClass, className)}
     >
@@ -340,8 +403,13 @@ export function BulkActionBar({
     <>
       <span {...regionProps} />
       {hasPanel ? (
+        /* eslint-disable-next-line jsx-a11y/no-static-element-interactions -- the focus is
+           only noted here (DSP-15): where it came from, whether it is in the bar; the
+           controls are the toolbar's and the panel's own. */
         <div
           {...rest}
+          onFocus={trackFocus.onFocus}
+          onBlur={trackFocus.onBlur}
           data-bulk-action-bar={variant}
           inert={!shown || undefined}
           style={surfaceStyle}

package/src/components/button-look.ts

@@ -9,8 +9,8 @@ import type { KitLinkComponent, KitLinkProps } from "../i18n/kit-labels";
  * and its router link. Both now draw from this module, which renders nothing, so neither
  * imports the other.
  *
- * Public through ./ui by name: `buttonClasses`, `TOUCH_TARGET_LARGE` and the four types.
- * The other exports are the two buttons' shared parts (`@internal`).
+ * Public through the barrel (src/index.ts) by name: `buttonClasses`, `TOUCH_TARGET_LARGE`
+ * and the four types. The other exports are the two buttons' shared parts (`@internal`).
  */
 
 /**
@@ -24,9 +24,9 @@ import type { KitLinkComponent, KitLinkProps } from "../i18n/kit-labels";
  *   (theme/palette-derive.ts), which no button paints.
  * - `secondary`: an outline. `ghost`: text or glyph only. `danger`: solid `--danger`,
  *   for an action that destroys something. `link`: a text link that acts (a `<button>`).
- * - `primary` and `brand` are **deprecated** aliases of `default` and `accent` (0.49,
- *   same look; a development build warns once per name). They are removed in 0.51, and
- *   `primary` will not come back with another meaning.
+ *
+ * 0.49's `primary` and `brand` (aliases of `default` and `accent`) were removed in 0.51;
+ * `primary` will not come back with another meaning.
  */
 export type ButtonVariant = "default" | "accent" | "secondary" | "ghost" | "danger" | "link";
 

package/src/components/button.tsx

@@ -25,8 +25,8 @@ import type { ButtonSize, ButtonTone, ButtonVariant } from "./button-look";
  */
 export interface ButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
   /** `default` (the quiet action, what a Button without `variant` draws), `accent` (the
-   *  strong call to action, solid brand), `secondary`, `ghost`, `danger` or `link`.
-   *  `primary` / `brand` are deprecated aliases of `default` / `accent`. See {@link ButtonVariant}. */
+   *  strong call to action, solid brand), `secondary`, `ghost`, `danger` or `link`. See
+   *  {@link ButtonVariant}. */
   variant?: ButtonVariant;
   /** `md` (default) is the page's action button. `sm` is the compact one — 12px text
    *  and `px-2 py-1` — for the secondary actions in a toolbar, a card header or a

package/src/components/calculator.tsx

@@ -1,4 +1,5 @@
-import { useEffect, useMemo, useRef, useState } from "react";
+import { useEffect, useEffectEvent, useMemo, useRef, useState } from "react";
+import type { RefObject } from "react";
 import { Calculator as CalculatorIcon, Delete } from "lucide-react";
 import { Popover } from "./popover";
 import { cn } from "../lib/cn";
@@ -30,6 +31,24 @@ interface CalculatorButtonProps {
    * the one argument and ignore this.
    */
   onChange: (value: string, expression?: string) => void;
+  /**
+   * Called ONCE per calculator session, with the result the host should keep: on "="
+   * (the key, or Enter in the display), and when the panel closes — Escape, a press
+   * outside, the trigger — on a result `onChange` reported after the last commit. Never
+   * per keystroke: `onChange` is the live channel, this is the one to save on.
+   *
+   * Not called when the button goes away with its panel open (a lock or `disabled`
+   * arriving, the field unmounting): those say the value must not move, and the result
+   * stays where `onChange` put it.
+   *
+   * Refactor audit 2026-10-30, INP-1: the pad had no commit point of its own, and the
+   * two field engines guessed in opposite directions. NumberInput never committed a
+   * result, so Kurvenschmiede's dialogs saved the number from before the calculation;
+   * AmountInput committed every keystroke that resolved, so "100+50" saved 105 on its way
+   * to 150, and keksdose's threshold field, `disabled` while it saves, lost its pad to the
+   * first of them.
+   */
+  onCommit?: (value: string) => void;
   className?: string;
   /** The trigger's accessible name; wins over `calculator.open` from the provider. */
   "aria-label"?: string;
@@ -89,10 +108,13 @@ function seed(initial: string): string {
 function CalculatorPanel({
   initial,
   onChange,
+  onEquals,
   labels,
 }: {
   initial: string;
   onChange: (value: string, expression?: string) => void;
+  /** "=" was pressed on a result: the session's commit point. */
+  onEquals: () => void;
   labels: CalculatorLabels;
 }) {
   const [expr, setExpr] = useState(() => seed(initial));
@@ -132,6 +154,7 @@ function CalculatorPanel({
     const out = formatResult(result);
     setExpr(out);
     onChange(out, text);
+    onEquals();
   };
 
   return (
@@ -213,15 +236,66 @@ function CalculatorPanel({
   );
 }
 
+/**
+ * The trigger, and the place a session ends. The render in which `open` turns false is
+ * the panel closing, however it closed — Escape, a press outside, this button — and
+ * that is when a result the pad left unsettled is committed. A component of its own
+ * because `open` lives in Popover and reaches only the trigger.
+ *
+ * Not the panel's unmount: the panel also goes when a lock or `disabled` takes the
+ * calculator away, and nothing may commit then. Those unmount this button with it, so no
+ * render ever sees `open` turn false.
+ */
+function CalculatorTrigger({
+  open,
+  onToggle,
+  onClosed,
+  buttonRef,
+  label,
+  className,
+}: {
+  open: boolean;
+  onToggle: () => void;
+  onClosed: () => void;
+  buttonRef: RefObject<HTMLButtonElement | null>;
+  label: string;
+  className?: string;
+}) {
+  const closed = useEffectEvent(onClosed);
+  const wasOpen = useRef(open);
+  useEffect(() => {
+    if (wasOpen.current && !open) closed();
+    wasOpen.current = open;
+  }, [open]);
+  return (
+    <button
+      ref={buttonRef}
+      type="button"
+      tabIndex={-1}
+      onClick={onToggle}
+      aria-label={label}
+      aria-expanded={open}
+      className={cn(
+        "flex items-center justify-center text-placeholder transition-colors hover:text-secondary",
+        className,
+      )}
+    >
+      <CalculatorIcon className="size-4" />
+    </button>
+  );
+}
+
 /**
  * A calculator icon that opens a small keypad popover anchored to its host
  * field. Designed as a trailing-edge adornment: render it inside the field's
  * `relative` wrapper, positioned absolutely. The keypad seeds from the current
- * field value and writes evaluated results straight back through `onChange`.
+ * field value and writes evaluated results straight back through `onChange`, and
+ * commits the session once through `onCommit`.
  */
 export function CalculatorButton({
   value,
   onChange,
+  onCommit,
   className,
   "aria-label": ariaLabel,
   labels: labelsProp,
@@ -233,28 +307,35 @@ export function CalculatorButton({
     [ariaLabel, labelsProp],
   );
   const labels = useKitLabels("calculator", DEFAULT_CALCULATOR_LABELS, fromProps);
+  // The last result `onChange` reported that no commit has covered yet — what closing
+  // the panel commits. Written by the pad's handlers and read when it closes; never
+  // rendered, so a ref.
+  const unsettled = useRef<string | null>(null);
+  const change = (next: string, expression?: string) => {
+    unsettled.current = next;
+    onChange(next, expression);
+  };
+  const settle = () => {
+    const next = unsettled.current;
+    unsettled.current = null;
+    if (next !== null) onCommit?.(next);
+  };
   return (
     <Popover
       width="14rem"
       labels={{ panel: labels.panel }}
       trigger={({ open, toggle, ref }) => (
-        <button
-          ref={ref}
-          type="button"
-          tabIndex={-1}
-          onClick={toggle}
-          aria-label={labels.open}
-          aria-expanded={open}
-          className={cn(
-            "flex items-center justify-center text-placeholder transition-colors hover:text-secondary",
-            className,
-          )}
-        >
-          <CalculatorIcon className="size-4" />
-        </button>
+        <CalculatorTrigger
+          open={open}
+          onToggle={toggle}
+          onClosed={settle}
+          buttonRef={ref}
+          label={labels.open}
+          className={className}
+        />
       )}
     >
-      {() => <CalculatorPanel initial={value} onChange={onChange} labels={labels} />}
+      {() => <CalculatorPanel initial={value} onChange={change} onEquals={settle} labels={labels} />}
     </Popover>
   );
 }

package/src/components/chart-edge.ts

@@ -1,7 +1,8 @@
 // The live side of `chartEdge` (theme/chart-palette.ts): which colours a FILLED mark is
 // painted with and which grounds it sits on, read off <html> as the page resolves them —
 // so the 1px ink edge follows a theme toggle and a palette switch without the chart
-// knowing either store. Shared by SeriesChart (bars, areas) and Treemap (tiles).
+// knowing either store. And WHETHER a mark gets one: `useEdgesInForce`, the contrast
+// setting's switch. Shared by SeriesChart (bars, areas) and Treemap (tiles).
 import { useCallback, useSyncExternalStore } from "react";
 import { chartEdge } from "../theme/chart-palette";
 import { parseHex } from "../theme/color";
@@ -71,3 +72,35 @@ export function useChartEdge(): (fill: string | undefined) => string | undefined
     [snapshot],
   );
 }
+
+/**
+ * How filled marks are parted — see `TreemapProps.edges` (0.51.6, keksdose dev #642).
+ * `"auto"`: `"uniform"` at Standard contrast, `"contrast"` while More contrast is in force.
+ */
+export type ChartEdges = "auto" | "uniform" | "contrast";
+
+// `<html data-contrast>`, followed live: what `"auto"` keys on. Read here rather than
+// through theme/contrast, whose store would come into the chart entry with it.
+function subscribeContrast(onChange: () => void): () => void {
+  if (typeof MutationObserver === "undefined" || typeof document === "undefined") return () => {};
+  const observer = new MutationObserver(onChange);
+  observer.observe(document.documentElement, { attributes: true, attributeFilter: ["data-contrast"] });
+  return () => observer.disconnect();
+}
+const readMoreContrast = () =>
+  typeof document !== "undefined" && document.documentElement.getAttribute("data-contrast") === "more";
+
+/**
+ * The edges a filled mark draws: `"auto"` resolved against the contrast in force, live.
+ *
+ * Under `"contrast"` a mark whose hue is under 3:1 against the ground gets the 1px ink
+ * edge ({@link useChartEdge}); under `"uniform"` none does. The tiles took this rule in
+ * 0.51.6 (#642: "The borders do not look nice when changing from tile to tile"), and
+ * SeriesChart's bars and areas in 0.52 (refactor audit 2026-10-30, DSP-18, Marcel's
+ * decision 3): at Standard contrast the edge fell on 5 of 8 hues in light, and in dark on
+ * chart-5 and chart-7 alone — the same unevenness, in a bar chart.
+ */
+export function useEdgesInForce(edges: ChartEdges = "auto"): "uniform" | "contrast" {
+  const more = useSyncExternalStore(subscribeContrast, readMoreContrast, () => false);
+  return edges === "auto" ? (more ? "contrast" : "uniform") : edges;
+}

package/src/components/chart-figure.tsx

@@ -0,0 +1,35 @@
+// A chart's accessible description — internal, not exported from the barrel.
+//
+// A chart is a `role="figure"` named by its `aria-label` and described by a sentence of
+// what it shows (0.52, refactor audit 2026-10-30, DSP-5). SeriesChart and Treemap each
+// built the `hidden` sentence and the `aria-describedby` that points at it, and already
+// differed: Treemap kept a caller's own ids, SeriesChart had none to keep. Both put the
+// sentence AFTER the figure, as its sibling, so the chart stopped being its parent's last
+// child and a stack's `space-y-*` or `divide-y` gave it a margin or a rule underneath (0.52
+// code review, deep, charts, findings 7 and 14). One copy now, rendered inside the root.
+import { useId, type ReactNode } from "react";
+
+export interface FigureDescription {
+  /** The root's `aria-describedby`: the caller's own ids, then the description's. */
+  describedBy: string | undefined;
+  /** The description, to render INSIDE the root; `null` when there is none. */
+  node: ReactNode;
+}
+
+/**
+ * The description of a figure, and the `aria-describedby` that reads it — after the
+ * caller's own ids (`describedBy`), which it keeps. The sentence is `hidden`: it is read
+ * through the reference, never a second time in browse mode, and takes no room.
+ */
+export function useFigureDescription(description: string | undefined, describedBy?: string): FigureDescription {
+  const id = useId();
+  if (!description) return { describedBy, node: null };
+  return {
+    describedBy: describedBy ? `${describedBy} ${id}` : id,
+    node: (
+      <span id={id} hidden>
+        {description}
+      </span>
+    ),
+  };
+}

package/src/components/chart-zoom-core.tsx

@@ -466,7 +466,6 @@ export function withChartZoom<P extends ZoomTarget>(Chart: ComponentType<P>) {
         <ZoomLayer
           axisIds={axes.map((axis) => axis.id)}
           only={only}
-          label={labels.zoomHint}
           onZoom={(selection) => {
             const next = zoomAfter(state, selection, source);
             if (next.x !== xWindow) setXWindow(next.x);
@@ -506,17 +505,20 @@ export function withChartZoom<P extends ZoomTarget>(Chart: ComponentType<P>) {
  * A transparent rectangle over the plot area that reads the drag. It does NOT stop the
  * event: recharts drives its tooltip from the same pointer move bubbling up to its own
  * wrapper, so swallowing it here would trade the tooltip for the zoom.
+ *
+ * Nothing to assistive technology (0.52, refactor audit 2026-10-30, DSP-5): it was a
+ * `role="application"` named by the drag hint, which could not take focus — the one name
+ * on an otherwise unnamed chart. The hint is in the chart's description now
+ * (`SeriesChart`'s figure), and `data-zoom-surface` is how a test finds the rect.
  */
 function ZoomLayer({
   axisIds,
   only,
-  label,
   onZoom,
   onReset,
 }: {
   axisIds: string[];
   only?: "x" | "y";
-  label: string;
   onZoom: (selection: ZoomSelection) => void;
   onReset: () => void;
 }) {
@@ -578,8 +580,7 @@ function ZoomLayer({
         height={plot.height}
         // `transparent`, not `none`: an unpainted shape takes no pointer events.
         fill="transparent"
-        role="application"
-        aria-label={label}
+        data-zoom-surface=""
         style={{ cursor: "crosshair" }}
         onPointerDown={(event) => {
           if (event.button !== 0) return;