@eifi1/ui-kit 0.51.7 → 0.52.0

package/dist/components/modal.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/components/modal.tsx"],"sourcesContent":["import { createContext, useCallback, useEffect, useMemo, useRef, useState } from \"react\";\nimport { createPortal } from \"react-dom\";\nimport type {\n  ComponentPropsWithoutRef,\n  KeyboardEvent,\n  MouseEvent as ReactMouseEvent,\n  PointerEvent as ReactPointerEvent,\n  ReactNode,\n  Ref,\n} from \"react\";\nimport { cn } from \"../lib/cn\";\nimport { mergeRefs } from \"./field-parts\";\nimport { useFocusTrap } from \"../hooks/use-focus-trap\";\nimport { useBodyScrollLock } from \"../hooks/use-body-scroll-lock\";\nimport { useOverlayHistory } from \"../hooks/use-overlay-history\";\nimport { useDialogParam, type DialogParam } from \"../hooks/use-search-param-state\";\nimport { OVERLAY_EXIT_MS, skipsExitAnimation, useCloseTransition } from \"../hooks/use-close-transition\";\nimport { runOwnKeyDown, takeEscape, useDismissLayer } from \"../hooks/use-dismiss\";\n\n/**\n * Drag the panel by its top strip, in pointer space (dev#460).\n *\n * Deliberately not a library and not persisted: the offset is component state that\n * dies with the dialog. It starts only on a press that lands on the panel's own\n * chrome — never on a field, a button or a link, which is what keeps \"drag to select\n * text in the textarea\" working. Above `md` only: below it the panel is a\n * full-width bottom sheet with nothing beside it to uncover.\n *\n * The whole gesture stays on the PANEL — captured pointer, React handlers — rather than\n * on `window`. The first shape of this added `pointermove`/`pointerup` to `window` from\n * inside the `pointerdown` handler and took them off again from the `pointerup` handler,\n * so the teardown ran only if the gesture ended: React never sees a listener added from\n * an event handler, and an unmount mid-drag left a live `pointermove` on `window` for\n * the life of the page, pinning this hook's state with it. The one caller that enables\n * dragging is the feedback composer, which closes ITSELF on submit — a Ctrl+Enter sent\n * with the pointer still down is exactly that order of events, once per drag.\n */\nfunction useDragOffset(enabled: boolean) {\n  const [offset, setOffset] = useState<{ x: number; y: number } | null>(null);\n  const from = useRef<{ x: number; y: number; ox: number; oy: number } | null>(null);\n\n  const endDrag = () => {\n    from.current = null;\n  };\n\n  return {\n    /** Back to where the panel opens. A `Modal` with an `open` prop outlives its own\n     *  closes, so \"the position resets when the dialog closes\" needs saying. */\n    reset: () => setOffset(null),\n    style: offset ? { transform: `translate(${offset.x}px, ${offset.y}px)` } : undefined,\n    handlers: !enabled\n      ? undefined\n      : {\n          onPointerDown: (e: ReactPointerEvent<HTMLDivElement>) => {\n            if (e.button !== 0 || window.innerWidth < 768) return;\n            const target = e.target as HTMLElement;\n            // Only the panel itself and its non-interactive chrome start a drag; a\n            // press inside any control belongs to that control.\n            if (target.closest(\"input,textarea,select,button,a,[role='button']\")) return;\n            from.current = { x: e.clientX, y: e.clientY, ox: offset?.x ?? 0, oy: offset?.y ?? 0 };\n            try {\n              // Capture is what lets the handlers live on the panel: every later\n              // pointer event for this pointer retargets here, so the drag keeps\n              // working once the pointer outruns the panel's own box — which it always\n              // does, since the panel moves out from under it.\n              e.currentTarget.setPointerCapture(e.pointerId);\n            } catch {\n              // jsdom implements no pointer capture, and a browser throws\n              // NotFoundError for a pointerId that is already gone. Neither is worth\n              // refusing the drag: uncaptured, the panel still gets the moves that\n              // land on it.\n            }\n          },\n          onPointerMove: (e: ReactPointerEvent<HTMLDivElement>) => {\n            const start = from.current;\n            if (!start) return;\n            setOffset({ x: start.ox + e.clientX - start.x, y: start.oy + e.clientY - start.y });\n          },\n          onPointerUp: endDrag,\n          // A cancel (the browser taking the pointer for a scroll or a gesture) and a\n          // lost capture both mean no `pointerup` is coming. Without them the drag would\n          // stay \"live\" and the next move over the panel would jump it.\n          onPointerCancel: endDrag,\n          onLostPointerCapture: endDrag,\n        },\n  };\n}\n\n/**\n * The panel's own ANIMATED dismissal, for chrome rendered inside it. `DialogFrame`'s X\n * and its `actions(close)` read this, so a Cancel or an X lowers the panel exactly the\n * way Escape does — calling `onClose` from inside unmounts with no exit, which is the\n * documented limit of {@link useCloseTransition}. `null` outside a `Modal`.\n */\nexport const ModalCloseContext = createContext<(() => void) | null>(null);\n\n/**\n * Backdrop handlers that close only when a press starts AND ends on the\n * backdrop itself. A plain onClick fires on mouseup, so dragging a text\n * selection that starts inside the panel and releases over the backdrop would\n * dismiss the dialog (feedback #254) — and the reverse drag would too, since\n * click targets the common ancestor of the down/up elements.\n */\nexport function useBackdropClose(onClose: () => void) {\n  const pressStartedOnBackdrop = useRef(false);\n  return {\n    onMouseDown: (e: ReactMouseEvent<HTMLDivElement>) => {\n      pressStartedOnBackdrop.current = e.target === e.currentTarget;\n    },\n    onMouseUp: (e: ReactMouseEvent<HTMLDivElement>) => {\n      const started = pressStartedOnBackdrop.current;\n      pressStartedOnBackdrop.current = false;\n      if (started && e.target === e.currentTarget) onClose();\n    },\n  };\n}\n\n// Tab-cycle target set: the interactive descendants the focus trap rotates\n// through. Querying live (per keystroke) means dynamically rendered fields are\n// included automatically.\n/**\n * `extends ComponentPropsWithoutRef<\"div\">` so anything a `<div>` takes reaches the\n * PANEL — the element with `role=\"dialog\"`, which is the one a consumer means. That is\n * where a `data-tour` anchor, a test id, an `aria-describedby` or an `aria-label` has\n * to land; before this, a closed prop list dropped all four silently (audit §api-design).\n */\nexport interface ModalProps extends Omit<ComponentPropsWithoutRef<\"div\">, \"role\"> {\n  /** Invoked on backdrop click and on Escape. */\n  onClose: () => void;\n  /**\n   * Who decides whether the dialog is up, when the caller wants to keep it MOUNTED.\n   *\n   * Left out, the dialog is open for as long as it is mounted — `{open && <Modal/>}`,\n   * which is every caller before this prop and stays exactly as it was. That idiom has\n   * one blind spot: a close the CALLER decides on (a save that succeeded, a\n   * `setOpen(false)` from outside) unmounts the panel on the spot, with no exit,\n   * because there is nothing left to animate. kastlan's `FormModal` was nothing but an\n   * `if (!open) return null` gate in front of this.\n   *\n   * Passed, the component stays mounted while closed and renders nothing, and a flip\n   * to `false` plays the same exit a dismissal does before the panel goes. The focus\n   * trap, the scroll lock and the Back-gesture history entry are held only while\n   * `open` is true — they are released the moment it turns false, so focus is back on\n   * the trigger while the panel is still lowering. A dismissal (Escape, the backdrop,\n   * Back, the frame's X) animates first and then calls `onClose`; the `false` that\n   * comes back from it is not animated a second time.\n   *\n   * The body is unmounted once the exit has finished, as it is today, so a form inside\n   * still starts fresh on the next open.\n   */\n  open?: boolean;\n  /** `\"alertdialog\"` for a dialog that interrupts to ask a question the user must\n   *  answer (a confirmation) — screen readers announce it with more urgency. Only the\n   *  two dialog roles are allowed: the panel stays modal either way. */\n  role?: \"dialog\" | \"alertdialog\";\n  children: ReactNode;\n  /**\n   * Panel max-width: `md` (28rem), `lg` (32rem), `xl` (48rem), `2xl` (the display less\n   * the backdrop's margin, capped at 110rem).\n   *\n   * `xl` exists because two callers had already written `className=\"max-w-3xl\"` to\n   * reach it — the payee backfill's preview table and the price-merge dialog, both\n   * of which hold a list and several fields rather than one question. A caller\n   * patching a missing size IS the signal that the size is missing, and a\n   * hand-written width in a `className` is a width nothing else can line up with.\n   *\n   * `2xl` is the same signal one size up (round 0.34 C3, KS U1): a dialog whose\n   * content is a TABLE to be read. Kurvenschmiede's five part dialogs hold a measured\n   * table pasted from a spreadsheet and had patched themselves to\n   * `w-[min(110rem,94vw)] max-w-none`; Keksdose's report drilldown passed `size=\"lg\"`\n   * and then `max-w-5xl`. The cap is the generous one of the two, because a table\n   * squeezed into a box in the middle of a wide screen is a table scrolled sideways\n   * (KS feedback #16); below the cap the panel is as wide as the backdrop lets it be.\n   * In rem, so it grows with the text size until the screen stops it.\n   *\n   * The panel is `w-full` under every one of them, so the cap only bites once the\n   * viewport is wider than it: on a phone all four are the same full-width bottom\n   * sheet. Nothing here may introduce a `min-w-*`, which is what would break that.\n   */\n  size?: \"md\" | \"lg\" | \"xl\" | \"2xl\";\n  /** Extra classes for the panel (e.g. `space-y-3` for form content spacing). */\n  className?: string;\n  /** id of the heading element, wired to `aria-labelledby`. */\n  labelledBy?: string;\n  /**\n   * Extra key handling on the panel (e.g. Ctrl/Cmd+Enter to submit). Runs first; a\n   * `preventDefault()` on Escape HERE keeps the dialog open — the owner's claim (see\n   * `use-dismiss.ts`). One a field inside makes does not, since 0.34: the rule\n   * `FullBleedDialog` already had, so a search box keeping Chromium from clearing itself\n   * no longer holds the dialog open (Wave 2, DUP-1).\n   */\n  onKeyDown?: (e: KeyboardEvent<HTMLDivElement>) => void;\n  /**\n   * Drop the backdrop's mobile margin so the panel can reach the screen edges\n   * (a full-screen sheet on phones). The panel still needs its own\n   * `h-[100dvh] max-w-full rounded-none` classes via `className` to fill it; the\n   * desktop `md:p-4` margin is kept. Defaults to false (padded on all sizes).\n   */\n  fullBleed?: boolean;\n  /**\n   * Let the user drag the panel out of the way by its top edge (Keksdose feedback\n   * dev#460: *\"Make the feedback dialog draggable so I can see behind it if it\n   * blocks something.\"*).\n   *\n   * Opt-in, because it only makes sense for a dialog whose content is ABOUT the page\n   * behind it — the feedback composer is the case, an ordinary form is not, and a\n   * draggable panel that has nothing to reveal is a control that can only get lost.\n   *\n   * Pointer-only by design: it is a \"move this out of the way\" gesture, not a layout\n   * choice worth persisting, and the position resets when the dialog closes. On a\n   * phone the panel is a bottom sheet the width of the screen, so dragging is\n   * suppressed there — there is nothing beside it to see.\n   */\n  draggable?: boolean;\n  /**\n   * Bind the open state to a URL search param (0.12.0): `\"edit\"` is open while\n   * `?edit` is in the query, `{ key: \"dialog\", value: \"create-lease\" }` while\n   * `?dialog=create-lease` is. The URL is then the only state — `open` is ignored —\n   * and the dialog opens from anywhere that sets the param: {@link useDialogParam}'s\n   * setter, a `<Link>`, a shared link, a reload.\n   *\n   * kastlan's `useDialogParam` did this beside the dialog, so its open state could be\n   * deep-linked and captured in a feedback report. Here it also owns the history:\n   * opening through `useDialogParam` pushes an entry, so the Back gesture closes the\n   * dialog by leaving it, and a close (Escape, the backdrop, the X) goes back over\n   * that entry rather than stacking a second one. The dialog's own Back handling\n   * ({@link useOverlayHistory}'s throwaway entry) stays off in this mode — the param's\n   * entry already is one, and two would take two Back presses to close one dialog.\n   *\n   * `onClose` still runs, after the param is cleared. Requires a react-router Router.\n   */\n  urlParam?: DialogParam;\n  /**\n   * A request the dialog started is in flight: it stays until the caller says otherwise\n   * (refactor audit 2026-10-30, DUP-3). A request that has left cannot be called back by\n   * closing the dialog, and the dialog should not pretend it can.\n   *\n   * While true the panel is `aria-busy`, and every dismissal is refused before the exit\n   * starts — the backdrop, Escape, Back, the frame's X and an `actions(close)` button —\n   * so nothing lowers and snaps back. Five dialogs used to hold Escape by hand, in an\n   * `onKeyDown`, and nothing else: a backdrop press or Android's Back closed four of them\n   * mid-request, and CancelSubscriptionConfirm, which guarded its `onClose`, lowered its\n   * panel and popped it back up.\n   *\n   * Escape still goes to whatever is open over the dialog first (a list, a tooltip); the\n   * press that reaches the dialog's own layer is taken and dropped. A refused Back puts\n   * the dialog's history entry back, so the Back after the request closes the dialog\n   * rather than leaving the page.\n   *\n   * Not held: a close the caller decides on (`open={false}`, unmounting), and — with\n   * `urlParam` — Back, which leaves the param's entry like any other navigation. A close\n   * the dialog asks for itself through `ModalCloseContext` while busy is refused too; one\n   * made from an effect that depends on that close (ReauthDialog's on a resolved submit)\n   * runs again once `busy` turns false, because the close changes with it.\n   */\n  busy?: boolean;\n  /**\n   * The PANEL — the `role=\"dialog\"` element the rest of the props go on, not the\n   * backdrop around it (0.35, round 0.35 R4, the follow-up to API-2; as on\n   * `FullBleedDialog`). Merged with the panel's own ref, which the focus\n   * trap holds. Set while the panel is in the document: `null` while a dialog with\n   * `open={false}` is closed, and after a `urlParam` dialog's param is cleared.\n   */\n  ref?: Ref<HTMLDivElement>;\n}\n\n/**\n * The URL-bound dialog: the param is the open state, and closing clears it. A\n * component of its own so the router hook is only called by a `Modal` that asked for\n * it — a plain `Modal` must keep working with no Router above it.\n */\nfunction UrlParamModal({ urlParam, onClose, ...rest }: ModalProps & { urlParam: DialogParam }) {\n  const [open, setOpen] = useDialogParam(urlParam);\n  // Closed from here the moment the dismissal is decided. Going back is a traversal\n  // the browser lands a task later, and between the two the param still says \"open\":\n  // without this the panel, already lowered, would pop back up for that task.\n  const [leaving, setLeaving] = useState(false);\n  if (leaving && !open) setLeaving(false);\n  return (\n    <ModalPanel\n      {...rest}\n      open={open && !leaving}\n      ownHistoryEntry={false}\n      onClose={() => {\n        setLeaving(true);\n        setOpen(false);\n        onClose();\n      }}\n    />\n  );\n}\n\n/**\n * Centered (bottom-sheet on mobile) modal dialog: dimmed backdrop, single\n * rounded panel. Owns the overlay mechanics that the hand-rolled dialogs each\n * re-implemented or lacked — backdrop-click + Escape to close, the platform Back\n * gesture (Keksdose feedback #172), background scroll lock (feedback #204), focus\n * into the panel on open and back to the trigger on close, a Tab focus trap, and\n * `role=\"dialog\"`/`aria-modal`.\n */\nexport function Modal(props: ModalProps) {\n  return props.urlParam !== undefined ? (\n    <UrlParamModal {...props} urlParam={props.urlParam} />\n  ) : (\n    <ModalPanel {...props} />\n  );\n}\n\nfunction ModalPanel({\n  onClose,\n  open,\n  children,\n  size = \"md\",\n  className,\n  labelledBy,\n  onKeyDown,\n  fullBleed,\n  draggable,\n  style,\n  role = \"dialog\",\n  urlParam: _urlParam,\n  busy = false,\n  \"aria-busy\": ariaBusy,\n  ownHistoryEntry = true,\n  ref,\n  ...rest\n}: ModalProps & {\n  /** False when the URL already holds an entry for this dialog — see `urlParam`. */\n  ownHistoryEntry?: boolean;\n}) {\n  const panelRef = useRef<HTMLDivElement>(null);\n  // The caller's `ref` beside the trap's (round 0.35 R4): memoised, so the panel is not\n  // detached and re-attached on every render.\n  const setPanel = useMemo(() => mergeRefs(panelRef, ref), [ref]);\n  const drag = useDragOffset(Boolean(draggable));\n  // Without `open`, mounted means open — the constant `true` every hook below used to\n  // be given. With it, `open` itself.\n  const active = open ?? true;\n\n  // Whether the last close came through `requestClose`, i.e. has ALREADY been\n  // animated. Set in the same batch as the caller's `onClose`, so the render that sees\n  // `open` turn false also sees this and does not lower the panel a second time.\n  const [dismissed, setDismissed] = useState(false);\n  // The exit of a close the caller decided on (only reachable with `open`). Adjusted\n  // during render when `open` flips — `Collapse`'s pattern — so the very render that\n  // closes it already paints the `-out` classes rather than a frame of nothing.\n  const [exiting, setExiting] = useState(false);\n  const [prevOpen, setPrevOpen] = useState(open);\n  if (open !== prevOpen) {\n    setPrevOpen(open);\n    setDismissed(false);\n    setExiting(open === false && prevOpen === true && !dismissed && !skipsExitAnimation());\n    if (open) drag.reset();\n  }\n  useEffect(() => {\n    if (!exiting) return;\n    const timer = setTimeout(() => setExiting(false), OVERLAY_EXIT_MS);\n    return () => clearTimeout(timer);\n  }, [exiting]);\n\n  // The panel lowers itself before the caller unmounts it (live #320 rework). Every\n  // dismissal below goes through `requestClose`; `onClose` still does the closing, one\n  // animation later. A caller that closes the dialog ITSELF — after a save, say —\n  // unmounts with no exit unless it passes `open`, which is what that prop is for.\n  const { closing, requestClose: lower } = useCloseTransition(() => {\n    setDismissed(true);\n    onClose();\n  });\n  // `busy` (DUP-3) refuses HERE, before `lower` starts the exit: a refusal in the\n  // caller's `onClose` comes 220ms too late, after the panel has already gone down.\n  // A new function when `busy` flips, so a close asked for from an effect while busy\n  // (a resolved action whose caller's `isPending` trails its promise) runs again.\n  const requestClose = useCallback(() => {\n    if (!busy) lower();\n  }, [busy, lower]);\n  // A panel on its way out after `open` turned false is already closed: a press on\n  // its fading backdrop must not report a second close.\n  const backdropClose = useBackdropClose(active ? requestClose : () => {});\n  // Back means the same as Escape here. On a phone Escape doesn't exist, so without\n  // this the only way out of a dialog is finding its close button — and Back, the\n  // gesture everyone reaches for, navigated the page underneath instead (#172).\n  // Held only while open: a closed `open={false}` dialog must not own a history entry.\n  // `held`: a Back while busy is refused, and the entry it took is put back.\n  useOverlayHistory(active && ownHistoryEntry, requestClose, { held: busy });\n\n  // Through the shared hook and not by hand: this component's own save/restore copy\n  // was one half of the pair that left the page permanently unscrollable when a dialog\n  // containing an open sheet was closed — see the note in use-body-scroll-lock.ts.\n  useBodyScrollLock(active);\n\n  // Focus the panel itself (not the first field) so opening doesn't pop the mobile\n  // keyboard, while still moving focus into the dialog for keyboard and screen-reader\n  // users. Through the shared hook since this component is where it came from — the\n  // hook adds per-keystroke recomputation, a guard on restoring to a detached node,\n  // and nesting, none of which this copy had. Released when `open` turns false, which\n  // hands focus back to the trigger while the panel is still on its way out.\n  //\n  // \"The panel itself\" only when nothing inside asked for focus: a field the app\n  // autofocuses on purpose keeps it (0.33.1, keksdose live #402 — the same trap took\n  // an autofocused amount straight back in `FullBleedDialog`). Its keyboard is then the\n  // one the app chose to show; the trigger still gets focus back on close.\n  useFocusTrap(panelRef, { active, initialFocus: \"container\" });\n  const leaving = closing || exiting;\n\n  // One layer on the Escape stack while open (Wave 2, DUP-1): a list, a popover or a\n  // tooltip opened inside takes the key before the dialog does, wherever focus is —\n  // and the dialog gets it even when focus is not in the panel.\n  const layer = useDismissLayer(active, requestClose);\n  const handleKeyDown = (e: KeyboardEvent<HTMLDivElement>) => {\n    // The caller's handler sees Escape only while this dialog is the layer on top: a\n    // tooltip or a list open over it takes that press first (0.35, KS's gear wizard).\n    runOwnKeyDown(e, onKeyDown, layer);\n    // To whatever is on top — this dialog, unless something opened over it — and\n    // stopped here. Tab containment lives in useFocusTrap, which listens on the panel.\n    takeEscape(e);\n  };\n\n  // Portal to <body> so the `fixed inset-0 z-50` overlay escapes whatever stacking\n  // context its caller sits in. Rendered inline, a modal opened from e.g. the top\n  // bar (a z-30 context) could paint BELOW a sibling z-30 sticky element like the\n  // expanded transaction editor (feedback #320). The tour/command-palette overlays\n  // already portal for the same reason.\n  if (!active && !exiting) return null;\n  return createPortal(\n    <div\n      // Out of the accessibility tree for the length of a caller-driven exit: focus is\n      // already back on the page, and an `aria-modal` panel that is leaving would hide\n      // that page from a screen reader for 220ms. Not `inert` — that would let a tap\n      // fall through the fading backdrop to the row underneath.\n      aria-hidden={exiting || undefined}\n      // A kit layer, for the tour's layer order (0.50, docs/tours-harmonization.md §11.6):\n      // a backdrop, so the tour measures the panel inside it to tell a full-screen sheet.\n      data-kit-layer=\"backdrop\"\n      className={cn(\n        // Live #320. The panel below rises only where it is bottom-anchored: from md up\n        // it is centred, and a centred box sliding up from off-screen reads as a\n        // different component arriving rather than as the same one settling.\n        leaving ? \"animate-overlay-out\" : \"animate-overlay\",\n        \"fixed inset-0 z-50 flex items-end justify-center bg-black/40 md:items-center\",\n        fullBleed ? \"p-0 md:p-4\" : \"p-4\",\n      )}\n      {...backdropClose}\n    >\n      {/* eslint-disable-next-line jsx-a11y/no-static-element-interactions -- always\n          role=\"dialog\" or \"alertdialog\" (the ternary hides that from the rule): `onKeyDown`\n          is Escape-to-close per the APG dialog pattern, and the drag handlers are\n          swipe-to-dismiss, whose keyboard path is that same Escape. */}\n      <div\n        // `...rest` FIRST, everything the dialog needs to be a dialog after it. A\n        // wrapper that spreads its own props through to this one cannot then take away\n        // the role, the modality or the `tabIndex={-1}` that `useFocusTrap` needs —\n        // losing any of the three is silent, and the symptom (a dialog a screen reader\n        // walks straight out of) shows up nowhere near the call site that caused it.\n        {...rest}\n        ref={setPanel}\n        // Normalised at runtime too: an untyped caller's `role=\"presentation\"` must not\n        // take the dialog role away (props-passthrough pins that).\n        role={role === \"alertdialog\" ? \"alertdialog\" : \"dialog\"}\n        aria-modal=\"true\"\n        // A caller's own `aria-busy` (a preview still loading) is kept beside `busy`.\n        aria-busy={busy ? true : ariaBusy}\n        aria-labelledby={labelledBy}\n        tabIndex={-1}\n        onKeyDown={handleKeyDown}\n        {...drag.handlers}\n        // MERGED, not replaced: `drag.style` is undefined until a drag starts, so\n        // assigning it outright would drop a caller's own `style` on every render but\n        // the ones where the panel is being dragged.\n        style={{ ...style, ...drag.style }}\n        className={cn(\n          leaving ? \"animate-sheet-out md:animate-none\" : \"animate-sheet md:animate-none\",\n          \"w-full rounded-lg border border-subtle bg-surface shadow-sm outline-none\",\n          { md: \"max-w-md\", lg: \"max-w-lg\", xl: \"max-w-3xl\", \"2xl\": \"max-w-[110rem]\" }[size],\n          // A panel taller than the screen has to scroll ITSELF. The backdrop is\n          // `fixed inset-0` and the body is scroll-locked while a dialog is open, so\n          // without this the overflow simply had nowhere to go: on a phone the panel\n          // is bottom-anchored, so it grew UPWARD past the top edge and the part that\n          // went past it could not be reached by any gesture (Keksdose live #254, on\n          // the price-merge dialog — but it was every dialog with more than a screen\n          // of content). `max-h-full` resolves against the backdrop's content box,\n          // which is the viewport minus its own padding, so the panel stops exactly\n          // where the screen does; `overscroll-contain` keeps the fling inside it.\n          //\n          // Three callers had already patched themselves with `max-h-[90vh]` +\n          // an inner scroller. Those still win — `cn` is tailwind-merge — and this is\n          // the default they should not have needed.\n          \"max-h-full overflow-y-auto overscroll-contain\",\n          \"p-4\",\n          // The grab affordance sits on the panel's own top strip: a drag handle of\n          // its own would be one more control in a dialog that is mostly one field.\n          draggable && \"md:[&>*:first-child]:cursor-grab\",\n          className,\n        )}\n      >\n        <ModalCloseContext.Provider value={requestClose}>{children}</ModalCloseContext.Provider>\n      </div>\n    </div>,\n    document.body,\n  );\n}\n"],"mappings":"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","names":[]}
+{"version":3,"sources":["../../src/components/modal.tsx"],"sourcesContent":["import { createContext, useCallback, useEffect, useMemo, useRef, useState } from \"react\";\nimport { createPortal } from \"react-dom\";\nimport type {\n  ComponentPropsWithoutRef,\n  KeyboardEvent,\n  MouseEvent as ReactMouseEvent,\n  PointerEvent as ReactPointerEvent,\n  ReactNode,\n  Ref,\n} from \"react\";\nimport { cn } from \"../lib/cn\";\nimport { mergeRefs } from \"./field-parts\";\nimport { useFocusTrap } from \"../hooks/use-focus-trap\";\nimport { useBreakpoint } from \"../hooks/use-breakpoint\";\nimport { useBodyScrollLock } from \"../hooks/use-body-scroll-lock\";\nimport { useOverlayHistory } from \"../hooks/use-overlay-history\";\nimport { useDialogParam, type DialogParam } from \"../hooks/use-search-param-state\";\nimport { OVERLAY_EXIT_MS, skipsExitAnimation, useCloseTransition } from \"../hooks/use-close-transition\";\nimport { runOwnKeyDown, takeEscape, useDismissLayer } from \"../hooks/use-dismiss\";\n\n/**\n * Drag the panel by its top strip, in pointer space (dev#460).\n *\n * Deliberately not a library and not persisted: the offset is component state that\n * dies with the dialog. It starts only on a press that lands on the panel's own\n * chrome — never on a field, a button or a link, which is what keeps \"drag to select\n * text in the textarea\" working. Above `md` only: below it the panel is a\n * full-width bottom sheet with nothing beside it to uncover.\n *\n * The whole gesture stays on the PANEL — captured pointer, React handlers — rather than\n * on `window`. The first shape of this added `pointermove`/`pointerup` to `window` from\n * inside the `pointerdown` handler and took them off again from the `pointerup` handler,\n * so the teardown ran only if the gesture ended: React never sees a listener added from\n * an event handler, and an unmount mid-drag left a live `pointermove` on `window` for\n * the life of the page, pinning this hook's state with it. The one caller that enables\n * dragging is the feedback composer, which closes ITSELF on submit — a Ctrl+Enter sent\n * with the pointer still down is exactly that order of events, once per drag.\n */\nfunction useDragOffset(enabled: boolean) {\n  const [offset, setOffset] = useState<{ x: number; y: number } | null>(null);\n  const from = useRef<{ x: number; y: number; ox: number; oy: number } | null>(null);\n  // `md:` as the panel's own CSS reads it, at the text size in force: 768 px at Normal,\n  // 960 at Large. `innerWidth >= 768` dragged the bottom sheet of an 800 px window at\n  // Large (refactor audit 2026-10-30, DUP-9). Without `matchMedia` (jsdom), the desktop.\n  const wide = useBreakpoint(\"md\", true);\n\n  const endDrag = () => {\n    from.current = null;\n  };\n\n  return {\n    /** Back to where the panel opens. A `Modal` with an `open` prop outlives its own\n     *  closes, so \"the position resets when the dialog closes\" needs saying. */\n    reset: () => setOffset(null),\n    style: offset ? { transform: `translate(${offset.x}px, ${offset.y}px)` } : undefined,\n    handlers: !enabled\n      ? undefined\n      : {\n          onPointerDown: (e: ReactPointerEvent<HTMLDivElement>) => {\n            if (e.button !== 0 || !wide) return;\n            const target = e.target as HTMLElement;\n            // Only the panel itself and its non-interactive chrome start a drag; a\n            // press inside any control belongs to that control.\n            if (target.closest(\"input,textarea,select,button,a,[role='button']\")) return;\n            from.current = { x: e.clientX, y: e.clientY, ox: offset?.x ?? 0, oy: offset?.y ?? 0 };\n            try {\n              // Capture is what lets the handlers live on the panel: every later\n              // pointer event for this pointer retargets here, so the drag keeps\n              // working once the pointer outruns the panel's own box — which it always\n              // does, since the panel moves out from under it.\n              e.currentTarget.setPointerCapture(e.pointerId);\n            } catch {\n              // jsdom implements no pointer capture, and a browser throws\n              // NotFoundError for a pointerId that is already gone. Neither is worth\n              // refusing the drag: uncaptured, the panel still gets the moves that\n              // land on it.\n            }\n          },\n          onPointerMove: (e: ReactPointerEvent<HTMLDivElement>) => {\n            const start = from.current;\n            if (!start) return;\n            setOffset({ x: start.ox + e.clientX - start.x, y: start.oy + e.clientY - start.y });\n          },\n          onPointerUp: endDrag,\n          // A cancel (the browser taking the pointer for a scroll or a gesture) and a\n          // lost capture both mean no `pointerup` is coming. Without them the drag would\n          // stay \"live\" and the next move over the panel would jump it.\n          onPointerCancel: endDrag,\n          onLostPointerCapture: endDrag,\n        },\n  };\n}\n\n/**\n * The panel's own ANIMATED dismissal, for chrome rendered inside it. `DialogFrame`'s X\n * and its `actions(close)` read this, so a Cancel or an X lowers the panel exactly the\n * way Escape does — calling `onClose` from inside unmounts with no exit, which is the\n * documented limit of {@link useCloseTransition}. `null` outside a `Modal`.\n */\nexport const ModalCloseContext = createContext<(() => void) | null>(null);\n\n/**\n * Backdrop handlers that close only when a press starts AND ends on the\n * backdrop itself. A plain onClick fires on mouseup, so dragging a text\n * selection that starts inside the panel and releases over the backdrop would\n * dismiss the dialog (feedback #254) — and the reverse drag would too, since\n * click targets the common ancestor of the down/up elements.\n */\nexport function useBackdropClose(onClose: () => void) {\n  const pressStartedOnBackdrop = useRef(false);\n  return {\n    onMouseDown: (e: ReactMouseEvent<HTMLDivElement>) => {\n      pressStartedOnBackdrop.current = e.target === e.currentTarget;\n    },\n    onMouseUp: (e: ReactMouseEvent<HTMLDivElement>) => {\n      const started = pressStartedOnBackdrop.current;\n      pressStartedOnBackdrop.current = false;\n      if (started && e.target === e.currentTarget) onClose();\n    },\n  };\n}\n\n// Tab-cycle target set: the interactive descendants the focus trap rotates\n// through. Querying live (per keystroke) means dynamically rendered fields are\n// included automatically.\n/**\n * `extends ComponentPropsWithoutRef<\"div\">` so anything a `<div>` takes reaches the\n * PANEL — the element with `role=\"dialog\"`, which is the one a consumer means. That is\n * where a `data-tour` anchor, a test id, an `aria-describedby` or an `aria-label` has\n * to land; before this, a closed prop list dropped all four silently (audit §api-design).\n */\nexport interface ModalProps extends Omit<ComponentPropsWithoutRef<\"div\">, \"role\"> {\n  /** Invoked on backdrop click and on Escape. */\n  onClose: () => void;\n  /**\n   * Who decides whether the dialog is up, when the caller wants to keep it MOUNTED.\n   *\n   * Left out, the dialog is open for as long as it is mounted — `{open && <Modal/>}`,\n   * which is every caller before this prop and stays exactly as it was. That idiom has\n   * one blind spot: a close the CALLER decides on (a save that succeeded, a\n   * `setOpen(false)` from outside) unmounts the panel on the spot, with no exit,\n   * because there is nothing left to animate. kastlan's `FormModal` was nothing but an\n   * `if (!open) return null` gate in front of this.\n   *\n   * Passed, the component stays mounted while closed and renders nothing, and a flip\n   * to `false` plays the same exit a dismissal does before the panel goes. The focus\n   * trap, the scroll lock and the Back-gesture history entry are held only while\n   * `open` is true — they are released the moment it turns false, so focus is back on\n   * the trigger while the panel is still lowering. A dismissal (Escape, the backdrop,\n   * Back, the frame's X) animates first and then calls `onClose`; the `false` that\n   * comes back from it is not animated a second time.\n   *\n   * The body is unmounted once the exit has finished, as it is today, so a form inside\n   * still starts fresh on the next open.\n   */\n  open?: boolean;\n  /** `\"alertdialog\"` for a dialog that interrupts to ask a question the user must\n   *  answer (a confirmation) — screen readers announce it with more urgency. Only the\n   *  two dialog roles are allowed: the panel stays modal either way. */\n  role?: \"dialog\" | \"alertdialog\";\n  children: ReactNode;\n  /**\n   * Panel max-width: `md` (28rem), `lg` (32rem), `xl` (48rem), `2xl` (the display less\n   * the backdrop's margin, capped at 110rem).\n   *\n   * `xl` exists because two callers had already written `className=\"max-w-3xl\"` to\n   * reach it — the payee backfill's preview table and the price-merge dialog, both\n   * of which hold a list and several fields rather than one question. A caller\n   * patching a missing size IS the signal that the size is missing, and a\n   * hand-written width in a `className` is a width nothing else can line up with.\n   *\n   * `2xl` is the same signal one size up (round 0.34 C3, KS U1): a dialog whose\n   * content is a TABLE to be read. Kurvenschmiede's five part dialogs hold a measured\n   * table pasted from a spreadsheet and had patched themselves to\n   * `w-[min(110rem,94vw)] max-w-none`; Keksdose's report drilldown passed `size=\"lg\"`\n   * and then `max-w-5xl`. The cap is the generous one of the two, because a table\n   * squeezed into a box in the middle of a wide screen is a table scrolled sideways\n   * (KS feedback #16); below the cap the panel is as wide as the backdrop lets it be.\n   * In rem, so it grows with the text size until the screen stops it.\n   *\n   * The panel is `w-full` under every one of them, so the cap only bites once the\n   * viewport is wider than it: on a phone all four are the same full-width bottom\n   * sheet. Nothing here may introduce a `min-w-*`, which is what would break that.\n   */\n  size?: \"md\" | \"lg\" | \"xl\" | \"2xl\";\n  /** Extra classes for the panel (e.g. `space-y-3` for form content spacing). */\n  className?: string;\n  /** id of the heading element, wired to `aria-labelledby`. */\n  labelledBy?: string;\n  /**\n   * Extra key handling on the panel (e.g. Ctrl/Cmd+Enter to submit). Runs first; a\n   * `preventDefault()` on Escape HERE keeps the dialog open — the owner's claim (see\n   * `use-dismiss.ts`). One a field inside makes does not, since 0.34: the rule\n   * `FullBleedDialog` already had, so a search box keeping Chromium from clearing itself\n   * no longer holds the dialog open (Wave 2, DUP-1).\n   */\n  onKeyDown?: (e: KeyboardEvent<HTMLDivElement>) => void;\n  /**\n   * Drop the backdrop's mobile margin so the panel can reach the screen edges\n   * (a full-screen sheet on phones). The panel still needs its own\n   * `h-[100dvh] max-w-full rounded-none` classes via `className` to fill it; the\n   * desktop `md:p-4` margin is kept. Defaults to false (padded on all sizes).\n   */\n  fullBleed?: boolean;\n  /**\n   * Let the user drag the panel out of the way by its top edge (Keksdose feedback\n   * dev#460: *\"Make the feedback dialog draggable so I can see behind it if it\n   * blocks something.\"*).\n   *\n   * Opt-in, because it only makes sense for a dialog whose content is ABOUT the page\n   * behind it — the feedback composer is the case, an ordinary form is not, and a\n   * draggable panel that has nothing to reveal is a control that can only get lost.\n   *\n   * Pointer-only by design: it is a \"move this out of the way\" gesture, not a layout\n   * choice worth persisting, and the position resets when the dialog closes. On a\n   * phone the panel is a bottom sheet the width of the screen, so dragging is\n   * suppressed there — there is nothing beside it to see.\n   */\n  draggable?: boolean;\n  /**\n   * Bind the open state to a URL search param (0.12.0): `\"edit\"` is open while\n   * `?edit` is in the query, `{ key: \"dialog\", value: \"create-lease\" }` while\n   * `?dialog=create-lease` is. The URL is then the only state — `open` is ignored —\n   * and the dialog opens from anywhere that sets the param: {@link useDialogParam}'s\n   * setter, a `<Link>`, a shared link, a reload.\n   *\n   * kastlan's `useDialogParam` did this beside the dialog, so its open state could be\n   * deep-linked and captured in a feedback report. Here it also owns the history:\n   * opening through `useDialogParam` pushes an entry, so the Back gesture closes the\n   * dialog by leaving it, and a close (Escape, the backdrop, the X) goes back over\n   * that entry rather than stacking a second one. The dialog's own Back handling\n   * ({@link useOverlayHistory}'s throwaway entry) stays off in this mode — the param's\n   * entry already is one, and two would take two Back presses to close one dialog.\n   *\n   * `onClose` still runs, after the param is cleared. Requires a react-router Router.\n   */\n  urlParam?: DialogParam;\n  /**\n   * A request the dialog started is in flight: it stays until the caller says otherwise\n   * (refactor audit 2026-10-30, DUP-3). A request that has left cannot be called back by\n   * closing the dialog, and the dialog should not pretend it can.\n   *\n   * While true the panel is `aria-busy`, and every dismissal is refused before the exit\n   * starts — the backdrop, Escape, Back, the frame's X and an `actions(close)` button —\n   * so nothing lowers and snaps back. Five dialogs used to hold Escape by hand, in an\n   * `onKeyDown`, and nothing else: a backdrop press or Android's Back closed four of them\n   * mid-request, and CancelSubscriptionConfirm, which guarded its `onClose`, lowered its\n   * panel and popped it back up.\n   *\n   * Escape still goes to whatever is open over the dialog first (a list, a tooltip); the\n   * press that reaches the dialog's own layer is taken and dropped. A refused Back puts\n   * the dialog's history entry back, so the Back after the request closes the dialog\n   * rather than leaving the page.\n   *\n   * Not held: a close the caller decides on (`open={false}`, unmounting), and — with\n   * `urlParam` — Back, which leaves the param's entry like any other navigation. A close\n   * the dialog asks for itself through `ModalCloseContext` while busy is refused too; one\n   * made from an effect that depends on that close (ReauthDialog's on a resolved submit)\n   * runs again once `busy` turns false, because the close changes with it.\n   */\n  busy?: boolean;\n  /**\n   * The PANEL — the `role=\"dialog\"` element the rest of the props go on, not the\n   * backdrop around it (0.35, round 0.35 R4, the follow-up to API-2; as on\n   * `FullBleedDialog`). Merged with the panel's own ref, which the focus\n   * trap holds. Set while the panel is in the document: `null` while a dialog with\n   * `open={false}` is closed, and after a `urlParam` dialog's param is cleared.\n   */\n  ref?: Ref<HTMLDivElement>;\n}\n\n/**\n * The URL-bound dialog: the param is the open state, and closing clears it. A\n * component of its own so the router hook is only called by a `Modal` that asked for\n * it — a plain `Modal` must keep working with no Router above it.\n */\nfunction UrlParamModal({ urlParam, onClose, ...rest }: ModalProps & { urlParam: DialogParam }) {\n  const [open, setOpen] = useDialogParam(urlParam);\n  // Closed from here the moment the dismissal is decided. Going back is a traversal\n  // the browser lands a task later, and between the two the param still says \"open\":\n  // without this the panel, already lowered, would pop back up for that task.\n  const [leaving, setLeaving] = useState(false);\n  if (leaving && !open) setLeaving(false);\n  return (\n    <ModalPanel\n      {...rest}\n      open={open && !leaving}\n      ownHistoryEntry={false}\n      onClose={() => {\n        setLeaving(true);\n        setOpen(false);\n        onClose();\n      }}\n    />\n  );\n}\n\n/**\n * Centered (bottom-sheet on mobile) modal dialog: dimmed backdrop, single\n * rounded panel. Owns the overlay mechanics that the hand-rolled dialogs each\n * re-implemented or lacked — backdrop-click + Escape to close, the platform Back\n * gesture (Keksdose feedback #172), background scroll lock (feedback #204), focus\n * into the panel on open and back to the trigger on close, a Tab focus trap, and\n * `role=\"dialog\"`/`aria-modal`.\n */\nexport function Modal(props: ModalProps) {\n  return props.urlParam !== undefined ? (\n    <UrlParamModal {...props} urlParam={props.urlParam} />\n  ) : (\n    <ModalPanel {...props} />\n  );\n}\n\nfunction ModalPanel({\n  onClose,\n  open,\n  children,\n  size = \"md\",\n  className,\n  labelledBy,\n  onKeyDown,\n  fullBleed,\n  draggable,\n  style,\n  role = \"dialog\",\n  urlParam: _urlParam,\n  busy = false,\n  \"aria-busy\": ariaBusy,\n  ownHistoryEntry = true,\n  ref,\n  ...rest\n}: ModalProps & {\n  /** False when the URL already holds an entry for this dialog — see `urlParam`. */\n  ownHistoryEntry?: boolean;\n}) {\n  const panelRef = useRef<HTMLDivElement>(null);\n  // The caller's `ref` beside the trap's (round 0.35 R4): memoised, so the panel is not\n  // detached and re-attached on every render.\n  const setPanel = useMemo(() => mergeRefs(panelRef, ref), [ref]);\n  const drag = useDragOffset(Boolean(draggable));\n  // Without `open`, mounted means open — the constant `true` every hook below used to\n  // be given. With it, `open` itself.\n  const active = open ?? true;\n\n  // Whether the last close came through `requestClose`, i.e. has ALREADY been\n  // animated. Set in the same batch as the caller's `onClose`, so the render that sees\n  // `open` turn false also sees this and does not lower the panel a second time.\n  const [dismissed, setDismissed] = useState(false);\n  // The exit of a close the caller decided on (only reachable with `open`). Adjusted\n  // during render when `open` flips — `Collapse`'s pattern — so the very render that\n  // closes it already paints the `-out` classes rather than a frame of nothing.\n  const [exiting, setExiting] = useState(false);\n  const [prevOpen, setPrevOpen] = useState(open);\n  if (open !== prevOpen) {\n    setPrevOpen(open);\n    setDismissed(false);\n    setExiting(open === false && prevOpen === true && !dismissed && !skipsExitAnimation());\n    if (open) drag.reset();\n  }\n  useEffect(() => {\n    if (!exiting) return;\n    const timer = setTimeout(() => setExiting(false), OVERLAY_EXIT_MS);\n    return () => clearTimeout(timer);\n  }, [exiting]);\n\n  // The panel lowers itself before the caller unmounts it (live #320 rework). Every\n  // dismissal below goes through `requestClose`; `onClose` still does the closing, one\n  // animation later. A caller that closes the dialog ITSELF — after a save, say —\n  // unmounts with no exit unless it passes `open`, which is what that prop is for.\n  const { closing, requestClose: lower } = useCloseTransition(() => {\n    setDismissed(true);\n    onClose();\n  });\n  // `busy` (DUP-3) refuses HERE, before `lower` starts the exit: a refusal in the\n  // caller's `onClose` comes 220ms too late, after the panel has already gone down.\n  // A new function when `busy` flips, so a close asked for from an effect while busy\n  // (a resolved action whose caller's `isPending` trails its promise) runs again.\n  const requestClose = useCallback(() => {\n    if (!busy) lower();\n  }, [busy, lower]);\n  // A panel on its way out after `open` turned false is already closed: a press on\n  // its fading backdrop must not report a second close.\n  const backdropClose = useBackdropClose(active ? requestClose : () => {});\n  // Back means the same as Escape here. On a phone Escape doesn't exist, so without\n  // this the only way out of a dialog is finding its close button — and Back, the\n  // gesture everyone reaches for, navigated the page underneath instead (#172).\n  // Held only while open: a closed `open={false}` dialog must not own a history entry.\n  // `held`: a Back while busy is refused, and the entry it took is put back.\n  useOverlayHistory(active && ownHistoryEntry, requestClose, { held: busy });\n\n  // Through the shared hook and not by hand: this component's own save/restore copy\n  // was one half of the pair that left the page permanently unscrollable when a dialog\n  // containing an open sheet was closed — see the note in use-body-scroll-lock.ts.\n  useBodyScrollLock(active);\n\n  // Focus the panel itself (not the first field) so opening doesn't pop the mobile\n  // keyboard, while still moving focus into the dialog for keyboard and screen-reader\n  // users. Through the shared hook since this component is where it came from — the\n  // hook adds per-keystroke recomputation, a guard on restoring to a detached node,\n  // and nesting, none of which this copy had. Released when `open` turns false, which\n  // hands focus back to the trigger while the panel is still on its way out.\n  //\n  // \"The panel itself\" only when nothing inside asked for focus: a field the app\n  // autofocuses on purpose keeps it (0.33.1, keksdose live #402 — the same trap took\n  // an autofocused amount straight back in `FullBleedDialog`). Its keyboard is then the\n  // one the app chose to show; the trigger still gets focus back on close.\n  useFocusTrap(panelRef, { active, initialFocus: \"container\" });\n  const leaving = closing || exiting;\n\n  // One layer on the Escape stack while open (Wave 2, DUP-1): a list, a popover or a\n  // tooltip opened inside takes the key before the dialog does, wherever focus is —\n  // and the dialog gets it even when focus is not in the panel.\n  const layer = useDismissLayer(active, requestClose);\n  const handleKeyDown = (e: KeyboardEvent<HTMLDivElement>) => {\n    // The caller's handler sees Escape only while this dialog is the layer on top: a\n    // tooltip or a list open over it takes that press first (0.35, KS's gear wizard).\n    runOwnKeyDown(e, onKeyDown, layer);\n    // To whatever is on top — this dialog, unless something opened over it — and\n    // stopped here. Tab containment lives in useFocusTrap, which listens on the panel.\n    takeEscape(e);\n  };\n\n  // Portal to <body> so the `fixed inset-0 z-50` overlay escapes whatever stacking\n  // context its caller sits in. Rendered inline, a modal opened from e.g. the top\n  // bar (a z-30 context) could paint BELOW a sibling z-30 sticky element like the\n  // expanded transaction editor (feedback #320). The tour/command-palette overlays\n  // already portal for the same reason.\n  if (!active && !exiting) return null;\n  return createPortal(\n    <div\n      // Out of the accessibility tree for the length of a caller-driven exit: focus is\n      // already back on the page, and an `aria-modal` panel that is leaving would hide\n      // that page from a screen reader for 220ms. Not `inert` — that would let a tap\n      // fall through the fading backdrop to the row underneath.\n      aria-hidden={exiting || undefined}\n      // A kit layer, for the tour's layer order (0.50, docs/tours-harmonization.md §11.6):\n      // a backdrop, so the tour measures the panel inside it to tell a full-screen sheet.\n      data-kit-layer=\"backdrop\"\n      className={cn(\n        // Live #320. The panel below rises only where it is bottom-anchored: from md up\n        // it is centred, and a centred box sliding up from off-screen reads as a\n        // different component arriving rather than as the same one settling.\n        leaving ? \"animate-overlay-out\" : \"animate-overlay\",\n        \"fixed inset-0 z-50 flex items-end justify-center bg-black/40 md:items-center\",\n        fullBleed ? \"p-0 md:p-4\" : \"p-4\",\n      )}\n      {...backdropClose}\n    >\n      {/* eslint-disable-next-line jsx-a11y/no-static-element-interactions -- always\n          role=\"dialog\" or \"alertdialog\" (the ternary hides that from the rule): `onKeyDown`\n          is Escape-to-close per the APG dialog pattern, and the drag handlers are\n          swipe-to-dismiss, whose keyboard path is that same Escape. */}\n      <div\n        // `...rest` FIRST, everything the dialog needs to be a dialog after it. A\n        // wrapper that spreads its own props through to this one cannot then take away\n        // the role, the modality or the `tabIndex={-1}` that `useFocusTrap` needs —\n        // losing any of the three is silent, and the symptom (a dialog a screen reader\n        // walks straight out of) shows up nowhere near the call site that caused it.\n        {...rest}\n        ref={setPanel}\n        // Normalised at runtime too: an untyped caller's `role=\"presentation\"` must not\n        // take the dialog role away (props-passthrough pins that).\n        role={role === \"alertdialog\" ? \"alertdialog\" : \"dialog\"}\n        aria-modal=\"true\"\n        // A caller's own `aria-busy` (a preview still loading) is kept beside `busy`.\n        aria-busy={busy ? true : ariaBusy}\n        aria-labelledby={labelledBy}\n        tabIndex={-1}\n        onKeyDown={handleKeyDown}\n        {...drag.handlers}\n        // MERGED, not replaced: `drag.style` is undefined until a drag starts, so\n        // assigning it outright would drop a caller's own `style` on every render but\n        // the ones where the panel is being dragged.\n        style={{ ...style, ...drag.style }}\n        className={cn(\n          leaving ? \"animate-sheet-out md:animate-none\" : \"animate-sheet md:animate-none\",\n          \"w-full rounded-lg border border-subtle bg-surface shadow-sm outline-none\",\n          { md: \"max-w-md\", lg: \"max-w-lg\", xl: \"max-w-3xl\", \"2xl\": \"max-w-[110rem]\" }[size],\n          // A panel taller than the screen has to scroll ITSELF. The backdrop is\n          // `fixed inset-0` and the body is scroll-locked while a dialog is open, so\n          // without this the overflow simply had nowhere to go: on a phone the panel\n          // is bottom-anchored, so it grew UPWARD past the top edge and the part that\n          // went past it could not be reached by any gesture (Keksdose live #254, on\n          // the price-merge dialog — but it was every dialog with more than a screen\n          // of content). `max-h-full` resolves against the backdrop's content box,\n          // which is the viewport minus its own padding, so the panel stops exactly\n          // where the screen does; `overscroll-contain` keeps the fling inside it.\n          //\n          // Three callers had already patched themselves with `max-h-[90vh]` +\n          // an inner scroller. Those still win — `cn` is tailwind-merge — and this is\n          // the default they should not have needed.\n          \"max-h-full overflow-y-auto overscroll-contain\",\n          \"p-4\",\n          // The grab affordance sits on the panel's own top strip: a drag handle of\n          // its own would be one more control in a dialog that is mostly one field.\n          draggable && \"md:[&>*:first-child]:cursor-grab\",\n          className,\n        )}\n      >\n        <ModalCloseContext.Provider value={requestClose}>{children}</ModalCloseContext.Provider>\n      </div>\n    </div>,\n    document.body,\n  );\n}\n"],"mappings":"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","names":[]}

