@astryxdesign/core 0.7.1 → 0.7.2-canary.020e1fe

package/src/DropdownMenu/__tests__/Menu.a11y.chromium.spec.ts

@@ -0,0 +1,145 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Menu.a11y.chromium.spec.ts
+ * @input Built menu stories and MENU_PATTERN in real Chromium
+ * @output Browser evidence for every menu expectation across the DropdownMenu pointer-menu states
+ * @position Chromium lane of the DropdownMenu menu-surface binding
+ */
+
+import {
+  expect,
+  test,
+  type CDPSession,
+  type Locator,
+  type Page,
+} from '@playwright/test';
+import {
+  MENU_PATTERN,
+  blockingResults,
+  checkAccessibilitySpec,
+  formatFailures,
+  neverExercised,
+  summarize,
+  unmatchedKnownFailures,
+  type BindingResult,
+} from '@astryxdesign/a11y-spec';
+import {
+  createChromiumHarness,
+  holdMotionStill,
+} from '@astryxdesign/a11y-spec/chromium';
+import {
+  DEFAULT_STORYBOOK_DIR,
+  serveStorybook,
+  type StaticServer,
+} from '@astryxdesign/a11y-spec/storybook';
+import {MENU_KNOWN_FAILURES} from './Menu.a11y.known-failures';
+import {MENU_BINDING_STATES, type MenuBindingState} from './Menu.a11y.states';
+
+let storybook: StaticServer;
+
+test.beforeAll(async () => {
+  storybook = await serveStorybook(
+    process.env.ASTRYX_STORYBOOK_DIR ?? DEFAULT_STORYBOOK_DIR,
+  );
+});
+
+test.afterAll(async () => {
+  await storybook?.close();
+});
+
+function storyUrl(storyId: string): string {
+  return `${storybook.origin}/iframe.html?id=${storyId}&viewMode=story`;
+}
+
+/**
+ * Opens the menu the way a keyboard user does — Enter on the focused trigger —
+ * and waits until focus is on the first item, so every expectation starts from
+ * a displayed menu with focus inside it.
+ */
+async function mountState(
+  page: Page,
+  state: MenuBindingState,
+): Promise<{subject: Locator; related: Record<string, Locator>}> {
+  await page.goto(storyUrl(state.storyId), {waitUntil: 'load'});
+  await holdMotionStill(page);
+  const opener = page
+    .locator('#storybook-root')
+    .getByRole('button', {name: state.label});
+  await opener.focus();
+  await page.keyboard.press('Enter');
+  const id = await opener.getAttribute('aria-controls');
+  if (id == null) {
+    throw new Error(`menu state "${state.id}" has no aria-controls`);
+  }
+  const related: Record<string, Locator> = {opener};
+  for (const [relation, [role, name]] of Object.entries(state.items)) {
+    related[relation] = page.getByRole(
+      role as Parameters<Page['getByRole']>[0],
+      {
+        name,
+        exact: true,
+        includeHidden: true,
+      },
+    );
+  }
+  await expect(related['first-item']).toBeFocused();
+  return {subject: page.locator(`[id="${id}"]`), related};
+}
+
+/**
+ * How many item actions the story's handlers have run. The story renders the
+ * count as an attribute, so this reads a fact the page shows rather than
+ * instrumenting it from the test.
+ */
+async function activationsOn(page: Page): Promise<number> {
+  const raw = await page
+    .locator('[data-a11y-activations]')
+    .first()
+    .getAttribute('data-a11y-activations');
+  return Number(raw ?? '0');
+}
+
+async function runState(
+  page: Page,
+  cdp: CDPSession,
+  state: MenuBindingState,
+): Promise<BindingResult> {
+  return checkAccessibilitySpec({
+    spec: MENU_PATTERN,
+    binding: 'DropdownMenu.menu',
+    state: state.id,
+    facts: state.facts,
+    knownFailures: MENU_KNOWN_FAILURES,
+    mount: async () => {
+      const {subject, related} = await mountState(page, state);
+      return createChromiumHarness({page, cdp, subject, related});
+    },
+    activations: async () => activationsOn(page),
+  });
+}
+
+test('every menu expectation is exercised by a DropdownMenu state', async ({
+  page,
+}) => {
+  const cdp = await page.context().newCDPSession(page);
+  const results: BindingResult[] = [];
+  for (const state of MENU_BINDING_STATES) {
+    results.push(await runState(page, cdp, state));
+  }
+  expect(neverExercised(results)).toEqual([]);
+  expect(unmatchedKnownFailures(MENU_KNOWN_FAILURES, results)).toEqual([]);
+});
+
+for (const state of MENU_BINDING_STATES) {
+  test(`DropdownMenu.menu [${state.id}] — ${state.summary}`, async ({page}) => {
+    const cdp = await page.context().newCDPSession(page);
+    const result = await runState(page, cdp, state);
+    const report = summarize(MENU_PATTERN, [result]);
+    // Required rows block (AST-020 FR9); advisory rows and exact known
+    // failures report.
+    expect(formatFailures(blockingResults([result]))).toBe('');
+    expect(report.unrunLayers).toEqual([]);
+    expect(report.counts.unexpectedPass).toBe(0);
+  });
+}

