@astryxdesign/core 0.7.2-canary.c68f5e8 → 0.7.2-canary.ccf1a1c

package/dist/Drawer/Drawer.d.ts

@@ -0,0 +1,191 @@
+/**
+ * @file Drawer.tsx
+ * @input Uses React, StyleX, theme tokens, the shared layer text/structure resets and content boundary, the Dialog purpose type, shared focus/dismissal/depth primitives, container padding lowering, scroll locking/dialog presence, BaseProps, merged refs/props, themeProps
+ * @output Exports Drawer component and DrawerProps
+ * @position Core implementation; consumed by index.ts, tested by Drawer.test.tsx, demonstrated in Storybook
+ *
+ * Overlay panel for inspectors and detail views — the "click a table row,
+ * see its details" pattern. Slides in from the inline start or end edge and
+ * floats above the page content: unlike a docked panel it never reflows the
+ * layout underneath, it overlays it (with or without a scrim).
+ *
+ * Inline axis only (start/end). Block-axis sheets are BottomSheet's job;
+ * a drawer is always a full-height side panel.
+ *
+ * Sizing is viewport-aware: `width` is the desktop budget, and below
+ * the mobile breakpoint it preserves a 56px reveal of the page behind, capped
+ * by the requested width (or fills the viewport with the experimental
+ * `experimental.isFullWidthOnMobile` option).
+ *
+ * Uses the native `<dialog>` element (same precedent as Dialog/MobileNav):
+ * - `showModal()` when `hasScrim` (default) — top-layer rendering, focus
+ *   trapping, `::backdrop`, no z-index management.
+ * - `showPopover()` when `hasScrim={false}` — non-modal top-layer overlay;
+ *   the page behind stays interactive (e.g. master-detail inspectors).
+ *
+ * Entry animation uses `@starting-style`; exit slides out before the active
+ * modal-dialog or manual-popover host releases the top layer and focus returns
+ * to the element that opened the drawer. React owns `display` for both legs
+ * rather than a discrete `display` transition, so the panel stops painting in
+ * the same commit as the host closes — see the `rendered` style for why.
+ *
+ * Sibling drawers use the shared layer dismissal stack for topmost-only Escape
+ * handling and the browser top layer's chronological paint order.
+ *
+ * Dismissal follows Dialog: `purpose` decides whether Escape and a scrim click
+ * request close, and Drawer renders no close button of its own. Compose
+ * `DrawerHeader` with `onOpenChange` for a visible close action, as with
+ * `DialogHeader`.
+ *
+ * The scrolling content area is the drawer's container, like Dialog's inner
+ * box: the `padding` prop, else the theme's `padding` on `drawer`, insets it
+ * through container tokens, defaulting to `--spacing-4` like Dialog, and the
+ * applied inset is published so a lone Section child escapes it and a Layout
+ * redistributes it to its regions. Compose `DrawerHeader` inside a `Layout`, as
+ * `DialogHeader` is composed in Dialog, so the header is not padded twice. The
+ * root dialog stays the overlay boundary (`overlayPaddingReset`).
+ *
+ * SYNC: When modified, update these files to stay in sync:
+ * - /packages/core/src/Drawer/Drawer.doc.mjs (props table, features, usage)
+ * - /packages/core/src/Drawer/Drawer.test.tsx (tests for new/changed behavior)
+ * - /packages/core/src/Drawer/Drawer.spec.md (component contract)
+ * - /packages/core/src/Drawer/index.ts (exports if types change)
+ * - /packages/cli/assets/templates/blocks/components/Drawer/ (showcase blocks)
+ * - /apps/storybook/stories/Drawer.stories.tsx (examples and visual coverage)
+ */
+import { type ReactNode } from 'react';
+import type { BaseProps } from '../BaseProps';
+import type { DialogPurpose } from '../Dialog';
+import type { SpacingStep } from '../Layout';
+export interface DrawerProps extends BaseProps<HTMLDialogElement> {
+    /** Ref forwarded to the root <dialog> element */
+    ref?: React.Ref<HTMLDialogElement>;
+    /**
+     * Whether the drawer is open. Fully controlled — pair with `onOpenChange`.
+     */
+    isOpen: boolean;
+    /**
+     * Called when the drawer requests an open-state change. Escape and a scrim
+     * click call it with `false` as `purpose` allows; a `DrawerHeader` close
+     * button calls it when you pass the same callback to the header. The caller
+     * owns the open state. When sibling drawers are open, Escape only closes the
+     * top (last-opened) drawer.
+     */
+    onOpenChange: (isOpen: boolean) => void;
+    /**
+     * Which edge the drawer slides from.
+     * - `'end'` — inline-end edge (right in LTR) — the inspector convention
+     * - `'start'` — inline-start edge (left in LTR)
+     * @default 'end'
+     */
+    side?: 'start' | 'end';
+    /**
+     * Desktop width budget. A number is pixels; a string is any CSS length
+     * (`'50%'`, `'32rem'`). Below the mobile breakpoint (640px), this
+     * remains the maximum while the drawer preserves a 56px reveal of the page
+     * behind — see `experimental.isFullWidthOnMobile`.
+     * @default 400
+     */
+    width?: number | string;
+    /**
+     * Experimental options, outside the stable compatibility promise: anything
+     * in this object may change or be removed in a patch release. Omit it for
+     * the stable behavior.
+     * @experimental
+     */
+    experimental?: {
+        /**
+         * Cover the full viewport width on mobile (below 640px) instead of
+         * preserving the default 56px reveal of the page behind. The reveal makes
+         * the drawer read as an overlay rather than a navigation.
+         * @experimental
+         * @default false
+         */
+        isFullWidthOnMobile?: boolean;
+    };
+    /**
+     * Accessible label for the drawer (required — the drawer has no
+     * built-in heading to derive a name from).
+     */
+    label: string;
+    /**
+     * Whether to render a modal scrim behind the drawer.
+     * - `true` (default) — `showModal()`: top layer, focus trap, body scroll
+     *   lock, click-outside-to-close.
+     * - `false` — `showPopover()`: non-modal top-layer overlay; the page behind
+     *   stays interactive. Escape still closes through the shared layer stack.
+     * @default true
+     */
+    hasScrim?: boolean;
+    /**
+     * Configures how the drawer enables dismissals, matching Dialog.
+     * - required: Disables Escape and scrim click (for mandatory flows); a
+     *   modal required drawer is exposed as an `alertdialog`
+     * - form: Prevents scrim click, allows the Escape key
+     * - info: Allows Escape and scrim click
+     *
+     * A non-modal drawer has no scrim, so `form` and `info` behave the same.
+     * @default 'info'
+     */
+    purpose?: DialogPurpose;
+    /**
+     * Internal padding of the drawer content using the spacing scale, matching
+     * Dialog. Accepts numeric spacing steps: 0, 0.5, 1, 1.5, 2, 3, 4, 5, 6, 8,
+     * 10. When omitted, uses the theme default for drawers (`--spacing-4`, 16px,
+     * unless the theme sets `padding` on `drawer`), as Dialog does. Pass `0` for
+     * a full-bleed content area. The content area is a container: a Section that
+     * is its only child escapes the padding, bleed children such as Table and
+     * Divider compensate against it, and a Layout picks it up for its regions.
+     */
+    padding?: SpacingStep;
+    /**
+     * Drawer content. Rendered inside a full-height scrollable area.
+     * Focus the element with `data-autofocus` on open, if present.
+     */
+    children: ReactNode;
+    /**
+     * Test ID for the root element.
+     */
+    'data-testid'?: string;
+}
+/**
+ * An overlay panel for inspectors and detail views.
+ *
+ * Slides in from the logical start or end edge and floats above the page
+ * using the native `<dialog>` element: modal with a scrim by default, or a
+ * non-modal overlay with `hasScrim={false}` that leaves the page behind
+ * interactive. `width` is the desktop budget; below 640px the panel preserves
+ * a 56px page reveal without exceeding that budget (or fills the viewport
+ * with the experimental `experimental.isFullWidthOnMobile`). Escape
+ * closes the top-most open drawer; focus returns to the element that
+ * opened it.
+ *
+ * Dismissal matches Dialog: `purpose` decides whether Escape and a scrim click
+ * close the drawer, and `DrawerHeader` renders a close button when given
+ * `onOpenChange`.
+ *
+ * Like Dialog, the drawer is a container: `padding` (or a theme's `padding`
+ * on `drawer`) insets the content area, a lone Section child escapes that
+ * inset, and a Layout inside picks it up for its header, content, and footer
+ * regions. The default inset is `--spacing-4`, matching Dialog.
+ *
+ * @example
+ * ```
+ * const [selected, setSelected] = useState(null);
+ * const handleOpenChange = isOpen => !isOpen && setSelected(null);
+ * <Drawer
+ *   isOpen={selected != null}
+ *   onOpenChange={handleOpenChange}
+ *   label={`Details: ${selected?.name}`}>
+ *   <Layout
+ *     header={<DrawerHeader title={selected?.name} onOpenChange={handleOpenChange} />}
+ *     content={<LayoutContent><HostDetails host={selected} /></LayoutContent>}
+ *   />
+ * </Drawer>
+ * ```
+ */
+export declare function Drawer({ isOpen, onOpenChange, side, width, experimental, label, hasScrim, purpose, padding, children, xstyle, className, style, onClick: onClickProp, onKeyDown: onKeyDownProp, ref, ...props }: DrawerProps): import("react").JSX.Element;
+export declare namespace Drawer {
+    var displayName: string;
+}
+//# sourceMappingURL=Drawer.d.ts.map

