@astryxdesign/core 0.7.2 → 0.7.3-canary.02f5fe4

package/src/DropdownMenu/DropdownMenu.tsx

@@ -61,7 +61,10 @@ import {
 import {
   DropdownMenuContext,
   DropdownMenuRootOpenContext,
+  DropdownMenuSurfaceContext,
   type DropdownMenuContextValue,
+  type DropdownMenuSurfaceHost,
+  type DropdownMenuSurfaceValue,
 } from './DropdownMenuContext';
 import {useIsomorphicLayoutEffect} from '../hooks/useIsomorphicLayoutEffect';
 import {useListFocus} from '../hooks/useListFocus';
@@ -112,6 +115,14 @@ const MENU_MAX_BLOCK_SIZE = `min(${MENU_BLOCK_CAP}, ${layerViewportInset.maxBloc
 const MENU_MAX_BLOCK_SIZE_FALLBACK = `min(${MENU_BLOCK_CAP}, ${layerViewportInset.maxBlockSizeFallback})`;
 const MENU_TRIGGER_OPEN_BACKGROUND = `linear-gradient(${colorVars['--color-overlay-pressed']}, ${colorVars['--color-overlay-pressed']})`;
 
+// A sub-menu's drilled-in view with a header or footer renders in the surface
+// host that follows the menu, as the frame marked
+// `data-astryx-submenu-regions="view"` (hidden while a deeper view shows).
+// While one shows, the menu and its header and footer step aside. The rule
+// reads that from the DOM, so no state mirrors which view shows.
+const STEPS_ASIDE_FOR_VIEW =
+  ':has(~ * > [data-astryx-submenu-regions="view"]:not([hidden]))';
+
 const styles = stylex.create({
   triggerOpen: {
     backgroundImage: MENU_TRIGGER_OPEN_BACKGROUND,
@@ -125,7 +136,12 @@ const styles = stylex.create({
   },
   dropdown: {
     boxSizing: 'border-box',
-    display: 'flex',
+    display: {
+      default: 'flex',
+      // A sub-menu's drilled-in view with a header or footer shows in its
+      // place (see `stepsAsideForView`).
+      [STEPS_ASIDE_FOR_VIEW]: 'none',
+    },
     flexDirection: 'column',
     gap: spacingVars['--spacing-0-5'],
     // Pointer opens focus this container so subsequent arrow keys and Escape
@@ -175,6 +191,22 @@ const styles = stylex.create({
     flexShrink: 1,
     minBlockSize: 0,
   },
+  // Where a sub-menu with a header or footer renders its surface: beside the
+  // menu, never inside it. It owns no box, so the popover's layout is
+  // unchanged.
+  surfaceHost: {
+    display: 'contents',
+  },
+  // While a sub-menu's drilled-in view with its own header or footer shows
+  // in the surface host, the header and footer step aside for it, as the menu
+  // does (see `dropdown`). Derived from the DOM by the rule itself: the view
+  // is the frame in the host that is not hidden.
+  stepsAsideForView: {
+    display: {
+      default: null,
+      [STEPS_ASIDE_FOR_VIEW]: 'none',
+    },
+  },
   region: {
     flexShrink: 0,
     padding: spacingVars['--spacing-1'],
@@ -1455,12 +1487,39 @@ function DropdownMenuPopover({
 
   // The drill-in view stack for sub-menus on a phone.
   const {drillIn, wrapContent} = useMenuDrillIn(isOpen);
+  // The surface host is owned through a ref. State keeps only a key that
+  // changes whenever a host element attaches, the host included when it
+  // moves (a header or footer coming or going), so sub-menus re-render into
+  // the element that is mounted.
+  const surfaceHostRef = useRef<HTMLDivElement | null>(null);
+  const [surfaceHostKey, setSurfaceHostKey] = useState(0);
+  const attachSurfaceHost = useCallback((node: HTMLDivElement | null) => {
+    surfaceHostRef.current = node;
+    if (node != null) {
+      setSurfaceHostKey(key => key + 1);
+    }
+  }, []);
+  const surfaceHost = useMemo<DropdownMenuSurfaceHost>(
+    () => ({
+      getElement: () => (surfaceHostKey > 0 ? surfaceHostRef.current : null),
+    }),
+    [surfaceHostKey],
+  );
   const resolvedMaxHeight = menuMaxHeight == null ? null : `${menuMaxHeight}px`;
   // Context for compound items
   const contextValue = useMemo<DropdownMenuContextValue>(
     () => ({closeMenu, menuSize, drillIn, menuLabel}),
     [closeMenu, menuSize, drillIn, menuLabel],
   );
+  // What a sub-menu with a header or footer needs, on an internal context.
+  const surfaceValue = useMemo<DropdownMenuSurfaceValue>(
+    () => ({
+      host: surfaceHost,
+      ownerId: menuId,
+      menuMaxHeight: resolvedMaxHeight ?? undefined,
+    }),
+    [surfaceHost, menuId, resolvedMaxHeight],
+  );
 
   // Resolve menu content: data-driven items become components
   const menuContent = wrapContent(
@@ -1469,7 +1528,13 @@ function DropdownMenuPopover({
   const hasOverflow = useMenuOverflow(listRef, menuContent, popover.isOpen);
 
   // The header and footer sit beside the menu inside the popover, never inside
-  // the role="menu" element: a menu holds only its rows.
+  // the role="menu" element: a menu holds only its rows. The surface host
+  // follows the menu, so a sub-menu with a header or footer renders beside the
+  // menu too; while such a sub-menu's drilled-in view shows there, the menu and
+  // the regions step aside (STEPS_ASIDE_FOR_VIEW).
+  const surfaceHostElement = (
+    <div ref={attachSurfaceHost} {...stylex.props(styles.surfaceHost)} />
+  );
   const renderWithRegions = (menu: ReactNode): ReactNode =>
     hasRegions ? (
       <div
@@ -1482,7 +1547,7 @@ function DropdownMenuPopover({
           <div
             ref={headerRef}
             onKeyDown={handleRegionKeyDown}
-            {...stylex.props(styles.region)}>
+            {...stylex.props(styles.region, styles.stepsAsideForView)}>
             {header}
           </div>
         )}
@@ -1491,13 +1556,17 @@ function DropdownMenuPopover({
           <div
             ref={footerRef}
             onKeyDown={handleRegionKeyDown}
-            {...stylex.props(styles.region)}>
+            {...stylex.props(styles.region, styles.stepsAsideForView)}>
             {footer}
           </div>
         )}
+        {surfaceHostElement}
       </div>
     ) : (
-      menu
+      <>
+        {menu}
+        {surfaceHostElement}
+      </>
     );
 
   const triggerProps: DropdownMenuTriggerProps = {
@@ -1636,9 +1705,11 @@ function DropdownMenuPopover({
             )}>
             <MenuRegionsContext value={hasRegions}>
               <DropdownMenuContext value={contextValue}>
-                <DropdownMenuRootOpenContext value={isOpen}>
-                  {menuContent}
-                </DropdownMenuRootOpenContext>
+                <DropdownMenuSurfaceContext value={surfaceValue}>
+                  <DropdownMenuRootOpenContext value={isOpen}>
+                    {menuContent}
+                  </DropdownMenuRootOpenContext>
+                </DropdownMenuSurfaceContext>
               </DropdownMenuContext>
             </MenuRegionsContext>
           </div>,

package/src/DropdownMenu/DropdownMenuContext.public.test.ts

@@ -0,0 +1,22 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file DropdownMenuContext.public.test.ts
+ * @input The DropdownMenu barrel and its public `DropdownMenuContextValue`
+ * @output Guards that the menu context keeps its members and that the internal
+ *   surface context a sub-menu with a header or footer reads is not exported
+ * @position Public API test guarding @astryxdesign/core/DropdownMenu
+ */
+
+import {describe, expect, expectTypeOf, it} from 'vitest';
+import * as dropdownMenu from './index';
+import type {DropdownMenuContextValue} from './index';
+
+describe('DropdownMenu public context', () => {
+  it('keeps its members and exports no surface context', () => {
+    expectTypeOf<keyof DropdownMenuContextValue>().toEqualTypeOf<
+      'closeMenu' | 'menuSize' | 'drillIn' | 'menuLabel'
+    >();
+    expect('DropdownMenuSurfaceContext' in dropdownMenu).toBe(false);
+  });
+});

package/src/DropdownMenu/DropdownMenuContext.tsx

@@ -45,7 +45,10 @@ export interface DropdownMenuDrillIn {
   viewStack: ReadonlyArray<string>;
   /** The element a shown view renders its rows into (a portal target). */
   host: HTMLElement | null;
-  /** Show a sub-menu's view in place of the current rows. */
+  /**
+   * Show a sub-menu's view in place of the current rows. A view with a header
+   * or footer renders into the root's surface host instead of `host`.
+   */
   push: (viewId: string) => void;
   /** Return to the rows the shown view replaced. */
   pop: () => void;
@@ -65,6 +68,41 @@ export interface DropdownMenuContextValue {
   menuLabel?: string;
 }
 
+/**
+ * The root's surface host. The root owns the element through a ref; this
+ * object is new whenever a new element attaches, so a sub-menu re-renders
+ * into it.
+ */
+export interface DropdownMenuSurfaceHost {
+  /** The host element, or `null` before it attaches. */
+  getElement: () => HTMLElement | null;
+}
+
+/** What a sub-menu with a header or footer needs from the root. Internal. */
+export interface DropdownMenuSurfaceValue {
+  /**
+   * An element inside the root's popover but outside every `role="menu"`
+   * element, where such a sub-menu renders its surface (its flyout layer, or
+   * its drilled-in view, while which the root's menu and regions step aside).
+   */
+  host: DropdownMenuSurfaceHost;
+  /**
+   * The root menu's `id`, which a sub-menu's menu in the host names so the
+   * press model counts it, and only it, as nested in the root.
+   */
+  ownerId: string;
+  /** The root's resolved `menuMaxHeight`, which a drilled-in view caps at. */
+  menuMaxHeight?: string;
+}
+
+/**
+ * The root's surface; `null` under a root with none (ContextMenu). Internal,
+ * off the public menu context, and layer-scoped, so each flyout re-provides it.
+ */
+export const DropdownMenuSurfaceContext =
+  createLayerScopedContext<DropdownMenuSurfaceValue | null>(null);
+DropdownMenuSurfaceContext.displayName = 'DropdownMenuSurfaceContext';
+
 /**
  * Whether the root menu of this layer tree is open; internal companion to
  * `DropdownMenuContext`, on its own unexported context so the public

package/src/DropdownMenu/DropdownMenuItem.doc.mjs

@@ -8,7 +8,50 @@ export const docs = {
   displayName: 'Dropdown Menu Item',
   isHiddenFromOverview: true,
   description:
-    'Helper component for custom item rendering with consistent styling. Host attributes and DOM event handlers (aria-*, data-*, id, drag and drop) reach the row root, the element carrying role="menuitem".',
+    'One action or destination row in the pointer presentation of DropdownMenu. The parent menu owns keyboard navigation; the row owns activation, disabled state, destination behavior, content layout, and its theme target. Supported host attributes, DOM handlers, className, style, xstyle, and ref reach or compose on the role="menuitem" root.',
+  usage: {
+    description:
+      'Use DropdownMenuItem inside DropdownMenu compound mode for one action or destination. Keep label, description, icon, and endContent non-interactive; controls belong in separate rows or the menu header/footer.',
+    bestPractices: [
+      {
+        guidance: true,
+        description:
+          'Use href for a destination so LinkProvider, modified clicks, middle clicks, and browser link affordances remain available.',
+      },
+      {
+        guidance: true,
+        description:
+          'Use hasCloseOnSelect=false only when activation reports a result in place on the same row.',
+      },
+      {
+        guidance: false,
+        description:
+          'Put buttons, links, or other focusable controls inside label, description, or endContent. Each menu row is one interactive target.',
+      },
+    ],
+    anatomy: [
+      {
+        name: 'Row',
+        required: true,
+        description:
+          'The role="menuitem" root that owns activation, disabled state, destination behavior, and theme state.',
+      },
+      {
+        name: 'Content',
+        required: true,
+        description:
+          'The non-interactive label plus optional icon, description, and end content.',
+      },
+    ],
+  },
+  theming: {
+    targets: [
+      {
+        className: 'astryx-dropdown-menu-item',
+        visualProps: ['size', 'variant'],
+      },
+    ],
+  },
   playground: {
     // Standalone DropdownMenuItem has no required props, so the properties-tab
     // preview renders an empty row without seeded content. Seed a label and
@@ -26,6 +69,7 @@ export const docs = {
       name: 'label',
       type: 'ReactNode',
       description: 'Primary label text.',
+      required: true,
     },
     {
       name: 'description',
@@ -55,11 +99,18 @@ export const docs = {
       description:
         'Link relationship. noopener noreferrer is added for target="_blank". Only used with href.',
     },
+    {
+      name: 'isDisabled',
+      type: 'boolean',
+      description:
+        'Whether the row is unavailable. Disabled rows expose aria-disabled, remove link destinations, and suppress activation.',
+      default: 'false',
+    },
     {
       name: 'endContent',
       type: 'ReactNode',
       description:
-        'Additional content rendered after the label and description.',
+        'Non-interactive content rendered after the label and description.',
     },
     {
       name: 'hasCloseOnSelect',
@@ -95,7 +146,7 @@ export const docsZh = {
   isHiddenFromOverview: true,
   displayName: 'Dropdown Menu Item',
   description:
-    '用于自定义项渲染的辅助组件，提供一致的样式。宿主属性和 DOM 事件处理器（aria-*、data-*、id、拖放）会落在行根元素上，即带 role="menuitem" 的元素。',
+    'DropdownMenu 指针呈现中的一个操作或目标行。父菜单负责键盘导航；该行负责激活、禁用状态、目标行为、内容布局和主题目标。支持的宿主属性、DOM 处理程序、className、style、xstyle 和 ref 会落在或组合到 role="menuitem" 根元素上。',
   props: [
     {
       name: 'icon',
@@ -106,6 +157,7 @@ export const docsZh = {
       name: 'label',
       type: 'ReactNode',
       description: '主标签文本。',
+      required: true,
     },
     {
       name: 'description',
@@ -134,10 +186,16 @@ export const docsZh = {
       type: 'string',
       description: '链接关系。target="_blank" 时自动加入 noopener noreferrer。',
     },
+    {
+      name: 'isDisabled',
+      type: 'boolean',
+      description: '该行是否不可用；不可用的行不会激活或导航。',
+      default: 'false',
+    },
     {
       name: 'endContent',
       type: 'ReactNode',
-      description: '在标签和描述之后渲染的附加内容。',
+      description: '在标签和描述之后渲染的非交互式附加内容。',
     },
     {
       name: 'hasCloseOnSelect',
@@ -168,9 +226,9 @@ export const docsZh = {
 
 export const docsDense = {
   name: 'DropdownMenuItem',
-  isHiddenFromOverview: true,
   displayName: 'Dropdown Menu Item',
-  description: 'helper for custom item rendering w/ consistent styling',
+  description:
+    'one pointer-menu action/destination row; parent owns keyboard, row owns activation, state, destination, content, and root inputs',
   propDescriptions: {
     icon: 'icon before label',
     label: 'primary label text',
@@ -180,7 +238,8 @@ export const docsDense = {
     href: 'row is a real anchor w/ role=menuitem; modified/middle click keeps browser meaning',
     target: "link target ('_blank' | '_self'), with href",
     rel: 'link rel; noopener noreferrer added for _blank',
-    endContent: 'additional content after label+description',
+    isDisabled: 'unavailable; removes destinations and suppresses activation',
+    endContent: 'non-interactive content after label+description',
     hasCloseOnSelect:
       'false keeps the menu open on activation (in-place result on the item)',
     variant:

package/src/DropdownMenu/DropdownMenuItem.spec.md

@@ -0,0 +1,209 @@
+---
+schema_version: 3
+template_version: 7
+kind: component
+id: component:DropdownMenuItem
+authority: draft
+archive_reason: null
+superseded_by: null
+approved_by: null
+approved_at: null
+owners: [cixzhang]
+review_triggers: [public-api, behavior, accessibility, theming, testing]
+verified_by:
+  [
+    packages/core/src/DropdownMenu/DropdownMenu.test.tsx,
+    packages/core/src/DropdownMenu/__tests__/Menu.a11y.test.tsx,
+    packages/core/src/theme/themingTargets.test.ts,
+    apps/storybook/stories/DropdownMenuItem.stories.tsx,
+    apps/storybook/rtl-audit/verified-not-applicable.json,
+    scripts/check-knowledge.mjs,
+  ]
+modules: []
+families: [family:navigation-destinations]
+design_specs: []
+architecture:
+  [
+    architecture:public-component-api,
+    architecture:component-theming-surface,
+    architecture:component-test-sufficiency,
+    architecture:interaction-modality,
+  ]
+contributing: []
+system_specs: [spec:AST-020, spec:AST-029]
+---
+
+# DropdownMenuItem component contract
+
+## Contract at a glance
+
+| Area                    | Contract                                                                                                                                                                                           |
+| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Public contract         | One compound pointer-menu row for an action or destination, with label, supporting content, disabled state, destructive paint, optional close suppression, root inputs, and a forwarded ref.       |
+| Behavior                | The parent menu owns roving focus and keyboard activation; the row owns click order, disabled suppression, close-on-select, destination handoff, hover focus, and its visible content composition. |
+| End-user impact         | Actions and destinations preserve keyboard, pointer, and browser link behavior while unavailable rows remain inert and destructive actions remain identifiable.                                    |
+| Builder impact          | Destinations use `href`; supporting content stays non-interactive; `hasCloseOnSelect=false` is reserved for in-place result feedback.                                                              |
+| Compatibility/readiness | Patch-compatible observational contract. Runtime, exports, defaults, and theme targets remain unchanged; authority stays `draft` until exact-head owner approval.                                  |
+| Review checks           | Reject nested controls, disabled activation, lost destination safety, broken modified-click behavior, dropped root inputs, a second keyboard owner, or state/target reflection moved off the row.  |
+| Governing rules         | `family:navigation-destinations/FR1–FR5`; `architecture:public-component-api/INV5–INV9`; `architecture:component-theming-surface/INV3–INV6`; `spec:AST-020/FR1,FR2,FR6,FR15`.                      |
+
+This table is a review projection; the body below is authoritative.
+
+## Intent
+
+DropdownMenuItem renders one compound-mode row in the pointer presentation of
+DropdownMenu. It owns the row element, content slots, action-versus-destination
+branch, activation order, disabled and destructive state, root composition, and
+`dropdown-menu-item` theme target. DropdownMenu owns the surrounding menu,
+keyboard collection, focus movement, typeahead, presentation choice, and close
+lifecycle.
+
+## Compatibility and migration
+
+- Released default preserved: yes.
+- Compatibility class: observational patch; no behavior or public surface changes.
+- Controlled/uncontrolled behavior: not applicable.
+- Migration decision: none.
+
+Consumer migration instructions belong in consumer docs and release notes.
+
+## Ownership boundary
+
+**Owns**
+
+- One `role="menuitem"` root and its label, description, icon, end content,
+  disabled state, destructive variant, ref, supported host inputs, and styling inputs.
+- Action callback order and `hasCloseOnSelect` behavior.
+- Link-row rendering, destination handoff, modified/middle-click preservation,
+  target and relationship handling, and disabled-link inertness.
+- Pointer hover focus and the row's press/hover/focus paint.
+- The `dropdown-menu-item` target and its size/variant state reflection.
+
+**Does not own / non-goals**
+
+- Menu naming, open/close state, focus entry, roving focus, typeahead, and keyboard
+  click synthesis — owned by DropdownMenu and its shared hooks.
+- Touch and bottom-sheet row rendering — the parent presentation delegates those
+  rows to List.
+- Destination acceptance and blocking — owned by `family:navigation-destinations`.
+- Interactive controls inside label, description, or end content. Controls belong
+  beside the menu or as separate rows.
+
+## Public concepts
+
+| Concept      | Closed values or states                             | Meaning                                                                        | Availability                | Default | Owner                           | Stability | Invalid-value behavior                                       |
+| ------------ | --------------------------------------------------- | ------------------------------------------------------------------------------ | --------------------------- | ------- | ------------------------------- | --------- | ------------------------------------------------------------ |
+| Row act      | action; destination                                 | Runs a callback or exposes a browser/router destination from the row itself.   | Every enabled row           | action  | component and navigation family | stable    | A blocked destination is inert; a disabled link has no href. |
+| Availability | enabled; disabled                                   | Controls whether the row can receive focus or activate.                        | Every row                   | enabled | component and parent menu       | stable    | Disabled suppresses activation and destination.              |
+| Close policy | close; remain open                                  | Whether successful activation closes the parent menu.                          | Action and destination rows | close   | component                       | stable    | Omission closes.                                             |
+| Visual state | default; destructive; hover; focus; press; disabled | Paints row meaning and interaction state without changing menuitem semantics.  | Pointer row                 | default | component                       | stable    | Unknown variants are rejected by the public type.            |
+| Root surface | ref; DOM/data/ARIA; class/style/xstyle/events       | Extends the row root while preserving component-owned role and keyboard state. | Every pointer row           | omitted | public component API            | stable    | Accepted inputs compose; owned role/tab stop remain fixed.   |
+
+## Behavioral and layout contract
+
+Draft requirements identify their basis so observed code is not mistaken for an
+intentional decision.
+
+| ID  | Candidate invariant                                                                                                                                                                                                                                  | Basis                                                            | Draft review state                                           |
+| --- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- | ------------------------------------------------------------ |
+| FR1 | The pointer row MUST expose one `role="menuitem"` root. Label, description, icon, and end content remain presentational content of that row rather than nested controls.                                                                             | WAI-ARIA menu pattern; released source/docs                      | verify                                                       |
+| FR2 | Enabled activation MUST run the row callback before optional close. Disabled rows MUST expose `aria-disabled=true`, remove link destinations, and run neither callback nor close.                                                                    | Released behavior; focused tests                                 | verify                                                       |
+| FR3 | A destination row MUST render as the link root through LinkProvider. Plain activation runs the callback then closes and navigates; modified and middle clicks preserve browser behavior without running the callback; blocked schemes are inert.     | `family:navigation-destinations/FR1–FR5`; released tests         | verify                                                       |
+| FR4 | The parent menu MUST remain the only keyboard owner. It synthesizes click activation with modifiers, moves focus, and runs typeahead; the row MAY focus itself on pointer hover but MUST NOT create a second roving-focus model.                     | `architecture:interaction-modality`; current parent tests        | verify                                                       |
+| FR5 | The visible root MUST carry `dropdown-menu-item`; size and destructive state MUST reflect through `themeProps`; semantic tokens own layout and paint before caller styling inputs compose.                                                           | `architecture:component-theming-surface/INV3–INV6`; source/tests | verify                                                       |
+| FR6 | Ref, supported host attributes and handlers, `className`, `style`, and `xstyle` MUST reach or compose on the row root without replacing owned role, tab stop, disabled behavior, destination handling, or activation order.                          | `architecture:public-component-api/INV5–INV9`; focused tests     | verify                                                       |
+| FR7 | Disabled menu rows remain inert. Whether the menu keyboard model should visit them is unresolved at the shared owner and MUST NOT be changed by a component-local audit.                                                                             | WAI-ARIA menu pattern; parent `component:DropdownMenu/OQ1`       | human API decision                                           |
+| FR8 | Keyboard focus MUST remain perceivable, including in forced-colors mode. The current background-only treatment is an objective gap; a remediation must preserve modality and row-content visibility without inventing new ordinary-theme appearance. | WCAG 2.2 SC 1.4.11 and 2.4.7; current rendered behavior          | objective gap; owner must confirm the shared visual boundary |
+
+### Allowed variation
+
+- **AV1 — Content.** Non-interactive icons, text, descriptions, shortcuts, badges,
+  and status text may vary without changing the row's menuitem semantics.
+- **AV2 — Theme paint.** A theme may restyle the target's admitted properties while
+  preserving visible state distinctions and forced-colors focus.
+- **AV3 — Parent size.** The parent menu supplies `sm`, `md`, or `lg`; the row reflects
+  that state and may vary its tokenized insets.
+
+### Representative states
+
+| State                  | Required invariant                                                                  | Allowed variation                            |
+| ---------------------- | ----------------------------------------------------------------------------------- | -------------------------------------------- |
+| Enabled action         | Callback runs, then close follows the close policy.                                 | Content, size, and visual variant.           |
+| In-place result action | Callback runs and the menu remains open.                                            | Label/end content may update.                |
+| Disabled action        | `aria-disabled=true`; callback, hover focus, and close are suppressed.              | Content remains visible.                     |
+| Destination            | One anchor root preserves safe destination and browser activation behavior.         | Target, rel, router provider, and content.   |
+| Destructive            | Error-role paint applies to label, icon, and description without changing behavior. | Other row content remains consumer-authored. |
+| Keyboard focus         | Parent focus lands on the row and remains visible.                                  | Exact theme-owned paint may vary.            |
+| RTL / narrow viewport  | Logical insets and start alignment follow direction without horizontal overflow.    | Menu placement remains parent-owned.         |
+
+### Transformation and precedence order
+
+- **ORD1 — Activation.** Disabled guard → browser-navigation classification → row
+  callback where applicable → close policy → browser/router navigation.
+- **ORD2 — Root composition.** Parent size → base row styles → variant/disabled state
+  → caller `xstyle`; target metadata and caller class/style compose on the same root.
+
+### Performance and resources
+
+- **PR1 — Shared press lifecycle.** DropdownMenuItem uses the shared counted press
+  controller through `usePressFeedback`; the first mounted pressable installs the
+  window listeners and the last removes them. The item adds no per-row listener,
+  observer, timer, request, or local resource owner.
+
+## Accessibility contract
+
+- **AR1 — Menu item semantics.** The root is one named `menuitem`; supporting content
+  does not introduce a nested interactive descendant.
+- **AR2 — Disabled state.** Disabled rows expose state and cannot activate or navigate.
+- **AR3 — Keyboard ownership.** DropdownMenu owns focus collection and activation;
+  the item remains a single row in that model.
+- **AR4 — Focus perception.** Focus remains visually perceivable in supported themes
+  and platform accessibility modes; the open forced-colors gap remains explicit.
+
+## Design relationships
+
+| Anatomy or state | Design requirement                                                                  | Representation authority                                           | Hierarchy role | Component contract |
+| ---------------- | ----------------------------------------------------------------------------------- | ------------------------------------------------------------------ | -------------- | ------------------ |
+| Row              | One full-width action/destination target with tokenized insets and start alignment. | Current source and parent menu composition                         | prominent      | FR1–FR6            |
+| Supporting text  | Description and end content remain subordinate to the row label.                    | Delegated Item layout and current consumer docs                    | supporting     | FR1                |
+| Interaction      | Hover, focus, press, disabled, and destructive states remain distinguishable.       | Current source; forced-colors focus is an unresolved objective gap | prominent      | FR5, FR8, AR4      |
+
+No new component-local visual decision is settled by this draft.
+
+## Family and system relationships
+
+- `family:navigation-destinations` owns destination acceptance and blocked-scheme
+  behavior; this component supplies the destination-bearing row.
+- `architecture:public-component-api` owns root input composition, refs, and released
+  compatibility.
+- `architecture:component-theming-surface` owns target placement and state reflection.
+- `architecture:component-test-sufficiency` owns proportionate observable evidence.
+- `architecture:interaction-modality` and DropdownMenu own parent keyboard behavior.
+- `spec:AST-020` supplies WCAG/APG adoption and evidence-layer boundaries.
+- `spec:AST-029` keeps this observational draft separate from the audit receipt.
+
+## Verification map
+
+| Contract         | Verification                                                                  | Representative states                                      | Mutation or failure expectation                                                                                       | Audit section                     |
+| ---------------- | ----------------------------------------------------------------------------- | ---------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- | --------------------------------- |
+| FR1–FR4, AR1–AR3 | `DropdownMenu.test.tsx`; reusable Menu accessibility tests; scoped axe        | action, destination, disabled, keyboard, modified clicks   | A nested control, activation while disabled, lost browser affordance, or second keyboard owner fails observable tests | `audit:DropdownMenuItem/§1,§4,§6` |
+| FR5, FR8, AR4    | theming-target tests; exact-head Neutral/Butter/RTL/narrow/focus/hover frames | default, destructive, disabled, focus, hover               | Target/state reflection disappears, paint is absent, or focus becomes unobservable                                    | `audit:DropdownMenuItem/§2,§5`    |
+| FR6              | root/ref/handler tests; lint and typecheck                                    | ref, host attributes, class/style/xstyle, pointer handlers | An accepted input is dropped or overrides component-owned semantics                                                   | `audit:DropdownMenuItem/§3`       |
+| RTL / responsive | source-hashed verified-N/A receipt plus exact-head browser frames             | LTR, RTL, 320px                                            | Physical direction leaks into the row or narrow layout overflows                                                      | `audit:DropdownMenuItem/§9,§10`   |
+
+## Decision log
+
+None. This draft records current facts and introduces no product decision.
+
+## Open questions
+
+- **OQ1 — Which shared keyboard owner should keep disabled menu items discoverable
+  while preserving their inert behavior?** (`human-api`)
+- **OQ2 — Should forced-colors focus use a component-specific system outline, or a
+  shared row-focus treatment that also governs ordinary themes?** (`human-design`)
+
+## Content boundary
+
+This file does not duplicate consumer prop tables/examples, current audit scores,
+screenshot matrices, implementation steps, or family/system rules. The audit pull
+request owns the closed run evidence required by `spec:AST-029/FR5`.

package/src/DropdownMenu/DropdownMenuSubMenu.doc.mjs

@@ -67,6 +67,18 @@ export const docs = {
         "How the sub-menu shows its rows. 'flyout' opens them beside the row; 'drill-in' replaces the menu's rows with them and a Back row, in the same box; 'adaptive' drills in when a finger opened the menu (a coarse pointer, decided when the menu opened) and flies out otherwise.",
       default: "'adaptive'",
     },
+    {
+      name: 'header',
+      type: 'ReactNode',
+      description:
+        'Content above the sub-menu\'s rows and outside its menu, a field that filters them, say. It keeps its own keys and presses. With a header or footer the sub-menu\'s surface (the flyout, or the drilled-in view on a phone) is a modal dialog named by the row, beside the menu rather than inside it: the row says aria-haspopup="dialog", Tab and Shift+Tab move through the header, the rows and the footer and wrap, Escape returns to the row, and a pointer leaving the flyout closes it only once focus leaves too. A ContextMenu does not show it.',
+    },
+    {
+      name: 'footer',
+      type: 'ReactNode',
+      description:
+        "Content below the sub-menu's rows and outside its menu, a door to where the options are managed, say. Same rules as header.",
+    },
     {
       name: 'xstyle',
       type: 'StyleXStyles',
@@ -77,7 +89,7 @@ export const docs = {
       name: 'ref',
       type: 'React.Ref<HTMLElement>',
       description:
-        'Ref forwarded to the trigger row, the element carrying role="menuitem" and aria-haspopup="menu".',
+        'Ref forwarded to the trigger row, the element carrying role="menuitem" and aria-haspopup="menu" ("dialog" with a header or footer).',
     },
   ],
 };
@@ -100,6 +112,9 @@ export const docsDense = {
     onOpenChange: 'called when flyout opens/closes',
     presentation:
       "'flyout' beside the row | 'drill-in' replaces the rows + Back row | 'adaptive' (default) drills in on a coarse pointer",
+    header:
+      'content above the rows, outside the menu; surface becomes a modal dialog named by the row (Tab wraps, Escape returns to the row)',
+    footer: 'content below the rows, outside the menu; same rules as header',
     xstyle: 'StyleX styles for the trigger row',
     ref: 'ref to the trigger row (role="menuitem")',
   },