@astryxdesign/core 0.7.1 → 0.7.2-canary.07f97c6

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"}

package/dist/Drawer/DrawerHeader.js

@@ -0,0 +1,134 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @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 * as stylex from '@stylexjs/stylex';
+import "../theme/tokens.stylex.js";
+import { sizeVars, spacingVars, typeScaleVars } from "../theme/tokens.stylex.js";
+import { Button } from "../Button/index.js";
+import { Heading } from "../Heading/index.js";
+import { Icon } from "../Icon/index.js";
+import { LayoutHeader } from "../Layout/index.js";
+import { Text } from "../Text/index.js";
+import { useTranslator } from "../i18n/index.js";
+import { isRenderable, mergeProps, themeProps } from "../utils/index.js";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * 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 function DrawerHeader({
+  title,
+  subtitle,
+  onOpenChange,
+  startContent,
+  endContent,
+  endContentEdgeCompensation,
+  hasDivider,
+  xstyle,
+  className,
+  style,
+  ref,
+  ...rest
+}) {
+  const t = useTranslator();
+  const hasSubtitle = isRenderable(subtitle);
+  const hasStartContent = isRenderable(startContent);
+  const hasEndContent = isRenderable(endContent);
+  const shouldCompensateEndBlock = endContentEdgeCompensation == null ? onOpenChange != null : endContentEdgeCompensation === 'block' || endContentEdgeCompensation === 'all';
+  const shouldCompensateEndInline = endContentEdgeCompensation == null ? onOpenChange != null : endContentEdgeCompensation === 'inline' || endContentEdgeCompensation === 'all';
+  return /*#__PURE__*/_jsx(LayoutHeader, {
+    ref: ref,
+    hasDivider: hasDivider,
+    xstyle: xstyle,
+    className: className,
+    style: style,
+    ...rest,
+    children: /*#__PURE__*/_jsxs("div", {
+      ...mergeProps(themeProps('drawer-header'), {
+        className: "x78zum5 x1cy8zhl x1qughib xjcht0a"
+      }),
+      children: [hasStartContent && /*#__PURE__*/_jsx("div", {
+        ...mergeProps(themeProps('drawer-header-start-content'), {
+          className: "x78zum5 x6s0dn4 x1txdalj x2lah0s"
+        }),
+        children: startContent
+      }), /*#__PURE__*/_jsxs("div", {
+        ...mergeProps(themeProps('drawer-header-title-block'), {
+          className: "x78zum5 xdt5ytf xsn7fz1 x98rzlu xeuugli xqixskq"
+        }),
+        children: [/*#__PURE__*/_jsx(Heading, {
+          level: 2,
+          children: title
+        }), hasSubtitle && /*#__PURE__*/_jsx(Text, {
+          type: "body",
+          size: "sm",
+          color: "secondary",
+          children: subtitle
+        })]
+      }), (hasEndContent || onOpenChange != null) && /*#__PURE__*/_jsxs("div", {
+        ...mergeProps(themeProps('drawer-header-end-content'), {
+          0: {
+            className: "x78zum5 x6s0dn4 x1txdalj x2lah0s"
+          },
+          2: {
+            className: "x78zum5 x6s0dn4 x1txdalj x2lah0s xhzvc8f"
+          },
+          1: {
+            className: "x78zum5 x6s0dn4 x1txdalj x2lah0s x3kzqx6"
+          },
+          3: {
+            className: "x78zum5 x6s0dn4 x1txdalj x2lah0s xhzvc8f x3kzqx6"
+          }
+        }[!!shouldCompensateEndBlock << 1 | !!shouldCompensateEndInline << 0]),
+        children: [endContent, onOpenChange && /*#__PURE__*/_jsx(Button, {
+          variant: "ghost",
+          label: t('@astryx.dialog.close'),
+          tooltip: t('@astryx.dialog.close'),
+          icon: /*#__PURE__*/_jsx(Icon, {
+            icon: "close",
+            color: "inherit",
+            ...themeProps('drawer-header-close-icon')
+          }),
+          onClick: () => {
+            onOpenChange(false);
+          },
+          isIconOnly: true
+        })]
+      })]
+    })
+  });
+}
+DrawerHeader.displayName = 'DrawerHeader';

