@astryxdesign/core 0.4.4 → 0.4.5-canary.1fdecb1

package/src/Markdown/Markdown.doc.mjs

@@ -169,6 +169,7 @@ export const docs = {
       { guidance: true, description: 'Set headingLevelStart to match the page hierarchy, e.g. start at 3 if the markdown sits inside an h2 section.' },
       { guidance: true, description: 'Use contentWidth to keep prose at a readable line length in wide layouts.' },
       { guidance: true, description: 'Use inlinePlugins for custom shorthand patterns like issue refs, diff refs, and mentions instead of preprocessing the markdown string.' },
+      { guidance: true, description: 'Pair with Outline and useOutlineFromMarkdown for section navigation: headings render generated id attributes that match the outline item ids, so hash links scroll to their target.' },
       { guidance: false, description: 'Use Markdown for hand-authored layouts; use Text and Heading directly when you control the content.' },
     ],
   },
@@ -381,6 +382,7 @@ export const docsZh = {
       { guidance: true, description: 'Set headingLevelStart to match the page hierarchy, e.g. start at 3 if the markdown sits inside an h2 section.' },
       { guidance: true, description: 'Use contentWidth to keep prose at a readable line length in wide layouts.' },
       { guidance: true, description: 'Use inlinePlugins for custom shorthand patterns like issue refs, diff refs, and mentions instead of preprocessing the markdown string.' },
+      { guidance: true, description: 'Pair with Outline and useOutlineFromMarkdown for section navigation: headings render generated id attributes that match the outline item ids, so hash links scroll to their target.' },
       { guidance: false, description: 'Use Markdown for hand-authored layouts; use Text and Heading directly when you control the content.' },
     ],
   },
@@ -396,6 +398,7 @@ export const docsDense = {
       { guidance: true, description: 'Set headingLevelStart to match the page hierarchy, e.g. start at 3 if the markdown sits inside an h2 section.' },
       { guidance: true, description: 'Use contentWidth to keep prose at a readable line length in wide layouts.' },
       { guidance: true, description: 'Use inlinePlugins for custom shorthand patterns (issue refs, diff refs, mentions) instead of preprocessing the markdown string.' },
+      { guidance: true, description: 'Headings render id attributes matching useOutlineFromMarkdown ids; pair with Outline for hash navigation.' },
       { guidance: false, description: 'Use Markdown for hand-authored layouts; use Text and Heading directly when you control the content.' },
     ],
   },

package/src/Markdown/Markdown.test.tsx

@@ -5,6 +5,7 @@ import {render, screen, fireEvent} from '@testing-library/react';
 import type {ReactNode} from 'react';
 import {Markdown} from './Markdown';
 import type {MarkdownInlinePlugin} from './Markdown';