package/src/DropdownMenu/__tests__/Menu.a11y.known-failures.ts

@@ -0,0 +1,26 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Menu.a11y.known-failures.ts
+ * @input The exact menu-contract failures the shipped DropdownMenu produces today
+ * @output MENU_KNOWN_FAILURES — records both lanes reconcile against, so a fix shows up as an unexpected pass and any other failure stays a failure
+ * @position Known-failure ledger for the DropdownMenu menu-surface binding
+ */
+
+import type {KnownFailure} from '@astryxdesign/a11y-spec';
+
+export const MENU_KNOWN_FAILURES: ReadonlyArray<KnownFailure> = [
+  {
+    expectation: 'menu.keys.enter-activates-and-closes',
+    binding: 'DropdownMenu.menu',
+    state: 'dropdown-selectable-checkbox-row',
+    evidenceLayer: 'real-browser',
+    failureEquals: 'Enter on an item left the menu displayed',
+    standardsReference:
+      'APG Menu and Menubar, Enter: "Otherwise, activates the item and closes the menu" (adopted as a required part by spec:AST-020 FR15); WCAG 2.2 2.1.1 Keyboard',
+    userImpact:
+      'A keyboard user who presses Enter on a checkbox row toggles it but stays in the open menu, where the pattern says Enter chooses and closes; Escape or Tab is needed to get back to the page.',
+    reason:
+      'DropdownMenuCheckboxItem keeps the menu open by default (hasCloseOnSelect is false), shipped as released behavior under component:DropdownMenu FR16. Whether Enter on a checkbox row closes the menu, or the component record names staying open as an exception, is a behavior decision for the component owner; this test-only binding records it and changes nothing.',
+  },
+];

package/src/DropdownMenu/__tests__/Menu.a11y.renders.tsx

@@ -0,0 +1,65 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file Menu.a11y.renders.tsx
+ * @input One menu binding state from Menu.a11y.states.ts
+ * @output The React tree every lane renders for that state (the jsdom test directly, the story through Storybook), publishing how many item actions have run as `data-a11y-activations`
+ * @position Shared fixture for the DropdownMenu menu-surface binding
+ */
+
+import {useState, type ReactElement} from 'react';
+import {DropdownMenu} from '../DropdownMenu';
+import {DropdownMenuItem} from '../DropdownMenuItem';
+import {DropdownMenuCheckboxItem} from '../DropdownMenuCheckboxItem';
+import {DropdownMenuRadioGroup} from '../DropdownMenuRadioGroup';
+import {DropdownMenuRadioItem} from '../DropdownMenuRadioItem';
+import {MENU_ACTION_ITEMS, type MenuBindingState} from './Menu.a11y.states';
+
+function MenuState({
+  content,
+  label,
+}: Pick<MenuBindingState, 'content' | 'label'>): ReactElement {
+  // An item's action leaves no trace on the menu, so every handler counts
+  // here and the count is rendered for the browser lane to read.
+  const [activations, setActivations] = useState(0);
+  const activate = () => setActivations(count => count + 1);
+  const menu =
+    content === 'actions' ? (
+      <DropdownMenu
+        button={{label}}
+        items={MENU_ACTION_ITEMS.map(item => ({...item, onClick: activate}))}
+        presentation="popover"
+      />
+    ) : (
+      <DropdownMenu button={{label}} presentation="popover">
+        <DropdownMenuItem label="Edit" onClick={activate} />
+        {/* No hasCloseOnSelect: the row keeps the menu open by default. */}
+        <DropdownMenuCheckboxItem
+          label="Show archived"
+          value={true}
+          onChange={activate}
+        />
+        <DropdownMenuRadioGroup
+          value="newest"
+          onChange={activate}
+          label="Sort by">
+          <DropdownMenuRadioItem value="newest" label="Newest" />
+          <DropdownMenuRadioItem value="oldest" label="Oldest" />
+        </DropdownMenuRadioGroup>
+      </DropdownMenu>
+    );
+  return (
+    <div data-a11y-activations={activations}>
+      {menu}
+      <button type="button">After the menu</button>
+    </div>
+  );
+}
+
+export function renderMenuState(
+  state: Pick<MenuBindingState, 'content' | 'label'>,
+): ReactElement {
+  return <MenuState content={state.content} label={state.label} />;
+}

