@apollion-dsi/core 7.2.0 → 7.4.0

package/lib/elements/Sheet/Sheet.helpers.d.ts

@@ -0,0 +1,36 @@
+import { SheetTriggerProps } from './Sheet.interface';
+/** Marks a static `Sheet` dialog — the scope `getSheetScript` acts on. */
+export declare const SHEET_ATTRIBUTE = "data-apollion-sheet";
+/** Marks an opener; its value is the target dialog id. */
+export declare const SHEET_OPEN_ATTRIBUTE = "data-apollion-sheet-open";
+/** Marks a closer — any element inside a static `Sheet` (button, nav link…). */
+export declare const SHEET_CLOSE_ATTRIBUTE = "data-apollion-sheet-close";
+/**
+ * DOM attributes that turn a `<button>` into the opener of a static `Sheet`.
+ *
+ * Emits the declarative Invoker Commands pair (`commandfor` +
+ * `command="show-modal"` — zero JS where supported) plus the
+ * `data-apollion-sheet-open` hook `getSheetScript` uses as the fallback, and
+ * the ARIA wiring. Spread it on any button-rendering component.
+ *
+ * @example
+ * ```tsx
+ * <IconButton label="Menu" icon={<Icon icon={menuBars} />} {...getSheetTriggerProps('site-menu')} />
+ * <Sheet static id="site-menu" placement="right" aria-label="Menu">…</Sheet>
+ * ```
+ */
+export declare const getSheetTriggerProps: (id: string) => SheetTriggerProps;
+/**
+ * Progressive-enhancement script for static `Sheet`s — inline it once per
+ * page (`<script dangerouslySetInnerHTML={{ __html: getSheetScript() }} />`).
+ *
+ * One delegated `click` listener covering what the platform does not yet do
+ * everywhere: opening from `[data-apollion-sheet-open]` where Invoker
+ * Commands are missing (or the opener is not a `<button>`), closing from any
+ * `[data-apollion-sheet-close]` descendant (e.g. in-page nav links), and
+ * scrim-click dismissal where `closedby="any"` is unsupported. Focus
+ * containment, `Escape` and focus return stay native to `<dialog>`.
+ * Dependency-free, idempotent per call site, and a no-op without
+ * `HTMLDialogElement#showModal`.
+ */
+export declare function getSheetScript(): string;

package/lib/elements/Sheet/Sheet.interface.d.ts

@@ -11,25 +11,18 @@ export type SheetPlacement = 'bottom' | 'left' | 'right';
 /**
  * How much of the viewport the sheet claims along its slide axis.
  *
- * - `auto`: sized by content — height capped at 84vh for `bottom` (Modal
+ * - `auto`: sized by content — height capped at 84svh for `bottom` (Modal
  *   parity), width capped for side drawers.
  * - `half`: half the viewport (height for `bottom`, width for sides).
  * - `full`: the whole axis, square corners (a full-screen takeover).
- */
-export type SheetSize = 'auto' | 'half' | 'full';
-/**
- * Props of the `Sheet` component.
  *
- * Controlled-only surface (`isOpen`/`onDismiss`) — the sliding sibling of
- * `Modal`: portal to `document.body`, scrim overlay, `role="dialog"` +
- * `aria-modal`, focus trap with Escape and focus return, and enter/exit via
- * the motion presets (`sheet` / `drawer-left` / `drawer-right`, ADR-027).
+ * On wide viewports an `adaptive` bottom sheet becomes a centered dialog:
+ * `auto`/`half` take the Modal `base` width (`half` keeps its 50dvh height),
+ * `full` takes the Modal `large` width at the 84svh dialog ceiling.
  */
-export type SheetProps = {
-    /** Controls the open state. The exit animation plays before unmount. */
-    isOpen: boolean;
-    /** Called on overlay click, close button and `Escape`. */
-    onDismiss: () => void;
+export type SheetSize = 'auto' | 'half' | 'full';
+/** Props shared by both `Sheet` modes (controlled and static). */
+export type SheetCommonProps = {
     /**
      * Edge the sheet slides from.
      *
@@ -42,6 +35,16 @@ export type SheetProps = {
      * @default 'auto'
      */
     size?: SheetSize;
+    /**
+     * Presents a `bottom` sheet as a centered dialog from the `md` breakpoint
+     * up — the sheet stays the mobile design, wide viewports get Modal
+     * geometry. Pure CSS: no JS, same markup, works in `static` mode. `false`
+     * keeps the bottom sheet on every viewport. Side drawers (`left`/`right`)
+     * are already the wide-screen pattern and ignore it.
+     *
+     * @default true
+     */
+    adaptive?: boolean;
     /** Title rendered in the header and wired to the dialog via `aria-labelledby`. */
     title?: string;
     /**
@@ -64,3 +67,48 @@ export type SheetProps = {
     /** Sheet content. */
     children?: React.ReactNode;
 };
+/**
+ * Controlled mode (default) — the parent owns `isOpen`/`onDismiss`: portal
+ * to `document.body`, scrim overlay, `role="dialog"` + `aria-modal`, focus
+ * trap with Escape and focus return, and enter/exit via the motion presets
+ * (`sheet` / `drawer-left` / `drawer-right`, ADR-027). Needs React on the
+ * client.
+ */
+export type SheetControlledProps = SheetCommonProps & {
+    static?: false;
+    /** Controls the open state. The exit animation plays before unmount. */
+    isOpen: boolean;
+    /** Called on overlay click, close button and `Escape`. */
+    onDismiss: () => void;
+};
+/**
+ * Static mode — SSR-inert: renders a native `<dialog>` inline (no portal, no
+ * hooks, no hydration), closed by default. The browser owns the modal
+ * behaviour (top layer, inert page, focus containment, `Escape`, focus
+ * return); it opens from any button spreading `getSheetTriggerProps(id)`,
+ * with `getSheetScript()` as the progressive-enhancement fallback.
+ */
+export type SheetStaticProps = SheetCommonProps & {
+    /** Opts into the SSR-inert native `<dialog>` render. */
+    static: true;
+    /** DOM id of the dialog — the handle triggers point at. Must be unique in the page. */
+    id: string;
+    isOpen?: never;
+    onDismiss?: never;
+};
+/**
+ * Props of the `Sheet` component — the sliding sibling of `Modal`.
+ *
+ * Two mutually exclusive modes: controlled (`isOpen`/`onDismiss`, the
+ * default) and `static` (native `<dialog>` for static/SSG output with no
+ * React on the client).
+ */
+export type SheetProps = SheetControlledProps | SheetStaticProps;
+/** DOM attributes returned by `getSheetTriggerProps` — spread them on a `<button>`. */
+export type SheetTriggerProps = {
+    commandfor: string;
+    command: 'show-modal';
+    'aria-controls': string;
+    'aria-haspopup': 'dialog';
+    'data-apollion-sheet-open': string;
+};