@astryxdesign/core 0.4.7 → 0.5.0-canary.32a62fd

package/src/Markdown/parser.ts

@@ -24,7 +24,15 @@ export type InlineNode =
   | {type: 'citation'; sourceId: string}
   | {type: 'break'};
 
-export type BlockNode =
+export type BlockNode = BlockNodeKind & {
+  /**
+   * Where this block came from in the source, when parsed with the
+   * `sourceRanges` option. Top-level blocks only.
+   */
+  range?: SourceRange;
+};
+
+type BlockNodeKind =
   | {type: 'heading'; level: 1 | 2 | 3 | 4 | 5 | 6; children: InlineNode[]}
   | {type: 'paragraph'; children: InlineNode[]}
   | {type: 'codeblock'; language: string; content: string}
@@ -47,6 +55,17 @@ export type BlockNode =
   | {type: 'hr'}
   | {type: 'image'; src: string; alt: string};
 
+/**
+ * Where a block sits in the source string handed to `parseMarkdown`:
+ * `source.slice(start, end)` is the block, and `end` excludes the block's
+ * trailing blank lines.
+ *
+ * An object rather than a `[start, end]` tuple so a second way of addressing
+ * the same block — line numbers, once a consumer needs them — can be added as
+ * optional fields without breaking anyone.
+ */
+export type SourceRange = {readonly start: number; readonly end: number};
+
 export type ListItemNode = {checked?: boolean; children: BlockNode[]};
 export type TableCellNode = {children: InlineNode[]};
 export type TableAlignment = 'left' | 'center' | 'right' | null;