package/src/DropdownMenu/__tests__/Menu.a11y.states.ts

@@ -0,0 +1,138 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Menu.a11y.states.ts
+ * @input The DropdownMenu pointer menu's representative open states and the facts MENU_PATTERN reads
+ * @output MENU_BINDING_STATES and the explicit ownership exclusions for this binding
+ * @position Binding inventory shared by the jsdom test and the Chromium spec (component:DropdownMenu menu surface under spec:AST-020 FR15)
+ */
+
+import type {MenuStateFacts} from '@astryxdesign/a11y-spec';
+
+export interface MenuBindingState {
+  readonly id: string;
+  readonly summary: string;
+  readonly storyId: string;
+  /** Which menu content the state renders. */
+  readonly content: 'actions' | 'selectable';
+  /** The trigger's accessible name; the menu is named by it. */
+  readonly label: string;
+  /** Relation name → [role, accessible name] of the item it designates. */
+  readonly items: Readonly<Record<string, readonly [string, string]>>;
+  readonly facts: MenuStateFacts;
+}
+
+export const MENU_ACTION_ITEMS = [
+  {label: 'Rename'},
+  {label: 'Duplicate'},
+  {label: 'Archive', isDisabled: true},
+  {label: 'Delete'},
+] as const;
+
+const story = (id: string) => `a11y-menu--${id}`;
+
+export const MENU_BINDING_STATES = [
+  {
+    id: 'dropdown-actions',
+    summary:
+      'a DropdownMenu of four actions, one disabled, opened from its Button trigger',
+    storyId: story('dropdown-actions'),
+    content: 'actions',
+    label: 'Actions',
+    items: {
+      'first-item': ['menuitem', 'Rename'],
+      'second-item': ['menuitem', 'Duplicate'],
+      'last-item': ['menuitem', 'Delete'],
+      'disabled-item': ['menuitem', 'Archive'],
+      'typeahead-target': ['menuitem', 'Duplicate'],
+    },
+    facts: {
+      enterTarget: 'first-item',
+      wraps: true,
+      homeEnd: true,
+      disabledItem: true,
+      checked: {},
+      typeaheadCharacter: 'd',
+    },
+  },
+  {
+    id: 'dropdown-selectable',
+    summary:
+      'a DropdownMenu holding an action, a checked checkbox row and a titled radio group',
+    storyId: story('dropdown-selectable'),
+    content: 'selectable',
+    label: 'View',
+    items: {
+      'first-item': ['menuitem', 'Edit'],
+      'second-item': ['menuitemcheckbox', 'Show archived'],
+      'last-item': ['menuitemradio', 'Oldest'],
+      'checkbox-item': ['menuitemcheckbox', 'Show archived'],
+      'radio-item': ['menuitemradio', 'Newest'],
+      'unchecked-radio-item': ['menuitemradio', 'Oldest'],
+      'typeahead-target': ['menuitemradio', 'Oldest'],
+    },
+    facts: {
+      enterTarget: 'first-item',
+      wraps: true,
+      homeEnd: true,
+      disabledItem: false,
+      checked: {
+        'checkbox-item': true,
+        'radio-item': true,
+        'unchecked-radio-item': false,
+      },
+      typeaheadCharacter: 'o',
+    },
+  },
+  {
+    id: 'dropdown-selectable-checkbox-row',
+    summary:
+      'the same selectable menu with Enter pressed on its checkbox row, which keeps the menu open (DropdownMenuCheckboxItem hasCloseOnSelect defaults to false)',
+    storyId: story('dropdown-selectable-checkbox-row'),
+    content: 'selectable',
+    label: 'View',
+    items: {
+      'first-item': ['menuitem', 'Edit'],
+      'second-item': ['menuitemcheckbox', 'Show archived'],
+      'last-item': ['menuitemradio', 'Oldest'],
+      'checkbox-item': ['menuitemcheckbox', 'Show archived'],
+      'radio-item': ['menuitemradio', 'Newest'],
+      'unchecked-radio-item': ['menuitemradio', 'Oldest'],
+      'typeahead-target': ['menuitemradio', 'Oldest'],
+    },
+    facts: {
+      enterTarget: 'checkbox-item',
+      wraps: true,
+      homeEnd: true,
+      disabledItem: false,
+      checked: {
+        'checkbox-item': true,
+        'radio-item': true,
+        'unchecked-radio-item': false,
+      },
+      typeaheadCharacter: 'o',
+    },
+  },
+] as const satisfies ReadonlyArray<MenuBindingState>;
+
+export const MENU_EXCLUSIONS = [
+  {
+    id: 'opening-control',
+    owner: 'the menu-button pattern (MENU_BUTTON_PATTERN, MenuButton.a11y.*)',
+    reason:
+      'How the trigger exposes itself and where focus lands when it opens the menu are the Menu Button contract. This binding opens the menu from the trigger with Enter only to reach the open state it checks.',
+  },
+  {
+    id: 'submenus',
+    owner:
+      'DropdownMenuSubMenu.test.tsx and DropdownMenuDrillIn.a11y.chromium.spec.ts',
+    reason:
+      'Right and Left Arrow opening and closing a flyout, a parent row’s haspopup and expanded state, and the compact-touch drill-in are not yet in a shared contract; the menu pattern exempts them to the binding, so none of these states renders a sub-menu.',
+  },
+  {
+    id: 'bottom-sheet-and-header-footer',
+    owner: 'component:DropdownMenu AR4/AR5 and the modal-dialog pattern',
+    reason:
+      'On a compact touch display the menu is a bottom sheet, and with a header or footer the popover is a modal dialog in which Tab cycles instead of closing; both are dialogs, so every state here uses the plain pointer popover.',
+  },
+] as const;

