@astryxdesign/lab 0.6.3-canary.2bb99ed → 0.6.3-canary.2bdba84

package/README.md

@@ -50,6 +50,29 @@ import '@astryxdesign/lab/lab.css';
 
 > Canary builds track the latest commit on `main` (`0.x.y-canary.<sha>`). They can break between any two versions — pin an exact version if you need stability.
 
+## Documenting a Lab component (canary docsite)
+
+Lab appears **only on the canary docsite** — the production site documents the published stable release and never loads this package (see the target gates in `apps/docsite/scripts/` and the exclusion tests in `apps/docsite/src/__tests__/integration-targets.test.ts`).
+
+Authoring is the same two-artifact flow a Core author uses; the only difference is where the runnable demos live (Core keeps its blocks centrally in `packages/cli/assets/templates/blocks/`, Lab owns its own `blocks/` directory here):
+
+1. **Component doc** — `src/<Name>/<Name>.doc.mjs` exporting `docs` (props, usage, playground config, `examples`). Picked up automatically on canary; no registration anywhere.
+2. **Runnable demos** — same-stem pairs in `blocks/`: `<BlockName>.tsx` + `<BlockName>.doc.mjs` (a `TemplateDoc` stamped `type: 'block'`). Discovered automatically once this package declares the directory — nothing per-component. The docsite renders the pair as the component page's showcase/examples and the playground can import anything the package exports.
+
+**First block only:** the pull request that adds Lab's first block also adds `templates: './blocks'` to `astryx.integration.mjs` and `"blocks"` to the `files` list in `package.json`. Declaring the root earlier would fail `astryx integration pack --check`, which rejects a declared root with no contributions. After that one-time step, a new demo is just its block pair.
+
+How a demo reaches a component page: **`exampleFor: '<Component>'` (or `alsoExampleFor`) is what attaches a block** — the page renders every block attributed to it, whatever the block is named. The block's `name` is the demo's display name; component-doc example `labels` are CLI-snippet headings. The two are independent mechanisms.
+
+Use these conventions for new demos:
+
+- Give the block descriptor the same `name` as the component doc's example `label`, so the snippet and its runnable demo read as one documented set (this naming convention is what the `example-coverage` report keys on — it is not how the docsite attaches demos).
+- Exactly one attributed block sets `isShowcase: true` (the hero demo — conventionally the first example).
+- `displayName` and `description` are required by the docsite build; set `componentsUsed` and `aspectRatio` for the gallery.
+
+A doc example with no corresponding block exists only as a CLI/code snippet — the docsite page's demos come solely from blocks. Note the converse does not follow from names alone: an example label with no _same-named_ block does not by itself mean the demo is missing, because the component may render demos under other names (several Core components do). The `example-coverage` docsite test output reports both sides of that pairing; it is a _report_, not a gate — Core has the same non-guarantee, and whether pairing should gate CI is an open repo-wide decision.
+
+> Note: `astryx integration add template` scaffolds a `./templates` root for a package that declares none. Declare `templates: './blocks'` explicitly instead, matching charts and richtext; unifying the two conventions is a pending repo decision.
+
 ## Why no stable release?
 
 `package.json` keeps `"private": true` plus an `"astryx": { "canaryOnly": true }` marker. The release workflow's stable (`latest`) job skips both private and `canaryOnly` packages, while the canary job strips `private` in its ephemeral CI checkout only (never in git) to publish the `@canary` tag. The committed `private: true` is npm's hard guarantee that no stable publish can ever happen — **do not remove it.**

package/dist/Drawer/Drawer.d.ts

