feat(design): dialogs open by purpose and keep their commit row pinned (E28 S3f1)
Modal takes a required initialFocus (field / close / action), a field that loads late takes the focus while it still rests on the close button, and ModalFooter portals a dialog's commit row under the scrolling body from any depth. The header and footer fades follow the body's scroll timeline, and the viewport's interactive-widget=resizes-content keeps the footer above an on-screen keyboard.
This commit is contained in:
@@ -194,11 +194,16 @@ function CommandPaletteBody({ onClose, groups }: { onClose: () => void; groups:
|
||||
};
|
||||
|
||||
return (
|
||||
<Modal title={t("palette.title")} onClose={onClose} maxWidth="max-w-xl" placement="top">
|
||||
<Modal
|
||||
initialFocus="field"
|
||||
title={t("palette.title")}
|
||||
onClose={onClose}
|
||||
maxWidth="max-w-xl"
|
||||
placement="top"
|
||||
>
|
||||
<div className={clsx(fieldClass({ size: "lg" }), "flex items-center gap-2")}>
|
||||
<Search className="w-4 h-4 shrink-0 text-muted" />
|
||||
<InnerInput
|
||||
autoFocus
|
||||
value={query}
|
||||
onChange={(e) => {
|
||||
setQuery(e.target.value);
|
||||
|
||||
@@ -49,7 +49,12 @@ export default function KeyboardHelp() {
|
||||
const lines = helpLines(live, pages).filter((l) => !l.when || !!conditions[l.when]);
|
||||
const words = { Space: t("keys.cap.space"), ContextMenu: t("keys.cap.menu") };
|
||||
return (
|
||||
<Modal title={t("keys.title")} onClose={closeKeyboardHelp} maxWidth="max-w-md">
|
||||
<Modal
|
||||
initialFocus="close"
|
||||
title={t("keys.title")}
|
||||
onClose={closeKeyboardHelp}
|
||||
maxWidth="max-w-md"
|
||||
>
|
||||
<dl className="grid grid-cols-[auto_1fr] items-center gap-x-4 gap-y-2.5 text-sm">
|
||||
{lines.map((line) => (
|
||||
<Fragment key={line.labelKey}>
|
||||
|
||||
@@ -66,7 +66,7 @@ describe("Modal focus trap (offsetParent stubbed 'visible')", () => {
|
||||
|
||||
it("moves initial focus to the first control on open", () => {
|
||||
render(
|
||||
<Modal title="t" onClose={() => {}}>
|
||||
<Modal initialFocus="close" title="t" onClose={() => {}}>
|
||||
<Body />
|
||||
</Modal>,
|
||||
);
|
||||
@@ -75,7 +75,7 @@ describe("Modal focus trap (offsetParent stubbed 'visible')", () => {
|
||||
|
||||
it("Tab from the last control wraps to the first", () => {
|
||||
render(
|
||||
<Modal title="t" onClose={() => {}}>
|
||||
<Modal initialFocus="close" title="t" onClose={() => {}}>
|
||||
<Body />
|
||||
</Modal>,
|
||||
);
|
||||
@@ -86,7 +86,7 @@ describe("Modal focus trap (offsetParent stubbed 'visible')", () => {
|
||||
|
||||
it("Shift+Tab from the first control wraps to the last", () => {
|
||||
render(
|
||||
<Modal title="t" onClose={() => {}}>
|
||||
<Modal initialFocus="close" title="t" onClose={() => {}}>
|
||||
<Body />
|
||||
</Modal>,
|
||||
);
|
||||
@@ -99,7 +99,7 @@ describe("Modal focus trap (offsetParent stubbed 'visible')", () => {
|
||||
// takes Escape first, but deferring the Tab trap to it let Shift+Tab walk out behind the scrim.
|
||||
it("keeps trapping while only a hover card is open above it", () => {
|
||||
render(
|
||||
<Modal title="t" onClose={() => {}}>
|
||||
<Modal initialFocus="close" title="t" onClose={() => {}}>
|
||||
<Body />
|
||||
</Modal>,
|
||||
);
|
||||
@@ -117,7 +117,7 @@ describe("Modal focus trap (offsetParent stubbed 'visible')", () => {
|
||||
// The dialog's toast host sits beside the panel; trapped to the panel, a toast's Undo or dismiss
|
||||
// could not be reached from the keyboard at all.
|
||||
render(
|
||||
<Modal title="t" onClose={() => {}}>
|
||||
<Modal initialFocus="close" title="t" onClose={() => {}}>
|
||||
<Body />
|
||||
</Modal>,
|
||||
);
|
||||
@@ -143,7 +143,7 @@ describe("Modal focus trap (offsetParent stubbed 'visible')", () => {
|
||||
const outside = document.createElement("button");
|
||||
document.body.appendChild(outside);
|
||||
render(
|
||||
<Modal title="t" onClose={() => {}}>
|
||||
<Modal initialFocus="close" title="t" onClose={() => {}}>
|
||||
<Body />
|
||||
</Modal>,
|
||||
);
|
||||
@@ -156,7 +156,7 @@ describe("Modal focus trap (offsetParent stubbed 'visible')", () => {
|
||||
|
||||
it("Shift+Tab from the panel container itself goes to the last control (no leak to the background)", () => {
|
||||
render(
|
||||
<Modal title="t" onClose={() => {}}>
|
||||
<Modal initialFocus="close" title="t" onClose={() => {}}>
|
||||
<Body />
|
||||
</Modal>,
|
||||
);
|
||||
@@ -167,7 +167,7 @@ describe("Modal focus trap (offsetParent stubbed 'visible')", () => {
|
||||
|
||||
it("does not trap a Tab in the middle — only the edges wrap", () => {
|
||||
render(
|
||||
<Modal title="t" onClose={() => {}}>
|
||||
<Modal initialFocus="close" title="t" onClose={() => {}}>
|
||||
<Body />
|
||||
</Modal>,
|
||||
);
|
||||
@@ -180,7 +180,7 @@ describe("Modal focus trap (offsetParent stubbed 'visible')", () => {
|
||||
it("Escape calls onClose", () => {
|
||||
const onClose = vi.fn();
|
||||
render(
|
||||
<Modal title="t" onClose={onClose}>
|
||||
<Modal initialFocus="close" title="t" onClose={onClose}>
|
||||
<Body />
|
||||
</Modal>,
|
||||
);
|
||||
@@ -192,12 +192,12 @@ describe("Modal focus trap (offsetParent stubbed 'visible')", () => {
|
||||
const outerClose = vi.fn();
|
||||
const innerClose = vi.fn();
|
||||
render(
|
||||
<Modal title="outer" onClose={outerClose}>
|
||||
<Modal initialFocus="close" title="outer" onClose={outerClose}>
|
||||
<button>outer-body</button>
|
||||
</Modal>,
|
||||
);
|
||||
render(
|
||||
<Modal title="inner" onClose={innerClose}>
|
||||
<Modal initialFocus="close" title="inner" onClose={innerClose}>
|
||||
<button>inner-body</button>
|
||||
</Modal>,
|
||||
);
|
||||
@@ -211,7 +211,7 @@ describe("Modal focus trap (offsetParent stubbed 'visible')", () => {
|
||||
document.body.appendChild(trigger);
|
||||
trigger.focus(); // captured as restoreTo during Modal's first render
|
||||
const { unmount } = render(
|
||||
<Modal title="t" onClose={() => {}}>
|
||||
<Modal initialFocus="close" title="t" onClose={() => {}}>
|
||||
<Body />
|
||||
</Modal>,
|
||||
);
|
||||
@@ -230,7 +230,7 @@ describe("Modal focus trap (offsetParent stubbed 'visible')", () => {
|
||||
document.body.appendChild(trigger);
|
||||
trigger.focus();
|
||||
const { unmount } = render(
|
||||
<Modal title="t" onClose={() => {}}>
|
||||
<Modal initialFocus="close" title="t" onClose={() => {}}>
|
||||
<Body />
|
||||
</Modal>,
|
||||
);
|
||||
@@ -256,10 +256,10 @@ describe("Modal focus trap (offsetParent stubbed 'visible')", () => {
|
||||
function Nested() {
|
||||
const [open, setOpen] = useState(false);
|
||||
return (
|
||||
<Modal title="outer" onClose={() => {}}>
|
||||
<Modal initialFocus="close" title="outer" onClose={() => {}}>
|
||||
<button onClick={() => setOpen(true)}>open inner</button>
|
||||
{open && (
|
||||
<Modal title="inner" onClose={() => {}}>
|
||||
<Modal initialFocus="close" title="inner" onClose={() => {}}>
|
||||
<button>inner-body</button>
|
||||
</Modal>
|
||||
)}
|
||||
@@ -291,11 +291,11 @@ describe("Modal focus trap (offsetParent stubbed 'visible')", () => {
|
||||
return (
|
||||
<>
|
||||
{lower && (
|
||||
<Modal title="lower" onClose={() => {}}>
|
||||
<Modal initialFocus="close" title="lower" onClose={() => {}}>
|
||||
<button onClick={() => setLower(false)}>close lower</button>
|
||||
</Modal>
|
||||
)}
|
||||
<Modal title="upper" onClose={() => {}}>
|
||||
<Modal initialFocus="close" title="upper" onClose={() => {}}>
|
||||
<button>upper-body</button>
|
||||
</Modal>
|
||||
</>
|
||||
@@ -319,7 +319,7 @@ describe("Modal focus trap (offsetParent stubbed 'visible')", () => {
|
||||
document.body.append(trigger, elsewhere);
|
||||
trigger.focus();
|
||||
const { unmount } = render(
|
||||
<Modal title="t" onClose={() => {}}>
|
||||
<Modal initialFocus="close" title="t" onClose={() => {}}>
|
||||
<Body />
|
||||
</Modal>,
|
||||
);
|
||||
@@ -336,7 +336,7 @@ describe("Modal focus trap (raw jsdom — every offsetParent null)", () => {
|
||||
|
||||
it("with no visible focusables: initial focus falls to the panel and Tab is a safe no-op", () => {
|
||||
render(
|
||||
<Modal title="t" onClose={() => {}}>
|
||||
<Modal initialFocus="close" title="t" onClose={() => {}}>
|
||||
<Body />
|
||||
</Modal>,
|
||||
);
|
||||
@@ -357,7 +357,7 @@ describe("Modal — toasts raised while it is open", () => {
|
||||
// The app's Toaster is in a stacking context under this body-level portal: a failed share or
|
||||
// rename was drawn under the scrim, and clicking it landed on the backdrop and closed the dialog.
|
||||
render(
|
||||
<Modal title="Share" onClose={() => {}}>
|
||||
<Modal initialFocus="close" title="Share" onClose={() => {}}>
|
||||
<Body />
|
||||
</Modal>,
|
||||
);
|
||||
@@ -390,7 +390,7 @@ describe("Modal — an Escape a layer above it already took", () => {
|
||||
const onClose = vi.fn();
|
||||
const listClosed = vi.fn();
|
||||
render(
|
||||
<Modal title="Share" onClose={onClose}>
|
||||
<Modal initialFocus="close" title="Share" onClose={onClose}>
|
||||
<List onClosed={listClosed} />
|
||||
</Modal>,
|
||||
);
|
||||
|
||||
@@ -33,7 +33,7 @@ describe("a dialog open while fullscreen is left", () => {
|
||||
document.body.appendChild(stage);
|
||||
setFullscreen(stage);
|
||||
render(
|
||||
<Modal title="Download" onClose={() => {}}>
|
||||
<Modal initialFocus="close" title="Download" onClose={() => {}}>
|
||||
<input aria-label="name" defaultValue="" />
|
||||
</Modal>,
|
||||
);
|
||||
@@ -60,7 +60,7 @@ describe("a dialog with an autoFocus child", () => {
|
||||
// command palette, the download rename dialog and every non-danger confirm shipped with after
|
||||
// deep-review round 4 (found in round 5).
|
||||
render(
|
||||
<Modal title="Search" onClose={() => {}}>
|
||||
<Modal initialFocus="close" title="Search" onClose={() => {}}>
|
||||
<input aria-label="query" autoFocus />
|
||||
</Modal>,
|
||||
);
|
||||
@@ -71,7 +71,7 @@ describe("a dialog with an autoFocus child", () => {
|
||||
const stage = document.createElement("div");
|
||||
document.body.appendChild(stage);
|
||||
render(
|
||||
<Modal title="Search" onClose={() => {}}>
|
||||
<Modal initialFocus="close" title="Search" onClose={() => {}}>
|
||||
<input aria-label="query" autoFocus />
|
||||
</Modal>,
|
||||
);
|
||||
|
||||
@@ -0,0 +1,209 @@
|
||||
// @vitest-environment jsdom
|
||||
//
|
||||
// C4 (DESIGN, Dialogs): a dialog opens focused by its PURPOSE, and its commit row is a footer pinned
|
||||
// outside the scrolling body. offsetParent is stubbed "visible" as in Modal.dom.test.tsx (jsdom never
|
||||
// lays out, and the focus rules skip unrendered controls).
|
||||
import { readFileSync } from "node:fs";
|
||||
import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
|
||||
import { act, cleanup, render, screen } from "@testing-library/react";
|
||||
|
||||
vi.mock("react-i18next", async (importOriginal) => {
|
||||
const actual = await importOriginal<typeof import("react-i18next")>();
|
||||
return { ...actual, useTranslation: () => ({ t: (key: string) => key }) };
|
||||
});
|
||||
vi.mock("../../lib/history", () => ({ useBackToClose: () => {} }));
|
||||
|
||||
import Modal, { ModalFooter } from "./Modal";
|
||||
|
||||
const closeBtn = () => screen.getByRole("button", { name: "common.close" });
|
||||
const press = (key: string, shiftKey = false) =>
|
||||
act(() => {
|
||||
window.dispatchEvent(
|
||||
new KeyboardEvent("keydown", { key, shiftKey, bubbles: true, cancelable: true }),
|
||||
);
|
||||
});
|
||||
|
||||
let origDesc: PropertyDescriptor | undefined;
|
||||
beforeEach(() => {
|
||||
origDesc = Object.getOwnPropertyDescriptor(HTMLElement.prototype, "offsetParent");
|
||||
Object.defineProperty(HTMLElement.prototype, "offsetParent", {
|
||||
configurable: true,
|
||||
get(this: HTMLElement) {
|
||||
return this.isConnected ? document.body : null;
|
||||
},
|
||||
});
|
||||
});
|
||||
afterEach(() => {
|
||||
cleanup();
|
||||
if (origDesc) Object.defineProperty(HTMLElement.prototype, "offsetParent", origDesc);
|
||||
else delete (HTMLElement.prototype as unknown as Record<string, unknown>).offsetParent;
|
||||
});
|
||||
|
||||
// A body that owns its footer, one component down — the issue composer's shape.
|
||||
function Form() {
|
||||
return (
|
||||
<div>
|
||||
<input aria-label="name" />
|
||||
<input aria-label="channel" />
|
||||
<ModalFooter>
|
||||
<button>cancel</button>
|
||||
<button>save</button>
|
||||
</ModalFooter>
|
||||
</div>
|
||||
);
|
||||
}
|
||||
|
||||
describe("Modal initial focus by purpose (C4)", () => {
|
||||
it("field: the body's first control", () => {
|
||||
render(
|
||||
<Modal initialFocus="field" title="t" onClose={() => {}}>
|
||||
<Form />
|
||||
</Modal>,
|
||||
);
|
||||
expect(document.activeElement).toBe(screen.getByLabelText("name"));
|
||||
});
|
||||
|
||||
it("field with nothing to fill in: the ✕", () => {
|
||||
render(
|
||||
<Modal initialFocus="field" title="t" onClose={() => {}}>
|
||||
<p>nothing here</p>
|
||||
</Modal>,
|
||||
);
|
||||
expect(document.activeElement).toBe(closeBtn());
|
||||
});
|
||||
|
||||
// The issue composer's shape: a spinner first, the form when its query lands.
|
||||
function Late({ ready }: { ready: boolean }) {
|
||||
return ready ? <input aria-label="title" /> : <p>loading…</p>;
|
||||
}
|
||||
|
||||
it("field that loads late: the focus moves to it when it arrives", async () => {
|
||||
const { rerender } = render(
|
||||
<Modal initialFocus="field" title="t" onClose={() => {}}>
|
||||
<Late ready={false} />
|
||||
</Modal>,
|
||||
);
|
||||
expect(document.activeElement).toBe(closeBtn());
|
||||
rerender(
|
||||
<Modal initialFocus="field" title="t" onClose={() => {}}>
|
||||
<Late ready />
|
||||
</Modal>,
|
||||
);
|
||||
await act(async () => {});
|
||||
expect(document.activeElement).toBe(screen.getByLabelText("title"));
|
||||
});
|
||||
|
||||
it("field that loads late: a focus the user has moved stays put", async () => {
|
||||
const { rerender } = render(
|
||||
<Modal initialFocus="field" title="t" onClose={() => {}}>
|
||||
<Late ready={false} />
|
||||
<ModalFooter>
|
||||
<button>cancel</button>
|
||||
</ModalFooter>
|
||||
</Modal>,
|
||||
);
|
||||
const cancel = screen.getByRole("button", { name: "cancel" });
|
||||
act(() => cancel.focus());
|
||||
rerender(
|
||||
<Modal initialFocus="field" title="t" onClose={() => {}}>
|
||||
<Late ready />
|
||||
<ModalFooter>
|
||||
<button>cancel</button>
|
||||
</ModalFooter>
|
||||
</Modal>,
|
||||
);
|
||||
await act(async () => {});
|
||||
expect(document.activeElement).toBe(cancel);
|
||||
});
|
||||
|
||||
it("close: the ✕, even with a field in the body", () => {
|
||||
render(
|
||||
<Modal initialFocus="close" title="t" onClose={() => {}}>
|
||||
<Form />
|
||||
</Modal>,
|
||||
);
|
||||
expect(document.activeElement).toBe(closeBtn());
|
||||
});
|
||||
|
||||
it("action: the footer's autoFocus button (a confirm's least destructive)", () => {
|
||||
render(
|
||||
<Modal initialFocus="action" title="t" onClose={() => {}}>
|
||||
<p>Delete it?</p>
|
||||
<ModalFooter>
|
||||
<button autoFocus>cancel</button>
|
||||
<button>delete</button>
|
||||
</ModalFooter>
|
||||
</Modal>,
|
||||
);
|
||||
expect(document.activeElement).toBe(screen.getByRole("button", { name: "cancel" }));
|
||||
});
|
||||
});
|
||||
|
||||
describe("Modal footer (C4)", () => {
|
||||
it("renders outside the scrolling body, inside the dialog, after it", () => {
|
||||
render(
|
||||
<Modal initialFocus="field" title="t" onClose={() => {}}>
|
||||
<Form />
|
||||
</Modal>,
|
||||
);
|
||||
const save = screen.getByRole("button", { name: "save" });
|
||||
const body = screen.getByLabelText("name").closest(".panel-scroller");
|
||||
expect(body).not.toBeNull();
|
||||
expect(body!.contains(save)).toBe(false);
|
||||
expect(screen.getByRole("dialog").contains(save)).toBe(true);
|
||||
expect(body!.compareDocumentPosition(save) & Node.DOCUMENT_POSITION_FOLLOWING).toBeTruthy();
|
||||
});
|
||||
|
||||
// The trap only acts at its ends (a middle Tab is the browser's, which jsdom does not move): the
|
||||
// footer's last button IS the dialog's last stop, both ways.
|
||||
it("the Tab trap counts the footer: its last button wraps to the ✕ and back", () => {
|
||||
render(
|
||||
<Modal initialFocus="field" title="t" onClose={() => {}}>
|
||||
<Form />
|
||||
</Modal>,
|
||||
);
|
||||
const save = screen.getByRole("button", { name: "save" });
|
||||
act(() => save.focus());
|
||||
press("Tab");
|
||||
expect(document.activeElement).toBe(closeBtn());
|
||||
press("Tab", true);
|
||||
expect(document.activeElement).toBe(save);
|
||||
});
|
||||
|
||||
it("no footer: the slot stays empty (and `empty:hidden` takes it out)", () => {
|
||||
render(
|
||||
<Modal initialFocus="close" title="t" onClose={() => {}}>
|
||||
<p>read me</p>
|
||||
</Modal>,
|
||||
);
|
||||
const slot = document.querySelector(".fade-above-panel");
|
||||
expect(slot).not.toBeNull();
|
||||
expect(slot!.childElementCount).toBe(0);
|
||||
expect(slot!.className).toContain("empty:hidden");
|
||||
});
|
||||
});
|
||||
|
||||
// The fades live in CSS, which jsdom cannot evaluate: the pairing is held here instead. Header and
|
||||
// footer sit OUTSIDE the scroller, so they reach its timeline only through the panel's scope.
|
||||
describe("the panel fades follow the body's scroll (C4 + B9)", () => {
|
||||
const read = (file: string) => readFileSync(new URL(file, import.meta.url), "utf8");
|
||||
const css = read("../../index.css");
|
||||
const modal = read("./Modal.tsx");
|
||||
|
||||
it("the Modal wires the scope, the scroller and both fades", () => {
|
||||
expect(modal).toMatch(/const PANEL = "[^"]*\bpanel-scroll-scope\b/);
|
||||
expect(modal).toMatch(/className="[^"]*\bpanel-scroller\b[^"]*"/);
|
||||
expect(modal).toMatch(/className="[^"]*\bfade-below-panel\b[^"]*"/);
|
||||
expect(modal).toMatch(/className="[^"]*\bfade-above-panel\b[^"]*"/);
|
||||
});
|
||||
|
||||
it("index.css names the timeline and drives both fades from it, off at rest", () => {
|
||||
expect(css).toMatch(/@utility panel-scroll-scope \{\s*timeline-scope: --panel-scroll;/);
|
||||
expect(css).toMatch(/@utility panel-scroller \{\s*scroll-timeline: --panel-scroll block;/);
|
||||
for (const util of ["fade-below-panel", "fade-above-panel"]) {
|
||||
const block = css.slice(css.indexOf(`@utility ${util} {`)).split(/\n}\n/)[0];
|
||||
expect(block, util).toMatch(/opacity: 0;/);
|
||||
expect(block, util).toMatch(/animation-timeline: --panel-scroll;/);
|
||||
}
|
||||
});
|
||||
});
|
||||
@@ -43,7 +43,7 @@ describe("Modal focus under StrictMode", () => {
|
||||
it("keeps the focus its autoFocus child asked for across the double mount", () => {
|
||||
render(
|
||||
<StrictMode>
|
||||
<Modal title="t" onClose={() => {}}>
|
||||
<Modal initialFocus="close" title="t" onClose={() => {}}>
|
||||
<input aria-label="field" autoFocus />
|
||||
</Modal>
|
||||
</StrictMode>,
|
||||
|
||||
@@ -1,16 +1,53 @@
|
||||
import { useEffect, useId, useRef, type ReactNode } from "react";
|
||||
import {
|
||||
createContext,
|
||||
useContext,
|
||||
useEffect,
|
||||
useId,
|
||||
useRef,
|
||||
useState,
|
||||
type ReactNode,
|
||||
} from "react";
|
||||
import { createPortal } from "react-dom";
|
||||
import { useTranslation } from "react-i18next";
|
||||
import { X } from "lucide-react";
|
||||
import { useBackToClose } from "../../lib/history";
|
||||
import { anyBlockingLayerAbove, pushLayer, removeLayer, takeEscape } from "../../lib/layerStack";
|
||||
import { useFullscreenPortalHost } from "../../lib/fullscreen";
|
||||
import { trapTab, useDialogChrome } from "./dialogFocus";
|
||||
import { focusablesIn, trapTab, useDialogChrome } from "./dialogFocus";
|
||||
import { IconButton } from "./IconButton";
|
||||
import Toaster from "./Toaster";
|
||||
import { useOverlayOrder } from "./overlayOrder";
|
||||
import { SURFACE } from "./surfaces";
|
||||
|
||||
/** Where a dialog opens focused (C4, by purpose — WAI-ARIA APG): `field` = the body's first control
|
||||
* (a form), `close` = the header's ✕ (anything to read or browse), `action` = the child that takes
|
||||
* `autoFocus` itself (a confirm's least destructive button; the ✕ if none does). Required, so every
|
||||
* dialog states its purpose instead of inheriting "the first focusable", which is always the ✕. */
|
||||
export type ModalFocus = "field" | "close" | "action";
|
||||
|
||||
// The footer slot of the open dialog. `ModalFooter` portals into it from any depth, so a body that
|
||||
// owns its own state (the issue composer) pins its buttons without lifting that state into the caller.
|
||||
const FooterSlot = createContext<HTMLElement | null>(null);
|
||||
|
||||
/** The dialog's commit row (Cancel / Save…). It renders OUTSIDE the scrolling body, pinned under it
|
||||
* (C4): the primary action stays on screen however long the body is, or however much of the screen
|
||||
* the on-screen keyboard takes. A section's own buttons (a sub-form inside a manager) stay in the body. */
|
||||
export function ModalFooter({
|
||||
children,
|
||||
className = "flex flex-wrap items-center justify-end gap-2",
|
||||
}: {
|
||||
children: ReactNode;
|
||||
className?: string;
|
||||
}) {
|
||||
const slot = useContext(FooterSlot);
|
||||
return slot ? createPortal(<div className={className}>{children}</div>, slot) : null;
|
||||
}
|
||||
|
||||
// A column: header, the scrolling body, the footer. `overflow-hidden` clips the body to the rounded
|
||||
// panel; the panel itself never scrolls any more. The scope names the body's scroll timeline for the
|
||||
// header's and the footer's fades, which sit outside that scroller.
|
||||
const PANEL = "relative flex flex-col overflow-hidden outline-none panel-scroll-scope";
|
||||
|
||||
// Small centered modal shell: backdrop + ESC + scroll-lock close. Each open modal is a layer in the
|
||||
// shared `layerStack` so ESC only closes the topmost one — e.g. an error dialog over the tag editor
|
||||
// dismisses just the error and returns to the editor underneath, and a player below defers to it
|
||||
@@ -23,8 +60,10 @@ export default function Modal({
|
||||
children,
|
||||
maxWidth = "max-w-lg",
|
||||
placement = "center",
|
||||
initialFocus,
|
||||
}: {
|
||||
title: ReactNode;
|
||||
initialFocus: ModalFocus;
|
||||
onClose: () => void;
|
||||
children: ReactNode;
|
||||
maxWidth?: string;
|
||||
@@ -49,7 +88,31 @@ export default function Modal({
|
||||
// Focus lands in the panel; OWNERSHIP is the whole dialog — the same element the Tab trap below
|
||||
// is scoped to, toast host included. Tracking ownership over the panel alone meant tabbing to an
|
||||
// in-dialog toast counted as leaving, and the close-time restore was then skipped (round 6).
|
||||
useDialogChrome(panelRef, rootRef);
|
||||
const bodyRef = useRef<HTMLDivElement>(null);
|
||||
const closeRef = useRef<HTMLButtonElement>(null);
|
||||
const [footerSlot, setFooterSlot] = useState<HTMLDivElement | null>(null);
|
||||
useDialogChrome(panelRef, rootRef, {
|
||||
// Only a rendered target (the trap's own `offsetParent` test); none falls back to the hook's
|
||||
// first-focusable rule. `action` lands on the ✕ here and its child's autoFocus then takes over.
|
||||
initial: () =>
|
||||
(initialFocus === "field" && bodyRef.current ? focusablesIn(bodyRef.current)[0] : null) ??
|
||||
(closeRef.current?.offsetParent != null ? closeRef.current : null),
|
||||
});
|
||||
// A form that loads after the dialog opens (the issue composer shows a spinner first) has no field
|
||||
// to take the focus at open, so it lands on the ✕. When the first control arrives the focus moves
|
||||
// there — but only while it still rests on the ✕: a user who has moved it keeps it where it is.
|
||||
useEffect(() => {
|
||||
const body = bodyRef.current;
|
||||
if (initialFocus !== "field" || !body || focusablesIn(body).length > 0) return;
|
||||
const watch = new MutationObserver(() => {
|
||||
const first = focusablesIn(body)[0];
|
||||
if (!first) return;
|
||||
watch.disconnect();
|
||||
if (document.activeElement === closeRef.current) first.focus();
|
||||
});
|
||||
watch.observe(body, { childList: true, subtree: true });
|
||||
return () => watch.disconnect();
|
||||
}, [initialFocus]);
|
||||
const overlayOrder = useOverlayOrder();
|
||||
|
||||
// Backdrop-click close must only fire when the press STARTED on the backdrop too. Otherwise a
|
||||
@@ -115,19 +178,34 @@ export default function Modal({
|
||||
tabIndex={-1}
|
||||
className={
|
||||
drawer
|
||||
? `${SURFACE.drawer} relative w-full ${maxWidth} h-full overflow-y-auto rounded-none sm:rounded-l-2xl outline-none overlay-drawer`
|
||||
: `${SURFACE.panel} relative w-full ${maxWidth} max-h-full overflow-y-auto rounded-2xl outline-none`
|
||||
? `${SURFACE.drawer} ${PANEL} w-full ${maxWidth} h-full rounded-none sm:rounded-l-2xl overlay-drawer`
|
||||
: `${SURFACE.panel} ${PANEL} w-full ${maxWidth} max-h-full rounded-2xl`
|
||||
}
|
||||
>
|
||||
<div className="flex items-start justify-between gap-3 p-5 pb-3">
|
||||
{/* C4: the header and the footer stay put and only the body scrolls, with the B9 fade at
|
||||
each edge — shown only while content is actually under it (the body's scroll timeline,
|
||||
see index.css), so a dialog that fits draws no fade over its first or last line. */}
|
||||
<div className="relative z-base flex shrink-0 items-start justify-between gap-3 p-5 pb-3 fade-below-panel">
|
||||
<h2 id={titleId} className="text-lg font-semibold leading-snug">
|
||||
{title}
|
||||
</h2>
|
||||
<IconButton label={t("common.close")} size="sm" variant="ghost" onClick={onClose}>
|
||||
<IconButton
|
||||
ref={closeRef}
|
||||
label={t("common.close")}
|
||||
size="sm"
|
||||
variant="ghost"
|
||||
onClick={onClose}
|
||||
>
|
||||
<X className="w-4 h-4" />
|
||||
</IconButton>
|
||||
</div>
|
||||
<div className="px-5 pb-5">{children}</div>
|
||||
<div ref={bodyRef} className="min-h-0 flex-auto overflow-y-auto px-5 pb-5 panel-scroller">
|
||||
<FooterSlot value={footerSlot}>{children}</FooterSlot>
|
||||
</div>
|
||||
<div
|
||||
ref={setFooterSlot}
|
||||
className="relative z-base shrink-0 px-5 pb-5 fade-above-panel empty:hidden"
|
||||
/>
|
||||
</div>
|
||||
{/* Toasts raised while a dialog is open show inside it: the app's own host is under this
|
||||
scrim, where a failed share or rename was unreadable and a click on it closed the dialog
|
||||
|
||||
@@ -36,10 +36,10 @@ domain-free.
|
||||
|
||||
## What lives here
|
||||
|
||||
| area | components |
|
||||
| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| overlays & anchoring | `AnchoredPopover` + `anchoredPopoverHooks` (the popover engine: arrows, typeahead, Escape, anchor-flip), `ActionMenu`, `ContextMenu` + `useContextMenu` (the SAME menu, opened by right-click / long-press / Shift+F10 / a row's `MoreButton` "…" via `buttonProps`; `anchor` for a panel a row opens; `PageMenu` for a page's background menu), `Modal`, `Overlay`, `SidePanel`, `Tooltip`, `Toaster` (+ `toastLevels`, `overlayOrder`; `lib/toastDock` docks one control under the stack, in every host), `CommandPalette`, `KeyboardHelp` |
|
||||
| actions & inputs | `Button`, `IconButton`, `Pressable` (`selectable` when its text is a title or a name), `Chip` + `chipStyles`, `DragHandle` + `OrderButtons` / `useOrderItems` (the non-drag reorder, WCAG 2.5.7) (one per button family, docs/DESIGN.md; a raw `<button>` outside this folder is a lint error), `Input` + `fieldStyles`, `NativeControls`, `MenuCheck` (the drawn check of a menu row or a whole-row checkbox button), `SelectTrigger` (the field family; a raw `<input>` is a lint error), `useReturnFocus`, `surfaces` (the |
|
||||
| area | components |
|
||||
| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| overlays & anchoring | `AnchoredPopover` + `anchoredPopoverHooks` (the popover engine: arrows, typeahead, Escape, anchor-flip), `ActionMenu`, `ContextMenu` + `useContextMenu` (the SAME menu, opened by right-click / long-press / Shift+F10 / a row's `MoreButton` "…" via `buttonProps`; `anchor` for a panel a row opens; `PageMenu` for a page's background menu), `Modal` (+ `ModalFooter`; `initialFocus` by purpose, C4), `Overlay`, `SidePanel`, `Tooltip`, `Toaster` (+ `toastLevels`, `overlayOrder`; `lib/toastDock` docks one control under the stack, in every host), `CommandPalette`, `KeyboardHelp` |
|
||||
| actions & inputs | `Button`, `IconButton`, `Pressable` (`selectable` when its text is a title or a name), `Chip` + `chipStyles`, `DragHandle` + `OrderButtons` / `useOrderItems` (the non-drag reorder, WCAG 2.5.7) (one per button family, docs/DESIGN.md; a raw `<button>` outside this folder is a lint error), `Input` + `fieldStyles`, `NativeControls`, `MenuCheck` (the drawn check of a menu row or a whole-row checkbox button), `SelectTrigger` (the field family; a raw `<input>` is a lint error), `useReturnFocus`, `surfaces` (the |
|
||||
|
||||
B5 glass roles; a bare glass class is a lint error), `Badge` (a static label), `LinkButton` / `IconLink` (a
|
||||
link wearing the button face) over `buttonStyles`, `Skeleton` (B8 first loads, through `LoadingState shape`), `NavRail` (B7), `form`, `DraftSaveBar`, `Combobox`, `FilterSelect`, `SegmentedToggle`, `SortControl`, `ColumnSortControl`, `PriorityStepper`, `UndoToolbar` |
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
import { useEffect, useRef, useState, type RefObject } from "react";
|
||||
import { useEffect, useEffectEvent, useRef, useState, type RefObject } from "react";
|
||||
|
||||
// The focus half of the dialog contract, in ONE place. `ui/Modal` owns it for every dialog that goes
|
||||
// through the shell; the onboarding wizard renders its own shell (a bare `ui/Overlay`, because it is
|
||||
@@ -13,7 +13,7 @@ import { useEffect, useRef, useState, type RefObject } from "react";
|
||||
const FOCUSABLE =
|
||||
'a[href], button:not([disabled]), textarea:not([disabled]), input:not([disabled]), select:not([disabled]), [tabindex]:not([tabindex="-1"])';
|
||||
|
||||
const focusablesIn = (root: HTMLElement): HTMLElement[] =>
|
||||
export const focusablesIn = (root: HTMLElement): HTMLElement[] =>
|
||||
[...root.querySelectorAll<HTMLElement>(FOCUSABLE)].filter((el) => el.offsetParent !== null);
|
||||
|
||||
/** Keep Tab / Shift+Tab cycling inside `scope` instead of reaching the inert page behind the
|
||||
@@ -71,11 +71,15 @@ function lockBodyScroll(): () => void {
|
||||
* panel, is that whole dialog — it must be the SAME element `trapTab` is scoped to, or the two
|
||||
* disagree about what counts as "inside" (see `heldRef`). `focusScope` opens the dialog focused on
|
||||
* the scope element itself rather than its first control: the player keeps the focus on its card, so
|
||||
* Space and the arrows reach its shortcuts instead of activating a button. */
|
||||
* Space and the arrows reach its shortcuts instead of activating a button. `initial`, when given,
|
||||
* picks the first-open target instead (`ui/Modal`'s focus-by-purpose rule); null falls back. */
|
||||
export function useDialogChrome(
|
||||
scopeRef: RefObject<HTMLElement | null>,
|
||||
ownerRef?: RefObject<HTMLElement | null>,
|
||||
{ focusScope = false }: { focusScope?: boolean } = {},
|
||||
{
|
||||
focusScope = false,
|
||||
initial,
|
||||
}: { focusScope?: boolean; initial?: () => HTMLElement | null } = {},
|
||||
): void {
|
||||
// Capture the trigger to restore focus to, during THIS render — i.e. before commit runs the
|
||||
// dialog's autoFocus (or our own initial focus) and moves activeElement into the dialog. Reading it
|
||||
@@ -101,6 +105,8 @@ export function useDialogChrome(
|
||||
// <body> instead of handing it back to the trigger. Measured in jsdom, and a regression: before
|
||||
// this hook existed the restore was unconditional (deep-review round 6).
|
||||
const heldRef = useRef(true);
|
||||
// Read at open, not a dependency: a caller's fresh function each render must not re-run the open.
|
||||
const pickInitial = useEffectEvent(() => initial?.() ?? null);
|
||||
useEffect(() => {
|
||||
const unlockScroll = lockBodyScroll();
|
||||
// Initial focus: unless an autoFocus child already placed it inside (e.g. a rename input), move
|
||||
@@ -117,6 +123,7 @@ export function useDialogChrome(
|
||||
const back = focusedRef.current;
|
||||
const target =
|
||||
(back?.isConnected && scope.contains(back) ? back : null) ??
|
||||
pickInitial() ??
|
||||
(focusScope ? scope : (focusablesIn(scope)[0] ?? scope));
|
||||
target.focus();
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user