package/src/DropdownMenu/__tests__/Menu.a11y.test.tsx

@@ -0,0 +1,136 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+/** @vitest-environment jsdom */
+
+/**
+ * @file Menu.a11y.test.tsx
+ * @input MENU_PATTERN bound to the open DropdownMenu pointer menu
+ * @output jsdom-lane proof of the DOM expectations and an honest "unrun" report for the browser layers
+ * @position Binding test for the DropdownMenu menu surface (the Chromium spec covers the rest)
+ */
+
+import {cleanup, render, screen} from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import {describe, expect, it} from 'vitest';
+import {
+  MENU_PATTERN,
+  checkAccessibilitySpec,
+  createJsdomHarness,
+  expectAccessibilitySpec,
+  summarize,
+  type BindingResult,
+} from '@astryxdesign/a11y-spec';
+import {MENU_KNOWN_FAILURES} from './Menu.a11y.known-failures';
+import {renderMenuState} from './Menu.a11y.renders';
+import {
+  MENU_BINDING_STATES,
+  MENU_EXCLUSIONS,
+  type MenuBindingState,
+} from './Menu.a11y.states';
+
+function trigger(state: MenuBindingState): HTMLElement {
+  return screen.getByRole('button', {name: state.label});
+}
+
+function menuFor(state: MenuBindingState): HTMLElement {
+  const id = trigger(state).getAttribute('aria-controls');
+  const menu = id == null ? null : document.getElementById(id);
+  if (menu == null) {
+    throw new Error(`menu state "${state.id}" has no controlled menu`);
+  }
+  return menu;
+}
+
+function relatedFor(
+  state: MenuBindingState,
+): Readonly<Record<string, Element>> {
+  const related: Record<string, Element> = {opener: trigger(state)};
+  for (const [relation, [role, name]] of Object.entries(state.items)) {
+    related[relation] = screen.getByRole(role, {name, hidden: true});
+  }
+  return related;
+}
+
+async function open(state: MenuBindingState): Promise<void> {
+  render(renderMenuState(state));
+  await userEvent.setup().click(trigger(state));
+}
+
+async function checkState(state: MenuBindingState): Promise<BindingResult> {
+  return checkAccessibilitySpec({
+    spec: MENU_PATTERN,
+    binding: 'DropdownMenu.menu',
+    state: state.id,
+    facts: state.facts,
+    knownFailures: MENU_KNOWN_FAILURES,
+    mount: async () => {
+      await open(state);
+      return createJsdomHarness({
+        subject: menuFor(state),
+        related: relatedFor(state),
+      });
+    },
+    unmount: cleanup,
+  });
+}
+
+describe('DropdownMenu pointer menu — menu pattern, jsdom lane', () => {
+  it.each(
+    MENU_BINDING_STATES.map(state => [state.id, state.summary, state] as const),
+  )('%s — %s', async (_id, _summary, state) => {
+    await expectAccessibilitySpec({
+      spec: MENU_PATTERN,
+      binding: 'DropdownMenu.menu',
+      state: state.id,
+      facts: state.facts,
+      knownFailures: MENU_KNOWN_FAILURES,
+      render: async () => {
+        await open(state);
+      },
+      subject: () => menuFor(state),
+      related: () => relatedFor(state),
+      cleanup,
+    });
+  });
+
+  it('runs the DOM layer and reports the browser-owned outcomes as unrun', async () => {
+    const results: BindingResult[] = [];
+    for (const state of MENU_BINDING_STATES) {
+      results.push(await checkState(state));
+    }
+    const report = summarize(MENU_PATTERN, results);
+    expect(report.counts.pass).toBeGreaterThan(0);
+    expect(report.unrunLayers).toEqual(['accessibility-tree', 'real-browser']);
+    expect(report.counts.unexpectedPass).toBe(0);
+  });
+});
+
+describe('menu binding inventory', () => {
+  it('gives every representative state a distinct checked-in story', () => {
+    const stories = MENU_BINDING_STATES.map(state => state.storyId);
+    expect(new Set(stories).size).toBe(stories.length);
+  });
+
+  it('keeps the opening control, submenus and dialog presentations explicit', () => {
+    expect(MENU_EXCLUSIONS.map(row => row.id)).toEqual([
+      'opening-control',
+      'submenus',
+      'bottom-sheet-and-header-footer',
+    ]);
+    for (const exclusion of MENU_EXCLUSIONS) {
+      expect(exclusion.owner.length, exclusion.id).toBeGreaterThan(20);
+      expect(exclusion.reason.length, exclusion.id).toBeGreaterThan(80);
+    }
+  });
+
+  it('renders the menu and every item relation it names for every state', async () => {
+    for (const state of MENU_BINDING_STATES) {
+      await open(state);
+      expect(menuFor(state).getAttribute('role'), state.id).toBe('menu');
+      expect(Object.keys(relatedFor(state)), state.id).toEqual([
+        'opener',
+        ...Object.keys(state.items),
+      ]);
+      cleanup();
+    }
+  });
+});