+import {parseOutlineFromMarkdown} from '../Outline/parseOutlineFromMarkdown';
 
 describe('Markdown', () => {
   it('renders with role="document"', () => {
@@ -23,6 +24,83 @@ describe('Markdown', () => {
     expect(screen.getByText('Heading 2').tagName).toBe('H2');
   });
 
+  describe('heading ids', () => {
+    // Outline's documented contract: an outline item id "should match the
+    // target heading element id". Markdown renders the ids that
+    // useOutlineFromMarkdown derives, so hash navigation resolves.
+    it('renders generated id attributes on headings', () => {
+      render(<Markdown>{'# Overview\n\ncontent\n\n# Installation'}</Markdown>);
+      expect(screen.getByText('Overview')).toHaveAttribute('id', 'overview');
+      expect(screen.getByText('Installation')).toHaveAttribute(
+        'id',
+        'installation',
+      );
+    });
+
+    it('disambiguates duplicate headings with numeric suffixes', () => {
+      render(<Markdown>{'# Setup\n\n# Setup\n\n# Setup'}</Markdown>);
+      const ids = screen.getAllByText('Setup').map(el => el.id);
+      expect(ids).toEqual(['setup', 'setup-1', 'setup-2']);
+    });
+
+    it('renders ids matching parseOutlineFromMarkdown for the same source', () => {
+      // Parity invariant: every id the outline derives must resolve to a
+      // rendered heading with that exact id — including slugified formatting,
+      // duplicate numbering, the empty-slug fallback, and code-fence decoys.
+      const source = [
+        '# **Bold** and _italic_ text',
+        '## Setup',
+        '## Setup',
+        '### !!!',
+        '```',
+        '# not a heading',
+        '```',
+        '## The `useState` hook',
+      ].join('\n\n');
+      const {container} = render(<Markdown>{source}</Markdown>);
+      const outline = parseOutlineFromMarkdown(source);
+      expect(outline.length).toBe(5);
+      for (const item of outline) {
+        const target = container.querySelector(`[id="${item.id}"]`);
+        expect(target, `no rendered heading with id "${item.id}"`).not.toBe(
+          null,
+        );
+        expect(target!.tagName).toMatch(/^H[1-6]$/);
+        expect(target!.textContent?.trim()).toBe(item.label);
+      }
+    });
+
+    it('passes the generated id to a custom heading component', () => {
+      const received: (string | undefined)[] = [];
+      render(
+        <Markdown
+          components={{
+            heading: ({children, id}: {children: ReactNode; id?: string}) => {
+              received.push(id);
+              return <h2 id={id}>{children}</h2>;
+            },
+          }}>
+          {'# Overview\n\n# Overview'}
+        </Markdown>,
+      );
+      expect(received).toEqual(['overview', 'overview-1']);
+    });
+
+    it('does not assign ids to headings nested inside blockquotes', () => {
+      // parseOutlineFromMarkdown only lists top-level headings. If nested
+      // headings consumed slugs too, duplicate numbering would drift and
+      // outline links would land on the wrong heading.
+      const source = '> # Quoted\n\n# Quoted';
+      const {container} = render(<Markdown>{source}</Markdown>);
+      const outline = parseOutlineFromMarkdown(source);
+      expect(outline.map(i => i.id)).toEqual(['quoted']);
+      const [nested, topLevel] = screen.getAllByText('Quoted');
+      expect(container.querySelector('blockquote')).toContainElement(nested);
+      expect(nested).not.toHaveAttribute('id');
+      expect(topLevel).toHaveAttribute('id', 'quoted');
+    });
+  });
+
   it('renders paragraphs as block <div> (never <p>) for composition safety', () => {
     render(<Markdown>{'Hello world'}</Markdown>);
     // Markdown paragraphs render as <div> so block-level inline content

package/src/Markdown/Markdown.tsx

@@ -53,6 +53,9 @@ import {
   parseMarkdownIncremental,
   createIncrementalState,
   trimStreamingArtifacts,
+  inlineText,
+  slugify,
+  uniqueSlug,
 } from './parser';
 import type {BlockNode, InlineNode, IncrementalState} from './parser';
 import {themeProps} from '../utils/themeProps';
@@ -108,6 +111,14 @@ export interface MarkdownComponents {
   heading?: React.ComponentType<{
     level: 1 | 2 | 3 | 4 | 5 | 6;
     children: React.ReactNode;
+    /**
+     * Generated slug for this heading, matching the ids produced by
+     * useOutlineFromMarkdown / parseOutlineFromMarkdown. Render it as the
+     * element's `id` to keep Outline hash navigation working. Undefined for
+     * headings nested inside blockquotes or list items (the outline only
+     * lists top-level headings).
+     */
+    id?: string;
   }>;
   paragraph?: React.ComponentType<{children: React.ReactNode}>;
   image?: React.ComponentType<{src: string; alt: string}>;
@@ -1045,6 +1056,7 @@ function renderBlock(
   inlinePlugins: MarkdownInlinePlugin[] | undefined,
   components: Partial<MarkdownComponents> | undefined,
   t: TranslatorFn,
+  headingIdMap?: ReadonlyMap<BlockNode, string>,
 ): SyncReactNode {
   const blockAlignMargin = BLOCK_ALIGN_MARGIN[contentAlign];
   const blockAlignStyle =
@@ -1071,10 +1083,15 @@ function renderBlock(
           components,
         ),
       );
+      // Only top-level headings get an id: the map is built from the same
+      // traversal parseOutlineFromMarkdown uses (which skips headings nested
+      // in blockquotes / list items), so rendered ids and outline ids stay
+      // identical — including duplicate-slug numbering.
+      const headingId = headingIdMap?.get(node);
       const HeadingComp = components?.heading;
       if (HeadingComp) {
         return (
-          <HeadingComp key={index} level={level}>
+          <HeadingComp key={index} level={level} id={headingId}>
             {headingChildren}
           </HeadingComp>
         );
@@ -1083,6 +1100,7 @@ function renderBlock(
       return (
         <Tag
           key={index}
+          id={headingId}
           {...mergeProps(
             themeProps('markdown-heading', {density, level}),
             stylex.props(
@@ -1652,6 +1670,27 @@ export function Markdown({
     return parseMarkdown(children, parseOptions);
   }, [display, smoothedText, children, isStreaming, parseOptions]);
 
+  // Assign each top-level heading the slug that parseOutlineFromMarkdown
+  // would derive for it, so Outline hash links built from the same source
+  // always find a matching DOM id. Mirrors that function's traversal exactly:
+  // top-level blocks only, one shared duplicate-numbering sequence.
+  // NOTE: must stay above the `display === 'inline'` early return below —
+  // hooks cannot be conditional.
+  const headingIdMap = useMemo(() => {
+    if (display === 'inline' || blocks.length === 0) {
+      return undefined;
+    }
+    const map = new Map<BlockNode, string>();
+    const counts = new Map<string, number>();
+    for (const block of blocks) {
+      if (block.type === 'heading') {
+        const label = inlineText(block.children).trim();
+        map.set(block, uniqueSlug(slugify(label), counts));
+      }
+    }
+    return map;
+  }, [display, blocks]);
+
   const inlineNodes = useMemo(() => {
     if (display !== 'inline') {
       return [];
@@ -1765,6 +1804,7 @@ export function Markdown({
           inlinePlugins,
           components,
           t,
+          headingIdMap,
         ),
       )}
     </div>

package/src/Markdown/parser.ts

@@ -3,8 +3,10 @@
 /**
  * @file parser.ts
  * @input Markdown string
- * @output Array of MarkdownNode AST nodes
- * @position Core parser; consumed by Markdown.tsx
+ * @output Array of MarkdownNode AST nodes; heading slug helpers
+ *   (inlineText, slugify, uniqueSlug) shared by Markdown rendering and
+ *   Outline's parseOutlineFromMarkdown
+ * @position Core parser; consumed by Markdown.tsx and Outline
  */
 
 // ---------------------------------------------------------------------------
@@ -1815,3 +1817,59 @@ export function parseMarkdownIncremental(
 
   return mergeSettledBlocks(settledBlocks, unsettledBlocks);
 }
+
+// ---------------------------------------------------------------------------
+// Heading slugs
+// ---------------------------------------------------------------------------
+// Single source of truth for the heading id contract: Markdown renders these
+// slugs as `id` attributes on h1–h6, and Outline's parseOutlineFromMarkdown
+// derives its item ids from the same functions, so outline hash links always
+// resolve to a rendered heading by construction.
+
+/** Flatten inline nodes into their plain text content. */
+export function inlineText(nodes: InlineNode[]): string {
+  return nodes
+    .map(node => {
+      switch (node.type) {
+        case 'text':
+        case 'code':
+          return node.content;
+        case 'bold':
+        case 'italic':
+        case 'strikethrough':
+        case 'link':
+          return inlineText(node.children);
+        case 'image':
+          return node.alt;
+        case 'citation':
+        case 'break':
+          return '';
+      }
+    })
+    .join('');
+}
+
+/** Turn heading text into a URL-safe slug (lowercase, hyphen-separated). */
+export function slugify(value: string): string {
+  return value
+    .trim()
+    .toLowerCase()
+    .replace(/['"]/g, '')
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '');
+}
+
+/**
+ * Disambiguate repeated slugs with a numeric suffix (`setup`, `setup-1`, …).
+ * Empty slugs fall back to `section`. The caller owns the counts map so one
+ * document shares a single numbering sequence.
+ */
+export function uniqueSlug(
+  baseSlug: string,
+  counts: Map<string, number>,
+): string {
+  const fallbackSlug = baseSlug || 'section';
+  const count = counts.get(fallbackSlug) ?? 0;
+  counts.set(fallbackSlug, count + 1);
+  return count === 0 ? fallbackSlug : `${fallbackSlug}-${count}`;
+}

package/src/MobileNav/MobileNav.tsx

@@ -23,6 +23,7 @@
  *
  * SYNC: When modified, update these files to stay in sync:
  * - /packages/core/src/MobileNav/index.ts (exports if types change)
+ * - /packages/core/src/hooks/scrollbarGutter.ts (shared scroll-lock gutter)
  * - /packages/cli/assets/templates/blocks/components/MobileNav/ (showcase blocks)
  */
 
@@ -47,7 +48,12 @@ import {Button} from '../Button';
 import {Icon} from '../Icon';
 import {Heading} from '../Heading/Heading';
 import {useAppShellMobile} from '../AppShell/AppShellMobileContext';
+import {
+  holdScrollbarGutter,
+  type ScrollbarGutterHold,
+} from '../hooks/scrollbarGutter';
 import {mergeProps, mergeRefs, composeEventHandlers} from '../utils';
+import {overlayPaddingReset} from '../Layout/padding.stylex';
 import type {BaseProps} from '../BaseProps';
 import {themeProps} from '../utils/themeProps';
 import {useTranslator} from '../i18n';
@@ -70,7 +76,16 @@ const styles = stylex.create({
     width: '100vw',
     height: '100dvh',
     backgroundColor: 'transparent',
-    overflow: 'hidden',
+    // `clip`, not `hidden`. Both clip the off-screen drawer, but `hidden` makes
+    // the dialog a SCROLL CONTAINER, and a scroll container in the top layer
+    // whose subtree holds another scroller (the drawer's content area) does not
+    // paint a @starting-style entry transition for its descendants in Chromium:
+    // the transition ticks in the CSSOM while every painted frame shows the
+    // end value, so the drawer appears fully open. `clip` clips without
+    // creating a scroll container and the slide-in paints normally. The dialog
+    // never scrolls anyway — its child is absolutely positioned — so nothing
+    // depended on it being a scroll container.
+    overflow: 'clip',
     overscrollBehavior: 'contain',
     // Prevent touch gestures (pull-to-refresh, background scroll) passing through
     touchAction: 'none',
@@ -112,7 +127,14 @@ const styles = stylex.create({
   },
   backdropOpen: {
     '::backdrop': {
-      opacity: 1,
+      // The ::backdrop only exists once showModal() has put the dialog in the
+      // top layer, so its first rendered frame already has the open opacity.
+      // Without a starting style there is no earlier value to transition from
+      // and the scrim snaps in — @starting-style supplies that value.
+      opacity: {
+        default: 1,
+        '@starting-style': 0,
+      },
     },
   },
   drawer: {
@@ -143,7 +165,17 @@ const styles = stylex.create({
     },
   },
   drawerStartOpen: {
-    transform: 'translateX(0)',
+    // The whole dialog is `display: none` while closed, so the drawer is not
+    // rendered and the open transform is the only value it has ever had — a
+    // transition needs a previous value to run from. @starting-style gives the
+    // first rendered frame the off-screen transform, so the slide-in plays.
+    transform: {
+      default: 'translateX(0)',
+      '@starting-style': {
+        default: 'translateX(-100%)',
+        ':is([dir="rtl"] *)': 'translateX(100%)',
+      },
+    },
   },
   drawerEnd: {
     insetInlineEnd: 0,
@@ -156,7 +188,14 @@ const styles = stylex.create({
     },
   },
   drawerEndOpen: {
-    transform: 'translateX(0)',
+    // See drawerStartOpen — same starting style, mirrored edge.
+    transform: {
+      default: 'translateX(0)',
+      '@starting-style': {
+        default: 'translateX(100%)',
+        ':is([dir="rtl"] *)': 'translateX(-100%)',
+      },
+    },
   },
   header: {
     display: 'flex',
@@ -396,6 +435,15 @@ export function MobileNav({
 
   const dialogRef = useRef<HTMLDialogElement>(null);
   const closeTimeoutRef = useRef<ReturnType<typeof setTimeout>>(null);
+  const gutterRef = useRef<ScrollbarGutterHold | null>(null);
+
+  // Gives back the gutter held open in place of the hidden scrollbar.
+  const releaseGutter = useCallback(() => {
+    if (gutterRef.current) {
+      gutterRef.current.release();
+      gutterRef.current = null;
+    }
+  }, []);
   // Resolved side — computed from trigger position when side='auto'
   const [resolvedSide, setResolvedSide] = useState<'start' | 'end'>(
     side === 'auto' ? 'end' : side,
@@ -438,6 +486,10 @@ export function MobileNav({
     }
 
     if (isOpen) {
+      // Taken first: every mutation below is one that can hide the scrollbar,
+      // and the gutter has to be measured while it is still there.
+      gutterRef.current ??= holdScrollbarGutter(document.documentElement);
+
       if (!dialog.open) {
         dialog.showModal();
       }
@@ -445,8 +497,10 @@ export function MobileNav({
       // overflow: clip avoids creating a scroll container (unlike hidden),
       // so there's no scroll bounce and no need to save/restore scroll position.
       document.documentElement.style.overflow = 'clip';
+      gutterRef.current.settle();
     } else if (dialog.open) {
       document.documentElement.style.overflow = '';
+      releaseGutter();
 
       closeTimeoutRef.current = setTimeout(() => {
         dialog.close();
@@ -459,8 +513,9 @@ export function MobileNav({
         closeTimeoutRef.current = null;
       }
       document.documentElement.style.overflow = '';
+      releaseGutter();
     };
-  }, [isOpen]);
+  }, [isOpen, releaseGutter]);
 
   // Close the native dialog on unmount if it's still open. Inside AppShell the
   // drawer is mounted in an <Activity> that switches to mode="hidden" when the
@@ -512,6 +567,7 @@ export function MobileNav({
         themeProps('mobile-nav', {side: resolvedSide}),
         stylex.props(
           styles.dialog,
+          overlayPaddingReset.reset,
           isOpen && styles.open,
           styles.backdrop,
           isOpen && styles.backdropOpen,

package/src/MobileNav/MobileNavEntryAnimation.test.tsx

@@ -0,0 +1,212 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file MobileNavEntryAnimation.test.tsx
+ * @input Uses vitest, @testing-library/react, the TypeScript compiler API
+ * @output Regression tests keeping the drawer's slide-in and scrim fade-in
+ * @position Testing; guards the open path of MobileNav.tsx
+ *
+ * The drawer used to open with no animation at all while closing smoothly.
+ *
+ * The dialog is `display: none` until `isOpen`, so nothing inside it is
+ * rendered while closed. React commits the open `display` and the open
+ * `transform` in the same pass, which means the first frame the drawer is ever
+ * rendered in already holds the open transform: a transition has no earlier
+ * value to run from and the drawer simply appears. Closing looked fine because
+ * both values exist by then — `display` stays in the transition with
+ * `allow-discrete`, so the element is still rendered as the transform animates
+ * out.
+ *
+ * `@starting-style` supplies that before-change style — the off-screen
+ * transform for the drawer, transparent for the `::backdrop`.
+ *
+ * That alone is NOT enough, and the second half is the part that is easy to
+ * undo by accident. The dialog used `overflow: hidden`, which makes it a
+ * SCROLL CONTAINER. A scroll container in the top layer whose subtree holds
+ * another scroller — here the drawer's own content area — does not paint a
+ * `@starting-style` entry transition for its descendants in Chromium: the
+ * transition ticks in the CSSOM (`getComputedStyle` interpolates perfectly)
+ * while every painted frame shows the end value. Measuring the CSSOM says
+ * "animating"; the screen says "snapped". `overflow: clip` clips the
+ * off-screen drawer exactly as `hidden` did without creating a scroll
+ * container, and the slide-in paints.
+ *
+ * Reproduced minimally: dialog `overflow: hidden` + a scrolling child inside
+ * the drawer snaps; either one alone animates.
+ *
+ * Note on scope: jsdom has no top layer, no transitions, no `@starting-style`
+ * evaluation and no compositor, so none of this is observable here. These
+ * tests pin the three declarations the behaviour rests on. Verified in
+ * Chromium by screencasting painted frames (not computed style) at both edges,
+ * LTR and RTL: open and close each paint ~60-100 distinct intermediate
+ * positions, and reduced motion collapses to a 10ms transition.
+ */
+
+import {describe, it, expect, beforeAll} from 'vitest';
+import {render, screen} from '@testing-library/react';
+import {readFileSync} from 'node:fs';
+import {join} from 'node:path';
+import ts from 'typescript';
+import {MobileNav} from './MobileNav';
+
+// jsdom doesn't implement showModal/close on <dialog>, so we mock them
+beforeAll(() => {
+  HTMLDialogElement.prototype.showModal =
+    HTMLDialogElement.prototype.showModal ||
+    function (this: HTMLDialogElement) {
+      this.setAttribute('open', '');
+    };
+  HTMLDialogElement.prototype.close =
+    HTMLDialogElement.prototype.close ||
+    function (this: HTMLDialogElement) {
+      this.removeAttribute('open');
+    };
+});
+
+/** Every CSS rule StyleX has injected into the document, as text. */
+function injectedRules(): string[] {
+  const rules: string[] = [];
+  for (const sheet of Array.from(document.styleSheets)) {
+    let cssRules: CSSRuleList;
+    try {
+      cssRules = sheet.cssRules;
+    } catch {
+      continue;
+    }
+    for (const rule of Array.from(cssRules)) {
+      rules.push(rule.cssText);
+    }
+  }
+  return rules;
+}
+
+describe('MobileNav scrim fades in', () => {
+  it('gives the ::backdrop a transparent starting style', () => {
+    render(
+      <MobileNav isOpen onOpenChange={() => {}} data-testid="mobile-nav">
+        <span>Nav content</span>
+      </MobileNav>,
+    );
+
+    const classes = Array.from(screen.getByTestId('mobile-nav').classList);
+    // Without this the scrim is opaque in the frame the dialog enters the top
+    // layer, so it has nothing to fade from and snaps in behind the drawer.
+    const startingStyleForThisDialog = injectedRules().filter(
+      rule =>
+        rule.startsWith('@starting-style') &&
+        rule.includes('::backdrop') &&
+        classes.some(cls => rule.includes(`.${cls}`)),
+    );
+
+    expect(startingStyleForThisDialog).toHaveLength(1);
+    expect(startingStyleForThisDialog[0]).toMatch(/opacity:\s*0/);
+  });
+});
+
+// =============================================================================
+// Drawer slide-in — asserted on the style definition
+// =============================================================================
+
+const SOURCE = readFileSync(join(__dirname, 'MobileNav.tsx'), 'utf8');
+
+/**
+ * The object literal a `styles.<name>` key is defined with, e.g. the value of
+ * `drawerStartOpen` inside the file's `stylex.create({...})` call.
+ */
+function styleDefinition(name: string): ts.ObjectLiteralExpression {
+  const file = ts.createSourceFile(
+    'MobileNav.tsx',
+    SOURCE,
+    ts.ScriptTarget.Latest,
+    true,
+    ts.ScriptKind.TSX,
+  );
+
+  let found: ts.ObjectLiteralExpression | undefined;
+  const visit = (node: ts.Node) => {
+    if (
+      ts.isPropertyAssignment(node) &&
+      ts.isIdentifier(node.name) &&
+      node.name.text === name &&
+      ts.isObjectLiteralExpression(node.initializer)
+    ) {
+      found = node.initializer;
+    }
+    ts.forEachChild(node, visit);
+  };
+  visit(file);
+
+  if (!found) {
+    throw new Error(`No style named "${name}" in MobileNav.tsx`);
+  }
+  return found;
+}
+
+/** The value of one property of a style definition, as source text. */
+function property(style: ts.ObjectLiteralExpression, key: string): string {
+  const prop = style.properties.find(
+    p =>
+      ts.isPropertyAssignment(p) &&
+      (ts.isIdentifier(p.name) || ts.isStringLiteral(p.name)) &&
+      p.name.text === key,
+  );
+
+  if (!prop) {
+    throw new Error(`No "${key}" in ${style.getText().slice(0, 40)}…`);
+  }
+  return (prop as ts.PropertyAssignment).initializer.getText();
+}
+
+describe('MobileNav dialog does not become a scroll container', () => {
+  it('clips the off-screen drawer with `clip`, not `hidden`', () => {
+    // This is the half of the fix with no visible declaration of its own
+    // purpose: `hidden` looks like a pure clipping choice and clips exactly as
+    // well, so it is an easy "harmless tidy-up" to make. It is not harmless —
+    // it makes the dialog a scroll container, and the entry animation then
+    // ticks in the CSSOM without ever painting. See the file header.
+    expect(property(styleDefinition('dialog'), 'overflow')).toBe("'clip'");
+  });
+});
+
+describe.each([
+  {
+    name: 'drawerStartOpen',
+    offscreen: 'translateX(-100%)',
+    offscreenRtl: 'translateX(100%)',
+  },
+  {
+    name: 'drawerEndOpen',
+    offscreen: 'translateX(100%)',
+    offscreenRtl: 'translateX(-100%)',
+  },
+])('MobileNav drawer slides in ($name)', ({name, offscreen, offscreenRtl}) => {
+  it('opens to the on-screen transform', () => {
+    expect(property(styleDefinition(name), 'transform')).toContain(
+      'translateX(0)',
+    );
+  });
+
+  it('starts off-screen so the open transform has something to run from', () => {
+    const transform = property(styleDefinition(name), 'transform');
+
+    // The whole point: the first rendered frame needs the closed transform.
+    // Drop this and the drawer is simply there, fully open, on frame one —
+    // while the close still animates, which is what made the bug look like a
+    // missing entry animation rather than a missing starting style.
+    expect(transform).toContain('@starting-style');
+    expect(transform).toContain(offscreen);
+    // Mirrored, like the closed styles it has to match: sliding in from the
+    // wrong edge in RTL is as broken as not sliding at all.
+    expect(transform).toContain(offscreenRtl);
+  });
+
+  it('starts from the same edge the closed style parks it at', () => {
+    const closed = property(
+      styleDefinition(name.replace('Open', '')),
+      'transform',
+    );
+
+    expect(closed).toContain(offscreen);
+    expect(closed).toContain(offscreenRtl);
+  });
+});