package/dist/components/month-grid.d.ts

@@ -0,0 +1,55 @@
+import type { KeyboardEvent } from "react";
+/** Months per row: a year is four rows of three. */
+export declare const MONTH_COLUMNS = 3;
+/** A "YYYY-MM" key as a count of months, and back: month arithmetic with no `Date`
+ *  rollover to step around. */
+export declare const monthIndex: (key: string) => number;
+export declare const keyOfIndex: (index: number) => string;
+export declare const shiftKey: (key: string, delta: number) => string;
+/** The 1st of a "YYYY-MM" month, for `Intl` to name. */
+export declare const firstOfKey: (key: string) => Date;
+/** `key` pulled inside the bounds — where a grid opens when the value is outside them. */
+export declare function clampKey(key: string, minKey: string | null, maxKey: string | null): string;
+/**
+ * Which of the year arrows over a grid on `active`'s year are dead: an arrow is, once
+ * EVERY month of the year it leads to is out of bounds. The arrows are their owner's —
+ * MonthPicker's sit around the year, JumpCalendar's double as its month arrows — and they
+ * stay focusable either way (`aria-disabled`, refactor audit 2026-10-30, INP-4).
+ */
+export declare function yearArrowsBlocked(active: string, minKey: string | null, maxKey: string | null): {
+    previous: boolean;
+    next: boolean;
+};
+export interface MonthGridProps {
+    /** The month holding the tab stop, "YYYY-MM" — and with it the year on show. Its owner
+     *  keeps it, because the owner's year arrows move it too. */
+    active: string;
+    /** The keys moved the tab stop; the grid moves the focus after it. */
+    onActiveChange: (key: string) => void;
+    /** A month inside the bounds was picked (a click, Enter, Space). */
+    onPick: (key: string) => void;
+    /** The selection, as months: a single month is both ends, and a range's months between
+     *  them are its band. `null` for none. */
+    from: string | null;
+    to: string | null;
+    minKey: string | null;
+    maxKey: string | null;
+    /** The month to ring as "now". */
+    currentKey: string;
+    locale: string | undefined;
+    /** A cell's accessible name, given "August 2026" — `monthPicker.month`. */
+    cellName: (monthYear: string) => string;
+    /** The id of what names the grid: the year caption above it. */
+    labelledBy: string;
+    /** Escape in the grid. Left out, it travels on to the popover around it, which closes. */
+    onEscape?: (e: KeyboardEvent<HTMLButtonElement>) => void;
+}
+/**
+ * A grid in the APG sense, like `MiniCalendar`'s days: one tab stop (the roving
+ * tabindex), the arrows walk the months — left/right by one, up/down by a row of three —
+ * and walking off either end of the year MOVES the year rather than stopping; Home/End
+ * the row, PageUp/PageDown a year. Out-of-bounds months are `aria-disabled`, not
+ * `disabled`, so the roving tab stop never falls into a hole. The focus lands on the tab
+ * stop when the grid mounts: both owners mount it only when asked to pick a month.
+ */
+export declare function MonthGrid({ active, onActiveChange, onPick, from, to, minKey, maxKey, currentKey, locale, cellName, labelledBy, onEscape, }: MonthGridProps): import("react").JSX.Element;