package/dist/Drawer/Drawer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Drawer.d.ts","sourceRoot":"","sources":["../../src/Drawer/Drawer.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsDG;AAEH,OAAO,EAAgC,KAAK,SAAS,EAAC,MAAM,OAAO,CAAC;AAEpE,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAQ5C,OAAO,KAAK,EAAC,aAAa,EAAC,MAAM,WAAW,CAAC;AAe7C,OAAO,KAAK,EAAC,WAAW,EAAe,MAAM,WAAW,CAAC;AAgMzD,MAAM,WAAW,WAAY,SAAQ,SAAS,CAAC,iBAAiB,CAAC;IAC/D,iDAAiD;IACjD,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,iBAAiB,CAAC,CAAC;IAEnC;;OAEG;IACH,MAAM,EAAE,OAAO,CAAC;IAEhB;;;;;;OAMG;IACH,YAAY,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,IAAI,CAAC;IAExC;;;;;OAKG;IACH,IAAI,CAAC,EAAE,OAAO,GAAG,KAAK,CAAC;IAEvB;;;;;;OAMG;IACH,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAExB;;;;;OAKG;IACH,YAAY,CAAC,EAAE;QACb;;;;;;WAMG;QACH,mBAAmB,CAAC,EAAE,OAAO,CAAC;KAC/B,CAAC;IAEF;;;OAGG;IACH,KAAK,EAAE,MAAM,CAAC;IAEd;;;;;;;OAOG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IAEnB;;;;;;;;;OASG;IACH,OAAO,CAAC,EAAE,aAAa,CAAC;IAExB;;;;;;;;OAQG;IACH,OAAO,CAAC,EAAE,WAAW,CAAC;IAEtB;;;OAGG;IACH,QAAQ,EAAE,SAAS,CAAC;IAEpB;;OAEG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,wBAAgB,MAAM,CAAC,EACrB,MAAM,EACN,YAAY,EACZ,IAAY,EACZ,KAAW,EACX,YAAY,EACZ,KAAK,EACL,QAAe,EACf,OAAgB,EAChB,OAAO,EACP,QAAQ,EACR,MAAM,EACN,SAAS,EACT,KAAK,EACL,OAAO,EAAE,WAAW,EACpB,SAAS,EAAE,aAAa,EACxB,GAAG,EACH,GAAG,KAAK,EACT,EAAE,WAAW,+BA4Kb;yBA9Le,MAAM"}

