@astryxdesign/core 0.4.4 → 0.4.5-canary.0472ec1

package/src/Layout/overlayPaddingReset.test.tsx

@@ -0,0 +1,222 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file overlayPaddingReset.test.tsx
+ * @input Uses vitest, @testing-library/react, overlay components from core
+ * @output Tests that overlay roots stop the container padding system at their
+ *   boundary, and that the public theme token still crosses it
+ * @position Layout tests; validates overlayPaddingReset in padding.stylex.ts
+ *
+ * The container padding system talks to descendants through INHERITED custom
+ * properties, but an overlay leaves its parent's visual box while staying a DOM
+ * descendant of it. Every overlay root therefore has to stop those values (see
+ * #5208: a Section in a 640px sheet rendered 672px wide).
+ *
+ * jsdom does no layout, so these assert on the custom properties themselves —
+ * the definitions the layout is computed from. The widths they stand in for are
+ * verified in a browser; see the PR description.
+ *
+ * SYNC: When an overlay is added, add it to OVERLAYS below.
+ */
+
+import {describe, it, expect, vi, beforeEach, afterEach} from 'vitest';
+import {readFileSync} from 'node:fs';
+import {join} from 'node:path';
+import {render, screen} from '@testing-library/react';
+import type {ReactNode} from 'react';
+import {Dialog} from '../Dialog';
+import {BottomSheet} from '../BottomSheet';
+import {MobileNav} from '../MobileNav';
+import {Lightbox} from '../Lightbox';
+import {Popover} from '../Popover';
+import {Section} from '../Section';
+
+// jsdom implements neither the <dialog> methods nor matchMedia.
+beforeEach(() => {
+  HTMLDialogElement.prototype.showModal = vi.fn(function (
+    this: HTMLDialogElement,
+  ) {
+    this.setAttribute('open', '');
+  });
+  HTMLDialogElement.prototype.show = vi.fn(function (this: HTMLDialogElement) {
+    this.setAttribute('open', '');
+  });
+  HTMLDialogElement.prototype.close = vi.fn(function (this: HTMLDialogElement) {
+    this.removeAttribute('open');
+  });
+  vi.stubGlobal(
+    'matchMedia',
+    vi.fn().mockReturnValue({
+      matches: false,
+      media: '',
+      onchange: null,
+      addEventListener: vi.fn(),
+      removeEventListener: vi.fn(),
+      addListener: vi.fn(),
+      removeListener: vi.fn(),
+      dispatchEvent: vi.fn(),
+    }),
+  );
+});
+
+afterEach(() => {
+  vi.unstubAllGlobals();
+});
+
+/**
+ * Values descendants SUBTRACT (bleed margins). The overlay root has no padding
+ * of its own to escape, so these must read a literal zero.
+ */
+const SUBTRACTED = [
+  '--container-padding-inline-start',
+  '--container-padding-inline-end',
+  '--container-padding-block-start',
+  '--container-padding-block-end',
+];
+
+/**
+ * Values descendants ADD. These must be guaranteed-invalid (`initial`) rather
+ * than zero, so readers fall through to their own default instead of losing
+ * their padding — a computed empty string is what `initial` looks like here.
+ */
+const CLEARED = [
+  '--layout-padding-outer-x',
+  '--layout-padding-outer-y',
+  '--layout-padding-inner-x',
+  '--layout-padding-inner-y',
+  '--_section-padding-propagated',
+];
+
+/** What a cleared custom property reads back as. See the assertion below. */
+const CLEARED_READBACK = ['', 'initial'];
+
+/** Each overlay, rendered open inside a page Section that leaks 40px. */
+const OVERLAYS: {
+  name: string;
+  render: (child: ReactNode) => ReactNode;
+  root: () => HTMLElement;
+}[] = [
+  {
+    name: 'Dialog',
+    render: child => (
+      <Dialog isOpen onOpenChange={() => {}}>
+        {child}
+      </Dialog>
+    ),
+    root: () => screen.getByRole('dialog'),
+  },
+  {
+    name: 'BottomSheet',
+    render: child => (
+      <BottomSheet isOpen onOpenChange={() => {}} label="S">
+        {child}
+      </BottomSheet>
+    ),
+    root: () =>
+      document.querySelector<HTMLElement>(
+        '.astryx-bottom-sheet',
+      ) as HTMLElement,
+  },
+  {
+    name: 'MobileNav',
+    render: child => (
+      <MobileNav isOpen onOpenChange={() => {}} label="N">
+        {child}
+      </MobileNav>
+    ),
+    root: () => screen.getByRole('dialog'),
+  },
+  {
+    name: 'Lightbox',
+    render: () => (
+      <Lightbox
+        isOpen
+        onOpenChange={() => {}}
+        media={{src: 'a.png', alt: 'a'}}
+      />
+    ),
+    root: () => screen.getByRole('dialog'),
+  },
+  {
+    name: 'Popover (useLayer surface)',
+    render: child => (
+      <Popover isOpen onOpenChange={() => {}} label="P" content={child}>
+        <button type="button">t</button>
+      </Popover>
+    ),
+    root: () => document.querySelector<HTMLElement>('[popover]') as HTMLElement,
+  },
+];
+
+describe('overlayPaddingReset', () => {
+  describe.each(OVERLAYS)('$name', ({render: renderOverlay, root}) => {
+    it('zeroes the values descendants subtract', () => {
+      render(<Section padding={10}>{renderOverlay(<div>c</div>)}</Section>);
+      const computed = getComputedStyle(root());
+      for (const name of SUBTRACTED) {
+        expect(computed.getPropertyValue(name), name).toBe('0px');
+      }
+    });
+
+    it('clears the values descendants add, so they fall to their default', () => {
+      render(<Section padding={10}>{renderOverlay(<div>c</div>)}</Section>);
+      const computed = getComputedStyle(root());
+      for (const name of CLEARED) {
+        // A browser resolves `initial` on a custom property to the
+        // guaranteed-invalid value and reports '' here; jsdom does not
+        // implement that and echoes the keyword. Either proves the
+        // declaration landed — and neither is the leaked '40px'.
+        expect(CLEARED_READBACK, name).toContain(
+          computed.getPropertyValue(name),
+        );
+      }
+    });
+  });
+
+  it('does not clear the public theme token', () => {
+    // The reset clears the PRIVATE propagation var only. The public
+    // `--astryx-section-padding` is theme surface, set once at the theme root,
+    // so it has to keep reaching inside every overlay — clearing it would
+    // blank a theme's section padding in every dialog. That is the whole
+    // reason the two names were split, and it is the mistake a later
+    // "simplification" would most plausibly make.
+    //
+    // jsdom does not inherit custom properties, so the cascade cannot show
+    // this; assert it where it is decided instead. (Verified in a browser: a
+    // theme's 20px still reaches a Section inside a Dialog nested under a
+    // 40px page Section.)
+    const source = readFileSync(join(__dirname, 'padding.stylex.ts'), 'utf8');
+    const reset = source.slice(
+      source.indexOf('export const overlayPaddingReset'),
+    );
+    expect(reset).toContain("'--_section-padding-propagated': 'initial'");
+    expect(reset).not.toContain('--astryx-section-padding');
+  });
+
+  it("stops an ancestor Section's propagated padding at the boundary", () => {
+    // The page Section propagates 40px. Without the reset it would reach the
+    // Section inside the overlay, which would pad itself 40px instead of the
+    // theme default — the second half of #5208.
+    render(
+      <Section padding={10}>
+        <Dialog isOpen onOpenChange={() => {}}>
+          <div data-testid="content">c</div>
+        </Dialog>
+      </Section>,
+    );
+    const dialog = screen.getByRole('dialog');
+    expect(CLEARED_READBACK).toContain(
+      getComputedStyle(dialog).getPropertyValue(
+        '--_section-padding-propagated',
+      ),
+    );
+    // ...while the page Section outside the overlay still propagates it.
+    // (jsdom does not resolve the token reference to its 40px value.)
+    const pageSection = document.querySelector<HTMLElement>('.astryx-section');
+    expect(
+      getComputedStyle(pageSection as HTMLElement).getPropertyValue(
+        '--_section-padding-propagated',
+      ),
+    ).toBe('var(--spacing-10)');
+  });
+});

package/src/Layout/padding.stylex.ts

@@ -326,21 +326,201 @@ export const paddingBlockStyles = stylex.create({
 });
 
 /**
- * Propagation styles for --astryx-section-padding.
+ * Inline-start-only padding override styles.
+ * Use when a component needs to override the inline-start edge independently
+ * of inline-end. Logical, so it follows the writing direction (left in LTR,
+ * right in RTL).
+ */
+export const paddingInlineStartStyles = stylex.create({
+  0: {paddingInlineStart: spacingVars['--spacing-0']},
+  0.5: {paddingInlineStart: spacingVars['--spacing-0-5']},
+  1: {paddingInlineStart: spacingVars['--spacing-1']},
+  1.5: {paddingInlineStart: spacingVars['--spacing-1-5']},
+  2: {paddingInlineStart: spacingVars['--spacing-2']},
+  3: {paddingInlineStart: spacingVars['--spacing-3']},
+  4: {paddingInlineStart: spacingVars['--spacing-4']},
+  5: {paddingInlineStart: spacingVars['--spacing-5']},
+  6: {paddingInlineStart: spacingVars['--spacing-6']},
+  8: {paddingInlineStart: spacingVars['--spacing-8']},
+  10: {paddingInlineStart: spacingVars['--spacing-10']},
+});
+
+/**
+ * Inline-end-only padding override styles.
+ * The inline-end counterpart of paddingInlineStartStyles.
+ */
+export const paddingInlineEndStyles = stylex.create({
+  0: {paddingInlineEnd: spacingVars['--spacing-0']},
+  0.5: {paddingInlineEnd: spacingVars['--spacing-0-5']},
+  1: {paddingInlineEnd: spacingVars['--spacing-1']},
+  1.5: {paddingInlineEnd: spacingVars['--spacing-1-5']},
+  2: {paddingInlineEnd: spacingVars['--spacing-2']},
+  3: {paddingInlineEnd: spacingVars['--spacing-3']},
+  4: {paddingInlineEnd: spacingVars['--spacing-4']},
+  5: {paddingInlineEnd: spacingVars['--spacing-5']},
+  6: {paddingInlineEnd: spacingVars['--spacing-6']},
+  8: {paddingInlineEnd: spacingVars['--spacing-8']},
+  10: {paddingInlineEnd: spacingVars['--spacing-10']},
+});
+
+/**
+ * Container padding inline-start CSS variable style, set independently of
+ * inline-end so a per-edge override keeps edge-compensating children (Card,
+ * Divider, a nested Section) compensating against the padding actually
+ * applied on that edge.
+ */
+export const containerPaddingInlineStartVarStyles = stylex.create({
+  0: {'--container-padding-inline-start': spacingVars['--spacing-0']},
+  0.5: {'--container-padding-inline-start': spacingVars['--spacing-0-5']},
+  1: {'--container-padding-inline-start': spacingVars['--spacing-1']},
+  1.5: {'--container-padding-inline-start': spacingVars['--spacing-1-5']},
+  2: {'--container-padding-inline-start': spacingVars['--spacing-2']},
+  3: {'--container-padding-inline-start': spacingVars['--spacing-3']},
+  4: {'--container-padding-inline-start': spacingVars['--spacing-4']},
+  5: {'--container-padding-inline-start': spacingVars['--spacing-5']},
+  6: {'--container-padding-inline-start': spacingVars['--spacing-6']},
+  8: {'--container-padding-inline-start': spacingVars['--spacing-8']},
+  10: {'--container-padding-inline-start': spacingVars['--spacing-10']},
+});
+
+/**
+ * Container padding inline-end CSS variable style, the counterpart of
+ * containerPaddingInlineStartVarStyles.
+ */
+export const containerPaddingInlineEndVarStyles = stylex.create({
+  0: {'--container-padding-inline-end': spacingVars['--spacing-0']},
+  0.5: {'--container-padding-inline-end': spacingVars['--spacing-0-5']},
+  1: {'--container-padding-inline-end': spacingVars['--spacing-1']},
+  1.5: {'--container-padding-inline-end': spacingVars['--spacing-1-5']},
+  2: {'--container-padding-inline-end': spacingVars['--spacing-2']},
+  3: {'--container-padding-inline-end': spacingVars['--spacing-3']},
+  4: {'--container-padding-inline-end': spacingVars['--spacing-4']},
+  5: {'--container-padding-inline-end': spacingVars['--spacing-5']},
+  6: {'--container-padding-inline-end': spacingVars['--spacing-6']},
+  8: {'--container-padding-inline-end': spacingVars['--spacing-8']},
+  10: {'--container-padding-inline-end': spacingVars['--spacing-10']},
+});
+
+/**
+ * Block-start-only padding override styles.
+ * Use when a component needs to override the block-start (top) edge
+ * independently of block-end — e.g. a section that sits under a sticky
+ * header and needs less padding above than below.
+ */
+export const paddingBlockStartStyles = stylex.create({
+  0: {paddingBlockStart: spacingVars['--spacing-0']},
+  0.5: {paddingBlockStart: spacingVars['--spacing-0-5']},
+  1: {paddingBlockStart: spacingVars['--spacing-1']},
+  1.5: {paddingBlockStart: spacingVars['--spacing-1-5']},
+  2: {paddingBlockStart: spacingVars['--spacing-2']},
+  3: {paddingBlockStart: spacingVars['--spacing-3']},
+  4: {paddingBlockStart: spacingVars['--spacing-4']},
+  5: {paddingBlockStart: spacingVars['--spacing-5']},
+  6: {paddingBlockStart: spacingVars['--spacing-6']},
+  8: {paddingBlockStart: spacingVars['--spacing-8']},
+  10: {paddingBlockStart: spacingVars['--spacing-10']},
+});
+
+/**
+ * Block-end-only padding override styles.
+ * The block-end counterpart of paddingBlockStartStyles.
+ */
+export const paddingBlockEndStyles = stylex.create({
+  0: {paddingBlockEnd: spacingVars['--spacing-0']},
+  0.5: {paddingBlockEnd: spacingVars['--spacing-0-5']},
+  1: {paddingBlockEnd: spacingVars['--spacing-1']},
+  1.5: {paddingBlockEnd: spacingVars['--spacing-1-5']},
+  2: {paddingBlockEnd: spacingVars['--spacing-2']},
+  3: {paddingBlockEnd: spacingVars['--spacing-3']},
+  4: {paddingBlockEnd: spacingVars['--spacing-4']},
+  5: {paddingBlockEnd: spacingVars['--spacing-5']},
+  6: {paddingBlockEnd: spacingVars['--spacing-6']},
+  8: {paddingBlockEnd: spacingVars['--spacing-8']},
+  10: {paddingBlockEnd: spacingVars['--spacing-10']},
+});
+
+/**
+ * Propagation styles for `--_section-padding-propagated`.
  * When a parent section sets explicit padding, this propagates the value
  * through the CSS custom property cascade so nested sections that use
  * useThemeDefault inherit the parent's padding instead of the theme default.
+ *
+ * This is deliberately NOT the public `--astryx-section-padding` token. The
+ * two carry different authority: the public token is the THEME's section
+ * padding, set once at the theme root, while this one is one ancestor
+ * Section's padding, propagated down the tree. An overlay has to drop the
+ * inherited value at its boundary (see {@link overlayPaddingReset}) without
+ * dropping the theme's — impossible while both live under one name.
+ * `container.stylex.ts` reads this ahead of the public token, so a propagated
+ * value still wins over the theme for nested sections, as before.
  */
 export const sectionPaddingPropagationStyles = stylex.create({
-  0: {'--astryx-section-padding': spacingVars['--spacing-0']},
-  0.5: {'--astryx-section-padding': spacingVars['--spacing-0-5']},
-  1: {'--astryx-section-padding': spacingVars['--spacing-1']},
-  1.5: {'--astryx-section-padding': spacingVars['--spacing-1-5']},
-  2: {'--astryx-section-padding': spacingVars['--spacing-2']},
-  3: {'--astryx-section-padding': spacingVars['--spacing-3']},
-  4: {'--astryx-section-padding': spacingVars['--spacing-4']},
-  5: {'--astryx-section-padding': spacingVars['--spacing-5']},
-  6: {'--astryx-section-padding': spacingVars['--spacing-6']},
-  8: {'--astryx-section-padding': spacingVars['--spacing-8']},
-  10: {'--astryx-section-padding': spacingVars['--spacing-10']},
+  0: {'--_section-padding-propagated': spacingVars['--spacing-0']},
+  0.5: {'--_section-padding-propagated': spacingVars['--spacing-0-5']},
+  1: {'--_section-padding-propagated': spacingVars['--spacing-1']},
+  1.5: {'--_section-padding-propagated': spacingVars['--spacing-1-5']},
+  2: {'--_section-padding-propagated': spacingVars['--spacing-2']},
+  3: {'--_section-padding-propagated': spacingVars['--spacing-3']},
+  4: {'--_section-padding-propagated': spacingVars['--spacing-4']},
+  5: {'--_section-padding-propagated': spacingVars['--spacing-5']},
+  6: {'--_section-padding-propagated': spacingVars['--spacing-6']},
+  8: {'--_section-padding-propagated': spacingVars['--spacing-8']},
+  10: {'--_section-padding-propagated': spacingVars['--spacing-10']},
+});
+
+/**
+ * Padding-variable reset for overlay roots (Dialog, BottomSheet, Drawer,
+ * MobileNav, Lightbox, and every layer surface).
+ *
+ * ## Why an overlay needs this
+ *
+ * The container padding system talks to descendants through inherited custom
+ * properties: a padded container announces its padding, and children read the
+ * value either to apply it or to cancel it with a negative margin
+ * (`Section`, `Divider`, `Layout`, `Table`).
+ *
+ * Inheritance follows the DOM, but an overlay leaves its parent's visual box —
+ * a fixed/top-layer `<dialog>` is a DOM descendant of the padded page while
+ * being nowhere near it on screen. It inherits values describing padding that
+ * is not there, and its content compensates against phantom space: a `Section`
+ * inside a 640px sheet rendered 672px wide and hung off both edges (#5208).
+ *
+ * Two families leak, and they need opposite treatments:
+ *
+ * - `--container-padding-*` -> `0px`. Descendants SUBTRACT these (bleed
+ *   margins). The overlay root has no padding of its own to escape, so the
+ *   honest answer is zero. Nested containers that do set padding (a Dialog's
+ *   content wrapper) re-announce their own values below this point, so
+ *   legitimate edge-to-edge bleed inside the overlay is unaffected.
+ * - `--layout-padding-*` and `--_section-padding-propagated` -> `initial`.
+ *   Descendants ADD these, so zeroing them would strip padding rather than
+ *   restore it. `initial` makes each guaranteed-invalid, so readers fall
+ *   through their own `var(…, fallback)` chain and land on the theme default —
+ *   which is what an overlay at the top of the tree should show.
+ *
+ * `initial` is also why propagation moved off `--astryx-section-padding`: that
+ * name is public theme surface, set at the theme root, and making it invalid
+ * here would blank the theme's own section padding inside every overlay.
+ *
+ * Apply on the overlay's outermost styled element.
+ *
+ * @example
+ * ```
+ * <dialog {...stylex.props(styles.dialog, overlayPaddingReset.reset)} />
+ * ```
+ */
+export const overlayPaddingReset = stylex.create({
+  reset: {
+    // Subtracted by descendants — the overlay root has no padding to escape.
+    '--container-padding-inline-start': '0px',
+    '--container-padding-inline-end': '0px',
+    '--container-padding-block-start': '0px',
+    '--container-padding-block-end': '0px',
+    // Added by descendants — fall through to each reader's own default.
+    '--layout-padding-outer-x': 'initial',
+    '--layout-padding-outer-y': 'initial',
+    '--layout-padding-inner-x': 'initial',
+    '--layout-padding-inner-y': 'initial',
+    '--_section-padding-propagated': 'initial',
+  },
 });

package/src/Lightbox/Lightbox.tsx

@@ -36,6 +36,7 @@ import {mergeProps, mergeRefs, rtlStyles} from '../utils';
 import type {BaseProps} from '../BaseProps';
 import {themeProps} from '../utils/themeProps';
 import {focusOutlineStyles} from '../utils/focusOutline.stylex';
+import {overlayPaddingReset} from '../Layout/padding.stylex';
 import {useTranslator} from '../i18n';
 
 /**
@@ -588,7 +589,7 @@ export function Lightbox({
       aria-label={currentItem.alt || t('@astryx.lightbox.mediaViewer')}
       {...mergeProps(
         themeProps('lightbox'),
-        stylex.props(styles.dialog, xstyle),
+        stylex.props(styles.dialog, overlayPaddingReset.reset, xstyle),
         className,
         style,
       )}

package/src/Link/Link.tsx

@@ -61,7 +61,7 @@ const styles = stylex.create({
     fontWeight: 'inherit',
     textDecoration: {
       default: 'none',
-      ':hover': {
+      ':hover:where(:not(:disabled,[aria-disabled="true"]))': {
         '@media (hover: hover)': 'underline',
       },
     },
@@ -103,7 +103,7 @@ const linkColorStyles = stylex.create({
   primary: {
     color: {
       default: colorVars['--color-text-primary'],
-      ':hover': {
+      ':hover:where(:not(:disabled,[aria-disabled="true"]))': {
         '@media (hover: hover)': `color-mix(in srgb, ${colorVars['--color-text-primary']}, ${colorVars['--color-tint-hover']} 15%)`,
       },
     },
@@ -111,7 +111,7 @@ const linkColorStyles = stylex.create({
   secondary: {
     color: {
       default: colorVars['--color-text-secondary'],
-      ':hover': {
+      ':hover:where(:not(:disabled,[aria-disabled="true"]))': {
         '@media (hover: hover)': `color-mix(in srgb, ${colorVars['--color-text-secondary']}, ${colorVars['--color-tint-hover']} 15%)`,
       },
     },
@@ -125,7 +125,7 @@ const linkColorStyles = stylex.create({
   accent: {
     color: {
       default: colorVars['--color-text-accent'],
-      ':hover': {
+      ':hover:where(:not(:disabled,[aria-disabled="true"]))': {
         '@media (hover: hover)': `color-mix(in srgb, ${colorVars['--color-text-accent']}, ${colorVars['--color-tint-hover']} 15%)`,
       },
     },

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