package/src/DropdownMenu/__tests__/warmMenuBottomSheet.tsx

@@ -0,0 +1,43 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file warmMenuBottomSheet.tsx
+ * @input Uses DropdownMenu and Testing Library
+ * @output Exports warmMenuBottomSheet, a test helper that resolves the lazily
+ *   loaded touch sheet once
+ * @position Test-only helper for suites that open a DropdownMenu bottom sheet
+ *
+ * DropdownMenu loads its touch sheet with React.lazy, so the first sheet
+ * renders a tick after it opens. Opening one up front caches the resolved
+ * modules on the lazy components, and every later sheet renders
+ * synchronously. Call it from `beforeAll`.
+ */
+
+import {cleanup, render, screen} from '@testing-library/react';
+import {DropdownMenu} from '../DropdownMenu';
+
+export async function warmMenuBottomSheet(): Promise<void> {
+  const {showModal, close} = HTMLDialogElement.prototype;
+  HTMLDialogElement.prototype.showModal = function (this: HTMLDialogElement) {
+    this.setAttribute('open', '');
+  };
+  HTMLDialogElement.prototype.close = function (this: HTMLDialogElement) {
+    this.removeAttribute('open');
+  };
+  try {
+    render(
+      <DropdownMenu
+        button={{label: 'Warm'}}
+        presentation="bottom-sheet"
+        isMenuOpen
+        items={[{label: 'Warm item'}]}
+      />,
+    );
+    // A cold import transforms the sheet's module graph; allow for it.
+    await screen.findByText('Warm item', undefined, {timeout: 15000});
+  } finally {
+    cleanup();
+    HTMLDialogElement.prototype.showModal = showModal;
+    HTMLDialogElement.prototype.close = close;
+  }
+}