package/dist/Drawer/Drawer.js

@@ -0,0 +1,382 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file Drawer.tsx
+ * @input Uses React, StyleX, theme tokens, the shared layer text/structure resets and content boundary, the Dialog purpose type, shared focus/dismissal/depth primitives, container padding lowering, scroll locking/dialog presence, BaseProps, merged refs/props, themeProps
+ * @output Exports Drawer component and DrawerProps
+ * @position Core implementation; consumed by index.ts, tested by Drawer.test.tsx, demonstrated in Storybook
+ *
+ * Overlay panel for inspectors and detail views — the "click a table row,
+ * see its details" pattern. Slides in from the inline start or end edge and
+ * floats above the page content: unlike a docked panel it never reflows the
+ * layout underneath, it overlays it (with or without a scrim).
+ *
+ * Inline axis only (start/end). Block-axis sheets are BottomSheet's job;
+ * a drawer is always a full-height side panel.
+ *
+ * Sizing is viewport-aware: `width` is the desktop budget, and below
+ * the mobile breakpoint it preserves a 56px reveal of the page behind, capped
+ * by the requested width (or fills the viewport with the experimental
+ * `experimental.isFullWidthOnMobile` option).
+ *
+ * Uses the native `<dialog>` element (same precedent as Dialog/MobileNav):
+ * - `showModal()` when `hasScrim` (default) — top-layer rendering, focus
+ *   trapping, `::backdrop`, no z-index management.
+ * - `showPopover()` when `hasScrim={false}` — non-modal top-layer overlay;
+ *   the page behind stays interactive (e.g. master-detail inspectors).
+ *
+ * Entry animation uses `@starting-style`; exit slides out before the active
+ * modal-dialog or manual-popover host releases the top layer and focus returns
+ * to the element that opened the drawer. React owns `display` for both legs
+ * rather than a discrete `display` transition, so the panel stops painting in
+ * the same commit as the host closes — see the `rendered` style for why.
+ *
+ * Sibling drawers use the shared layer dismissal stack for topmost-only Escape
+ * handling and the browser top layer's chronological paint order.
+ *
+ * Dismissal follows Dialog: `purpose` decides whether Escape and a scrim click
+ * request close, and Drawer renders no close button of its own. Compose
+ * `DrawerHeader` with `onOpenChange` for a visible close action, as with
+ * `DialogHeader`.
+ *
+ * The scrolling content area is the drawer's container, like Dialog's inner
+ * box: the `padding` prop, else the theme's `padding` on `drawer`, insets it
+ * through container tokens, defaulting to `--spacing-4` like Dialog, and the
+ * applied inset is published so a lone Section child escapes it and a Layout
+ * redistributes it to its regions. Compose `DrawerHeader` inside a `Layout`, as
+ * `DialogHeader` is composed in Dialog, so the header is not padded twice. The
+ * root dialog stays the overlay boundary (`overlayPaddingReset`).
+ *
+ * SYNC: When modified, update these files to stay in sync:
+ * - /packages/core/src/Drawer/Drawer.doc.mjs (props table, features, usage)
+ * - /packages/core/src/Drawer/Drawer.test.tsx (tests for new/changed behavior)
+ * - /packages/core/src/Drawer/Drawer.spec.md (component contract)
+ * - /packages/core/src/Drawer/index.ts (exports if types change)
+ * - /packages/cli/assets/templates/blocks/components/Drawer/ (showcase blocks)
+ * - /apps/storybook/stories/Drawer.stories.tsx (examples and visual coverage)
+ */
+import { useCallback, useRef, useState } from 'react';
+import * as stylex from '@stylexjs/stylex';
+import "../theme/tokens.stylex.js";
+import { borderVars, colorVars, durationVars, easeVars, shadowVars } from "../theme/tokens.stylex.js";
+import { useFocusTrap, useMergedRefs, useScrollLock } from "../hooks/index.js";
+import { LayerDepthProvider, useLayerDismissal } from "../Layer/index.js";
+import { layerTextReset } from "../Layer/layerTextReset.stylex.js";
+import { layerStructureReset } from "../Layer/layerStructureReset.stylex.js";
+import { LayerContentBoundary } from "../Layer/layerScopedContext.js";
+import { composeEventHandlers, mergeProps, themeProps } from "../utils/index.js";
+import { container, overlayPaddingReset } from "../Layout/index.js";
+import { containerPaddingBlockEndVarStyles, containerPaddingBlockStartVarStyles, containerPaddingInlineVarStyles, paddingStyles, spacingStepToToken } from "../Layout/padding.stylex.js";
+import { useDrawerDialogPresence } from "./useDrawerDialogPresence.js";
+
+// =============================================================================
+// Styles
+// =============================================================================
+
+// Below this viewport width the drawer preserves a fixed reveal of the page
+// behind instead of growing proportionally with the viewport. 640px is the
+// repo's mobile breakpoint.
+import { jsx as _jsx } from "react/jsx-runtime";
+const MOBILE_BREAKPOINT = 640;
+
+// Material's established mobile drawer pattern leaves a 56dp reveal. Using
+// the same value in CSS pixels gives the overlay a stable visual relationship
+// to the page behind while the requested width remains an upper bound.
+const MOBILE_PAGE_REVEAL = 56;
+const MOBILE_WIDTH_FULL = '100dvw';
+const styles = {
+  dialog: {
+    kVAEAm: "xixxii4",
+    kogj98: "x1ghz6dp",
+    kmVPX3: "x1717udv",
+    kMzoRj: "xc342km",
+    ksu8eU: "xng3xce",
+    kaIpWk: "x2u8bby",
+    ks0D6T: "x1x1rfll",
+    kskxy: "x7ab17h",
+    kB7OPa: "x9f619",
+    kXwgrk: "xdt5ytf",
+    kWkggS: "x10xzikg",
+    kGVxlE: "x1kcpxr7",
+    kVQacm: "xb3r6kr",
+    kZeWKH: "xish69e",
+    kI3sdo: "x1a2a7pz",
+    k87sOh: "x13vifvy",
+    krVfgx: "x1ey2m1c",
+    kZKoxP: "xtdtrs8",
+    k1xSpc: "x1s85apg",
+    k1ekBW: "x11xpdln",
+    kIyJzY: "x80gvsz",
+    kAMwcw: "xlr8y92",
+    k6CgDc: "xzg1mie",
+    $$css: true
+  },
+  rendered: {
+    k1xSpc: "x78zum5",
+    $$css: true
+  },
+  end: {
+    kt4wiu: "xtijo5x",
+    kLqNvP: "xhi6v0a",
+    k2ei4v: "xgbv0en",
+    kVhnKS: "x1t7ytsu",
+    kGJrpR: "x1j92z86",
+    k3aq6I: "xumwmo6 xbw113y",
+    $$css: true
+  },
+  endOpen: {
+    k3aq6I: "xbryuvx x1yqmsfc xrxqmjf",
+    $$css: true
+  },
+  start: {
+    kLqNvP: "x1o0tod",
+    kt4wiu: "x1woyocn",
+    ke9TFa: "xw8tdv1",
+    k8ry5P: "x18b5jzi",
+    kBCPoo: "x1gejf6u",
+    k3aq6I: "x5i6ehr x1eqdj8u",
+    $$css: true
+  },
+  startOpen: {
+    k3aq6I: "xbryuvx x6mt36l x1r0dqvm",
+    $$css: true
+  },
+  scrim: {
+    kGyWv1: "xnixb3f",
+    kba3nw: "x1abwkk1",
+    k5sjJv: "xph5o2a",
+    kND0Po: "x167zut7",
+    k9an0g: "xft5bk6",
+    kb4ib: "x15h3t91",
+    kA5Tbj: "x1viac0w",
+    $$css: true
+  },
+  scrimOpen: {
+    k5sjJv: "xb3n6bw xxiuuzi",
+    $$css: true
+  },
+  content: {
+    kzQI83: "x1iyjqo2",
+    kAzted: "x2lwn1j",
+    kzqmXN: "xh8yej3",
+    kORKVm: "x1odjw0f",
+    kXHlph: "x6ikm8r",
+    kZeWKH: "xish69e",
+    kFalU9: "xx69xxh",
+    kI3sdo: "x1a2a7pz",
+    kWkggS: "x10xzikg",
+    $$css: true
+  },
+  contentSafeArea: {
+    kGO01o: "xvmia7e",
+    $$css: true
+  }
+};
+const _temp = {
+  ks0D6T: "xlbgzzq",
+  "$$css": true
+};
+const dynamicStyles = {
+  inlineSize: (desktopWidth, mobileWidth) => [_temp, {
+    kzqmXN: (desktopWidth != null ? "x11ymkkh " : desktopWidth) + (mobileWidth != null ? "xci7e5a" : mobileWidth),
+    $$css: true
+  }, {
+    "--x-1xmrurk": (val => typeof val === "number" ? val + "px" : val != null ? val : undefined)(desktopWidth),
+    "--x-fqzwsx": (val => typeof val === "number" ? val + "px" : val != null ? val : undefined)(mobileWidth)
+  }]
+};
+
+// =============================================================================
+// Types
+// =============================================================================
+
+// =============================================================================
+// Component
+// =============================================================================
+
+/**
+ * An overlay panel for inspectors and detail views.
+ *
+ * Slides in from the logical start or end edge and floats above the page
+ * using the native `<dialog>` element: modal with a scrim by default, or a
+ * non-modal overlay with `hasScrim={false}` that leaves the page behind
+ * interactive. `width` is the desktop budget; below 640px the panel preserves
+ * a 56px page reveal without exceeding that budget (or fills the viewport
+ * with the experimental `experimental.isFullWidthOnMobile`). Escape
+ * closes the top-most open drawer; focus returns to the element that
+ * opened it.
+ *
+ * Dismissal matches Dialog: `purpose` decides whether Escape and a scrim click
+ * close the drawer, and `DrawerHeader` renders a close button when given
+ * `onOpenChange`.
+ *
+ * Like Dialog, the drawer is a container: `padding` (or a theme's `padding`
+ * on `drawer`) insets the content area, a lone Section child escapes that
+ * inset, and a Layout inside picks it up for its header, content, and footer
+ * regions. The default inset is `--spacing-4`, matching Dialog.
+ *
+ * @example
+ * ```
+ * const [selected, setSelected] = useState(null);
+ * const handleOpenChange = isOpen => !isOpen && setSelected(null);
+ * <Drawer
+ *   isOpen={selected != null}
+ *   onOpenChange={handleOpenChange}
+ *   label={`Details: ${selected?.name}`}>
+ *   <Layout
+ *     header={<DrawerHeader title={selected?.name} onOpenChange={handleOpenChange} />}
+ *     content={<LayoutContent><HostDetails host={selected} /></LayoutContent>}
+ *   />
+ * </Drawer>
+ * ```
+ */
+export function Drawer({
+  isOpen,
+  onOpenChange,
+  side = 'end',
+  width = 400,
+  experimental,
+  label,
+  hasScrim = true,
+  purpose = 'info',
+  padding,
+  children,
+  xstyle,
+  className,
+  style,
+  onClick: onClickProp,
+  onKeyDown: onKeyDownProp,
+  ref,
+  ...props
+}) {
+  const dialogRef = useRef(null);
+  const {
+    containerRef: focusTrapRef
+  } = useFocusTrap({
+    isActive: isOpen && hasScrim
+  });
+  const mergedDialogRef = useMergedRefs(ref, dialogRef, focusTrapRef);
+  // Derive dismissal behavior from purpose, as Dialog does.
+  const allowEscape = purpose !== 'required';
+  const allowScrimClick = purpose === 'info';
+  // Same lowering as Dialog: with no padding prop the content area reads the
+  // theme's --astryx-drawer-padding chain (--spacing-4 when unset), else the
+  // explicit step.
+  const usesThemePadding = padding == null;
+  const effectivePadding = padding ?? 4;
+  const paddingToken = spacingStepToToken[effectivePadding];
+  // Whether the panel paints: true while open and for the whole slide-out.
+  const [isRendered, setIsRendered] = useState(isOpen);
+
+  // Adjusted during render, not in an effect: the panel has to be rendered in
+  // the same commit that targets the open transform, or @starting-style has
+  // nothing to animate from.
+  if (isOpen && !isRendered) {
+    setIsRendered(true);
+  }
+  useDrawerDialogPresence({
+    dialogRef,
+    isOpen,
+    isModal: hasScrim,
+    setIsRendered
+  });
+  const handleDismiss = useCallback(() => {
+    onOpenChange(false);
+  }, [onOpenChange]);
+
+  // The shared stack owns Escape delivery across every overlay family. The
+  // provider below gives layers opened from Drawer content a greater logical
+  // depth even when they render elsewhere in the DOM or browser top layer.
+  const {
+    shouldDismissOnCloseRequest
+  } = useLayerDismissal({
+    // The native host stays present through the slide-out. Keep this entry on
+    // the stack until the same commit that hides the host, so a second Escape
+    // cannot fall through to a lower layer during the exit animation.
+    isActive: isRendered,
+    // A `required` drawer consumes Escape without closing, so the press cannot
+    // fall through and dismiss a layer behind it either.
+    escapeBehavior: allowEscape ? 'close' : 'block',
+    onDismiss: handleDismiss,
+    getContainer: () => dialogRef.current
+  });
+
+  // Lock body scroll while a modal drawer is open (iOS Safari workaround).
+  useScrollLock(isOpen && hasScrim);
+
+  // A modal dialog's native cancel event is a platform close request (for
+  // example Android Back). Keep controlled state authoritative and apply the
+  // same top-most/IME rules as the shared Escape listener.
+  const handleCancel = useCallback(event => {
+    event.preventDefault();
+    if (shouldDismissOnCloseRequest() && allowEscape) {
+      handleDismiss();
+    }
+  }, [allowEscape, handleDismiss, shouldDismissOnCloseRequest]);
+
+  // Clicks on the ::backdrop target the <dialog> element itself; clicks on
+  // drawer content always target a child (the content area fills the panel).
+  const handleClick = useCallback(event => {
+    if (event.target === event.currentTarget && hasScrim && allowScrimClick) {
+      onOpenChange(false);
+    }
+  }, [allowScrimClick, hasScrim, onOpenChange]);
+  const widthValue = typeof width === 'number' ? `${width}px` : width;
+  const isFullWidthOnMobile = experimental?.isFullWidthOnMobile ?? false;
+  const mobileWidth = isFullWidthOnMobile ? MOBILE_WIDTH_FULL : `min(${widthValue}, calc(100dvw - ${MOBILE_PAGE_REVEAL}px))`;
+
+  // The side the panel is ANCHORED to, which is the side it must slide back
+  // out to. Latched at open, because a consumer commonly derives `side` from
+  // the same state that drives `isOpen` (`side={selected?.side ?? 'end'}`):
+  // that state clears on close, so the live prop flips mid-exit and the panel
+  // teleports to the other edge and slides out the wrong way. Children stay
+  // mounted for the exit for the same reason; so does the anchor.
+  const exitSideRef = useRef(side);
+  if (isOpen) {
+    exitSideRef.current = side;
+  }
+  const anchoredSide = isOpen ? side : exitSideRef.current;
+  const sideStyle = anchoredSide === 'start' ? styles.start : styles.end;
+  const sideOpenStyle = anchoredSide === 'start' ? styles.startOpen : styles.endOpen;
+
+  // Filter out native `open` to prevent InvalidStateError when passed
+  const {
+    open: _open,
+    ...safeProps
+  } = props;
+  return /*#__PURE__*/_jsx("dialog", {
+    ref: mergedDialogRef,
+    ...mergeProps(themeProps('drawer', {
+      side: anchoredSide
+    }), stylex.props(layerTextReset.reset, layerStructureReset.reset, styles.dialog, overlayPaddingReset.reset, sideStyle, dynamicStyles.inlineSize(widthValue, mobileWidth), isRendered && styles.rendered, isOpen && sideOpenStyle, hasScrim && styles.scrim, hasScrim && isOpen && styles.scrimOpen, xstyle), className, style),
+    ...safeProps,
+    popover: hasScrim ? undefined : 'manual',
+    "aria-label": label,
+    "aria-modal": hasScrim ? 'true' : undefined,
+    ...(purpose === 'required' && hasScrim ? {
+      role: 'alertdialog'
+    } : undefined),
+    onClick: composeEventHandlers(onClickProp, handleClick),
+    onKeyDown: onKeyDownProp,
+    onCancel: handleCancel,
+    children: /*#__PURE__*/_jsx(LayerDepthProvider, {
+      children: /*#__PURE__*/_jsx(LayerContentBoundary, {
+        children: /*#__PURE__*/_jsx("div", {
+          tabIndex: -1,
+          ...stylex.props(styles.content, ...container(usesThemePadding ? {
+            useThemeDefault: 'drawer'
+          } : {
+            paddingInnerX: paddingToken,
+            paddingInnerY: paddingToken,
+            paddingOuterX: paddingToken,
+            paddingOuterY: paddingToken
+          }), !usesThemePadding && effectivePadding !== 4 && paddingStyles[effectivePadding], !usesThemePadding && effectivePadding !== 4 && containerPaddingInlineVarStyles[effectivePadding], !usesThemePadding && effectivePadding !== 4 && containerPaddingBlockStartVarStyles[effectivePadding], !usesThemePadding && effectivePadding !== 4 && containerPaddingBlockEndVarStyles[effectivePadding], styles.contentSafeArea),
+          children: children
+        })
+      })
+    })
+  });
+}
+Drawer.displayName = 'Drawer';