@@ -78,11 +97,28 @@ export type ParseOptions = {
    * suffix is not rejected (Astryx accepts any plausible TLD shape).
    */
   autolink?: 'gfm';
+  /**
+   * When true, every top-level block carries a `range` — the offsets it
+   * occupies in the string passed in. Lets a consumer that still holds the
+   * source slice the original markdown for a block instead of reconstructing
+   * it from the parsed node (or from the rendered DOM). Off by default: the
+   * field is absent unless asked for, so nothing that compares nodes changes.
+   *
+   * Blocks nested inside a list item or a blockquote do not carry one.
+   */
+  sourceRanges?: boolean;
 };
 
 type ResolvedOptions = {
   readonly sourceIds: ReadonlySet<string> | undefined;
   readonly autolink: 'gfm' | undefined;
+  readonly sourceRanges?: boolean;
+  /**
+   * Offset of this parse's input within the document the ranges are reported
+   * against. Internal only — the incremental parser parses slices and needs
+   * their blocks' ranges to come out absolute.
+   */
+  readonly baseOffset?: number;
   /**
    * Link reference definitions (`[label]: url`) collected from the whole
    * document, keyed by normalized label. Internal only — populated by the
@@ -109,7 +145,11 @@ function resolveOptions(
     return {sourceIds: arg as ReadonlySet<string>, autolink: undefined};
   }
   const opts = arg as ParseOptions;
-  return {sourceIds: opts.sourceIds, autolink: opts.autolink};
+  return {
+    sourceIds: opts.sourceIds,
+    autolink: opts.autolink,
+    sourceRanges: opts.sourceRanges,
+  };
 }
 
 // ---------------------------------------------------------------------------
@@ -174,6 +214,11 @@ function matchLinkDefinition(
 function extractLinkDefinitions(input: string): {
   defs: ReadonlyMap<string, string>;
   cleaned: string;
+  /**
+   * For each line of `cleaned`, the line of `input` it came from. Undefined
+   * when nothing was stripped and the two are the same text.
+   */
+  lineMap?: number[];
 } {
   const lines = input.split('\n');
   const defs = new Map<string, string>();
@@ -235,8 +280,14 @@ function extractLinkDefinitions(input: string): {
   if (defs.size === 0) {
     return {defs, cleaned: input};
   }
-  const cleaned = lines.filter((_, index) => keep[index]).join('\n');
-  return {defs, cleaned};
+  const lineMap: number[] = [];
+  for (let index = 0; index < lines.length; index++) {
+    if (keep[index]) {
+      lineMap.push(index);
+    }
+  }
+  const cleaned = lineMap.map(index => lines[index]).join('\n');
+  return {defs, cleaned, lineMap};
 }
 
 /** Order-independent signature of a link-definition set, for cache checks. */
@@ -1042,6 +1093,16 @@ function isTableSeparator(line: string): boolean {
   return nonEmpty.length > 0 && nonEmpty.every(cell => /^:?-+:?$/.test(cell));
 }
 
+/**
+ * The same options for content parsed out of an enclosing block. Ranges are a
+ * top-level contract: a list item's or a blockquote's children are parsed from
+ * text the caller reassembled (markers and `>` prefixes stripped), so an
+ * offset into it would not address the document.
+ */
+function nested(opts: ResolvedOptions): ResolvedOptions {
+  return opts.sourceRanges ? {...opts, sourceRanges: false} : opts;
+}
+
 /**
  * Returns true when a line could start a new block — used to stop paragraph
  * continuation.  Every regex here uses bounded or single-class quantifiers
@@ -1213,7 +1274,7 @@ function parseList(
       itemText += '\n' + deindented.join('\n');
     }
 
-    items.push({checked, children: parseMarkdownImpl(itemText, opts)});
+    items.push({checked, children: parseMarkdownImpl(itemText, nested(opts))});
 
     // CommonMark loose list: blank line(s) between items of the same style
     // and indent still form one list. Skip the blanks and continue if the
@@ -1274,7 +1335,7 @@ function parseMarkdownImpl(
   // definitions win on conflict, matching CommonMark's first-definition-wins
   // in document order; locally-nested definitions still resolve within this
   // parse.
-  const {defs, cleaned} = extractLinkDefinitions(input);
+  const {defs, cleaned, lineMap} = extractLinkDefinitions(input);
   const inherited = baseOpts.linkDefs;
   let linkDefs: ReadonlyMap<string, string> | undefined;
   if (defs.size === 0) {
@@ -1288,9 +1349,25 @@ function parseMarkdownImpl(
     linkDefs != null ? {...baseOpts, linkDefs} : baseOpts;
   const lines = cleaned.split('\n');
   const blocks: BlockNode[] = [];
+  // The line each block started on, parallel to `blocks`. Only collected when
+  // ranges were asked for; a block's end is resolved after the loop, since the
+  // branch that produced it has already moved `index` past whatever it read.
+  const blockStartLines: number[] | null = opts.sourceRanges ? [] : null;
+  // Set only by a block that consumes blank lines as content, where the
+  // positional end derivation would trim them away.
+  const blockEndLines: (number | undefined)[] | null = opts.sourceRanges
+    ? []
+    : null;
+  let blockStartLine = 0;
+  const pushBlock = (node: BlockNode, endLine?: number) => {
+    blocks.push(node);
+    blockStartLines?.push(blockStartLine);
+    blockEndLines?.push(endLine);
+  };
   let index = 0;
 
   while (index < lines.length) {
+    blockStartLine = index;
     const line = lines[index];
     if (line.trim() === '') {
       index++;
@@ -1309,14 +1386,20 @@ function parseMarkdownImpl(
         index++;
       }
       index++; // skip closing fence
-      blocks.push({type: 'codeblock', language, content: codeLines.join('\n')});
+      // A fence owns its blank lines, and an unterminated one (mid-stream)
+      // can end on them, so it states its own end rather than letting the
+      // positional derivation trim them off.
+      pushBlock(
+        {type: 'codeblock', language, content: codeLines.join('\n')},
+        Math.min(index, lines.length) - 1,
+      );
       continue;
     }
 
     // --- Heading ---
     const headingMatch = line.match(/^(#{1,6}) +(.*)/);
     if (headingMatch) {
-      blocks.push({
+      pushBlock({
         type: 'heading',
         level: headingMatch[1].length as 1 | 2 | 3 | 4 | 5 | 6,
         children: parseInlineEntry(headingMatch[2], opts),
@@ -1327,7 +1410,7 @@ function parseMarkdownImpl(
 
     // --- HR (must precede list check to handle `- - -`, `* * *`, `_ _ _`) ---
     if (isHorizontalRule(line)) {
-      blocks.push({type: 'hr'});
+      pushBlock({type: 'hr'});
       index++;
       continue;
     }
@@ -1335,7 +1418,7 @@ function parseMarkdownImpl(
     // --- Standalone image ---
     const imageMatch = line.match(/^!\[([^\]]*)\]\(([^)]+)\)/);
     if (imageMatch && line.trim() === imageMatch[0]) {
-      blocks.push({type: 'image', alt: imageMatch[1], src: imageMatch[2]});
+      pushBlock({type: 'image', alt: imageMatch[1], src: imageMatch[2]});
       index++;
       continue;
     }
@@ -1347,7 +1430,7 @@ function parseMarkdownImpl(
       isTableSeparator(lines[index + 1])
     ) {
       const tableResult = parseTable(lines, index, opts);
-      blocks.push(tableResult.node);
+      pushBlock(tableResult.node);
       index = tableResult.nextIndex;
       continue;
     }
@@ -1362,9 +1445,9 @@ function parseMarkdownImpl(
         quoteLines.push(lines[index].replace(/^> ?/, ''));
         index++;
       }
-      blocks.push({
+      pushBlock({
         type: 'blockquote',
-        children: parseMarkdownImpl(quoteLines.join('\n'), opts),
+        children: parseMarkdownImpl(quoteLines.join('\n'), nested(opts)),
       });
       continue;
     }
@@ -1372,7 +1455,7 @@ function parseMarkdownImpl(
     // --- Unordered list ---
     if (/^ {0,9}[-*+] /.test(line)) {
       const listResult = parseList(lines, index, false, opts);
-      blocks.push(listResult.node);
+      pushBlock(listResult.node);
       index = listResult.nextIndex;
       continue;
     }
@@ -1380,7 +1463,7 @@ function parseMarkdownImpl(
     // --- Ordered list ---
     if (/^ {0,9}\d+[.)] /.test(line)) {
       const listResult = parseList(lines, index, true, opts);
-      blocks.push(listResult.node);
+      pushBlock(listResult.node);
       index = listResult.nextIndex;
       continue;
     }
@@ -1396,14 +1479,76 @@ function parseMarkdownImpl(
       paraLines.push(lines[index]);
       index++;
     }
-    blocks.push({
+    pushBlock({
       type: 'paragraph',
       children: parseInlineEntry(paraLines.join('\n'), opts),
     });
   }
+  if (blockStartLines != null) {
+    stampSourceRanges(
+      blocks,
+      blockStartLines,
+      blockEndLines ?? [],
+      lines,
+      lineMap,
+      input,
+      opts,
+    );
+  }
   return blocks;
 }
 
+/**
+ * Give each block the offsets it occupies in the original input.
+ *
+ * Blocks are contiguous and in source order, so a block runs from its own
+ * first line to the line before the next block starts, minus the blank lines
+ * between them. Offsets are computed against the *input*, not the text the
+ * block loop saw: link reference definitions are stripped before parsing, and
+ * `lineMap` says which input line each surviving line came from.
+ */
+function stampSourceRanges(
+  blocks: BlockNode[],
+  blockStartLines: number[],
+  blockEndLines: (number | undefined)[],
+  lines: string[],
+  lineMap: number[] | undefined,
+  input: string,
+  opts: ResolvedOptions,
+): void {
+  const base = opts.baseOffset ?? 0;
+  // Offset of the first character of every line of the input.
+  const inputLineStarts = [0];
+  for (let i = 0; i < input.length; i++) {
+    if (input[i] === '\n') {
+      inputLineStarts.push(i + 1);
+    }
+  }
+  // Stripping removes whole lines and never edits one, so a parsed line's
+  // length is its input line's length.
+  const lineStart = (line: number): number =>
+    base + inputLineStarts[lineMap != null ? lineMap[line] : line];
+
+  for (let i = 0; i < blocks.length; i++) {
+    const startLine = blockStartLines[i];
+    let endLine = blockEndLines[i];
+    if (endLine == null) {
+      const nextStart =
+        i + 1 < blocks.length ? blockStartLines[i + 1] : lines.length;
+      endLine = nextStart - 1;
+      while (endLine > startLine && lines[endLine].trim() === '') {
+        endLine--;
+      }
+    }
+    // Exactly the block's own lines, verbatim — a CRLF document's trailing
+    // `\r` included, since the parser reads it as part of the line too and a
+    // range that dropped it would slice to something that re-parses
+    // differently.
+    const end = lineStart(endLine) + lines[endLine].length;
+    blocks[i] = {...blocks[i], range: {start: lineStart(startLine), end}};
+  }
+}
+
 // ---------------------------------------------------------------------------
 // Incremental parsing
 // ---------------------------------------------------------------------------
@@ -1420,6 +1565,12 @@ export interface IncrementalState {
    * with newly-arriving content.
    */
   autolink?: 'gfm';
+  /**
+   * The `sourceRanges` option the cached `settledBlocks` were parsed with.
+   * Flipping it invalidates them the same way `autolink` does: they either
+   * lack the ranges the caller now asks for, or carry ones it did not.
+   */
+  sourceRanges?: boolean;
   /**
    * Signature of the link reference definitions the cached `settledBlocks`
    * were parsed with. Definitions are document-global and typically arrive
@@ -1435,12 +1586,26 @@ export function createIncrementalState(): IncrementalState {
 
 /**
  * Find the line-index of the last blank line that is NOT inside a fenced code
- * block.  Returns -1 when nothing is settled (unclosed fence or no blank line).
+ * block, and report whether a fence is still open at the end of the input.
+ * Returns -1 when nothing is settled.
+ *
+ * This index must never move backwards as more of the document arrives. The
+ * caller's cache is keyed on the settled text staying a prefix of what it was,
+ * so a boundary that retracts by one line costs a re-parse of every block in
+ * the document. Two things used to retract it: a blank last line, which is
+ * just the newline the stream has written so far and stops being blank as soon
+ * as the next chunk appends to it; and an open fence, which used to collapse
+ * the boundary to -1 even though the content before the fence opened cannot be
+ * changed by anything typed inside it.
  */
-function findSettledBoundary(lines: string[]): number {
+function findSettledBoundary(lines: string[]): {
+  boundary: number;
+  openFence: boolean;
+} {
   let inFence = false;
   let fenceMarker = '';
   let lastBoundary = -1;
+  let boundaryBeforeFence = -1;
 
   for (let lineIndex = 0; lineIndex < lines.length; lineIndex++) {
     const line = lines[lineIndex];
@@ -1451,6 +1616,7 @@ function findSettledBoundary(lines: string[]): number {
       if (!inFence) {
         inFence = true;
         fenceMarker = fenceMatch[1];
+        boundaryBeforeFence = lastBoundary;
       } else if (
         fenceMatch[1].startsWith(fenceMarker[0]) &&
         fenceMatch[1].length >= fenceMarker.length
@@ -1460,12 +1626,20 @@ function findSettledBoundary(lines: string[]): number {
       }
     }
 
-    if (!inFence && line.trim() === '' && lineIndex > 0) {
+    if (
+      !inFence &&
+      line.trim() === '' &&
+      lineIndex > 0 &&
+      lineIndex < lines.length - 1
+    ) {
       lastBoundary = lineIndex;
     }
   }
 
-  return inFence ? -1 : lastBoundary;
+  return {
+    boundary: inFence ? boundaryBeforeFence : lastBoundary,
+    openFence: inFence,
+  };
 }
 
 /**
@@ -1689,6 +1863,15 @@ function trimUnsettledStructural(text: string): string {
   return lines.join('\n');
 }
 
+/**
+ * The same options, for parsing a slice that starts at `offset` of the
+ * document — so the slice's blocks report ranges into the whole document
+ * rather than into the slice.
+ */
+function atOffset(opts: ResolvedOptions, offset: number): ResolvedOptions {
+  return opts.sourceRanges ? {...opts, baseOffset: offset} : opts;
+}
+
 /**
  * Concatenate freshly-parsed delta blocks with previously-settled blocks,
  * merging adjacent same-style lists into a single loose list. The boundary
@@ -1718,6 +1901,11 @@ function mergeSettledBlocks(
       delimiter: prevLast.delimiter,
       loose: true,
       items: [...prevLast.items, ...deltaFirst.items],
+      // One list now, so one range: from where the first half started to
+      // where the second half ended.
+      ...(prevLast.range != null && deltaFirst.range != null
+        ? {range: {start: prevLast.range.start, end: deltaFirst.range.end}}
+        : null),
     };
     return [...prev.slice(0, -1), merged, ...delta.slice(1)];
   }
@@ -1740,15 +1928,19 @@ export function parseMarkdownIncremental(
   arg?: ReadonlySet<string> | ParseOptions,
 ): BlockNode[] {
   const opts = resolveOptions(arg);
-  // Invalidate cache when the autolink option flips — cached settled blocks
-  // were parsed with the previous setting and would otherwise be reused
-  // unchanged.
-  if (state.autolink !== opts.autolink) {
+  // Invalidate cache when the autolink or sourceRanges option flips — cached
+  // settled blocks were parsed with the previous setting and would otherwise
+  // be reused unchanged.
+  if (
+    state.autolink !== opts.autolink ||
+    Boolean(state.sourceRanges) !== Boolean(opts.sourceRanges)
+  ) {
     state.prevInput = '';
     state.settledText = '';
     state.settledBlocks = [];
     state.settledUpTo = 0;
     state.autolink = opts.autolink;
+    state.sourceRanges = opts.sourceRanges;
   }
   if (input === '') {
     state.prevInput = '';
@@ -1776,17 +1968,23 @@ export function parseMarkdownIncremental(
     linkDefs.size > 0 ? {...opts, linkDefs} : opts;
 
   const lines = input.split('\n');
-  const boundary = findSettledBoundary(lines);
+  const {boundary, openFence} = findSettledBoundary(lines);
 
   if (boundary < 0) {
-    // Inside an unclosed fence or no blank-line boundary — full re-parse
+    // Nothing settled yet — no blank line, or a fence opened before the first
+    // one — so there is no prefix to keep and the whole input is re-parsed.
     state.prevInput = input;
     return parseMarkdownImpl(input, parseOpts);
   }
 
   const settledText = lines.slice(0, boundary).join('\n');
   const unsettledRaw = lines.slice(boundary).join('\n').trim();
-  const unsettledText = trimUnsettledStructural(unsettledRaw);
+  // Structural trimming holds back lines that look like an incomplete list or
+  // table, which inside a fence is ordinary code: a TypeScript union or a `- `
+  // would disappear from the code block as it streams.
+  const unsettledText = openFence
+    ? unsettledRaw
+    : trimUnsettledStructural(unsettledRaw);
 
   let settledBlocks: BlockNode[];
 
@@ -1799,15 +1997,32 @@ export function parseMarkdownIncremental(
   ) {
     // Settled portion grew — parse only the new delta
     const delta = settledText.slice(state.settledText.length);
-    const deltaBlocks = parseMarkdownImpl(delta, parseOpts);
+    const deltaBlocks = parseMarkdownImpl(
+      delta,
+      atOffset(parseOpts, state.settledText.length),
+    );
     settledBlocks = mergeSettledBlocks(state.settledBlocks, deltaBlocks);
   } else {
     // Content before the boundary changed — full re-parse of settled portion
     settledBlocks = parseMarkdownImpl(settledText, parseOpts);
   }
 
+  // The unsettled tail is trimmed before parsing, so its offset in the
+  // document is where that trimmed text actually starts — not the boundary,
+  // which is a line index. If it somehow can't be located, parse it without
+  // ranges rather than report wrong ones. Only worth searching for when
+  // ranges were asked for: this runs on every streamed chunk.
+  const unsettledStart =
+    unsettledText && opts.sourceRanges
+      ? input.indexOf(unsettledText, settledText.length)
+      : -1;
   const unsettledBlocks = unsettledText
-    ? parseMarkdownImpl(unsettledText, parseOpts)
+    ? parseMarkdownImpl(
+        unsettledText,
+        unsettledStart >= 0
+          ? atOffset(parseOpts, unsettledStart)
+          : nested(parseOpts),
+      )
     : [];
 
   state.settledText = settledText;

package/src/MobileNav/MobileNav.tsx

@@ -19,10 +19,15 @@
  * - `::backdrop` pseudo-element
  * - Body scroll lock
  * - Focus trapping
- * - Escape key handling via `cancel` event
+ *
+ * Escape is owned by the shared dismissal stack (`useLayerDismissal`), so a
+ * drawer opened over another layer takes the press and nothing behind it
+ * closes. The native `cancel` event still handles the dismissals the browser
+ * starts itself, such as the Android back gesture.
  *
  * SYNC: When modified, update these files to stay in sync:
  * - /packages/core/src/MobileNav/index.ts (exports if types change)
+ * - /packages/core/src/Layer/useLayerDismissal.ts (dismissal stack)
  * - /packages/core/src/hooks/scrollbarGutter.ts (shared scroll-lock gutter)
  * - /packages/cli/assets/templates/blocks/components/MobileNav/ (showcase blocks)
  */
@@ -52,12 +57,15 @@ import {
   holdScrollbarGutter,
   type ScrollbarGutterHold,
 } from '../hooks/scrollbarGutter';
-import {mergeProps, mergeRefs, composeEventHandlers} from '../utils';
+import {mergeProps, composeEventHandlers} from '../utils';
 import {overlayPaddingReset} from '../Layout/padding.stylex';
+import {LayerDepthProvider} from '../Layer/LayerDepthContext';
+import {useLayerDismissal} from '../Layer/useLayerDismissal';
 import type {BaseProps} from '../BaseProps';
 import {themeProps} from '../utils/themeProps';
 import {useTranslator} from '../i18n';
 
+import {useMergedRefs} from '../hooks/useMergedRefs';
 // =============================================================================
 // Styles
 // =============================================================================
@@ -536,13 +544,28 @@ export function MobileNav({
     };
   }, []);
 
-  // Handle native cancel event (Escape key) — prevent default and route through onOpenChange
+  const {shouldDismissOnCloseRequest} = useLayerDismissal({
+    isActive: isOpen,
+    onDismiss: () => onOpenChange(false),
+  });
+
+  // The native `cancel` event is the browser's own close-watcher firing: an
+  // Android back gesture, or a close request the stack never saw a press for.
+  // Escape presses the stack owns never arrive here — it preventDefault()s
+  // those, which suppresses the close watcher.
+  //
+  // Always preventDefault so the browser cannot close a controlled <dialog>
+  // behind React's back, then answer with the stack's own rules: top-most
+  // only, and never while an IME composition is in progress.
   const handleCancel = useCallback(
     (event: React.SyntheticEvent<HTMLDialogElement>) => {
       event.preventDefault();
+      if (!shouldDismissOnCloseRequest()) {
+        return;
+      }
       onOpenChange(false);
     },
-    [onOpenChange],
+    [onOpenChange, shouldDismissOnCloseRequest],
   );
 
   // Handle clicks on the dialog backdrop area (outside the drawer)
@@ -561,7 +584,7 @@ export function MobileNav({
 
   return (
     <dialog
-      ref={mergeRefs(ref, dialogRef)}
+      ref={useMergedRefs(ref, dialogRef)}
       id={dialogId}
       {...mergeProps(
         themeProps('mobile-nav', {side: resolvedSide}),
@@ -586,38 +609,41 @@ export function MobileNav({
       }
       onClick={composeEventHandlers(onClickProp, handleDialogClick)}
       onCancel={handleCancel}>
-      {/* Drawer panel — tabIndex so showModal() focuses the drawer, not the close button */}
-      <div
-        tabIndex={-1}
-        {...stylex.props(
-          styles.drawer,
-          dynamicStyles.width(width),
-          isStart && styles.drawerStart,
-          isStart && isOpen && styles.drawerStartOpen,
-          !isStart && styles.drawerEnd,
-          !isStart && isOpen && styles.drawerEndOpen,
-        )}>
-        {/* Header — content + close button */}
-        <div {...stylex.props(styles.header, !header && styles.headerNoTitle)}>
-          {typeof header === 'string' ? (
-            <Heading level={2} xstyle={styles.headerText}>
-              {header}
-            </Heading>
-          ) : (
-            (header ?? null)
-          )}
-          <Button
-            variant="ghost"
-            label={t('@astryx.mobileNav.closeNavigation')}
-            icon={<Icon icon="close" color="inherit" />}
-            onClick={() => onOpenChange(false)}
-            isIconOnly
-          />
+      <LayerDepthProvider>
+        {/* Drawer panel — tabIndex so showModal() focuses the drawer, not the close button */}
+        <div
+          tabIndex={-1}
+          {...stylex.props(
+            styles.drawer,
+            dynamicStyles.width(width),
+            isStart && styles.drawerStart,
+            isStart && isOpen && styles.drawerStartOpen,
+            !isStart && styles.drawerEnd,
+            !isStart && isOpen && styles.drawerEndOpen,
+          )}>
+          {/* Header — content + close button */}
+          <div
+            {...stylex.props(styles.header, !header && styles.headerNoTitle)}>
+            {typeof header === 'string' ? (
+              <Heading level={2} xstyle={styles.headerText}>
+                {header}
+              </Heading>
+            ) : (
+              (header ?? null)
+            )}
+            <Button
+              variant="ghost"
+              label={t('@astryx.mobileNav.closeNavigation')}
+              icon={<Icon icon="close" color="inherit" />}
+              onClick={() => onOpenChange(false)}
+              isIconOnly
+            />
+          </div>
+
+          {/* Scrollable content */}
+          <div {...stylex.props(styles.content)}>{children}</div>
         </div>
-
-        {/* Scrollable content */}
-        <div {...stylex.props(styles.content)}>{children}</div>
-      </div>
+      </LayerDepthProvider>
     </dialog>
   );
 }

package/src/MoreMenu/MoreMenu.doc.mjs

@@ -46,7 +46,8 @@ export const docs = {
       type: 'boolean',
       description: 'Whether the menu trigger is disabled.',
       default: 'false',
-    },    {
+    },
+    {
       name: 'placement',
       type: "'above' | 'below' | 'start' | 'end'",
       description:
@@ -60,6 +61,11 @@ export const docs = {
         "Alignment along the placement axis. Use 'end' to align the menu with the trigger's trailing edge, which is usually what an overflow menu wants.",
       default: "'start'",
     },
+    {
+      name: 'onOpenChange',
+      type: '(isOpen: boolean) => void',
+      description: 'Callback fired when the menu opens or closes.',
+    },
     {
       name: 'xstyle',
       type: 'StyleXStyles',