package/dist/components/month-grid.js

@@ -0,0 +1,148 @@
+"use client";
+import { jsx } from "react/jsx-runtime";
+import { useEffect, useMemo, useRef } from "react";
+import { cn } from "../lib/cn.js";
+import { horizontalStep } from "../lib/direction.js";
+import { pad } from "../lib/dates.js";
+import { upperFirst } from "../lib/text-case.js";
+import { FOCUS_RING_WIDTH } from "./focus-ring.js";
+const MONTH_COLUMNS = 3;
+const monthIndex = (key) => Number(key.slice(0, 4)) * 12 + Number(key.slice(5, 7)) - 1;
+const keyOfIndex = (index) => `${String(Math.floor(index / 12)).padStart(4, "0")}-${pad(index % 12 + 1)}`;
+const shiftKey = (key, delta) => keyOfIndex(monthIndex(key) + delta);
+const firstOfKey = (key) => new Date(Number(key.slice(0, 4)), Number(key.slice(5, 7)) - 1, 1);
+function clampKey(key, minKey, maxKey) {
+  if (minKey && key < minKey) return minKey;
+  if (maxKey && key > maxKey) return maxKey;
+  return key;
+}
+function yearArrowsBlocked(active, minKey, maxKey) {
+  const year = Number(active.slice(0, 4));
+  return {
+    previous: Boolean(minKey && year - 1 < Number(minKey.slice(0, 4))),
+    next: Boolean(maxKey && year + 1 > Number(maxKey.slice(0, 4)))
+  };
+}
+function MonthGrid({
+  active,
+  onActiveChange,
+  onPick,
+  from,
+  to,
+  minKey,
+  maxKey,
+  currentKey,
+  locale,
+  cellName,
+  labelledBy,
+  onEscape
+}) {
+  const gridRef = useRef(null);
+  const year = Number(active.slice(0, 4));
+  const outOfBounds = (key) => Boolean(minKey && key < minKey || maxKey && key > maxKey);
+  const shortNames = useMemo(() => {
+    const fmt = new Intl.DateTimeFormat(locale, { month: "short" });
+    return Array.from({ length: 12 }, (_, i) => upperFirst(fmt.format(new Date(2e3, i, 1)), locale));
+  }, [locale]);
+  const longName = useMemo(() => new Intl.DateTimeFormat(locale, { month: "long", year: "numeric" }), [locale]);
+  useEffect(() => {
+    gridRef.current?.querySelector('[tabindex="0"]')?.focus();
+  }, []);
+  const pendingFocus = useRef(null);
+  useEffect(() => {
+    const key = pendingFocus.current;
+    if (!key) return;
+    pendingFocus.current = null;
+    gridRef.current?.querySelector(`[data-month="${key}"]`)?.focus();
+  });
+  const onCellKeyDown = (e) => {
+    if (e.key === "Escape") {
+      onEscape?.(e);
+      return;
+    }
+    const step = horizontalStep(e.key, e.currentTarget);
+    const col = monthIndex(active) % 12 % MONTH_COLUMNS;
+    let delta;
+    switch (step ? "horizontal" : e.key) {
+      case "horizontal":
+        delta = step;
+        break;
+      case "ArrowUp":
+        delta = -MONTH_COLUMNS;
+        break;
+      case "ArrowDown":
+        delta = MONTH_COLUMNS;
+        break;
+      case "Home":
+        delta = -col;
+        break;
+      case "End":
+        delta = MONTH_COLUMNS - 1 - col;
+        break;
+      case "PageUp":
+        delta = -12;
+        break;
+      case "PageDown":
+        delta = 12;
+        break;
+      default:
+        return;
+    }
+    e.preventDefault();
+    if (delta === 0) return;
+    const next = shiftKey(active, delta);
+    pendingFocus.current = next;
+    onActiveChange(next);
+  };
+  const low = from ?? to;
+  const high = to ?? from;
+  return /* @__PURE__ */ jsx("div", { ref: gridRef, role: "grid", "aria-labelledby": labelledBy, className: "grid gap-1", children: Array.from({ length: 12 / MONTH_COLUMNS }, (_, row) => /* @__PURE__ */ jsx("div", { role: "row", className: "grid grid-cols-3 gap-1", children: Array.from({ length: MONTH_COLUMNS }, (_2, c) => {
+    const index = row * MONTH_COLUMNS + c;
+    const key = keyOfIndex(year * 12 + index);
+    const disabled = outOfBounds(key);
+    const selected = low !== null && high !== null && key >= low && key <= high;
+    const end = key === from || key === to;
+    const current = key === currentKey;
+    return /* @__PURE__ */ jsx(
+      "button",
+      {
+        type: "button",
+        role: "gridcell",
+        "data-month": key,
+        tabIndex: key === active ? 0 : -1,
+        "aria-label": cellName(longName.format(firstOfKey(key))),
+        "aria-selected": selected,
+        "aria-disabled": disabled || void 0,
+        "aria-current": current ? "date" : void 0,
+        onClick: () => {
+          if (!disabled) onPick(key);
+        },
+        onKeyDown: onCellKeyDown,
+        className: cn(
+          // 44px rows: the touch-target size, and four of them stand as tall as a
+          // month of days, so JumpCalendar's panel does not jump as its views swap.
+          "h-11 rounded px-1 text-sm tabular-nums transition-colors",
+          FOCUS_RING_WIDTH,
+          "focus-visible:outline-none focus-visible:ring-inset",
+          // A --brand ring on a --brand fill exists only in the DOM.
+          end && !disabled ? "focus-visible:ring-brand-contrast" : "focus-visible:ring-brand",
+          disabled ? "cursor-not-allowed text-placeholder" : end ? "bg-brand text-brand-contrast hover:bg-brand-hover" : selected ? "bg-brand-soft font-medium text-brand-muted hover:bg-brand-soft-hover" : "text-primary hover:bg-hover",
+          current && !selected && !disabled && "ring-1 ring-inset ring-strong"
+        ),
+        children: shortNames[index]
+      },
+      c
+    );
+  }) }, row)) });
+}
+export {
+  MONTH_COLUMNS,
+  MonthGrid,
+  clampKey,
+  firstOfKey,
+  keyOfIndex,
+  monthIndex,
+  shiftKey,
+  yearArrowsBlocked
+};
+//# sourceMappingURL=month-grid.js.map