package/dist/Drawer/DrawerHeader.d.ts

@@ -0,0 +1,85 @@
+/**
+ * @file DrawerHeader.tsx
+ * @input Uses React, StyleX, LayoutHeader, Button, Icon, Heading, Text, i18n, BaseProps, isRenderable, mergeProps, themeProps
+ * @output Exports DrawerHeader component and DrawerHeaderProps
+ * @position Drawer header; composed in a Layout header slot inside Drawer, tested by DrawerHeader.test.tsx
+ *
+ * Mirrors DialogHeader's API: a title, an optional subtitle, start/end content
+ * slots, and a close button that renders only when `onOpenChange` is passed.
+ * Two differences follow from Drawer's contract:
+ * - It does not move focus on mount. Drawer owns focus entry through
+ *   `data-autofocus` once its native host is presented.
+ * - It does not name the drawer. Drawer's required `label` does.
+ *
+ * SYNC: When modified, update these files to stay in sync:
+ * - /packages/core/src/Drawer/DrawerHeader.doc.mjs (props, anatomy, theming)
+ * - /packages/core/src/Drawer/DrawerHeader.test.tsx (tests for new/changed behavior)
+ * - /packages/core/src/Drawer/index.ts (exports if types change)
+ * - /packages/cli/assets/templates/blocks/components/Drawer/ (showcase blocks)
+ * - /packages/cli/assets/templates/blocks/components/DrawerHeader/ (showcase blocks)
+ * - /apps/storybook/stories/Drawer.stories.tsx (examples and visual coverage)
+ * - /apps/storybook/stories/DrawerHeader.stories.tsx (component audit fixture)
+ */
+import type { ReactNode } from 'react';
+import type { BaseProps } from '../BaseProps';
+export interface DrawerHeaderProps extends BaseProps<HTMLDivElement> {
+    /** Ref forwarded to the root element */
+    ref?: React.Ref<HTMLDivElement>;
+    /**
+     * The title of the drawer, rendered as an h2. Keep it inline and
+     * non-interactive. It does not name the drawer; Drawer's `label` does.
+     */
+    title: ReactNode;
+    /**
+     * Optional subtitle displayed below the title in smaller, secondary text.
+     * Accepts inline content such as a Link; it renders inside a span, so
+     * avoid block elements. Nothing renders for `null`, `undefined`, booleans,
+     * or an empty string.
+     */
+    subtitle?: ReactNode;
+    /**
+     * Called with `false` when the close button is clicked. Pass the Drawer's
+     * own `onOpenChange`. If not provided, no close button is rendered.
+     */
+    onOpenChange?: (isOpen: boolean) => unknown;
+    /**
+     * Content to render before the title (e.g., a back button).
+     */
+    startContent?: ReactNode;
+    /**
+     * Content to render after the title, before the close button (e.g., action
+     * buttons).
+     */
+    endContent?: ReactNode;
+    /**
+     * Overrides automatic end-slot compensation. When omitted, rendering the
+     * close action applies block and logical inline-end compensation. Use
+     * `inline`, `block`, or `all` to select the axes explicitly.
+     */
+    endContentEdgeCompensation?: 'inline' | 'block' | 'all';
+    /**
+     * Adds a themed border at the bottom edge.
+     * When false, spacing collapse is applied automatically for seamless visual flow.
+     * Defaults to the parent Layout's `defaultHasDividers` context value.
+     */
+    hasDivider?: boolean;
+}
+/**
+ * Header for a Drawer: a title, optional subtitle and start/end content, and a
+ * close button when `onOpenChange` is passed. Same API as DialogHeader.
+ *
+ * Uses LayoutHeader internally for consistent styling with other layout headers.
+ *
+ * @example
+ * ```
+ * <Drawer isOpen={isOpen} onOpenChange={setIsOpen} label="Details">
+ *   <DrawerHeader title="Details" onOpenChange={setIsOpen} />
+ *   <Section padding={4}>Content</Section>
+ * </Drawer>
+ * ```
+ */
+export declare function DrawerHeader({ title, subtitle, onOpenChange, startContent, endContent, endContentEdgeCompensation, hasDivider, xstyle, className, style, ref, ...rest }: DrawerHeaderProps): import("react").JSX.Element;
+export declare namespace DrawerHeader {
+    var displayName: string;
+}
+//# sourceMappingURL=DrawerHeader.d.ts.map

