@12-apps/ui 6.93.2 → 6.95.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@12-apps/ui",
-  "version": "6.93.2",
+  "version": "6.95.0",
   "license": "MIT",
   "packageManager": "pnpm@10.34.5",
   "type": "module",
@@ -348,6 +348,10 @@
       "types": "./dist/types/components/feedback/TutorialOverlay/index.d.ts",
       "default": "./dist/feedback/TutorialOverlay.js"
     },
+    "./feedback/UsableModal": {
+      "types": "./dist/types/components/feedback/UsableModal/index.d.ts",
+      "default": "./dist/feedback/UsableModal.js"
+    },
     "./form/AddressAutocomplete": {
       "types": "./dist/types/components/form/AddressAutocomplete/index.d.ts",
       "default": "./dist/form/AddressAutocomplete.js"

package/src/components/data-display/Sheet/Sheet.body.tsx

@@ -24,6 +24,8 @@ export interface SheetBodyProps extends Pick<
   | 'onBlur'
 > {
   testId: string;
+  /** The title's element id, which a dialog sheet's `aria-labelledby` names. */
+  titleId?: string;
   isDragging: boolean;
   isVerticalSheet: boolean;
   isDraggableVariant: boolean;
@@ -79,6 +81,7 @@ export const SheetBody: React.FC<SheetBodyProps> = (props) => {
     onFocus,
     onBlur,
     testId,
+    titleId,
     isDragging,
     isVerticalSheet,
     isDraggableVariant,
@@ -115,6 +118,7 @@ export const SheetBody: React.FC<SheetBodyProps> = (props) => {
           showHandle={showHandle && isVerticalSheet}
           isDraggable={isDraggableVariant && isVerticalSheet}
           onDragStart={onDragStart}
+          titleId={titleId}
           dataTestId={`${testId}-header`}
         >
           {header}

package/src/components/data-display/Sheet/Sheet.md

@@ -43,6 +43,11 @@ A vertical sheet's **width** is one rule rather than one per preset: `min(100%,
 - **elevation** (number): Shadow depth level (0-24)
 - **animated** (boolean, default true): `false` opens and closes the panel at once, with no slide, and shows and hides its veil with no fade (`SheetOverlay` takes the same prop)
 
+### Stacking and announcing
+
+- **zIndex** (number): The drawer's stacking level, its veil one below. A sheet opened over a `StackedModal` stack (1300 and up) passes one above it; the drawer's default (1200) would slide in under the panels.
+- **asDialog** (boolean): Announce the panel as a modal dialog named by its `title` — `role="dialog"`, `aria-modal` and `aria-labelledby`. Off by default: a sheet used as a side panel or a menu is not a dialog.
+
 ### Interactive Behavior
 
 - **swipeable** (boolean): Enable swipe gestures for touch devices (default: true)

package/src/components/data-display/Sheet/Sheet.parts.tsx

@@ -103,6 +103,7 @@ export const SheetHeader: React.FC<SheetHeaderProps> = (props) => {
     className,
     style,
     children,
+    titleId,
     dataTestId,
   } = withDefaults(props, HEADER_DEFAULTS);
 
@@ -125,7 +126,7 @@ export const SheetHeader: React.FC<SheetHeaderProps> = (props) => {
       <Box sx={{ display: 'flex', alignItems: 'flex-start', justifyContent: 'space-between' }}>
         <Box sx={{ flex: 1 }}>
           {title && (
-            <Typography variant="h6" sx={{ fontWeight: 600 }} data-testid={`${dataTestId}-title`}>
+            <Typography id={titleId} variant="h6" sx={{ fontWeight: 600 }} data-testid={`${dataTestId}-title`}>
               {title}
             </Typography>
           )}

package/src/components/data-display/Sheet/Sheet.tsx

@@ -2,7 +2,7 @@ import Drawer from '@mui/material/Drawer/index.js';
 import SwipeableDrawer from '@mui/material/SwipeableDrawer/index.js';
 import { useTheme } from '@mui/material/styles/index.js';
 import type { BackdropProps } from '@mui/material/Backdrop/index.js';
-import React from 'react';
+import React, { useId } from 'react';
 
 import { withDefaults } from '../../../utils/withDefaults';
 
@@ -102,9 +102,31 @@ const orientationOf = ({ position, variant }: ResolvedSheetProps) => {
   };
 };
 
+/** The paper's dialog attributes: named only when it is a dialog AND has a title to be named by. */
+const dialogAriaOf = ({ asDialog, title }: ResolvedSheetProps, titleId: string) =>
+  asDialog ? { role: 'dialog', 'aria-modal': true, ...(title ? { 'aria-labelledby': titleId } : {}) } : {};
+
+/** The drawer at a caller's stacking level, or MUI's own. */
+const stackedAt = (zIndex: number | undefined) => (zIndex === undefined ? {} : { sx: { zIndex } });
+
+/**
+ * The drawer's modal: kept mounted, its own Escape off (the hook's listener
+ * honours `closeOnEscape`), and an invisible backdrop that catches the tap.
+ */
+const modalPropsOf = (testId: string | undefined) => ({
+  keepMounted: true,
+  disableEscapeKeyDown: true,
+  BackdropComponent: ClickCatcher,
+  BackdropProps: { 'data-testid': testId ? `${testId}-click-catcher` : undefined } as Partial<BackdropProps>,
+});
+
+/** The veil one below the drawer it dims. */
+const veilStyleOf = (zIndex: number | undefined) => (zIndex === undefined ? undefined : { zIndex: zIndex - 1 });
+
 export const Sheet: React.FC<SheetProps> = (props) => {
   const resolved = withDefaults(props, DEFAULTS) as ResolvedSheetProps;
-  const { position, variant, showOverlay, swipeable, className, dataTestId } = resolved;
+  const { position, variant, showOverlay, swipeable, className, dataTestId, zIndex, asDialog } = resolved;
+  const titleId = useId();
 
   const theme = useTheme();
   const orientation = orientationOf(resolved);
@@ -125,6 +147,7 @@ export const Sheet: React.FC<SheetProps> = (props) => {
     anchor: position,
     open: isOpen,
     className,
+    ...stackedAt(zIndex),
     ...(resolved.animated === false ? { transitionDuration: 0 } : {}),
     // A tap outside obeys `closeOnOverlayClick`. A swipe-to-dismiss (no
     // reason: SwipeableDrawer calls `onClose()` bare) closes. Escape is the
@@ -134,14 +157,10 @@ export const Sheet: React.FC<SheetProps> = (props) => {
       reason === 'backdropClick' ? handleOverlayClick() : handleClose(),
     PaperProps: {
       ref: sheetRef,
+      ...dialogAriaOf(resolved, titleId),
       sx: panelSx({ ...resolved, ...orientation, theme, currentHeight, isDragging, isAnimating }),
     },
-    ModalProps: {
-      keepMounted: true,
-      disableEscapeKeyDown: true,
-      BackdropComponent: ClickCatcher,
-      BackdropProps: { 'data-testid': testId ? `${testId}-click-catcher` : undefined } as Partial<BackdropProps>,
-    },
+    ModalProps: modalPropsOf(testId),
   };
 
   const body = (
@@ -149,6 +168,7 @@ export const Sheet: React.FC<SheetProps> = (props) => {
       {...resolved}
       {...orientation}
       testId={testId}
+      titleId={asDialog ? titleId : undefined}
       isDragging={isDragging}
       onClose={handleClose}
       onDragStart={handleDragStart}
@@ -162,7 +182,7 @@ export const Sheet: React.FC<SheetProps> = (props) => {
   return (
     <>
       {showOverlay && isOpen && (
-        <SheetOverlay open={isOpen} onClick={handleOverlayClick} blur={variant === 'glass'} animated={resolved.animated} />
+        <SheetOverlay open onClick={handleOverlayClick} blur={variant === 'glass'} animated={resolved.animated} style={veilStyleOf(zIndex)} />
       )}
 
       {isSwipeable ? (

package/src/components/data-display/Sheet/Sheet.types.ts

@@ -62,6 +62,18 @@ export interface SheetProps {
   elevation?: number;
   /** Slide in and out (default). `false` opens and closes at once. */
   animated?: boolean;
+  /**
+   * The drawer's stacking level, its veil one below. For a sheet opened over a
+   * `StackedModal` stack (1300 and up), which the drawer's default (1200) would
+   * slide under.
+   */
+  zIndex?: number;
+  /**
+   * Announce the panel as a modal dialog named by its `title`: `role="dialog"`,
+   * `aria-modal` and `aria-labelledby`. Off by default — a sheet used as a side
+   * panel or a menu is not a dialog.
+   */
+  asDialog?: boolean;
   dataTestId?: string;
 }
 
@@ -81,6 +93,8 @@ export interface SheetHeaderProps {
   className?: string;
   style?: CSSProperties;
   children?: ReactNode;
+  /** The title's element id, for a sheet that names itself as a dialog (`asDialog`). */
+  titleId?: string;
   dataTestId?: string;
 }
 

package/src/components/feedback/StackedModal/StackedModal.hooks.ts

@@ -91,6 +91,22 @@ const useStackRegistration = (open: boolean, modalId: string): void => {
     const timer = window.setTimeout(() => popModal(modalId), ROLE_TRANSITION_MS);
     return () => window.clearTimeout(timer);
   }, [open, modalId, popModal, isModalInStack]);
+
+  // A panel unmounted while open, or before its slide-out timer fired, still
+  // leaves the stack: otherwise its entry stays `primary` and the panel below
+  // is stuck as `secondary` (no Esc, no backdrop, a back arrow to nowhere).
+  // `popModal(id)` filters by id, so popping one already gone is a no-op, and
+  // it is a stable callback, so this runs on unmount (or an id change) only.
+  // The registration flag goes with the entry: StrictMode runs this cleanup and
+  // then the effects again on the SAME instance, and a flag left `true` would
+  // skip the re-push and leave an open panel out of its stack.
+  useEffect(
+    () => () => {
+      popModal(modalId);
+      hasRegisteredRef.current = false;
+    },
+    [modalId, popModal],
+  );
 };
 
 interface PanelChromeOptions {

package/src/components/feedback/StackedModal/modal-stack.tsx

@@ -17,7 +17,8 @@ const noop = (): void => {
   /** do nothing */
 };
 
-const ModalStackContext = createContext<ModalStackContextValue>({
+/** What a `StackedModal` reads with no provider above it: an empty stack nothing can push onto. */
+const NO_STACK: ModalStackContextValue = {
   stack: [],
   pushModal: noop,
   popModal: noop,
@@ -25,7 +26,16 @@ const ModalStackContext = createContext<ModalStackContextValue>({
   currentDepth: 0,
   isModalInStack: () => false,
   getModalRole: () => null,
-});
+};
+
+const ModalStackContext = createContext<ModalStackContextValue>(NO_STACK);
+
+/**
+ * Whether a `ModalStackProvider` is above this point. A component that opens a
+ * `StackedModal` on its own (`UsableModal`) brings a provider only when the
+ * host has none, so its panel still joins a stack the host already keeps.
+ */
+export const useInModalStack = (): boolean => useContext(ModalStackContext) !== NO_STACK;
 
 export const useModalStack = (): ModalStackContextValue => {
   const context = useContext(ModalStackContext);

package/src/components/feedback/UsableModal/UsableModal.md

@@ -0,0 +1,95 @@
+# UsableModal
+
+A modal that is a **`StackedModal` on a computer** and a **bottom `Sheet` on a
+phone**, behind one API. A screen that opens "the same task" on both — a form, a
+wizard, a pedido being written — uses this instead of switching between the two
+by hand.
+
+```tsx
+import { UsableModal } from '@12-apps/ui/feedback/UsableModal';
+
+<UsableModal
+  open={open}
+  onClose={close}
+  title="Novo pedido"
+  closeLabel="Fechar"
+  backLabel="Voltar"
+  footer={<Actions />}
+  dataTestId="new-order"
+>
+  <Form />
+</UsableModal>
+```
+
+## The surface
+
+| viewport | surface | from |
+|---|---|---|
+| below the theme's `sm` | bottom `Sheet`, as tall as its body up to the screen less a 3rem strip (a ceiling, not a height) | `UsableModal.sheet.tsx` |
+| `sm` and up | `StackedModal` (`size`, `panelWidth` pass through) | `UsableModal.modal.tsx` |
+
+`layout="modal"` or `layout="sheet"` fixes one surface for a host that already
+knows (a test, a kiosk). With the default `auto` the surface is chosen when the
+modal **opens** and kept until it closes: a phone turned to landscape or a
+window narrowed past `sm` mid-task does not swap the surface and lose what was
+typed. The next opening asks the viewport again.
+
+## Loaded on demand
+
+Each surface is its own lazily imported chunk (the package builds with
+`splitting: true`). A closed modal renders nothing and loads nothing; the first
+open loads the one surface the viewport asks for. A phone never downloads
+`StackedModal`, a computer never downloads `Sheet`. While the chunk loads the
+screen shows nothing — no spinner before the content.
+
+Closing hands the surface `open={false}`, so it runs its own way out (the
+slide-out, the stacked modal leaving its stack), and `SURFACE_EXIT_MS` (400 ms)
+later it unmounts. Every opening starts a fresh body on both surfaces, and a
+closed sheet leaves nothing on the page, not even the drawer's swipe strip
+along the bottom edge.
+
+**A chunk a deploy replaced** (a tab opened before it asks for a file that is
+gone) is retried once, then the page reloads once onto the current build; if
+that already happened in this tab in the last five minutes the modal renders
+nothing rather than throwing to the host's error boundary (`recover-chunk.ts`).
+A later deploy earns its own reload.
+
+## Props
+
+- **open**, **onClose** — `onClose` fires for every way out: the ✕, Esc, the
+  backdrop, a swipe down on the sheet.
+- **title** — names the dialog (the stacked modal's bar, the sheet's header).
+- **children** — the body. It scrolls.
+- **footer** — the pinned action bar at the bottom of either surface. On the
+  stacked modal it is NOT `StackedModal`'s `actions`, which sit in the header
+  from `sm` up: a screen's acts belong under what they act on.
+- **closeLabel** — the ✕'s accessible name, `common.close` by default.
+- **backLabel** — the back arrow's (required, as on `StackedModal`; it shows when
+  the stacked modal opens over another panel).
+- **layout**, **size**, **panelWidth**, **dataTestId**.
+
+## The stack
+
+On a computer the panel joins a `ModalStackProvider` the host already keeps
+(it is pushed over the host's panel and offers the way back) and leaves it when
+it closes. A host with no provider gets a stack of one, so the component works
+on its own.
+
+On a phone the sheet takes the level a panel pushed onto the stack would take:
+**above** any open `StackedModal` (a drawer's own level, 1200, is under the
+stack's 1300 and up), and with no stack 1300, MUI's modal level, so the menus a
+Select or a Popover in its body opens still land on top. It is a named modal dialog
+(`role="dialog"`, `aria-modal`, `aria-labelledby` its title), like the stacked
+surface.
+
+## Test ids
+
+`dataTestId` marks the surface; `<id>-footer` marks the action bar on both.
+The rest are each surface's own, so a host test that must not branch asks by
+role instead (`getByRole('dialog', { name: title })`, the ✕ by `closeLabel`):
+
+| | computer (`StackedModal`) | phone (`Sheet`) |
+|---|---|---|
+| title | `<id>-title` | `<id>-header-title` |
+| ✕ | `<id>-close-button` | `<id>-header-close-button` |
+| back | `<id>-back-button` | — |

package/src/components/feedback/UsableModal/UsableModal.modal.tsx

@@ -0,0 +1,76 @@
+import Box from '@mui/material/Box/index.js';
+import type { ReactNode } from 'react';
+
+import { safeAreaBottom } from '../../../utils/viewport';
+import { StackedModal, StackedModalContent } from '../StackedModal/StackedModal';
+import { ModalStackProvider, useInModalStack } from '../StackedModal/modal-stack';
+import { hasFooter } from './has-footer';
+import type { UsableModalSurfaceProps } from './UsableModal.types';
+
+/**
+ * The computer's surface: a `StackedModal`, loaded only when this layout is the
+ * one drawn (`./UsableModal`).
+ *
+ * The footer is pinned at the bottom of the panel's scroll, not handed to
+ * `StackedModal`'s `actions`: those sit in the header from `sm` up, and a
+ * screen's acts belong under what they act on.
+ */
+export function UsableModalStacked(props: UsableModalSurfaceProps): React.JSX.Element {
+  const inStack = useInModalStack();
+  const panel = <StackedPanel {...props} />;
+  // A host that keeps its own stack gets this panel pushed onto it; one that
+  // keeps none gets a stack of one, which is what `StackedModal` needs to draw.
+  return inStack ? panel : <ModalStackProvider>{panel}</ModalStackProvider>;
+}
+
+function StackedPanel({
+  open,
+  onClose,
+  title,
+  children,
+  footer,
+  closeLabel,
+  backLabel,
+  size,
+  panelWidth,
+  dataTestId,
+}: UsableModalSurfaceProps): React.JSX.Element {
+  return (
+    <StackedModal
+      open={open}
+      onClose={onClose}
+      navigationTitle={title}
+      closeLabel={closeLabel}
+      backLabel={backLabel}
+      size={size}
+      panelWidth={panelWidth}
+      dataTestId={dataTestId}
+    >
+      <StackedModalContent sx={{ p: 0, display: 'flex', flexDirection: 'column', minHeight: '100%' }}>
+        <Box sx={{ flex: 1, p: 3 }}>{children}</Box>
+        {hasFooter(footer) && <PinnedFooter dataTestId={dataTestId}>{footer}</PinnedFooter>}
+      </StackedModalContent>
+    </StackedModal>
+  );
+}
+
+/** The action bar, held at the panel's bottom edge while the body scrolls under it. */
+function PinnedFooter({ dataTestId, children }: { dataTestId?: string; children: ReactNode }): React.JSX.Element {
+  return (
+    <Box
+      sx={{
+        position: 'sticky',
+        bottom: 0,
+        px: 3,
+        py: 2,
+        bgcolor: 'background.paper',
+        borderTop: (theme) => `1px solid ${theme.palette.divider}`,
+        // Full screen under `sm` (`layout="modal"` on a phone): clear of the iOS home indicator.
+        ...safeAreaBottom(16),
+      }}
+      data-testid={dataTestId ? `${dataTestId}-footer` : undefined}
+    >
+      {children}
+    </Box>
+  );
+}

package/src/components/feedback/UsableModal/UsableModal.sheet.tsx

@@ -0,0 +1,65 @@
+import Box from '@mui/material/Box/index.js';
+import { useTheme, type Theme } from '@mui/material/styles/index.js';
+
+import { Sheet } from '../../data-display/Sheet/Sheet';
+import { MODAL_STACK_BASE_Z_INDEX, MODAL_STACK_Z_INDEX_STEP } from '../../../tokens/layers';
+import { rem } from '../../../tokens/relative';
+import { safeAreaBottom } from '../../../utils/viewport';
+import { useModalStack } from '../StackedModal/modal-stack';
+import { hasFooter } from './has-footer';
+import type { UsableModalSurfaceProps } from './UsableModal.types';
+
+/**
+ * How tall the sheet may grow: the whole screen but a strip of the dimmed page
+ * above it, so it still reads as a sheet over the screen it came from. The
+ * Sheet's own `xl` ceiling is 600px — a phone of 844 lost a quarter of the
+ * screen to it, and a modal's body (a form, a cardápio) is what needs it.
+ */
+const sheetCeiling = (theme: Theme) => ({ maxHeight: `calc(100% - ${rem(theme, 48)})` });
+
+/**
+ * The phone's surface: a bottom `Sheet`, loaded only when this layout is the one
+ * drawn (`./UsableModal`). Its height is a ceiling, not a height: a short body
+ * gives a short sheet, and a long one grows to `sheetCeiling` and scrolls above
+ * the pinned footer.
+ *
+ * It is a named modal dialog (`asDialog`), like the stacked surface. And it
+ * takes the level a panel pushed onto the stack would take (`BASE + depth *
+ * STEP`): above any `StackedModal` already open — a drawer's default (1200) is
+ * under the stack's 1300 and up, and a sheet opened from a panel would slide in
+ * behind it, invisible, holding the focus — and never above the menus its own
+ * body opens. With no stack that is 1300, MUI's `zIndex.modal`, the level a
+ * Select's or a Popover's menu opens at; portalled later, the menu is on top.
+ */
+export function UsableModalSheet({
+  open,
+  onClose,
+  title,
+  children,
+  footer,
+  closeLabel,
+  dataTestId,
+}: UsableModalSurfaceProps): React.JSX.Element {
+  const { currentDepth } = useModalStack();
+  const theme = useTheme();
+  return (
+    <Sheet
+      open={open}
+      onOpenChange={(next) => {
+        if (!next) onClose();
+      }}
+      position="bottom"
+      size="xl"
+      style={sheetCeiling(theme)}
+      title={title}
+      closeLabel={closeLabel}
+      asDialog
+      zIndex={MODAL_STACK_BASE_Z_INDEX + currentDepth * MODAL_STACK_Z_INDEX_STEP}
+      // The sheet marks its own footer `${dataTestId}-footer`, as the stacked surface does.
+      footer={hasFooter(footer) ? <Box sx={safeAreaBottom(0)}>{footer}</Box> : undefined}
+      dataTestId={dataTestId}
+    >
+      {children}
+    </Sheet>
+  );
+}

package/src/components/feedback/UsableModal/UsableModal.tsx

@@ -0,0 +1,92 @@
+import { useTheme } from '@mui/material/styles/index.js';
+import useMediaQuery from '@mui/material/useMediaQuery/index.js';
+import { lazy, Suspense, useEffect, useState, type ComponentType } from 'react';
+
+import { recoverChunk } from './recover-chunk';
+import type { UsableModalLayout, UsableModalProps, UsableModalSurfaceProps } from './UsableModal.types';
+
+type Surface = 'modal' | 'sheet';
+
+/**
+ * Each surface is its own chunk (the package builds with `splitting: true`), so
+ * a phone never downloads `StackedModal` and a computer never downloads `Sheet`.
+ * A chunk a deploy replaced is retried, then the page reloads once onto the
+ * current build (`./recover-chunk`) — never the host's error boundary.
+ */
+const StackedSurface = lazy(
+  recoverChunk(async (): Promise<{ default: ComponentType<UsableModalSurfaceProps> }> => ({
+    default: (await import('./UsableModal.modal')).UsableModalStacked,
+  })),
+);
+const SheetSurface = lazy(
+  recoverChunk(async (): Promise<{ default: ComponentType<UsableModalSurfaceProps> }> => ({
+    default: (await import('./UsableModal.sheet')).UsableModalSheet,
+  })),
+);
+
+/** The surface the viewport asks for now: a sheet below `sm`, a stacked modal from `sm` up. */
+function useViewportSurface(layout: UsableModalLayout): Surface {
+  const theme = useTheme();
+  // `noSsr`: the first render already knows the width, so a phone never mounts
+  // (and never fetches) the stacked modal for one frame before the sheet.
+  const phone = useMediaQuery(theme.breakpoints.down('sm'), { noSsr: true });
+  if (layout !== 'auto') return layout;
+  return phone ? 'sheet' : 'modal';
+}
+
+/**
+ * How long a closed surface stays mounted: longer than its own way out — the
+ * drawer's slide-down (225 ms) and the stacked modal's leaving its stack
+ * (300 ms) — so neither is cut off.
+ */
+export const SURFACE_EXIT_MS = 400;
+
+/**
+ * The surface is chosen when the modal OPENS and kept until it closes: a phone
+ * turned to landscape, or a window narrowed past `sm`, mid-task, does not swap
+ * the surface and throw away what the person typed. The next opening asks the
+ * viewport again.
+ *
+ * Once closed, and its way out run, the surface is let go of: every opening
+ * starts with a fresh body on both surfaces (the sheet would otherwise keep its
+ * content mounted, and the last half-written form, while the stacked modal
+ * drops its own), and a closed sheet leaves nothing on the page — not even the
+ * drawer's edge strip that swallows taps and swipes the sheet open.
+ */
+function useOpenedSurface(open: boolean, layout: UsableModalLayout): Surface | null {
+  const viewport = useViewportSurface(layout);
+  const [surface, setSurface] = useState<Surface | null>(open ? viewport : null);
+  const [wasOpen, setWasOpen] = useState(open);
+  if (open !== wasOpen) {
+    setWasOpen(open);
+    if (open) setSurface(viewport);
+  }
+  useEffect(() => {
+    if (open || surface === null) return;
+    const timer = window.setTimeout(() => setSurface(null), SURFACE_EXIT_MS);
+    return () => window.clearTimeout(timer);
+  }, [open, surface]);
+  return surface;
+}
+
+/**
+ * A modal that is a `StackedModal` on a computer and a bottom `Sheet` on a
+ * phone, behind one API: title, body, a pinned footer, and the ways out.
+ *
+ * Nothing is fetched until the first open: until then it renders nothing.
+ * Closing hands the surface `open={false}`, so it runs its own way out — the
+ * slide-out, and the stacked modal leaving its stack — and then it unmounts
+ * (`SURFACE_EXIT_MS`). While the
+ * chunk loads the screen shows no placeholder: a modal that blinks a spinner
+ * before its content is worse than one that appears a frame later.
+ */
+export function UsableModal({ layout = 'auto', ...props }: UsableModalProps): React.JSX.Element | null {
+  const surface = useOpenedSurface(props.open, layout);
+  if (surface === null) return null;
+  const Shown = surface === 'sheet' ? SheetSurface : StackedSurface;
+  return (
+    <Suspense fallback={null}>
+      <Shown {...props} />
+    </Suspense>
+  );
+}

package/src/components/feedback/UsableModal/UsableModal.types.ts

@@ -0,0 +1,38 @@
+import type { ReactNode } from 'react';
+
+import type { PanelSize, PanelWidth } from '../StackedModal/StackedModal.types';
+
+/** Which surface draws the modal: chosen by the viewport, or fixed by the host. */
+export type UsableModalLayout = 'auto' | 'modal' | 'sheet';
+
+export interface UsableModalProps {
+  /** Controls the visibility of the modal. */
+  open: boolean;
+  /** Fired by every way out: the ✕, Esc, the backdrop, a swipe down on the sheet. */
+  onClose: () => void;
+  /** Names the dialog: the stacked modal's bar, the sheet's header. */
+  title: string;
+  /** The body. It scrolls; the footer does not. */
+  children?: ReactNode;
+  /** The pinned action bar at the bottom of either surface — the screen's acts. */
+  footer?: ReactNode;
+  /** The ✕'s accessible name — it carries a glyph only. Defaults to `common.close` (`EN_US_UI_LABELS`). */
+  closeLabel?: string;
+  /** The stacked modal's back arrow, shown when it opens over another panel. REQUIRED. */
+  backLabel: string;
+  /**
+   * `auto` (default): a bottom `Sheet` below the theme's `sm` breakpoint, a
+   * `StackedModal` from `sm` up. `modal` and `sheet` fix one surface, for a host
+   * that already knows (a test, a kiosk).
+   */
+  layout?: UsableModalLayout;
+  /** The stacked modal's viewport share (`StackedModal`'s `size`). */
+  size?: PanelSize;
+  /** An exact width for the stacked modal (`StackedModal`'s `panelWidth`). */
+  panelWidth?: PanelWidth;
+  /** Base test id: the surface carries it, and `-footer` marks the action bar. */
+  dataTestId?: string;
+}
+
+/** What each lazily loaded surface receives: the host's props, layout already decided. */
+export type UsableModalSurfaceProps = Omit<UsableModalProps, 'layout'>;

package/src/components/feedback/UsableModal/has-footer.ts

@@ -0,0 +1,4 @@
+import type { ReactNode } from 'react';
+
+/** A footer worth a bar: `null`, `false` and `undefined` draw none, on either surface. */
+export const hasFooter = (footer: ReactNode): boolean => footer !== undefined && footer !== null && footer !== false;

package/src/components/feedback/UsableModal/index.ts

@@ -0,0 +1,2 @@
+export { UsableModal } from './UsableModal';
+export type { UsableModalLayout, UsableModalProps } from './UsableModal.types';