package/dist/Drawer/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * @file index.ts
+ * @input Drawer.tsx, DrawerHeader.tsx
+ * @output Re-exports Drawer and DrawerHeader components and their prop types
+ * @position Core entry point for the Drawer directory (`@astryxdesign/core/Drawer`)
+ */
+export { Drawer } from './Drawer';
+export type { DrawerProps } from './Drawer';
+export { DrawerHeader } from './DrawerHeader';
+export type { DrawerHeaderProps } from './DrawerHeader';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/Drawer/index.ts"],"names":[],"mappings":"AAEA;;;;;GAKG;AAEH,OAAO,EAAC,MAAM,EAAC,MAAM,UAAU,CAAC;AAChC,YAAY,EAAC,WAAW,EAAC,MAAM,UAAU,CAAC;AAC1C,OAAO,EAAC,YAAY,EAAC,MAAM,gBAAgB,CAAC;AAC5C,YAAY,EAAC,iBAAiB,EAAC,MAAM,gBAAgB,CAAC"}

package/dist/Drawer/index.js

@@ -0,0 +1,11 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file index.ts
+ * @input Drawer.tsx, DrawerHeader.tsx
+ * @output Re-exports Drawer and DrawerHeader components and their prop types
+ * @position Core entry point for the Drawer directory (`@astryxdesign/core/Drawer`)
+ */
+
+export { Drawer } from "./Drawer.js";
+export { DrawerHeader } from "./DrawerHeader.js";

package/dist/Drawer/useDrawerDialogPresence.d.ts

@@ -0,0 +1,42 @@
+/**
+ * @file useDrawerDialogPresence.ts
+ * @input Controlled open state, modal mode, dialog ref, and rendered-state setter
+ * @output Coordinates native top-layer presence, exit timing, focus restoration, and unmount cleanup
+ * @position Drawer-internal hook; consumed only by Drawer.tsx
+ *
+ * The drawer has two independent notions of presence:
+ * - React's rendered state keeps the panel visible for its CSS exit.
+ * - Native `showModal()` or `showPopover()` state keeps it in the browser top
+ *   layer.
+ *
+ * Their close ordering is a browser-visible invariant: the panel must finish
+ * its exit, then leave the active native host and hide in the same task. If the
+ * hide lands a frame later, a transformed ancestor becomes the containing block
+ * for the now-non-top-layer `position: fixed` panel and it paints back inside
+ * the page for one frame.
+ *
+ * SYNC: When modified, update:
+ * - /packages/core/src/Drawer/Drawer.test.tsx
+ * - /.github/scripts/modal-close-visibility.js
+ */
+import { type Dispatch, type RefObject, type SetStateAction } from 'react';
+type UseDrawerDialogPresenceOptions = {
+    dialogRef: RefObject<HTMLDialogElement | null>;
+    isOpen: boolean;
+    isModal: boolean;
+    setIsRendered: Dispatch<SetStateAction<boolean>>;
+};
+/**
+ * Coordinates the native dialog and React-rendered presence for Drawer.
+ *
+ * Opening captures the trigger, enters the modal-dialog or manual-popover host,
+ * and honours the component's `data-autofocus` contract. Closing waits for the
+ * actual transform transition (with a computed-duration backstop), then leaves
+ * the native host and synchronously hides the panel before the browser can paint
+ * it outside the top layer, restores focus to the captured trigger, and only
+ * then dispatches the popover host's synthetic `close`. Unmount cleanup closes
+ * a host left open by React Activity or a removed subtree.
+ */
+export declare function useDrawerDialogPresence({ dialogRef, isOpen, isModal, setIsRendered, }: UseDrawerDialogPresenceOptions): void;
+export {};
+//# sourceMappingURL=useDrawerDialogPresence.d.ts.map