package/dist/Drawer/DrawerHeader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DrawerHeader.d.ts","sourceRoot":"","sources":["../../src/Drawer/DrawerHeader.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,OAAO,CAAC;AAErC,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AA0C5C,MAAM,WAAW,iBAAkB,SAAQ,SAAS,CAAC,cAAc,CAAC;IAClE,wCAAwC;IACxC,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;IAEhC;;;OAGG;IACH,KAAK,EAAE,SAAS,CAAC;IAEjB;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,SAAS,CAAC;IAErB;;;OAGG;IACH,YAAY,CAAC,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,OAAO,CAAC;IAE5C;;OAEG;IACH,YAAY,CAAC,EAAE,SAAS,CAAC;IAEzB;;;OAGG;IACH,UAAU,CAAC,EAAE,SAAS,CAAC;IAEvB;;;;OAIG;IACH,0BAA0B,CAAC,EAAE,QAAQ,GAAG,OAAO,GAAG,KAAK,CAAC;IAExD;;;;OAIG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,YAAY,CAAC,EAC3B,KAAK,EACL,QAAQ,EACR,YAAY,EACZ,YAAY,EACZ,UAAU,EACV,0BAA0B,EAC1B,UAAU,EACV,MAAM,EACN,SAAS,EACT,KAAK,EACL,GAAG,EACH,GAAG,IAAI,EACR,EAAE,iBAAiB,+BAoFnB;yBAjGe,YAAY"}