@@ -1,6 +1,6 @@
 /**
  * @file Drawer.tsx
- * @input Uses React, StyleX, theme tokens, Icon/IconButton, useScrollLock/useDrawerDialogPresence, BaseProps, mergeProps/mergeRefs, themeProps
+ * @input Uses React, StyleX, theme tokens and text defaults, Icon/IconButton, shared focus/dismissal/depth primitives, i18n, scroll locking/dialog presence, BaseProps, merged refs/props, themeProps
  * @output Exports Drawer component and DrawerProps
  * @position Lab implementation; consumed by index.ts, tested by Drawer.test.tsx, demonstrated in Storybook
  *
@@ -19,18 +19,17 @@
  * Uses the native `<dialog>` element (same precedent as Dialog/MobileNav):
  * - `showModal()` when `hasScrim` (default) — top-layer rendering, focus
  *   trapping, `::backdrop`, no z-index management.
- * - `show()` when `hasScrim={false}` — non-modal overlay; the page behind
- *   stays interactive (e.g. master-detail inspectors).
+ * - `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
- * `dialog.close()` releases the top layer and restores focus 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 `close()` — see the `rendered` style for why that matters.
+ * 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 coordinate through a module-level LIFO registry: Escape
- * closes only the top (last-opened) drawer, and non-modal drawers stack
- * last-opened-on-top via registry-assigned z-indexes.
+ * Sibling drawers use the shared layer dismissal stack for topmost-only Escape
+ * handling and the browser top layer's chronological paint order.
  *
  * SYNC: When modified, update these files to stay in sync:
  * - /packages/lab/src/Drawer/Drawer.doc.mjs (props table, features, usage)
@@ -86,8 +85,8 @@ export interface DrawerProps extends BaseProps<HTMLDialogElement> {
      * Whether to render a modal scrim behind the drawer.
      * - `true` (default) — `showModal()`: top layer, focus trap, body scroll
      *   lock, click-outside-to-close.
-     * - `false` — `show()`: non-modal overlay; the page behind stays
-     *   interactive. Escape still closes while focus is inside the drawer.
+     * - `false` — `showPopover()`: non-modal top-layer overlay; the page behind
+     *   stays interactive. Escape still closes through the shared layer stack.
      * @default true
      */
     hasScrim?: boolean;

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

