@eifi1/ui-kit 0.9.0 → 0.11.0

package/src/components/mini-calendar.tsx

@@ -1,10 +1,17 @@
 import { useEffect, useId, useMemo, useRef, useState } from "react";
-import type { ComponentPropsWithoutRef, KeyboardEvent } from "react";
+import type { ComponentPropsWithoutRef, KeyboardEvent, ReactNode } from "react";
 import { ChevronLeft, ChevronRight } from "lucide-react";
 import { cn } from "../lib/cn";
 import { horizontalStep } from "../lib/direction";
 import { useAnnounce } from "../hooks/use-announce";
-import { parseIsoDate, sameYmd, toLocalIso } from "../lib/dates";
+import {
+  addMonthsClamped,
+  localeWeekStart,
+  monthKey,
+  parseIsoDate,
+  sameYmd,
+  toLocalIso,
+} from "../lib/dates";
 import { useKitLabels, useKitLocale, useKitWeekStart } from "../i18n/kit-labels";
 
 /**
@@ -80,8 +87,10 @@ const DAY_NAME_FORMAT: Intl.DateTimeFormatOptions = {
  * before this, a closed prop list dropped both (audit §api-design).
  */
 export interface MiniCalendarProps extends Omit<ComponentPropsWithoutRef<"div">, "onSelect"> {
-  from: string;
-  to: string;
+  /** The selection's start as "YYYY-MM-DD"; `""` (the default) for none. */
+  from?: string;
+  /** The selection's end; `""` (the default) for none. */
+  to?: string;
   /**
    * BCP 47 tag for the month caption, the weekday heads, the day numbers and the
    * spoken dates. Optional since the kit grew `<UiKitProvider locale>`: a calendar
@@ -122,47 +131,92 @@ export interface MiniCalendarProps extends Omit<ComponentPropsWithoutRef<"div">,
    * merely by existing.
    */
   focusOnOpen?: boolean;
+  /**
+   * `"sm"` (default) is the compact picker: 32px round days, the size the date
+   * pickers and the data-table filter draw. `"lg"` is a MONTH VIEW for a page — tall
+   * cells in a ruled grid, the day number in the top corner and {@link renderDay}'s
+   * content under it — the calendar a planner page hand-built before this existed.
+   * Both are the same grid underneath: the same roles, roving tabindex, keys, RTL
+   * mirroring and week start.
+   */
+  size?: "sm" | "lg";
+  /**
+   * Custom content for one day: events, an amount, a dot. Called for every day of the
+   * month on show; return `null` for none.
+   *
+   * ⚠️ **It renders INSIDE the day's button** — a dot under the number at `"sm"`, a
+   * column under it at `"lg"` — so it must not be interactive: no links, no buttons,
+   * no inputs. A control inside a control is invalid HTML, and a screen reader lands
+   * on the day and never reaches what is inside it. Events that are themselves
+   * clickable are shown here as plain text, and the DAY is what is clicked: pass
+   * `mode="single"` and let `onSelect` open a day panel (a drawer, a popover) that
+   * lists that day's events as real links.
+   *
+   * The day's accessible name stays the full date; this content is attached to it as
+   * its DESCRIPTION (`aria-describedby`), so "Monday, 14 September 2026" is read
+   * first and "Rent due · Plumber" after it. Anything decorative (a coloured dot)
+   * should be `aria-hidden` or carry an `sr-only` word for what it means.
+   */
+  renderDay?: (day: Date, state: MiniCalendarDayState) => ReactNode;
+  /**
+   * The month on show, as "YYYY-MM". FOLLOWED rather than controlled, exactly like
+   * `from`/`to`: when it changes the grid moves there, and in between the user pages
+   * freely — every move to another month is reported through {@link onMonthChange}.
+   * For a month page whose own header (a month picker, a Today button) drives the
+   * calendar. Left out, the grid opens on the selection or today.
+   */
+  month?: string;
+  /** Called with "YYYY-MM" whenever the USER moves the grid to another month (the
+   *  arrows, PageUp/PageDown, arrowing off the edge). */
+  onMonthChange?: (month: string) => void;
+  /**
+   * Hide the built-in previous/next arrows and month caption, for a page that draws
+   * its own. The caption is kept for assistive technology (visually hidden), because
+   * it is what names the grid.
+   */
+  hideNavigation?: boolean;
   /** Extra classes for the calendar's root. */
   className?: string;
 }
 