package/dist/components/month-grid.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/components/month-grid.tsx"],"sourcesContent":["// The year's twelve months as a grid: what MonthPicker opens, and what DatePicker's month\n// jump (JumpCalendar) swaps in for the days. One component since 0.52 (refactor audit\n// 2026-10-30, DUP-11): the two were copies — the same keys, bounds and cells — and had\n// drifted, only JumpCalendar's rows being the 44px touch target. Internal; not re-exported\n// from the barrel.\nimport { useEffect, useMemo, useRef } from \"react\";\nimport type { KeyboardEvent } from \"react\";\nimport { cn } from \"../lib/cn\";\nimport { horizontalStep } from \"../lib/direction\";\nimport { pad } from \"../lib/dates\";\nimport { upperFirst } from \"../lib/text-case\";\nimport { FOCUS_RING_WIDTH } from \"./focus-ring\";\n\n/** Months per row: a year is four rows of three. */\nexport const MONTH_COLUMNS = 3;\n\n/** A \"YYYY-MM\" key as a count of months, and back: month arithmetic with no `Date`\n *  rollover to step around. */\nexport const monthIndex = (key: string) => Number(key.slice(0, 4)) * 12 + Number(key.slice(5, 7)) - 1;\nexport const keyOfIndex = (index: number) =>\n  `${String(Math.floor(index / 12)).padStart(4, \"0\")}-${pad((index % 12) + 1)}`;\nexport const shiftKey = (key: string, delta: number) => keyOfIndex(monthIndex(key) + delta);\n/** The 1st of a \"YYYY-MM\" month, for `Intl` to name. */\nexport const firstOfKey = (key: string) => new Date(Number(key.slice(0, 4)), Number(key.slice(5, 7)) - 1, 1);\n\n/** `key` pulled inside the bounds — where a grid opens when the value is outside them. */\nexport function clampKey(key: string, minKey: string | null, maxKey: string | null): string {\n  if (minKey && key < minKey) return minKey;\n  if (maxKey && key > maxKey) return maxKey;\n  return key;\n}\n\n/**\n * Which of the year arrows over a grid on `active`'s year are dead: an arrow is, once\n * EVERY month of the year it leads to is out of bounds. The arrows are their owner's —\n * MonthPicker's sit around the year, JumpCalendar's double as its month arrows — and they\n * stay focusable either way (`aria-disabled`, refactor audit 2026-10-30, INP-4).\n */\nexport function yearArrowsBlocked(\n  active: string,\n  minKey: string | null,\n  maxKey: string | null,\n): { previous: boolean; next: boolean } {\n  const year = Number(active.slice(0, 4));\n  return {\n    previous: Boolean(minKey && year - 1 < Number(minKey.slice(0, 4))),\n    next: Boolean(maxKey && year + 1 > Number(maxKey.slice(0, 4))),\n  };\n}\n\nexport interface MonthGridProps {\n  /** The month holding the tab stop, \"YYYY-MM\" — and with it the year on show. Its owner\n   *  keeps it, because the owner's year arrows move it too. */\n  active: string;\n  /** The keys moved the tab stop; the grid moves the focus after it. */\n  onActiveChange: (key: string) => void;\n  /** A month inside the bounds was picked (a click, Enter, Space). */\n  onPick: (key: string) => void;\n  /** The selection, as months: a single month is both ends, and a range's months between\n   *  them are its band. `null` for none. */\n  from: string | null;\n  to: string | null;\n  minKey: string | null;\n  maxKey: string | null;\n  /** The month to ring as \"now\". */\n  currentKey: string;\n  locale: string | undefined;\n  /** A cell's accessible name, given \"August 2026\" — `monthPicker.month`. */\n  cellName: (monthYear: string) => string;\n  /** The id of what names the grid: the year caption above it. */\n  labelledBy: string;\n  /** Escape in the grid. Left out, it travels on to the popover around it, which closes. */\n  onEscape?: (e: KeyboardEvent<HTMLButtonElement>) => void;\n}\n\n/**\n * A grid in the APG sense, like `MiniCalendar`'s days: one tab stop (the roving\n * tabindex), the arrows walk the months — left/right by one, up/down by a row of three —\n * and walking off either end of the year MOVES the year rather than stopping; Home/End\n * the row, PageUp/PageDown a year. Out-of-bounds months are `aria-disabled`, not\n * `disabled`, so the roving tab stop never falls into a hole. The focus lands on the tab\n * stop when the grid mounts: both owners mount it only when asked to pick a month.\n */\nexport function MonthGrid({\n  active,\n  onActiveChange,\n  onPick,\n  from,\n  to,\n  minKey,\n  maxKey,\n  currentKey,\n  locale,\n  cellName,\n  labelledBy,\n  onEscape,\n}: MonthGridProps) {\n  const gridRef = useRef<HTMLDivElement>(null);\n  const year = Number(active.slice(0, 4));\n  const outOfBounds = (key: string) => Boolean((minKey && key < minKey) || (maxKey && key > maxKey));\n\n  // Short names for the cells — upper-cased the one way (DUP-11); MonthPicker's CSS\n  // `capitalize` and JumpCalendar's `upperFirst` agreed only because \"Aug\" is one word —\n  // and \"Month YYYY\" for their accessible names.\n  const shortNames = useMemo(() => {\n    const fmt = new Intl.DateTimeFormat(locale, { month: \"short\" });\n    return Array.from({ length: 12 }, (_, i) => upperFirst(fmt.format(new Date(2000, i, 1)), locale));\n  }, [locale]);\n  const longName = useMemo(() => new Intl.DateTimeFormat(locale, { month: \"long\", year: \"numeric\" }), [locale]);\n\n  // Mounted to pick a month: land on it. In MonthPicker this runs before the popover's\n  // focus trap (a child's effect fires first), which then keeps this focus.\n  useEffect(() => {\n    gridRef.current?.querySelector<HTMLElement>('[tabindex=\"0\"]')?.focus();\n  }, []);\n\n  // A month whose cell must take focus after the next commit. Arrowing across a year's\n  // edge relabels the same twelve buttons, so the one to focus is a DIFFERENT button from\n  // the one the key landed on.\n  const pendingFocus = useRef<string | null>(null);\n  useEffect(() => {\n    const key = pendingFocus.current;\n    if (!key) return;\n    pendingFocus.current = null;\n    gridRef.current?.querySelector<HTMLElement>(`[data-month=\"${key}\"]`)?.focus();\n  });\n\n  const onCellKeyDown = (e: KeyboardEvent<HTMLButtonElement>) => {\n    if (e.key === \"Escape\") {\n      onEscape?.(e);\n      return;\n    }\n    // Left and right are VISUAL directions: in a right-to-left panel the grid runs the\n    // other way. The panel is portalled, but its owner puts the field's `dir` on it, so\n    // the nearest `dir` is right.\n    const step = horizontalStep(e.key, e.currentTarget);\n    const col = (monthIndex(active) % 12) % MONTH_COLUMNS;\n    let delta: number;\n    switch (step ? \"horizontal\" : e.key) {\n      case \"horizontal\":\n        delta = step;\n        break;\n      case \"ArrowUp\":\n        delta = -MONTH_COLUMNS;\n        break;\n      case \"ArrowDown\":\n        delta = MONTH_COLUMNS;\n        break;\n      case \"Home\":\n        delta = -col;\n        break;\n      case \"End\":\n        delta = MONTH_COLUMNS - 1 - col;\n        break;\n      case \"PageUp\":\n        delta = -12;\n        break;\n      case \"PageDown\":\n        delta = 12;\n        break;\n      default:\n        return;\n    }\n    // Before the no-op check: these keys also scroll the panel, and a month that cannot\n    // move still must not move the page.\n    e.preventDefault();\n    if (delta === 0) return;\n    const next = shiftKey(active, delta);\n    pendingFocus.current = next;\n    onActiveChange(next);\n  };\n\n  const low = from ?? to;\n  const high = to ?? from;\n\n  return (\n    <div ref={gridRef} role=\"grid\" aria-labelledby={labelledBy} className=\"grid gap-1\">\n      {Array.from({ length: 12 / MONTH_COLUMNS }, (_, row) => (\n        <div key={row} role=\"row\" className=\"grid grid-cols-3 gap-1\">\n          {Array.from({ length: MONTH_COLUMNS }, (_, c) => {\n            const index = row * MONTH_COLUMNS + c;\n            const key = keyOfIndex(year * 12 + index);\n            const disabled = outOfBounds(key);\n            const selected = low !== null && high !== null && key >= low && key <= high;\n            const end = key === from || key === to;\n            const current = key === currentKey;\n            return (\n              <button\n                key={c}\n                type=\"button\"\n                role=\"gridcell\"\n                data-month={key}\n                tabIndex={key === active ? 0 : -1}\n                aria-label={cellName(longName.format(firstOfKey(key)))}\n                aria-selected={selected}\n                aria-disabled={disabled || undefined}\n                aria-current={current ? \"date\" : undefined}\n                onClick={() => {\n                  // The guard `disabled` would have been; see the component note.\n                  if (!disabled) onPick(key);\n                }}\n                onKeyDown={onCellKeyDown}\n                className={cn(\n                  // 44px rows: the touch-target size, and four of them stand as tall as a\n                  // month of days, so JumpCalendar's panel does not jump as its views swap.\n                  \"h-11 rounded px-1 text-sm tabular-nums transition-colors\",\n                  FOCUS_RING_WIDTH,\n                  \"focus-visible:outline-none focus-visible:ring-inset\",\n                  // A --brand ring on a --brand fill exists only in the DOM.\n                  end && !disabled ? \"focus-visible:ring-brand-contrast\" : \"focus-visible:ring-brand\",\n                  disabled\n                    ? \"cursor-not-allowed text-placeholder\"\n                    : end\n                      ? \"bg-brand text-brand-contrast hover:bg-brand-hover\"\n                      : selected\n                        ? \"bg-brand-soft font-medium text-brand-muted hover:bg-brand-soft-hover\"\n                        : \"text-primary hover:bg-hover\",\n                  current && !selected && !disabled && \"ring-1 ring-inset ring-strong\",\n                )}\n              >\n                {shortNames[index]}\n              </button>\n            );\n          })}\n        </div>\n      ))}\n    </div>\n  );\n}\n"],"mappings":"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","names":["_"]}

