@molecule/app-ui-react 1.0.2 → 1.2.0

package/dist/components/ResponsiveAppShell.d.ts

@@ -0,0 +1,327 @@
+/**
+ * ResponsiveAppShell — the shared responsive app shell: a top bar, a desktop
+ * sidebar (≥768px) and a mobile nav drawer (<768px) around one content region.
+ *
+ * Roughly 89 flagship apps hand-roll this shell in ~15 drifting variants
+ * (inline-style panels, `max-width: 768px` fenceposts, CSS-hidden duplicate
+ * shells, hydration-spinner gates). This family is the fleet standard; it
+ * follows the QA-hardened shape the best templates converged on
+ * (`time-tracking`'s `useIsDesktop`, `blog`'s drawer, `weather-dashboard`'s
+ * one-shell-per-breakpoint doctrine).
+ *
+ * Compose it:
+ *
+ * ```tsx
+ * import { ResponsiveAppShell } from '@molecule/app-ui-react'
+ * import { NavLink, Outlet } from 'react-router'
+ *
+ * const nav = (
+ *   <>
+ *     <NavLink to="/dashboard">Dashboard</NavLink>
+ *     <NavLink to="/projects">Projects</NavLink>
+ *     <NavLink to="/reports">Reports</NavLink>
+ *   </>
+ * )
+ *
+ * export function Shell() {
+ *   return (
+ *     <ResponsiveAppShell>
+ *       <ResponsiveAppShell.TopBar
+ *         brand={<NavLink to="/dashboard">Timetrack</NavLink>}
+ *         actions={<UserMenu />}
+ *       />
+ *       <ResponsiveAppShell.Sidebar>{nav}</ResponsiveAppShell.Sidebar>
+ *       <ResponsiveAppShell.Drawer>{nav}</ResponsiveAppShell.Drawer>
+ *       <ResponsiveAppShell.Content>
+ *         <Outlet />
+ *       </ResponsiveAppShell.Content>
+ *     </ResponsiveAppShell>
+ *   )
+ * }
+ * ```
+ *
+ * @remarks
+ * - **Breakpoint: 768px** — the fleet-wide `md` breakpoint. Exactly ONE shell
+ *   is MOUNTED per breakpoint: `Sidebar` renders only ≥768px, `Drawer` (and
+ *   the menu trigger) only below. This is deliberate — rendering both and
+ *   hiding one with CSS (`hidden md:block` style) leaves duplicate `<main>`/
+ *   `<nav>` landmarks in the accessibility tree, double-mounts route content
+ *   (double fetches, duplicate text matches for e2e locators). CSS-only
+ *   responsive pairs remain available for NON-duplicating surface swaps via
+ *   `hiddenBelow()` / `hiddenFrom()` on the UIClassMap. The `useIsDesktop`
+ *   hook is exported for apps that need the same signal elsewhere: it reads
+ *   `matchMedia` synchronously on first client render (no mounted-then-swap
+ *   flicker in this CSR-only package) and subscribes to `change` events; the
+ *   initializer is guarded (`typeof window`/`matchMedia`) so SSR and
+ *   non-browser harnesses render the mobile shell instead of crashing.
+ * - **a11y contract.** `TopBar` renders the `<header>` landmark and its menu
+ *   trigger carries `aria-label` + `aria-expanded` + `aria-controls` (the
+ *   panel id comes from `useId()`). `Sidebar` renders `<aside>` with a
+ *   `<nav aria-label>` landmark around its children. `Drawer` implements the
+ *   WAI-ARIA APG dialog pattern on mobile: `role="dialog"` + `aria-modal`
+ *   panel, focus moves into the panel on open and returns to the trigger on
+ *   close, Tab/Shift+Tab are trapped inside, Escape and a backdrop click
+ *   close, and body scroll is locked (reference-counted, so a `<Modal>`
+ *   confirm stacked above the drawer never unlocks early). `Content` renders
+ *   the `<main>` landmark. Marking the CURRENT nav item is the CONSUMER's job
+ *   — pass `aria-current="page"` from your nav children (the shell renders
+ *   them pass-through).
+ * - **Behavior.** The drawer auto-closes on SPA navigation (react-router
+ *   location change) so it never sticks over the next page, and when the
+ *   viewport crosses to desktop while it is open. Apps need an
+ *   `I18nProvider` (all visible labels go through `t(key, {}, {
+ *   defaultValue })`) and a react-router context; without the router the
+ *   shell still renders — it just cannot auto-close on navigation.
+ * - **Locators.** Every fixed element carries a `data-mol-id` default,
+ *   overridable per sub-component: `shell-topbar`, `shell-drawer-open`
+ *   (trigger), `shell-sidebar`, `shell-drawer` (panel), `shell-drawer-close`,
+ *   `shell-content`, and `shell-root` on the root `<div>`.
+ * - **ClassMap gaps routed around (Rule 5 inline-style exceptions, each
+ *   commented at the call site).** The UIClassMap `drawer` token is a
+ *   RIGHT-anchored settings-panel shape (`!right-0 … !max-w-sm`) and cannot
+ *   serve a left nav drawer; there is no standalone `overflowY: auto`,
+ *   `z-index`, or `left: 0` token. The shell therefore applies small
+ *   documented inline styles for the drawer/sidebar geometry (pixel width à
+ *   la `@molecule/app-sidebar-layout-react`, `max-width: 85vw`,
+ *   `overflow-y: auto`, stacking `zIndex`) instead of widening UIClassMap —
+ *   a `navDrawer()`-style token belongs in `@molecule/app-ui` + the ClassMap
+ *   bond, both outside this package.
+ * - **Siblings.** `@molecule/app-sidebar-layout-react` `SidebarLayout` is the
+ *   router-coupled DESKTOP-only sidebar (no mobile collapse);
+ *   `@molecule/app-shell-layout-react` `AppShellLayout` is the marketing
+ *   header/footer frame. THIS family is the responsive authenticated shell.
+ *   Do not nest `SidebarLayout` inside it — pick one shell per app.
+ *
+ * @module
+ */
+import { type JSX, type ReactNode } from 'react';
+/**
+ * Whether the viewport is at least 768px wide (the fleet's `md` breakpoint).
+ *
+ * Reads `window.matchMedia` synchronously in the state initializer, so the
+ * FIRST client render is already correct — no mobile-then-desktop swap frame
+ * (this is time-tracking's QA-hardened version; the naive
+ * "state starts false, sync in an effect" variant mounts the wrong shell for
+ * one frame and double-fetches route data on desktop). Subscribes to
+ * `change` events afterwards. Guarded for non-browser environments
+ * (SSR/node): returns `false` (the mobile shell) when no `window.matchMedia`
+ * exists.
+ *
+ * @param query - Override the media query. Defaults to `(min-width: 768px)`.
+ * @returns Whether the desktop shell should mount.
+ */
+export declare function useIsDesktop(query?: string): boolean;
+/**
+ * Semantic sidebar width — the same stack-agnostic presets
+ * `@molecule/app-sidebar-layout-react` uses, so both shells render the same
+ * fleet geometry: `sm` → 208px, `md` → 240px (default), `lg` → 256px. A raw
+ * `number` is an exact pixel width. Applied via inline style (a specific
+ * pixel width is the documented "value a swappable ClassMap cannot express
+ * as a token" case).
+ */
+export type ShellSidebarWidth = 'sm' | 'md' | 'lg' | number;
+/**
+ * Props for the {@link ResponsiveAppShell} root.
+ */
+export interface ResponsiveAppShellProps {
+    /**
+     * The shell sub-components — `<ResponsiveAppShell.TopBar />`,
+     * `<ResponsiveAppShell.Sidebar />`, `<ResponsiveAppShell.Drawer />` and
+     * `<ResponsiveAppShell.Content />`.
+     */
+    children: ReactNode;
+    /**
+     * Sidebar (and drawer) width: `'sm'` (208px), `'md'` (240px, default),
+     * `'lg'` (256px) or an exact pixel number.
+     */
+    sidebarWidth?: ShellSidebarWidth;
+    /** Extra classes on the root flex-row container. */
+    className?: string;
+    /**
+     * `data-mol-id` for the root container. Defaults to `'shell-root'`.
+     */
+    dataMolId?: string;
+}
+/**
+ * Root of the responsive app shell. Owns the breakpoint signal and the
+ * drawer open state, closes the drawer on SPA navigation and on
+ * desktop-crossing resizes, and provides both to the sub-components via
+ * context.
+ *
+ * Render the four sub-components inside it — see the module example for the
+ * canonical composition.
+ *
+ * @param props - The shell sub-components, sidebar width, and className.
+ * @returns The flex-row shell root.
+ */
+declare function ResponsiveAppShellBase({ children, sidebarWidth, className, dataMolId, }: ResponsiveAppShellProps): JSX.Element;
+/**
+ * Props for the {@link ResponsiveAppShellTopBar} sub-component.
+ */
+export interface ResponsiveAppShellTopBarProps {
+    /**
+     * Brand/title node, rendered after the menu trigger — typically a
+     * `<Link to="/…">` with the app name or logo. The shell wraps it in a
+     * flex row; style the node itself.
+     */
+    brand?: ReactNode;
+    /** Trailing actions — user menu, theme toggle, search, etc. */
+    actions?: ReactNode;
+    /**
+     * Render the top bar only below the breakpoint (mount-conditioned, not
+     * CSS-hidden — no dead DOM on desktop). For apps whose desktop shell has
+     * no top bar (e.g. the sidebar carries everything). Default: `false`
+     * (top bar on every breakpoint).
+     */
+    mobileOnly?: boolean;
+    /** Extra classes on the `<header>`. */
+    className?: string;
+    /** `data-mol-id` override. Default: `'shell-topbar'`. */
+    dataMolId?: string;
+    /** `data-testid` override. */
+    testId?: string;
+}
+/**
+ * The shell's `<header>` landmark: menu trigger (mobile, when a Drawer is
+ * composed), brand, and trailing actions.
+ *
+ * Sticks to the top of the viewport by default. The menu trigger renders
+ * only while a `ResponsiveAppShell.Drawer` is part of the composition AND
+ * the viewport is below the breakpoint.
+ *
+ * @param props - Brand/actions slots, `mobileOnly`, and class/id overrides.
+ * @returns The header landmark, or `null` when `mobileOnly` is set on desktop.
+ */
+export declare function ResponsiveAppShellTopBar({ brand, actions, mobileOnly, className, dataMolId, testId, }: ResponsiveAppShellTopBarProps): JSX.Element | null;
+/**
+ * Props for the {@link ResponsiveAppShellSidebar} sub-component.
+ */
+export interface ResponsiveAppShellSidebarProps {
+    /**
+     * Nav content — the links (they land inside the sidebar's `<nav>` landmark;
+     * pass `aria-current="page"` from the active one yourself). Typically the
+     * SAME element variable the Drawer receives, so only the mounted
+     * breakpoint's copy ever instantiates.
+     */
+    children: ReactNode;
+    /**
+     * Accessible name for the sidebar's `<nav>` landmark. Defaults to the
+     * `appShell.primaryNav` translation (English fallback `"Primary
+     * navigation"`).
+     */
+    navLabel?: string;
+    /**
+     * Below-nav content (user card, quick action) — rendered after the `<nav>`
+     * in a bordered footer row, so it does not sit inside the nav landmark.
+     */
+    footer?: ReactNode;
+    /** Extra classes on the `<aside>`. */
+    className?: string;
+    /** `data-mol-id` override. Default: `'shell-sidebar'`. */
+    dataMolId?: string;
+    /** `data-testid` override. */
+    testId?: string;
+}
+/**
+ * The desktop sidebar (`<aside>` + `<nav>` landmarks). Renders NOTHING below
+ * 768px — the {@link ResponsiveAppShellDrawer} carries the nav there.
+ *
+ * Full viewport height, sticky at the top edge, scrolls internally when its
+ * content outgrows the viewport.
+ *
+ * @param props - Nav children, nav label, footer slot, class/id overrides.
+ * @returns The sidebar landmarks, or `null` below the breakpoint.
+ */
+export declare function ResponsiveAppShellSidebar({ children, navLabel, footer, className, dataMolId, testId, }: ResponsiveAppShellSidebarProps): JSX.Element | null;
+/**
+ * Props for the {@link ResponsiveAppShellDrawer} sub-component.
+ */
+export interface ResponsiveAppShellDrawerProps {
+    /**
+     * Nav content — the links, same as (or adapted from) the Sidebar's. Only
+     * mounted while the drawer is open on a below-breakpoint viewport.
+     */
+    children: ReactNode;
+    /**
+     * Header row content (typically the brand), rendered next to the close
+     * button.
+     */
+    header?: ReactNode;
+    /**
+     * Accessible name for the dialog and its `<nav>` landmark. Defaults to the
+     * `appShell.primaryNav` translation (English fallback `"Primary
+     * navigation"`).
+     */
+    navLabel?: string;
+    /** Below-nav content (user card, sign-out), after the `<nav>`. */
+    footer?: ReactNode;
+    /** Whether the panel shows a close (X) button. Default: `true`. */
+    showCloseButton?: boolean;
+    /** Extra classes on the dialog panel. */
+    className?: string;
+    /** `data-mol-id` override for the panel. Default: `'shell-drawer'`. */
+    dataMolId?: string;
+    /** `data-mol-id` override for the close button. Default: `'shell-drawer-close'`. */
+    closeDataMolId?: string;
+    /** `data-testid` override for the panel. */
+    testId?: string;
+}
+/**
+ * The mobile nav drawer (<768px): a left-anchored dialog panel over a
+ * backdrop, opened by the menu trigger the TopBar renders.
+ *
+ * Implements the WAI-ARIA APG dialog pattern — focus moves into the panel on
+ * open and returns to the previously focused element (the trigger) on close,
+ * Tab is trapped inside, Escape and backdrop clicks close, body scroll locks
+ * (reference-counted with any stacked `<Modal>`), and the shell closes it on
+ * SPA navigation. Renders nothing on desktop or while closed.
+ *
+ * @param props - Nav children, header/nav-label/footer slots, close-button
+ * and class/id overrides.
+ * @returns The drawer portal while open on mobile, otherwise `null`.
+ */
+export declare function ResponsiveAppShellDrawer({ children, header, navLabel, footer, showCloseButton, className, dataMolId, closeDataMolId, testId, }: ResponsiveAppShellDrawerProps): JSX.Element | null;
+/**
+ * Props for the {@link ResponsiveAppShellContent} sub-component.
+ */
+export interface ResponsiveAppShellContentProps {
+    /** The routed page content — typically an `<Outlet />`. */
+    children: ReactNode;
+    /** Extra classes on the `<main>`. */
+    className?: string;
+    /** Inline styles on the `<main>` (rarely needed — layout is owned). */
+    style?: React.CSSProperties;
+    /** `data-mol-id` override. Default: `'shell-content'`. */
+    dataMolId?: string;
+    /** `data-testid` override. */
+    testId?: string;
+}
+/**
+ * The shell's `<main>` landmark. Grows to fill the row and may shrink below
+ * its content width, so page-level `overflow-x` strips scroll inside the
+ * page instead of widening the whole shell.
+ *
+ * @param props - The page content and class/id overrides.
+ * @returns The main landmark.
+ */
+export declare function ResponsiveAppShellContent({ children, className, style, dataMolId, testId, }: ResponsiveAppShellContentProps): JSX.Element;
+/**
+ * The responsive app shell family — see the {@link ResponsiveAppShellBase |
+ * root component} and the module docs for the full contract.
+ *
+ * Consumed as `<ResponsiveAppShell.TopBar />`, `.Sidebar`, `.Drawer` and
+ * `.Content` inside `<ResponsiveAppShell>`; each is also exported as a named
+ * component (`ResponsiveAppShellTopBar`, …) for star-import consumers.
+ */
+export declare const ResponsiveAppShell: typeof ResponsiveAppShellBase & {
+    /** The `<header>` landmark — brand + actions + the drawer menu trigger. */
+    TopBar: typeof ResponsiveAppShellTopBar;
+    /** The desktop `<aside>`/`<nav>` landmarks (≥768px only). */
+    Sidebar: typeof ResponsiveAppShellSidebar;
+    /** The mobile dialog drawer (<768px only). */
+    Drawer: typeof ResponsiveAppShellDrawer;
+    /** The `<main>` landmark. */
+    Content: typeof ResponsiveAppShellContent;
+};
+export {};
+//# sourceMappingURL=ResponsiveAppShell.d.ts.map

package/dist/components/ResponsiveAppShell.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ResponsiveAppShell.d.ts","sourceRoot":"","sources":["../../src/components/ResponsiveAppShell.tsx"],"names":[],"mappings":"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"}