@terpjs/react-core 0.7.0 → 0.9.0

package/src/ui/DatePicker.tsx

@@ -1,11 +1,10 @@
 import { useEffect, useId, useMemo, useRef, useState } from "react";
-import type { CSSProperties, KeyboardEvent } from "react";
+import type { KeyboardEvent } from "react";
 
 import { useLocale } from "../locale";
 import { injectTerpStyles } from "../styles";
 import { useUiText } from "../uiText";
 import type { UiText } from "../uiText";
-import { CONTROL_TEXT_STYLE } from "./controlStyles";
 import { Popover } from "./Popover";
 
 injectTerpStyles();
@@ -25,6 +24,8 @@ export interface DatePickerProps {
   placeholder?: UiText;
   "aria-label"?: string;
   "aria-invalid"?: boolean | "true" | "false";
+  /** Open the calendar on mount (uncontrolled), the same shape `Popover` and `Menu` take. */
+  defaultOpen?: boolean;
 }
 
 export interface DateRangePickerProps {
@@ -37,61 +38,10 @@ export interface DateRangePickerProps {
   placeholder?: UiText;
   "aria-label"?: string;
   "aria-invalid"?: boolean | "true" | "false";
+  /** Open the calendar on mount (uncontrolled), the same shape `Popover` and `Menu` take. */
+  defaultOpen?: boolean;
 }
 
-const triggerStyle: CSSProperties = {
-  ...CONTROL_TEXT_STYLE,
-  lineHeight: 1.2,
-  minHeight: "2.25rem",
-  width: "100%",
-  display: "inline-flex",
-  alignItems: "center",
-  justifyContent: "space-between",
-  gap: "var(--space-2)",
-  padding: "0 var(--space-3)",
-  border: "1px solid var(--color-neutral-300)",
-  borderRadius: "var(--radius-md)",
-  color: "var(--color-neutral-900)",
-  background: "var(--color-neutral-0)",
-  boxSizing: "border-box",
-  cursor: "pointer",
-};
-const calendarStyle: CSSProperties = { display: "grid", gap: "var(--space-2)", minWidth: "18rem" };
-const headerStyle: CSSProperties = { display: "flex", alignItems: "center", justifyContent: "space-between", gap: "var(--space-2)" };
-const titleStyle: CSSProperties = { fontWeight: "var(--font-weight-semibold)" as never, color: "var(--color-neutral-900)" };
-const navButtonStyle: CSSProperties = {
-  display: "inline-flex",
-  alignItems: "center",
-  justifyContent: "center",
-  width: "2rem",
-  height: "2rem",
-  border: "1px solid var(--color-neutral-300)",
-  borderRadius: "var(--radius-md)",
-  background: "transparent",
-  color: "var(--color-neutral-700)",
-  cursor: "pointer",
-};
-const weekStyle: CSSProperties = { display: "grid", gridTemplateColumns: "repeat(7, 1fr)", gap: "var(--space-1)" };
-const weekdayStyle: CSSProperties = { textAlign: "center", fontSize: "var(--font-size-xs)", color: "var(--color-neutral-500)" };
-const dayStyle = (selected: boolean, inRange: boolean, disabled: boolean): CSSProperties => ({
-  ...CONTROL_TEXT_STYLE,
-  minHeight: "2rem",
-  border: selected ? "1px solid var(--color-brand-primary)" : "1px solid transparent",
-  borderRadius: "var(--radius-md)",
-  background: selected
-    ? "var(--color-brand-primary)"
-    : inRange
-      ? "var(--color-brand-primary-soft)"
-      : "transparent",
-  color: disabled
-    ? "var(--color-neutral-300)"
-    : selected
-      ? "var(--color-brand-primary-contrast)"
-      : "var(--color-neutral-900)",
-  cursor: disabled ? "not-allowed" : "pointer",
-});
-const mutedDayStyle: CSSProperties = { opacity: 0.45 };
-
 /** Single-date calendar picker with locale-aware labels and keyboard navigation. */
 export function DatePicker({
   value,
@@ -103,10 +53,17 @@ export function DatePicker({
   placeholder = "Select date",
   "aria-label": ariaLabel,
   "aria-invalid": ariaInvalid,
+  defaultOpen = false,
 }: DatePickerProps) {
   const [uncontrolledValue, setUncontrolledValue] = useState<Date | null>(defaultValue);
   const selected = normalizeDate(value ?? uncontrolledValue);
-  const [open, setOpen] = useState(false);
+  // `&& !disabled` is not belt-and-braces. Every close path runs through
+  // onOpenChange, which swallows the change while disabled — so a disabled picker seeded
+  // open would render a calendar that Escape, an outside click and its own onEscape all
+  // fail to dismiss, and whose day clicks still fire onChange from a control the app
+  // marked disabled. Only reachable since defaultOpen existed: before it, the sole way in
+  // was clicking the disabled trigger.
+  const [open, setOpen] = useState(defaultOpen && !disabled);
   const locale = useDateLocale();
   const resolve = useUiText();
   const formatted = selected === null ? resolve(placeholder) : formatDate(selected, locale);
@@ -121,7 +78,7 @@ export function DatePicker({
 
   return (
     <Popover
-      open={open}
+      open={open && !disabled}
       onOpenChange={(next) => !disabled && setOpen(next)}
       align="start"
       trigger={
@@ -132,7 +89,7 @@ export function DatePicker({
           aria-label={ariaLabel}
           aria-invalid={ariaInvalid}
           disabled={disabled}
-          style={{ ...triggerStyle, color: selected === null ? "var(--color-neutral-500)" : triggerStyle.color }}
+          data-placeholder={selected === null ? "true" : undefined}
         >
           <span>{formatted}</span>
           <span aria-hidden="true">📅</span>
@@ -166,10 +123,17 @@ export function DateRangePicker({
   placeholder = "Select date range",
   "aria-label": ariaLabel,
   "aria-invalid": ariaInvalid,
+  defaultOpen = false,
 }: DateRangePickerProps) {
   const [uncontrolledValue, setUncontrolledValue] = useState<DateRangeValue>(defaultValue);
   const selected = normalizeRange(value ?? uncontrolledValue);
-  const [open, setOpen] = useState(false);
+  // `&& !disabled` is not belt-and-braces. Every close path runs through
+  // onOpenChange, which swallows the change while disabled — so a disabled picker seeded
+  // open would render a calendar that Escape, an outside click and its own onEscape all
+  // fail to dismiss, and whose day clicks still fire onChange from a control the app
+  // marked disabled. Only reachable since defaultOpen existed: before it, the sole way in
+  // was clicking the disabled trigger.
+  const [open, setOpen] = useState(defaultOpen && !disabled);
   const locale = useDateLocale();
   const resolve = useUiText();
   const formatted = selected.start === null
@@ -190,7 +154,7 @@ export function DateRangePicker({
 
   return (
     <Popover
-      open={open}
+      open={open && !disabled}
       onOpenChange={(next) => !disabled && setOpen(next)}
       align="start"
       trigger={
@@ -201,7 +165,7 @@ export function DateRangePicker({
           aria-label={ariaLabel}
           aria-invalid={ariaInvalid}
           disabled={disabled}
-          style={{ ...triggerStyle, color: selected.start === null ? "var(--color-neutral-500)" : triggerStyle.color }}
+          data-placeholder={selected.start === null ? "true" : undefined}
         >
           <span>{formatted}</span>
           <span aria-hidden="true">📅</span>
@@ -239,19 +203,61 @@ interface CalendarProps {
 
 function Calendar({ mode, locale, visibleSeed, selected = null, range, min, max, onSelect, onRangeSelect, onEscape }: CalendarProps) {
   const gridId = useId();
+  const titleId = useId();
   const minDate = normalizeDate(min);
   const maxDate = normalizeDate(max);
   const initial = clampDate(normalizeDate(visibleSeed) ?? today(), minDate, maxDate);
   const [month, setMonth] = useState(() => startOfMonth(initial));
   const [activeDate, setActiveDate] = useState(initial);
   const activeRef = useRef<HTMLButtonElement>(null);
-  const days = useMemo(() => monthGrid(month), [month]);
+  const follow = useRef(false);
+  const weeks = useMemo(() => monthWeeks(month), [month]);
   const weekdays = useMemo(() => weekdayNames(locale), [locale]);
+  const activeKey = toKey(activeDate);
 
+  // Opening: focus the cursor once the portalled panel exists where it will finally sit
+  // (Popover positions it in a layout effect, hence the tick). Its own effect with its own
+  // cleanup, deliberately — folding it into the cursor effect below and gating it on a
+  // did-mount ref meant StrictMode's mount / cleanup / mount cycle cleared the first timer
+  // and then took the other branch, so in development the calendar opened with focus outside
+  // the grid and the arrow keys inert.
   useEffect(() => {
-    window.setTimeout(() => activeRef.current?.focus(), 0);
+    const timer = window.setTimeout(() => activeRef.current?.focus(), 0);
+    return () => window.clearTimeout(timer);
   }, []);
 
+  // The roving cursor has to move DOM focus, not just `tabIndex` — an arrow key used to move
+  // `tabIndex={0}` and `activeRef` to another cell while the browser's focus, the focus ring
+  // and every screen reader stayed on the day the calendar opened on.
+  //
+  // The intent is recorded at the EVENT rather than inferred afterwards, and that is the whole
+  // correctness argument. Reading `document.activeElement` after the commit looks equivalent
+  // and is not: a move across a month boundary re-keys the week rows, so the row holding the
+  // focused cell is unmounted, which moves focus to <body> — and a post-commit check then sees
+  // focus outside the grid and declines to follow. Measured in a browser: arrowing from
+  // 29 January to 5 February left `document.activeElement` on BODY and the calendar
+  // keyboard-dead, because the grid's handler is the only key listener. The flag cannot be
+  // fooled that way, because only the grid's own handler sets it.
+  useEffect(() => {
+    if (!follow.current) {
+      return;
+    }
+    follow.current = false;
+    activeRef.current?.focus();
+  }, [activeKey]);
+
+  /** Move the cursor from a key the grid handled, and take focus with it. */
+  function moveCursor(daysDelta: number) {
+    follow.current = true;
+    move(daysDelta);
+  }
+
+  /** Page the month from a key the grid handled. The header buttons deliberately do not. */
+  function pageMonth(delta: number) {
+    follow.current = true;
+    changeMonth(delta);
+  }
+
   function move(daysDelta: number) {
     const next = clampDate(addDays(activeDate, daysDelta), minDate, maxDate);
     setActiveDate(next);
@@ -290,35 +296,35 @@ function Calendar({ mode, locale, visibleSeed, selected = null, range, min, max,
         break;
       case "ArrowRight":
         event.preventDefault();
-        move(1);
+        moveCursor(1);
         break;
       case "ArrowLeft":
         event.preventDefault();
-        move(-1);
+        moveCursor(-1);
         break;
       case "ArrowDown":
         event.preventDefault();
-        move(7);
+        moveCursor(7);
         break;
       case "ArrowUp":
         event.preventDefault();
-        move(-7);
+        moveCursor(-7);
         break;
       case "Home":
         event.preventDefault();
-        move(-activeDate.getDay());
+        moveCursor(-activeDate.getDay());
         break;
       case "End":
         event.preventDefault();
-        move(6 - activeDate.getDay());
+        moveCursor(6 - activeDate.getDay());
         break;
       case "PageUp":
         event.preventDefault();
-        changeMonth(-1);
+        pageMonth(-1);
         break;
       case "PageDown":
         event.preventDefault();
-        changeMonth(1);
+        pageMonth(1);
         break;
       case "Enter":
       case " ":
@@ -331,41 +337,74 @@ function Calendar({ mode, locale, visibleSeed, selected = null, range, min, max,
   }
 
   return (
-    <div role="dialog" aria-modal="false" style={calendarStyle}>
-      <div style={headerStyle}>
-        <button type="button" data-terp="iconbutton" aria-label="Previous month" onClick={() => changeMonth(-1)} style={navButtonStyle}>‹</button>
-        <div style={titleStyle}>{formatMonth(month, locale)}</div>
-        <button type="button" data-terp="iconbutton" aria-label="Next month" onClick={() => changeMonth(1)} style={navButtonStyle}>›</button>
+    // Named by its month heading. role="dialog" with no accessible name announces itself as
+    // just "dialog", and the month was one level down on the grid — reached only after the
+    // dialog boundary had already been crossed unnamed. axe does not report this at the
+    // wcag2a/aa tags the lane runs, so opening the calendar in stage 4 did not surface it.
+    <div role="dialog" aria-modal="false" aria-labelledby={titleId} data-terp="calendar">
+      <div data-terp="calendar-header">
+        <button type="button" data-terp="iconbutton" aria-label="Previous month" onClick={() => changeMonth(-1)}>‹</button>
+        <div id={titleId} data-terp="calendar-title">{formatMonth(month, locale)}</div>
+        <button type="button" data-terp="iconbutton" aria-label="Next month" onClick={() => changeMonth(1)}>›</button>
       </div>
-      <div style={weekStyle} aria-hidden="true">
-        {weekdays.map((day) => <div key={day} style={weekdayStyle}>{day}</div>)}
+      <div data-terp="calendar-week" aria-hidden="true">
+        {weekdays.map((day) => <div key={day} data-terp="calendar-weekday">{day}</div>)}
       </div>
-      <div id={gridId} role="grid" aria-label={formatMonth(month, locale)} style={weekStyle} onKeyDown={onGridKeyDown}>
-        {days.map((day) => {
-          const disabled = isDisabled(day, minDate, maxDate);
-          const isSelected = mode === "single"
-            ? sameDate(day, selected)
-            : sameDate(day, range?.start) || sameDate(day, range?.end);
-          const inRange = mode === "range" && isWithinRange(day, range);
-          const active = sameDate(day, activeDate);
-          return (
-            <button
-              key={toKey(day)}
-              ref={active ? activeRef : undefined}
-              type="button"
-              role="gridcell"
-              aria-selected={isSelected}
-              aria-disabled={disabled}
-              tabIndex={active ? 0 : -1}
-              disabled={disabled}
-              onClick={() => selectDate(day)}
-              onFocus={() => setActiveDate(day)}
-              style={{ ...dayStyle(isSelected, inRange, disabled), ...(day.getMonth() === month.getMonth() ? undefined : mutedDayStyle) }}
-            >
-              {day.getDate()}
-            </button>
-          );
-        })}
+      {/* grid → row → gridcell. The 42 day buttons used to be DIRECT children of the
+          role="grid", which is an invalid ARIA grid: `grid` must own `row`s and a
+          `gridcell` must be owned by one, so axe rated it a critical violation on two
+          rules at once and no screen reader could report "week 3, Wednesday". Nothing
+          caught it because nothing in the repo opened a calendar — the resting-state
+          baselines have no picture of it and axe never reached the subtree.
+
+          The geometry is unchanged and that is why the rows can be real elements rather
+          than `display: contents`: the outer box keeps the row gap, each row keeps the
+          seven equal columns and the column gap, and both gaps are the same token they
+          always were, so 42 cells land on exactly the pixels they did as one flat grid. */}
+      <div
+        id={gridId}
+        role="grid"
+        aria-label={formatMonth(month, locale)}
+        data-terp="calendar-grid"
+        onKeyDown={onGridKeyDown}
+      >
+        {weeks.map((week) => (
+          <div key={toKey(week[0]!)} role="row" data-terp="calendar-week">
+            {week.map((day) => {
+              const disabled = isDisabled(day, minDate, maxDate);
+              const isSelected = mode === "single"
+                ? sameDate(day, selected)
+                : sameDate(day, range?.start) || sameDate(day, range?.end);
+              const inRange = mode === "range" && isWithinRange(day, range);
+              const active = sameDate(day, activeDate);
+              return (
+                <button
+                  key={toKey(day)}
+                  ref={active ? activeRef : undefined}
+                  type="button"
+                  role="gridcell"
+                  aria-selected={isSelected}
+                  aria-disabled={disabled}
+                  tabIndex={active ? 0 : -1}
+                  disabled={disabled}
+                  onClick={() => selectDate(day)}
+                  onFocus={() => setActiveDate(day)}
+                  // The full date, because the visible text is a bare number and the weekday
+                  // row is aria-hidden AND a sibling of the grid rather than columnheaders
+                  // inside it — so a cell had no weekday, no month and no year to announce.
+                  // aria-label is allowed on a gridcell, leaves the visible glyph alone, and is
+                  // what every calendar in the APG's own examples effectively gives AT.
+                  aria-label={formatFullDate(day, locale)}
+                  data-terp="calendar-day"
+                  data-in-range={inRange ? "true" : undefined}
+                  data-outside-month={day.getMonth() === month.getMonth() ? undefined : "true"}
+                >
+                  {day.getDate()}
+                </button>
+              );
+            })}
+          </div>
+        ))}
       </div>
     </div>
   );
@@ -379,6 +418,16 @@ function formatDate(date: Date, locale: string | undefined) {
   return new Intl.DateTimeFormat(locale, { year: "numeric", month: "short", day: "numeric" }).format(date);
 }
 
+/** The whole date, spoken: what a day cell announces, since its text is only a number. */
+function formatFullDate(date: Date, locale: string | undefined) {
+  return new Intl.DateTimeFormat(locale, {
+    weekday: "long",
+    day: "numeric",
+    month: "long",
+    year: "numeric",
+  }).format(date);
+}
+
 function formatMonth(date: Date, locale: string | undefined) {
   return new Intl.DateTimeFormat(locale, { year: "numeric", month: "long" }).format(date);
 }
@@ -408,10 +457,13 @@ function clampDate(date: Date, min: Date | null, max: Date | null) {
   if (max !== null && compareDate(date, max) > 0) return max;
   return date;
 }
-function monthGrid(month: Date) {
+/** Six weeks of seven days covering `month`, the first cell being that month's Sunday-start. */
+function monthWeeks(month: Date) {
   const first = startOfMonth(month);
   const start = addDays(first, -first.getDay());
-  return Array.from({ length: 42 }, (_, index) => addDays(start, index));
+  return Array.from({ length: 6 }, (_, week) =>
+    Array.from({ length: 7 }, (_, day) => addDays(start, week * 7 + day)),
+  );
 }
 function isWithinRange(date: Date, range: DateRangeValue | undefined) {
   if (range?.start === null || range?.start === undefined || range.end === null || range.end === undefined) {

package/src/ui/Input.tsx

@@ -1,30 +1,17 @@
-import type { CSSProperties, InputHTMLAttributes } from "react";
+import type { InputHTMLAttributes } from "react";
 
 import { injectTerpStyles } from "../styles";
-import { CONTROL_TEXT_STYLE } from "./controlStyles";
 
 injectTerpStyles();
 
-const inputStyle: CSSProperties = {
-  ...CONTROL_TEXT_STYLE,
-  lineHeight: 1.2,
-  minHeight: "2.25rem",
-  padding: "0 var(--space-3)",
-  border: "1px solid var(--color-neutral-300)",
-  borderRadius: "var(--radius-md)",
-  color: "var(--color-neutral-900)",
-  background: "var(--color-neutral-0)",
-  boxSizing: "border-box",
-};
-
 export type InputProps = InputHTMLAttributes<HTMLInputElement>;
 
 /**
  * Token-styled text input — use instead of a raw `<input>` (the module-boundary rule).
- * The `data-terp="input"` marker opts the element into the shared focus ring and
- * hover polish injected by react-core.
+ * The `data-terp="input"` marker is the whole styling hook: it carries the shared control
+ * surface, the focus ring, the hover border and the disabled treatment from the injected
+ * sheet, with the element type deciding the geometry (ADR 0094).
  */
-export function Input({ style, ...rest }: InputProps) {
-  return <input data-terp="input" {...rest} style={{ ...inputStyle, ...style }} />;
+export function Input(props: InputProps) {
+  return <input data-terp="input" {...props} />;
 }
-

package/src/ui/Markdown.test.tsx

@@ -29,4 +29,30 @@ describe("Markdown", () => {
     expect(screen.getByText(/<img src=x/)).toBeInTheDocument();
     expect(container.querySelector("img")).toBeNull();
   });
+  it("wraps its blocks in a boxless root, and renders nothing at all when empty", () => {
+    const { container } = render(
+      <Markdown
+        source={`# Title
+
+Body paragraph.`}
+      />,
+    );
+    const root = container.querySelector('[data-terp="markdown"]');
+    expect(root).not.toBeNull();
+    // The wrapper exists so the component can be found and styled at all. It is boxless by
+    // rule — display: contents lives in the sheet — which is what keeps these blocks
+    // individual items of any parent that spaces its children with gap, so marking the
+    // component changed no consumer's layout.
+    expect(root!.children.length).toBe(2);
+    expect(root!.getAttribute("style")).toBeNull();
+
+    cleanup();
+    // An empty source still renders NOTHING, and that is load-bearing rather than tidy: the
+    // layout contract's runtime check reads the direct children of a governed body slot and
+    // refuses any marker its allow table does not name. An unconditional wrapper would turn
+    // an empty Markdown beside allowed components from a passing body into a fail-closed
+    // refusal — thrown for rendering no content.
+    const empty = render(<Markdown source="   " />);
+    expect(empty.container.firstChild).toBeNull();
+  });
 });

package/src/ui/Markdown.tsx

@@ -1,8 +1,25 @@
 import type { ReactNode } from "react";
 
+import { injectTerpStyles } from "../styles";
 import { useUiText } from "../uiText";
 import type { UiText } from "../uiText";
 
+// The sheet matters more here than anywhere else in the package, and it is worth being precise
+// about why rather than overstating it. Every other component DEGRADES without its rules — a
+// Stack falls back to a block and looks wrong. This one RESTRUCTURES: the wrapper below is only
+// free because a rule makes it boxless, and as a plain block box it collapses however many
+// prose blocks into a single flex or grid item of its parent.
+//
+// That said, this call is belt-and-braces rather than the thing standing between the two. The
+// package publishes one entry point (exports is "." -> src/index.ts, which re-exports
+// everything) and declares no `sideEffects` field, so importing anything from it loads every
+// module and some two dozen of them inject. Twelve marker-rendering modules rely on exactly
+// that and call nothing themselves. It is here because a module that owns a rule this load
+// bearing should not depend on a sibling being imported, and because the guarantee is a
+// packaging property nothing asserts — a future `sideEffects: false` plus tree-shaking would
+// remove it silently.
+injectTerpStyles();
+
 export interface MarkdownProps {
   source: UiText;
 }
@@ -177,8 +194,17 @@ function renderInline(text: string): ReactNode[] {
 export function Markdown({ source }: MarkdownProps) {
   const resolve = useUiText();
   const blocks = parseBlocks(resolve(source));
+  // An empty or whitespace-only source rendered literally nothing before this wrapper existed,
+  // and it still does. That is not tidiness: the layout contract's runtime check reads the
+  // DIRECT children of a governed body slot and refuses any whose marker is not in the slot's
+  // allow table, `markdown` included. So an unconditional wrapper would turn an empty Markdown
+  // beside allowed components from a passing body into a refused one — a fail-closed throw for
+  // rendering nothing.
+  if (blocks.length === 0) {
+    return null;
+  }
   return (
-    <>
+    <div data-terp="markdown">
       {blocks.map((block, index) => {
         if (block.type === "heading") {
           const content = renderInline(block.text);
@@ -208,6 +234,6 @@ export function Markdown({ source }: MarkdownProps) {
         }
         return <p key={index}>{renderInline(block.text)}</p>;
       })}
-    </>
+    </div>
   );
 }

package/src/ui/Menu.test.tsx

@@ -21,10 +21,18 @@ describe("Menu", () => {
     fireEvent.click(screen.getByRole("button", { name: "Actions" }));
     const menu = screen.getByRole("menu");
     expect(screen.getByTestId("clip")).not.toContainElement(menu);
-    expect(menu.parentElement).toHaveStyle({
-      fontFamily: "var(--font-family-sans)",
-      color: "var(--color-neutral-900)",
-    });
+    const panel = menu.parentElement as HTMLElement;
+    expect(panel).toHaveAttribute("data-terp", "popover-panel");
+    // The panel's appearance is a sheet rule now (ADR 0094), so what it inlines is the whole
+    // assertion — and it can be the whole assertion, because nothing can inject panel styles
+    // any more: `panelStyle` went with UserMenu's migration. Exactly three declarations, the
+    // measured ones.
+    expect([...panel.style].sort()).toEqual(["left", "top", "visibility"]);
+    expect(panel.style.top).not.toBe("");
+    expect(panel.style.left).not.toBe("");
+    // And the owner attribute, which is the only handle a rule has on a panel this component
+    // portalled to document.body.
+    expect(panel).toHaveAttribute("data-owner", "popover");
     fireEvent.pointerDown(menu);
     expect(menu).toBeInTheDocument();
   });
@@ -82,4 +90,30 @@ describe("Menu", () => {
     expect(onOpenChange).toHaveBeenCalledTimes(1);
     expect(onOpenChange).toHaveBeenCalledWith(false);
   });
+  it("returns focus to the trigger on Tab, so the tab order continues after the button", () => {
+    render(
+      <Menu trigger="Open" triggerLabel="Actions">
+        {() => (
+          <>
+            <MenuItem label="Archive" onSelect={() => {}} />
+            <MenuItem label="Delete" onSelect={() => {}} />
+          </>
+        )}
+      </Menu>,
+    );
+    const trigger = screen.getByRole("button", { name: "Actions" });
+    fireEvent.click(trigger);
+    const menu = screen.getByRole("menu");
+    expect(menu.contains(document.activeElement)).toBe(true);
+
+    fireEvent.keyDown(menu, { key: "Tab" });
+
+    // The panel closes AND focus goes back to the trigger. Closing without restoring left focus
+    // on a tabIndex=-1 item inside a panel portalled to the end of document.body, which is then
+    // unmounted — so the browser's sequential-navigation starting point was a removed node at
+    // the wrong end of the document and Tab landed past all page content. The APG menu-button
+    // contract is that Tab moves to the next element after the BUTTON.
+    expect(screen.queryByRole("menu")).not.toBeInTheDocument();
+    expect(document.activeElement).toBe(trigger);
+  });
 });