package/dist/components/month-picker.d.ts

@@ -1,7 +1,8 @@
 import type { ComponentPropsWithoutRef, ReactNode, Ref } from "react";
 import { type LabelOverride } from "../i18n/kit-labels.js";
-import { type FieldHelpProps } from "./field-parts.js";
+import { type DisabledReasonDisplay, type FieldHelpProps } from "./field-parts.js";
 import { DEFAULT_MONTH_PICKER_LABELS } from "./month-picker-labels.js";
+import type { CommitScope } from "./write-lock.js";
 /**
  * Every string the month picker can speak. The month and year names are NOT here —
  * they come from `Intl` in the `locale` prop, so they are already in the user's
@@ -59,8 +60,9 @@ export interface MonthPickerProps extends Omit<ComponentPropsWithoutRef<"div">,
     /**
      * Inclusive bounds, as `"YYYY-MM"`. A full ISO date (`"YYYY-MM-DD"`) is accepted and
      * read as its month, so a host holding "the first day we have data for" can pass it
-     * straight in. Months outside are shown but refuse selection; a year arrow is
-     * disabled once the whole year beyond it is out of bounds.
+     * straight in. Months outside are shown but refuse selection; a year arrow refuses
+     * once the whole year beyond it is out of bounds (`aria-disabled`, so the focus stays
+     * on the arrow just pressed — 0.52).
      */
     min?: string;
     max?: string;