-export type WeekDay = 0 | 1 | 2 | 3 | 4 | 5 | 6;
-
-/**
- * The first day of the week in `locale`, as a `Date#getDay` index.
- *
- * `Intl.Locale#getWeekInfo()` is the standard spelling; V8 shipped it first as the
- * `weekInfo` accessor, and Firefox has neither yet — hence both reads and a Monday
- * fallback, which is ISO 8601 and what this grid did unconditionally before. Its
- * `firstDay` counts 1 = Monday … 7 = Sunday, so `% 7` maps it onto `getDay`.
- */
-function localeWeekStart(locale: string | undefined): WeekDay {
-  try {
-    const tag = locale ?? new Intl.DateTimeFormat().resolvedOptions().locale;
-    const loc = new Intl.Locale(tag) as Intl.Locale & {
-      getWeekInfo?: () => { firstDay: number };
-      weekInfo?: { firstDay: number };
-    };
-    const firstDay = (loc.getWeekInfo?.() ?? loc.weekInfo)?.firstDay;
-    if (typeof firstDay === "number") return (firstDay % 7) as WeekDay;
-  } catch {
-    // A malformed tag throws from `Intl.Locale`; the calendar still has to render.
-  }
-  return 1;
+/** What {@link MiniCalendarProps.renderDay} is told about the day it draws. */
+export interface MiniCalendarDayState {
+  /** The day as "YYYY-MM-DD". */
+  iso: string;
+  /** The day number as drawn, in the calendar's locale. */
+  label: string;
+  today: boolean;
+  /** Outside `min`/`max`. */
+  disabled: boolean;
+  /** Part of the selection — an end or a day between. */
+  selected: boolean;
+  rangeStart: boolean;
+  rangeEnd: boolean;
+  /** Strictly between the two ends of a range. */
+  inRange: boolean;
+  /** The day that holds the tab stop. */
+  active: boolean;
+  size: "sm" | "lg";
 }
 
+export type WeekDay = 0 | 1 | 2 | 3 | 4 | 5 | 6;
+
 /** Where `d` sits in a week that starts on `weekStart` (the first column = 0). */
 const weekdayIndex = (d: Date, weekStart: WeekDay) => (d.getDay() - weekStart + 7) % 7;
 
-/** Move `d` by whole months, keeping the day of the month where the target has one.
- *  `setMonth` alone ROLLS OVER — 31 January + 1 month is 3 March — which would skip
- *  February entirely for anyone paging through the year with PageDown. */
-function stepMonths(d: Date, months: number): Date {
-  const day = d.getDate();
-  const out = new Date(d.getFullYear(), d.getMonth() + months, 1);
-  const lastOfTarget = new Date(out.getFullYear(), out.getMonth() + 1, 0).getDate();
-  out.setDate(Math.min(day, lastOfTarget));
-  return out;
+/** Move `d` by whole months without rolling over (see {@link addMonthsClamped}). */
+const stepMonths = addMonthsClamped;
+
+/** A month-view cell: tall enough for two or three event lines, shorter on a phone. */
+const LG_CELL_HEIGHT = "min-h-16 md:min-h-24";
+
+/** The 1st of a "YYYY-MM" month, or null when absent or malformed. */
+const monthStart = (key: string | undefined) => (key ? parseIsoDate(`${key}-01`) : null);
+
+/** `day`'s day of the month in `first`'s month, clamped to that month's length. */
+function sameDayIn(first: Date, day: Date): Date {
+  const last = new Date(first.getFullYear(), first.getMonth() + 1, 0).getDate();
+  return new Date(first.getFullYear(), first.getMonth(), Math.min(day.getDate(), last));
 }
 
 /**
@@ -187,8 +241,8 @@ function stepMonths(d: Date, months: number): Date {
  * readable, and the click handler is what refuses them.
  */
 export function MiniCalendar({
-  from,
-  to,
+  from = "",
+  to = "",
   locale: localeProp,
   weekStartsOn,
   onSelect,
@@ -197,9 +251,15 @@ export function MiniCalendar({
   max,
   labels: labelsProp,
   focusOnOpen,
+  size = "sm",
+  renderDay,
+  month,
+  onMonthChange,
+  hideNavigation,
   className,
   ...rest
 }: MiniCalendarProps) {
+  const lg = size === "lg";
   const labels = useKitLabels("miniCalendar", DEFAULT_MINI_CALENDAR_LABELS, labelsProp);
   const locale = useKitLocale(localeProp);
   const providerWeekStart = useKitWeekStart();
@@ -232,7 +292,11 @@ export function MiniCalendar({
    * so a bounded calendar opens on a day it will actually let you pick.
    */
   const [activeIso, setActiveIso] = useState(() => {
-    const start = fromDate ?? toDate ?? new Date();
+    let start = fromDate ?? toDate ?? new Date();
+    // A `month` wins over the selection's month: the page asked for THAT month. The
+    // selection (or today) is kept when it falls inside it, else the 1st.
+    const first = monthStart(month);
+    if (first && monthKey(start) !== month) start = first;
     if (minDate && start < minDate) return toLocalIso(minDate);
     if (maxDate && start > maxDate) return toLocalIso(maxDate);
     return toLocalIso(start);
@@ -253,6 +317,19 @@ export function MiniCalendar({
     if (next && toLocalIso(next) !== activeIso) setActiveIso(toLocalIso(next));
   }
 
+  // …and the caller's month, the same way. Only a CHANGE moves the grid, so paging
+  // with the arrows is not snapped back by a parent that ignores `onMonthChange`.
+  const [lastMonth, setLastMonth] = useState(month);
+  if (lastMonth !== month) {
+    setLastMonth(month);
+    const first = monthStart(month);
+    const current = parseIsoDate(activeIso) ?? new Date();
+    if (first && monthKey(current) !== month) {
+      // Keep the day of the month, clamped: the 31st in a 30-day month is the 30th.
+      setActiveIso(toLocalIso(sameDayIn(first, current)));
+    }
+  }
+
   const activeDate = parseIsoDate(activeIso) ?? new Date();
   const view = { year: activeDate.getFullYear(), month: activeDate.getMonth() };
 
@@ -281,6 +358,7 @@ export function MiniCalendar({
       d.setDate(ref.getDate() + i);
       return {
         narrow: d.toLocaleDateString(locale, { weekday: "narrow" }),
+        short: d.toLocaleDateString(locale, { weekday: "short" }),
         long: d.toLocaleDateString(locale, { weekday: "long" }),
       };
     });
@@ -312,6 +390,8 @@ export function MiniCalendar({
     if (iso === activeIso) return;
     if (focus) pendingFocus.current = iso;
     setActiveIso(iso);
+    const key = monthKey(d);
+    if (key !== monthKey(activeDate)) onMonthChange?.(key);
   };
 
   /**
@@ -414,7 +494,13 @@ export function MiniCalendar({
     // `className` does everywhere else in the kit; `...rest` first, as in the rest of
     // this wave, so nothing from outside can take the grid's own wiring away.
     <div {...rest} className={cn("select-none", className)}>
-      <div className="flex items-center justify-between pb-1">
+      {hideNavigation ? (
+        // Still in the tree: the caption is what names the grid.
+        <div id={monthId} className="sr-only-fixed">
+          {monthLabel}
+        </div>
+      ) : (
+      <div className={cn("flex items-center justify-between", lg ? "pb-2" : "pb-1")}>
         <button
           type="button"
           onClick={() => moveMonth(-1)}
@@ -431,7 +517,12 @@ export function MiniCalendar({
         <div
           id={monthId}
           aria-live="polite"
-          className="text-xs font-medium capitalize text-[var(--text-secondary)]"
+          className={cn(
+            "capitalize",
+            lg
+              ? "text-base font-semibold text-[var(--text-primary)]"
+              : "text-xs font-medium text-[var(--text-secondary)]",
+          )}
         >
           {monthLabel}
         </div>
@@ -444,31 +535,57 @@ export function MiniCalendar({
           <ChevronRight className="size-4 rtl:-scale-x-100" aria-hidden />
         </button>
       </div>
+      )}
       <div
         ref={gridRef}
         role="grid"
         aria-labelledby={monthId}
         aria-describedby={mode === "range" ? hintId : undefined}
-        className="grid gap-y-0.5"
+        className={cn(
+          "grid",
+          // The month view is RULED: a 1px gap over a border-coloured ground draws the
+          // lines between the cells, the way a wall calendar does.
+          lg
+            ? "gap-px overflow-hidden rounded-lg border border-[var(--border)] bg-[var(--border)]"
+            : "gap-y-0.5",
+        )}
       >
         <div
           role="row"
-          className="grid grid-cols-7 text-center text-[10px] font-medium uppercase text-[var(--text-placeholder)]"
+          className={cn(
+            "grid grid-cols-7 text-center font-medium",
+            lg
+              ? "gap-px text-xs text-[var(--text-muted)]"
+              : "text-[10px] uppercase text-[var(--text-placeholder)]",
+          )}
         >
           {weekdayLabels.map((w, i) => (
-            <div key={i} role="columnheader" aria-label={w.long} className="py-0.5">
-              {w.narrow}
+            <div
+              key={i}
+              role="columnheader"
+              aria-label={w.long}
+              className={lg ? "bg-[var(--bg-surface)] py-2" : "py-0.5"}
+            >
+              {lg ? w.short : w.narrow}
             </div>
           ))}
         </div>
         {weeks.map((week, wi) => (
           // No column gap: the days of a range join into ONE band. With a gap each day
           // was its own tinted box, and a selected fortnight read as fourteen chips.
-          <div key={wi} role="row" className="grid grid-cols-7">
+          <div key={wi} role="row" className={cn("grid grid-cols-7", lg && "gap-px")}>
             {week.map((d, di) => {
               // The padding cells still have to BE cells, or the rows are ragged and
               // a screen reader's "column 3" stops meaning Wednesday.
-              if (!d) return <div key={di} role="gridcell" className="h-8" />;
+              if (!d) {
+                return (
+                  <div
+                    key={di}
+                    role="gridcell"
+                    className={lg ? cn(LG_CELL_HEIGHT, "bg-[var(--bg-surface-2)]") : "h-8"}
+                  />
+                );
+              }
               const iso = toLocalIso(d);
               const disabled = isDisabled(d);
               const isStart = !disabled && fromDate && sameYmd(d, fromDate);
@@ -476,12 +593,29 @@ export function MiniCalendar({
               const isToday = sameYmd(d, today);
               const isInRange = !disabled && inRange(d) && !isStart && !isEnd;
               const isActive = iso === activeIso;
+              const isSelected = Boolean(isStart || isEnd || isInRange);
+              const label = dayNumber.format(d.getDate());
+              const content = renderDay?.(d, {
+                iso,
+                label,
+                today: isToday,
+                disabled,
+                selected: isSelected,
+                rangeStart: Boolean(isStart),
+                rangeEnd: Boolean(isEnd),
+                inRange: isInRange,
+                active: isActive,
+                size,
+              });
+              const hasContent = content != null && content !== false && content !== "";
+              const contentId = `${id}-day-${iso}`;
               // The band behind the day: full width between the ends, half width at an
               // end (so the round endpoint sits ON the band's tip), rounded where a row
               // or the month breaks it. Only when both ends exist and differ — a lone
-              // start is a dot, not a band of one.
+              // start is a dot, not a band of one. The month view tints whole cells
+              // instead, so it has no band.
               const banded =
-                hasBand && !disabled && (isStart || isEnd || isInRange);
+                !lg && hasBand && !disabled && (isStart || isEnd || isInRange);
               const lastOfMonth = d.getDate() === daysInMonth(d);
               const band = banded
                 ? cn(
@@ -494,7 +628,14 @@ export function MiniCalendar({
                   )
                 : null;
               return (
-                <div key={di} role="none" className="relative flex h-8 items-center justify-center">
+                <div
+                  key={di}
+                  role="none"
+                  className={cn(
+                    "relative flex",
+                    lg ? "min-w-0" : "h-8 items-center justify-center",
+                  )}
+                >
                 {band && <span aria-hidden className={band} />}
                 <button
                   key={di}
@@ -506,12 +647,28 @@ export function MiniCalendar({
                   // control, which is the same reason the pattern exists.
                   tabIndex={isActive ? 0 : -1}
                   aria-label={labels.day(formatDay(d))}
-                  aria-selected={Boolean(isStart || isEnd || isInRange)}
+                  // The custom content is the day's DESCRIPTION: `aria-label` replaces
+                  // the button's text as its name, so without this link a screen
+                  // reader would hear the date and never the events drawn under it.
+                  aria-describedby={hasContent ? contentId : undefined}
+                  aria-selected={isSelected}
                   aria-disabled={disabled || undefined}
                   aria-current={isToday ? "date" : undefined}
                   onClick={() => handleClick(d)}
                   onKeyDown={onDayKeyDown}
-                  className={cn(
+                  className={
+                    lg
+                      ? cn(
+                          "flex w-full min-w-0 flex-col items-stretch gap-1 overflow-hidden p-1.5 text-start text-xs transition-colors",
+                          LG_CELL_HEIGHT,
+                          "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-inset focus-visible:ring-[var(--brand)]",
+                          disabled
+                            ? "cursor-not-allowed bg-[var(--bg-surface)] text-[var(--text-placeholder)]"
+                            : isSelected
+                              ? "bg-[var(--brand-bg)] text-[var(--text-primary)] hover:bg-[var(--brand-bg-hover)]"
+                              : "bg-[var(--bg-surface)] text-[var(--text-primary)] hover:bg-[var(--bg-hover)]",
+                        )
+                      : cn(
                     "relative size-8 rounded-full text-xs tabular-nums transition-colors",
                     // A grid you can walk with the keyboard needs to show where the
                     // keyboard IS. Inset because the cells sit half a pixel apart and
@@ -537,9 +694,43 @@ export function MiniCalendar({
                           ? "font-medium text-[var(--brand-muted)] hover:bg-[var(--brand-bg-hover)]"
                           : "text-[var(--text-primary)] hover:bg-[var(--bg-hover)]",
                     isToday && !isStart && !isEnd && !isInRange && !disabled && "ring-1 ring-inset ring-[var(--border-strong)]",
-                  )}
+                  )
+                  }
                 >
-                  {dayNumber.format(d.getDate())}
+                  {lg ? (
+                    <>
+                      <span
+                        className={cn(
+                          "inline-flex size-6 shrink-0 items-center justify-center self-start rounded-full tabular-nums",
+                          isStart || isEnd
+                            ? "bg-[var(--brand)] font-semibold text-[var(--brand-contrast)]"
+                            : isToday && !disabled
+                              ? "font-semibold text-[var(--brand)] ring-1 ring-inset ring-[var(--brand)]"
+                              : isInRange && "font-medium text-[var(--brand-muted)]",
+                        )}
+                      >
+                        {label}
+                      </span>
+                      {hasContent && (
+                        <span id={contentId} className="flex min-w-0 flex-col gap-0.5">
+                          {content}
+                        </span>
+                      )}
+                    </>
+                  ) : (
+                    <>
+                      {label}
+                      {/* Under the number, inside the circle: room for a dot or two. */}
+                      {hasContent && (
+                        <span
+                          id={contentId}
+                          className="pointer-events-none absolute inset-x-0 bottom-0.5 flex justify-center gap-px leading-none"
+                        >
+                          {content}
+                        </span>
+                      )}
+                    </>
+                  )}
                 </button>
                 </div>
               );

package/src/components/modal.tsx

@@ -1,4 +1,4 @@
-import { createContext, useRef, useState } from "react";
+import { createContext, useEffect, useRef, useState } from "react";
 import { createPortal } from "react-dom";
 import type {
   ComponentPropsWithoutRef,
@@ -11,7 +11,7 @@ import { cn } from "../lib/cn";
 import { useFocusTrap } from "../hooks/use-focus-trap";
 import { useBodyScrollLock } from "../hooks/use-body-scroll-lock";
 import { useOverlayHistory } from "../hooks/use-overlay-history";
-import { useCloseTransition } from "../hooks/use-close-transition";
+import { OVERLAY_EXIT_MS, prefersReducedMotion, useCloseTransition } from "../hooks/use-close-transition";
 
 /**
  * Drag the panel by its top strip, in pointer space (dev#460).
@@ -40,6 +40,9 @@ function useDragOffset(enabled: boolean) {
   };
 
   return {
+    /** Back to where the panel opens. A `Modal` with an `open` prop outlives its own
+     *  closes, so "the position resets when the dialog closes" needs saying. */
+    reset: () => setOffset(null),
     style: offset ? { transform: `translate(${offset.x}px, ${offset.y}px)` } : undefined,
     handlers: !enabled
       ? undefined
@@ -120,6 +123,28 @@ export function useBackdropClose(onClose: () => void) {
 export interface ModalProps extends Omit<ComponentPropsWithoutRef<"div">, "role"> {
   /** Invoked on backdrop click and on Escape. */
   onClose: () => void;
+  /**
+   * Who decides whether the dialog is up, when the caller wants to keep it MOUNTED.
+   *
+   * Left out, the dialog is open for as long as it is mounted — `{open && <Modal/>}`,
+   * which is every caller before this prop and stays exactly as it was. That idiom has
+   * one blind spot: a close the CALLER decides on (a save that succeeded, a
+   * `setOpen(false)` from outside) unmounts the panel on the spot, with no exit,
+   * because there is nothing left to animate. kastlan's `FormModal` was nothing but an
+   * `if (!open) return null` gate in front of this.
+   *
+   * Passed, the component stays mounted while closed and renders nothing, and a flip
+   * to `false` plays the same exit a dismissal does before the panel goes. The focus
+   * trap, the scroll lock and the Back-gesture history entry are held only while
+   * `open` is true — they are released the moment it turns false, so focus is back on
+   * the trigger while the panel is still lowering. A dismissal (Escape, the backdrop,
+   * Back, the frame's X) animates first and then calls `onClose`; the `false` that
+   * comes back from it is not animated a second time.
+   *
+   * The body is unmounted once the exit has finished, as it is today, so a form inside
+   * still starts fresh on the next open.
+   */
+  open?: boolean;
   /** `"alertdialog"` for a dialog that interrupts to ask a question the user must
    *  answer (a confirmation) — screen readers announce it with more urgency. Only the
    *  two dialog roles are allowed: the panel stays modal either way. */
@@ -183,6 +208,7 @@ export interface ModalProps extends Omit<ComponentPropsWithoutRef<"div">, "role"
  */
 export function Modal({
   onClose,
+  open,
   children,
   size = "md",
   className,
@@ -196,37 +222,68 @@ export function Modal({
 }: ModalProps) {
   const panelRef = useRef<HTMLDivElement>(null);
   const drag = useDragOffset(Boolean(draggable));
+  // Without `open`, mounted means open — the constant `true` every hook below used to
+  // be given. With it, `open` itself.
+  const active = open ?? true;
+
+  // Whether the last close came through `requestClose`, i.e. has ALREADY been
+  // animated. Set in the same batch as the caller's `onClose`, so the render that sees
+  // `open` turn false also sees this and does not lower the panel a second time.
+  const [dismissed, setDismissed] = useState(false);
+  // The exit of a close the caller decided on (only reachable with `open`). Adjusted
+  // during render when `open` flips — `Collapse`'s pattern — so the very render that
+  // closes it already paints the `-out` classes rather than a frame of nothing.
+  const [exiting, setExiting] = useState(false);
+  const [prevOpen, setPrevOpen] = useState(open);
+  if (open !== prevOpen) {
+    setPrevOpen(open);
+    setDismissed(false);
+    setExiting(open === false && prevOpen === true && !dismissed && !prefersReducedMotion());
+    if (open) drag.reset();
+  }
+  useEffect(() => {
+    if (!exiting) return;
+    const timer = setTimeout(() => setExiting(false), OVERLAY_EXIT_MS);
+    return () => clearTimeout(timer);
+  }, [exiting]);
+
   // The panel lowers itself before the caller unmounts it (live #320 rework). Every
   // dismissal below goes through `requestClose`; `onClose` still does the closing, one
   // animation later. A caller that closes the dialog ITSELF — after a save, say —
-  // unmounts with no exit, which is the documented limit of this.
-  const { closing, requestClose } = useCloseTransition(onClose);
-  const backdropClose = useBackdropClose(requestClose);
+  // unmounts with no exit unless it passes `open`, which is what that prop is for.
+  const { closing, requestClose } = useCloseTransition(() => {
+    setDismissed(true);
+    onClose();
+  });
+  // A panel on its way out after `open` turned false is already closed: a press on
+  // its fading backdrop must not report a second close.
+  const backdropClose = useBackdropClose(active ? requestClose : () => {});
   // Back means the same as Escape here. On a phone Escape doesn't exist, so without
   // this the only way out of a dialog is finding its close button — and Back, the
   // gesture everyone reaches for, navigated the page underneath instead (#172).
-  // Mounted only while open, hence the constant `true`.
-  useOverlayHistory(true, requestClose);
+  // Held only while open: a closed `open={false}` dialog must not own a history entry.
+  useOverlayHistory(active, requestClose);
 
-  // Mounted only while open, hence the constant `true`. Through the shared hook and
-  // not by hand: this component's own save/restore copy was one half of the pair that
-  // left the page permanently unscrollable when a dialog containing an open sheet was
-  // closed — see the note in use-body-scroll-lock.ts.
-  useBodyScrollLock(true);
+  // Through the shared hook and not by hand: this component's own save/restore copy
+  // was one half of the pair that left the page permanently unscrollable when a dialog
+  // containing an open sheet was closed — see the note in use-body-scroll-lock.ts.
+  useBodyScrollLock(active);
 
   // Focus the panel itself (not the first field) so opening doesn't pop the mobile
   // keyboard, while still moving focus into the dialog for keyboard and screen-reader
   // users. Through the shared hook since this component is where it came from — the
   // hook adds per-keystroke recomputation, a guard on restoring to a detached node,
-  // and nesting, none of which this copy had.
-  useFocusTrap(panelRef, { active: true, initialFocus: "container" });
+  // and nesting, none of which this copy had. Released when `open` turns false, which
+  // hands focus back to the trigger while the panel is still on its way out.
+  useFocusTrap(panelRef, { active, initialFocus: "container" });
+  const leaving = closing || exiting;
 
   const handleKeyDown = (e: KeyboardEvent<HTMLDivElement>) => {
     onKeyDown?.(e);
     if (e.defaultPrevented) return;
     if (e.key === "Escape") {
       e.stopPropagation();
-      requestClose();
+      if (active) requestClose();
       return;
     }
     // Tab containment lives in useFocusTrap, which listens on the panel itself.
@@ -237,13 +294,19 @@ export function Modal({
   // bar (a z-30 context) could paint BELOW a sibling z-30 sticky element like the
   // expanded transaction editor (feedback #320). The tour/command-palette overlays
   // already portal for the same reason.
+  if (!active && !exiting) return null;
   return createPortal(
     <div
+      // Out of the accessibility tree for the length of a caller-driven exit: focus is
+      // already back on the page, and an `aria-modal` panel that is leaving would hide
+      // that page from a screen reader for 220ms. Not `inert` — that would let a tap
+      // fall through the fading backdrop to the row underneath.
+      aria-hidden={exiting || undefined}
       className={cn(
         // Live #320. The panel below rises only where it is bottom-anchored: from md up
         // it is centred, and a centred box sliding up from off-screen reads as a
         // different component arriving rather than as the same one settling.
-        closing ? "animate-overlay-out" : "animate-overlay",
+        leaving ? "animate-overlay-out" : "animate-overlay",
         "fixed inset-0 z-50 flex items-end justify-center bg-black/40 md:items-center",
         fullBleed ? "p-0 md:p-4" : "p-4",
       )}
@@ -270,7 +333,7 @@ export function Modal({
         // the ones where the panel is being dragged.
         style={{ ...style, ...drag.style }}
         className={cn(
-          closing ? "animate-sheet-out md:animate-none" : "animate-sheet md:animate-none",
+          leaving ? "animate-sheet-out md:animate-none" : "animate-sheet md:animate-none",
           "w-full rounded-lg border border-[var(--border)] bg-[var(--bg-surface)] shadow-sm outline-none",
           { md: "max-w-md", lg: "max-w-lg", xl: "max-w-3xl" }[size],
           // A panel taller than the screen has to scroll ITSELF. The backdrop is