@@ -1 +1 @@
-{"version":3,"file":"Drawer.d.ts","sourceRoot":"","sources":["../../src/Drawer/Drawer.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAEH,OAAO,EAML,KAAK,SAAS,EACf,MAAM,OAAO,CAAC;AAEf,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,oBAAoB,CAAC;AA+OlD,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;;;;;OAKG;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;;;;;;OAMG;IACH,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAE9B;;;OAGG;IACH,KAAK,EAAE,MAAM,CAAC;IAEd;;;;;;;OAOG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IAEnB;;;;;OAKG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;IAEzB;;;OAGG;IACH,QAAQ,EAAE,SAAS,CAAC;IAEpB;;OAEG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAMD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,MAAM,CAAC,EACrB,MAAM,EACN,YAAY,EACZ,IAAY,EACZ,KAAW,EACX,mBAA2B,EAC3B,KAAK,EACL,QAAe,EACf,cAAqB,EACrB,QAAQ,EACR,MAAM,EACN,SAAS,EACT,KAAK,EACL,OAAO,EAAE,WAAW,EACpB,SAAS,EAAE,aAAa,EACxB,GAAG,EACH,GAAG,KAAK,EACT,EAAE,WAAW,+BAqJb;yBAtKe,MAAM"}
+{"version":3,"file":"Drawer.d.ts","sourceRoot":"","sources":["../../src/Drawer/Drawer.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AAEH,OAAO,EAAgC,KAAK,SAAS,EAAC,MAAM,OAAO,CAAC;AAEpE,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,oBAAoB,CAAC;AA4NlD,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;;;;;OAKG;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;;;;;;OAMG;IACH,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAE9B;;;OAGG;IACH,KAAK,EAAE,MAAM,CAAC;IAEd;;;;;;;OAOG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IAEnB;;;;;OAKG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;IAEzB;;;OAGG;IACH,QAAQ,EAAE,SAAS,CAAC;IAEpB;;OAEG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAMD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,MAAM,CAAC,EACrB,MAAM,EACN,YAAY,EACZ,IAAY,EACZ,KAAW,EACX,mBAA2B,EAC3B,KAAK,EACL,QAAe,EACf,cAAqB,EACrB,QAAQ,EACR,MAAM,EACN,SAAS,EACT,KAAK,EACL,OAAO,EAAE,WAAW,EACpB,SAAS,EAAE,aAAa,EACxB,GAAG,EACH,GAAG,KAAK,EACT,EAAE,WAAW,+BAwIb;yBAzJe,MAAM"}

package/dist/Drawer/Drawer.js

@@ -4,7 +4,7 @@
 
 /**
  * @file Drawer.tsx
- * @input Uses React, StyleX, theme tokens, Icon/IconButton, useScrollLock/useDrawerDialogPresence, BaseProps, mergeProps/mergeRefs, themeProps
+ * @input Uses React, StyleX, theme tokens and text defaults, Icon/IconButton, shared focus/dismissal/depth primitives, i18n, scroll locking/dialog presence, BaseProps, merged refs/props, themeProps
  * @output Exports Drawer component and DrawerProps
  * @position Lab implementation; consumed by index.ts, tested by Drawer.test.tsx, demonstrated in Storybook
  *
@@ -23,18 +23,17 @@
  * Uses the native `<dialog>` element (same precedent as Dialog/MobileNav):
  * - `showModal()` when `hasScrim` (default) — top-layer rendering, focus
  *   trapping, `::backdrop`, no z-index management.
- * - `show()` when `hasScrim={false}` — non-modal overlay; the page behind
- *   stays interactive (e.g. master-detail inspectors).
+ * - `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
- * `dialog.close()` releases the top layer and restores focus 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 `close()` — see the `rendered` style for why that matters.
+ * 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 coordinate through a module-level LIFO registry: Escape
- * closes only the top (last-opened) drawer, and non-modal drawers stack
- * last-opened-on-top via registry-assigned z-indexes.
+ * Sibling drawers use the shared layer dismissal stack for topmost-only Escape
+ * handling and the browser top layer's chronological paint order.
  *
  * SYNC: When modified, update these files to stay in sync:
  * - /packages/lab/src/Drawer/Drawer.doc.mjs (props table, features, usage)
@@ -42,55 +41,19 @@
  * - /packages/lab/src/Drawer/index.ts (exports if types change)
  * - /apps/storybook/stories/Drawer.stories.tsx (examples and visual coverage)
  */
-import { useCallback, useEffect, useId, useRef, useState } from 'react';
+import { useCallback, useRef, useState } from 'react';
 import * as stylex from '@stylexjs/stylex';
 import '@astryxdesign/core/theme/tokens.stylex';
-import { borderVars, colorVars, durationVars, easeVars, shadowVars, spacingVars } from '@astryxdesign/core/theme/tokens.stylex';
+import { borderVars, colorVars, durationVars, easeVars, shadowVars, spacingVars, typeScaleVars, typographyVars } from '@astryxdesign/core/theme/tokens.stylex';
 import { Icon } from '@astryxdesign/core/Icon';
 import { IconButton } from '@astryxdesign/core/IconButton';
-import { useScrollLock } from '@astryxdesign/core/hooks';
-import { composeEventHandlers, mergeProps, mergeRefs, themeProps } from '@astryxdesign/core/utils';
+import { useFocusTrap, useMergedRefs, useScrollLock } from '@astryxdesign/core/hooks';
+import { LayerDepthProvider, useLayerDismissal } from '@astryxdesign/core/Layer';
+import { useTranslator } from '@astryxdesign/core/i18n';
+import { composeEventHandlers, mergeProps, themeProps } from '@astryxdesign/core/utils';
 import { overlayPaddingReset } from '@astryxdesign/core/Layout';
 import { useDrawerDialogPresence } from "./useDrawerDialogPresence.js";
 
-// =============================================================================
-// LIFO stacking registry (internal)
-// =============================================================================
-
-// Module-level registry of currently open drawers, in open order (last entry
-// is the top of the stack). SSR-safe: only mutated inside effects. Escape
-// handling consults isTopDrawer() so sibling drawers close innermost-first,
-// and non-modal (show()) drawers get incrementing z-indexes so the
-// last-opened one paints on top; modal drawers rely on the native top
-// layer's chronological stacking instead.
-import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-// Without the top layer (hasScrim={false} uses show(), not showModal())
-// the panel needs explicit stacking. No z-index token exists in the theme;
-// 1000 matches the app-level drawer convention.
-const NON_MODAL_BASE_Z = 1000;
-const openDrawerStack = [];
-let registrationCounter = 0;
-function registerDrawer(id, close) {
-  openDrawerStack.push({
-    id,
-    close
-  });
-  registrationCounter += 1;
-  return NON_MODAL_BASE_Z + registrationCounter - 1;
-}
-function unregisterDrawer(id) {
-  const index = openDrawerStack.findIndex(entry => entry.id === id);
-  if (index !== -1) {
-    openDrawerStack.splice(index, 1);
-  }
-  if (openDrawerStack.length === 0) {
-    registrationCounter = 0;
-  }
-}
-function isTopDrawer(id) {
-  return openDrawerStack[openDrawerStack.length - 1]?.id === id;
-}
-
 // =============================================================================
 // Styles
 // =============================================================================
@@ -98,6 +61,7 @@ function isTopDrawer(id) {
 // 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, jsxs as _jsxs } from "react/jsx-runtime";
 const MOBILE_BREAKPOINT = 640;
 
 // Material's established mobile drawer pattern leaves a 56dp reveal. Using
@@ -107,6 +71,22 @@ const MOBILE_PAGE_REVEAL = 56;
 const MOBILE_WIDTH_FULL = '100dvw';
 const styles = {
   dialog: {
+    kMv6JI: "x9ynric",
+    kGuDYH: "xjm74w1",
+    k63SB2: "xxovm9e",
+    kLWn49: "xw6l6zx",
+    kKX8nH: "x1j61x8r",
+    k9WMMc: "x1yc453h",
+    kJI5tL: "x7ssn7h",
+    kTHuQy: "xzugeeo",
+    kP9fke: "x6mezaz",
+    kb6lSQ: "x1i21sxh",
+    k4JVr9: "xp3md9m",
+    kKMj4B: "x19pm5ym",
+    khDVqt: "xeaf4i8",
+    kTgw9: "x1lldw8n",
+    kHjlTd: "x1h4wwuj",
+    kE4Cay: "xxydokm",
     kVAEAm: "xixxii4",
     kogj98: "x1ghz6dp",
     kmVPX3: "x1717udv",
@@ -186,12 +166,6 @@ const dynamicStyles = {
   }, {
     "--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)
-  }],
-  stackZ: z => [{
-    kY2c9j: z != null ? "xr3buco" : z,
-    $$css: true
-  }, {
-    "--x-zIndex": z != null ? z : undefined
   }]
 };
 
@@ -245,15 +219,13 @@ export function Drawer({
   ...props
 }) {
   const dialogRef = useRef(null);
-  // Registry identity + latest onOpenChange (stable across re-renders so the
-  // registration effect doesn't churn on every onOpenChange identity change).
-  const drawerId = useId();
-  const onOpenChangeRef = useRef(onOpenChange);
-  useEffect(() => {
-    onOpenChangeRef.current = onOpenChange;
-  }, [onOpenChange]);
-  // z-index assigned by the registry on open (non-modal stacking only).
-  const [stackZ, setStackZ] = useState(NON_MODAL_BASE_Z);
+  const {
+    containerRef: focusTrapRef
+  } = useFocusTrap({
+    isActive: isOpen && hasScrim
+  });
+  const mergedDialogRef = useMergedRefs(ref, dialogRef, focusTrapRef);
+  const t = useTranslator();
   // Whether the panel paints: true while open and for the whole slide-out.
   const [isRendered, setIsRendered] = useState(isOpen);
 
@@ -269,44 +241,36 @@ export function Drawer({
     isModal: hasScrim,
     setIsRendered
   });
+  const handleDismiss = useCallback(() => {
+    onOpenChange(false);
+  }, [onOpenChange]);
 
-  // LIFO registry membership: register on open, unregister on close or
-  // unmount. The returned z-index stacks non-modal siblings in open order.
-  useEffect(() => {
-    if (!isOpen) {
-      return;
-    }
-    const z = registerDrawer(drawerId, () => onOpenChangeRef.current(false));
-    setStackZ(z);
-    return () => unregisterDrawer(drawerId);
-  }, [isOpen, drawerId]);
+  // 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,
+    onDismiss: handleDismiss,
+    getContainer: () => dialogRef.current
+  });
 
   // Lock body scroll while a modal drawer is open (iOS Safari workaround).
   useScrollLock(isOpen && hasScrim);
 
-  // Escape closes. The native `cancel` event only fires for showModal();
-  // this React keydown handler covers the non-modal show() path too. Only the
-  // top of the drawer stack closes, so stacked siblings peel off
-  // innermost-first.
-  const handleKeyDown = useCallback(event => {
-    if (event.key === 'Escape') {
-      event.preventDefault();
-      if (isTopDrawer(drawerId)) {
-        onOpenChange(false);
-      }
-    }
-  }, [onOpenChange, drawerId]);
-
-  // Native cancel event (browser Escape handling) — prevent the browser
-  // from closing the dialog directly and route through onOpenChange so the
-  // caller's state stays the source of truth. Same top-of-stack rule as
-  // the keydown path.
+  // 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 (isTopDrawer(drawerId)) {
-      onOpenChange(false);
+    if (shouldDismissOnCloseRequest()) {
+      handleDismiss();
     }
-  }, [onOpenChange, drawerId]);
+  }, [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).
@@ -337,38 +301,41 @@ export function Drawer({
     open: _open,
     ...safeProps
   } = props;
-  return /*#__PURE__*/_jsxs("dialog", {
-    ref: mergeRefs(ref, dialogRef),
+  return /*#__PURE__*/_jsx("dialog", {
+    ref: mergedDialogRef,
     ...mergeProps(themeProps('drawer', {
       side: anchoredSide
-    }), stylex.props(styles.dialog, overlayPaddingReset.reset, sideStyle, dynamicStyles.inlineSize(widthValue, mobileWidth), isRendered && styles.rendered, isOpen && sideOpenStyle, hasScrim ? styles.scrim : dynamicStyles.stackZ(stackZ), hasScrim && isOpen && styles.scrimOpen, xstyle), className, style),
+    }), stylex.props(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,
     onClick: composeEventHandlers(onClickProp, handleClick),
-    onKeyDown: composeEventHandlers(onKeyDownProp, handleKeyDown),
+    onKeyDown: onKeyDownProp,
     onCancel: handleCancel,
-    children: [/*#__PURE__*/_jsx("div", {
-      tabIndex: -1,
-      ...{
-        className: "x1iyjqo2 x2lwn1j xh8yej3 x1odjw0f x6ikm8r xish69e xx69xxh x1a148e8 x1a2a7pz"
-      },
-      children: children
-    }), hasCloseButton && /*#__PURE__*/_jsx("div", {
-      ...{
-        className: "x10l6tqk xctzyg x72tfeb x78zum5 xzye2dw x1vjfegm"
-      },
-      children: /*#__PURE__*/_jsx(IconButton, {
-        icon: /*#__PURE__*/_jsx(Icon, {
-          icon: "close",
-          size: "sm",
-          color: "inherit"
-        }),
-        label: "Close",
-        variant: "ghost",
-        onClick: () => onOpenChange(false)
-      })
-    })]
+    children: /*#__PURE__*/_jsxs(LayerDepthProvider, {
+      children: [/*#__PURE__*/_jsx("div", {
+        tabIndex: -1,
+        ...{
+          className: "x1iyjqo2 x2lwn1j xh8yej3 x1odjw0f x6ikm8r xish69e xx69xxh x1a148e8 x1a2a7pz"
+        },
+        children: children
+      }), hasCloseButton && /*#__PURE__*/_jsx("div", {
+        ...{
+          className: "x10l6tqk xctzyg x72tfeb x78zum5 xzye2dw x1vjfegm"
+        },
+        children: /*#__PURE__*/_jsx(IconButton, {
+          icon: /*#__PURE__*/_jsx(Icon, {
+            icon: "close",
+            size: "sm",
+            color: "inherit"
+          }),
+          label: t('@astryx.dialog.close'),
+          variant: "ghost",
+          onClick: handleDismiss
+        })
+      })]
+    })
   });
 }
 Drawer.displayName = 'Drawer';

package/dist/Drawer/useDrawerDialogPresence.d.ts

@@ -1,18 +1,19 @@
 /**
  * @file useDrawerDialogPresence.ts
  * @input Controlled open state, modal mode, dialog ref, and rendered-state setter
- * @output Coordinates native dialog presence, exit timing, focus restoration, and unmount cleanup
+ * @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.
- * - The native <dialog> `open` state keeps it in the top layer.
+ * - 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 `dialog.close()` and the React hide must happen 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.
+ * 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/lab/src/Drawer/Drawer.test.tsx
@@ -28,12 +29,13 @@ type UseDrawerDialogPresenceOptions = {
 /**
  * Coordinates the native dialog and React-rendered presence for Drawer.
  *
- * Opening captures the trigger, opens the native dialog, and honours the
- * component's `data-autofocus` contract. Closing waits for the actual
- * transform transition (with a computed-duration backstop), then closes the
- * native dialog and synchronously hides the panel before the browser can paint
- * it outside the top layer. Unmount cleanup closes a dialog left open by React
- * Activity or a removed subtree.
+ * 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 {};

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

@@ -1 +1 @@
-{"version":3,"file":"useDrawerDialogPresence.d.ts","sourceRoot":"","sources":["../../src/Drawer/useDrawerDialogPresence.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAGL,KAAK,QAAQ,EACb,KAAK,SAAS,EACd,KAAK,cAAc,EACpB,MAAM,OAAO,CAAC;AAaf,KAAK,8BAA8B,GAAG;IACpC,SAAS,EAAE,SAAS,CAAC,iBAAiB,GAAG,IAAI,CAAC,CAAC;IAC/C,MAAM,EAAE,OAAO,CAAC;IAChB,OAAO,EAAE,OAAO,CAAC;IACjB,aAAa,EAAE,QAAQ,CAAC,cAAc,CAAC,OAAO,CAAC,CAAC,CAAC;CAClD,CAAC;AAEF;;;;;;;;;GASG;AACH,wBAAgB,uBAAuB,CAAC,EACtC,SAAS,EACT,MAAM,EACN,OAAO,EACP,aAAa,GACd,EAAE,8BAA8B,GAAG,IAAI,CA6DvC"}
+{"version":3,"file":"useDrawerDialogPresence.d.ts","sourceRoot":"","sources":["../../src/Drawer/useDrawerDialogPresence.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,EAGL,KAAK,QAAQ,EACb,KAAK,SAAS,EACd,KAAK,cAAc,EACpB,MAAM,OAAO,CAAC;AAaf,KAAK,8BAA8B,GAAG;IACpC,SAAS,EAAE,SAAS,CAAC,iBAAiB,GAAG,IAAI,CAAC,CAAC;IAC/C,MAAM,EAAE,OAAO,CAAC;IAChB,OAAO,EAAE,OAAO,CAAC;IACjB,aAAa,EAAE,QAAQ,CAAC,cAAc,CAAC,OAAO,CAAC,CAAC,CAAC;CAClD,CAAC;AAuDF;;;;;;;;;;GAUG;AACH,wBAAgB,uBAAuB,CAAC,EACtC,SAAS,EACT,MAAM,EACN,OAAO,EACP,aAAa,GACd,EAAE,8BAA8B,GAAG,IAAI,CAmEvC"}

package/dist/Drawer/useDrawerDialogPresence.js

@@ -5,18 +5,19 @@
 /**
  * @file useDrawerDialogPresence.ts
  * @input Controlled open state, modal mode, dialog ref, and rendered-state setter
- * @output Coordinates native dialog presence, exit timing, focus restoration, and unmount cleanup
+ * @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.
- * - The native <dialog> `open` state keeps it in the top layer.
+ * - 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 `dialog.close()` and the React hide must happen 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.
+ * 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/lab/src/Drawer/Drawer.test.tsx
@@ -34,15 +35,63 @@ const EXIT_BACKSTOP_BUFFER_MS = 50;
  * an assumption about the consumer's theme.
  */
 const EXIT_FALLBACK_MS = 250;
+function isPopoverOpen(dialog) {
+  try {
+    return dialog.matches(':popover-open');
+  } catch {
+    // jsdom and pre-Popover browsers do not recognize :popover-open.
+    return false;
+  }
+}
+function isDrawerHostOpen(dialog, isModal) {
+  return isModal ? dialog.open : isPopoverOpen(dialog) || dialog.open;
+}
+function showDrawerHost(dialog, isModal) {
+  if (isModal) {
+    dialog.showModal();
+  } else if (typeof dialog.showPopover === 'function') {
+    dialog.showPopover();
+  } else {
+    // Reduced fallback for browsers below the Popover API support floor.
+    dialog.show();
+  }
+}
+function dispatchDialogClose(dialog) {
+  const EventConstructor = dialog.ownerDocument.defaultView?.Event ?? Event;
+  dialog.dispatchEvent(new EventConstructor('close'));
+}
+
+/**
+ * Leaves the active native host. Returns whether the caller owes a synthetic
+ * `close` dispatch: `dialog.close()` used to power the non-modal path, and
+ * consumers observe its native `close` event through refs/onClose. Popover
+ * dismissal has no equivalent event, so that public DOM contract is preserved
+ * explicitly — but by the caller, not here. Native `close` is queued as a
+ * task, so a consumer's listener always ran after this hook's own focus
+ * restore; the synthetic event must keep that ordering (and fire exactly once
+ * per exit, including the unmount path).
+ */
+function hideDrawerHost(dialog, isModal) {
+  if (!isModal && typeof dialog.hidePopover === 'function') {
+    dialog.hidePopover();
+    return true;
+  }
+  if (dialog.open) {
+    dialog.close();
+  }
+  return false;
+}
+
 /**
  * Coordinates the native dialog and React-rendered presence for Drawer.
  *
- * Opening captures the trigger, opens the native dialog, and honours the
- * component's `data-autofocus` contract. Closing waits for the actual
- * transform transition (with a computed-duration backstop), then closes the
- * native dialog and synchronously hides the panel before the browser can paint
- * it outside the top layer. Unmount cleanup closes a dialog left open by React
- * Activity or a removed subtree.
+ * 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 function useDrawerDialogPresence({
   dialogRef,
@@ -58,25 +107,21 @@ export function useDrawerDialogPresence({
       return;
     }
     if (isOpen) {
-      if (!dialog.open) {
+      if (!isDrawerHostOpen(dialog, isModal)) {
         triggerElementRef.current = document.activeElement;
-        if (isModal) {
-          dialog.showModal();
-        } else {
-          dialog.show();
-        }
-        // React's autoFocus calls .focus() during commit, before the dialog is
-        // shown, so it silently fails — honour data-autofocus instead (same
+        showDrawerHost(dialog, isModal);
+        // React's autoFocus calls .focus() during commit, before the native host
+        // is visible, so it silently fails — honour data-autofocus instead (same
         // contract as Dialog).
         dialog.querySelector('[data-autofocus]')?.focus();
       }
       return;
     }
-    if (!dialog.open) {
+    if (!isDrawerHostOpen(dialog, isModal)) {
       return;
     }
     return waitForDrawerExit(dialog, () => {
-      dialog.close();
+      const owesCloseEvent = hideDrawerHost(dialog, isModal);
       // flushSync, not a plain setState: React's default scheduling can land
       // the commit after the next paint, and that one frame is exactly the
       // bug — the panel paints outside the top layer. Both happen in this
@@ -84,27 +129,37 @@ export function useDrawerDialogPresence({
       flushSync(() => {
         setIsRendered(false);
       });
-      // Return focus after close(): a modal dialog makes the rest of the
-      // document inert, so focusing the trigger before close() silently fails.
+      // Return focus after leaving the native host: a modal dialog makes the
+      // rest of the document inert, so focusing earlier silently fails.
       triggerElementRef.current?.focus();
       triggerElementRef.current = null;
+      // The synthetic popover close fires after the focus restore above,
+      // mirroring the task-queued native event: a consumer close listener
+      // that retargets focus (master-detail row switching) gets the last word.
+      if (owesCloseEvent) {
+        dispatchDialogClose(dialog);
+      }
     });
   }, [dialogRef, isModal, isOpen, setIsRendered]);
 
-  // Close the native dialog on unmount if it is still open. When the drawer is
-  // mounted inside an <Activity> that flips to mode="hidden", React runs effect
-  // cleanups (with stale isOpen) instead of re-running the effect with
-  // isOpen=false. Leaving `open` set would skip showModal() on the next open.
+  // Leave the active native host on unmount. When the drawer is mounted inside
+  // an <Activity> that flips to mode="hidden", React runs effect cleanups (with
+  // stale isOpen) instead of re-running the effect with isOpen=false. Leaving
+  // the host active would strand the top-layer surface and skip the next open.
   // This is deliberately separate from the open/close effect: putting it in
   // that cleanup would cut off every delayed slide-out.
   useEffect(() => {
     const dialog = dialogRef.current;
     return () => {
-      if (dialog?.open) {
-        dialog.close();
+      if (dialog && isDrawerHostOpen(dialog, isModal)) {
+        if (hideDrawerHost(dialog, isModal)) {
+          // No focus restore on this path — the drawer is being torn down, so
+          // the owed synthetic close fires immediately (still exactly once).
+          dispatchDialogClose(dialog);
+        }
       }
     };
-  }, [dialogRef]);
+  }, [dialogRef, isModal]);
 }
 
 /**