@@ -69,6 +71,26 @@ export interface MonthPickerProps extends Omit<ComponentPropsWithoutRef<"div">,
     /** Trigger text when `value` is `""`. */
     placeholder?: string;
     disabled?: boolean;
+    /**
+     * Why the month cannot be changed — {@link Select}'s `disabledReason`, for a picker
+     * that SAVES on change (a budget page's month, a calendar view kept per user). The
+     * trigger stays focusable and `aria-disabled`, the grid does not open, the stepper's
+     * Today and ‹ › refuse, and `onChange` never fires; the reason is a line under the
+     * field (or the stepper) at Large and on a touch screen, else in the kit
+     * {@link Tooltip} (`disabledReasonDisplay`), and on the trigger's `aria-describedby`.
+     * Wins over `disabled`. 0.52 (refactor audit 2026-10-30, API-3).
+     */
+    disabledReason?: ReactNode;
+    /** Where the reason shows — {@link Button}'s `disabledReasonDisplay`: a line under the
+     *  field at Large and on a touch screen by default, the tooltip otherwise. */
+    disabledReasonDisplay?: DisabledReasonDisplay;
+    /**
+     * This picker COMMITS — picking saves. Under a locked {@link WriteLockProvider} it is
+     * locked the `disabledReason` way, with the lock's reason; a {@link CommitScope}, as on
+     * every kit control. A month field inside a form with its own Save stays editable
+     * under the lock — leave this off there, and put `commit` on the Save. 0.52 (API-3).
+     */
+    commit?: CommitScope;
     /** Required and unanswered — {@link FIELD_INVALID}. See {@link Input}'s `invalid`. */
     invalid?: boolean;
     /**
@@ -147,4 +169,14 @@ export interface MonthPickerProps extends Omit<ComponentPropsWithoutRef<"div">,
      */
     ref?: Ref<HTMLButtonElement>;
 }
-export declare function MonthPicker(props: MonthPickerProps): import("react").JSX.Element;
+/**
+ * Month picker: a field showing the selected month ("August 2026"), opening a 12-month
+ * grid with year arrows. For a value that IS a month — a budget period, a calendar
+ * view, a statement — where a day picker would ask for a day nobody means.
+ *
+ * One component for the two app-local pickers it replaces: keksdose's budget-header
+ * popover (grid + year steppers + a floor) and kastlan's calendar header (a month list
+ * and a year list in two popovers). The grid does both jobs — the year arrows and
+ * PageUp/PageDown cover what the year list did, without a fixed ±5-year window.
+ */
+export declare function MonthPicker(props: MonthPickerProps): string | number | bigint | boolean | Iterable<ReactNode> | Promise<string | number | bigint | boolean | import("react").ReactPortal | import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>> | Iterable<ReactNode> | null | undefined> | import("react").JSX.Element | null | undefined;