package/src/DropdownMenu/lazyMenuBottomSheet.ts

@@ -0,0 +1,71 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file lazyMenuBottomSheet.ts
+ * @input Uses React lazy and Suspense, useIsHydrating, MenuBottomSheet, and
+ *   MenuBottomSheetActionList
+ * @output Exports MenuBottomSheet and MenuBottomSheetActionList wrappers that
+ *   load the touch sheet on first render
+ * @position Internal to DropdownMenu
+ *
+ * The touch sheet (BottomSheet, its gestures, and the touch action list) only
+ * renders for the bottom-sheet presentation. Loading it on demand keeps it out
+ * of pages whose dropdowns only open as anchored popovers. Each wrapper keeps
+ * the wrapped component's props and renders nothing until its module loads.
+ *
+ * Neither wrapper renders on the server or in the render that hydrates server
+ * HTML (spec:AST-013 FR9): a lazy component that has not loaded yet would
+ * leave server markup incomplete and abort hydration. The closed sheet has no
+ * visible markup, so it first renders right after hydration.
+ */
+
+import {
+  createElement,
+  lazy,
+  Suspense,
+  type ComponentProps,
+  type ReactElement,
+} from 'react';
+import {useIsHydrating} from '../hooks/useIsHydrating';
+import type {MenuBottomSheet as EagerMenuBottomSheet} from './MenuBottomSheet';
+import type {MenuBottomSheetActionList as EagerMenuBottomSheetActionList} from './MenuBottomSheetActionList';
+
+const LazyMenuBottomSheet = lazy(async () =>
+  import('./MenuBottomSheet').then(module => ({
+    default: module.MenuBottomSheet,
+  })),
+);
+
+const LazyMenuBottomSheetActionList = lazy(async () =>
+  import('./MenuBottomSheetActionList').then(module => ({
+    default: module.MenuBottomSheetActionList,
+  })),
+);
+
+export function MenuBottomSheet(
+  props: ComponentProps<typeof EagerMenuBottomSheet>,
+): ReactElement | null {
+  if (useIsHydrating()) {
+    return null;
+  }
+  return createElement(
+    Suspense,
+    {fallback: null},
+    createElement(LazyMenuBottomSheet, props),
+  );
+}
+
+export function MenuBottomSheetActionList(
+  props: ComponentProps<typeof EagerMenuBottomSheetActionList>,
+): ReactElement | null {
+  if (useIsHydrating()) {
+    return null;
+  }
+  return createElement(
+    Suspense,
+    {fallback: null},
+    createElement(LazyMenuBottomSheetActionList, props),
+  );
+}

package/src/EmptyState/EmptyState.doc.mjs

@@ -12,7 +12,7 @@ export const docs = {
       name: 'title',
       type: 'string',
       description:
-        'Primary message rendered as an <h3> heading inside the empty state.',
+        'Primary message rendered as the configured heading level inside the empty state.',
       required: true,
     },
     {
@@ -81,6 +81,7 @@ export const docs = {
       { guidance: false, description: 'Use an EmptyState for error messages that require immediate action; use a Banner instead.' },
     ],
     anatomy: [
+      {name: 'Container', required: true, description: 'The centered status region that owns spacing, reading order, and the compact layout variant.'},
       {name: 'Icon', required: false, description: 'A visual cue above the title that reinforces the context, like a search icon for no results.'},
       {name: 'Title', required: true, description: 'Primary message explaining what is empty: "No projects yet" not "No data".'},
       {name: 'Description', required: false, description: 'Additional context explaining why it is empty or what the user can do.'},
@@ -98,7 +99,7 @@ export const docsZh = {
       name: 'title',
       type: 'string',
       description:
-        '在空状态内部渲染为 <h3> 标题的主要信息。',
+        '在空状态内部按配置的标题级别渲染主要信息。',
       required: true,
     },
     {