@astryxdesign/core 0.5.2-canary.c9c8564 → 0.5.2-canary.e03511b

package/src/MobileNav/MobileNav.doc.mjs

@@ -1,5 +1,43 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
+/** @type {import('@astryxdesign/cli/authoring').ComponentAnatomyElement[]} */
+const anatomy = [
+  {
+    name: 'Navigation overlay',
+    required: true,
+    description:
+      'Full-viewport dialog overlay that hosts the mobile navigation drawer.',
+  },
+  {
+    name: 'Drawer',
+    required: true,
+    description:
+      'Painted panel that slides in from the resolved viewport edge.',
+  },
+  {
+    name: 'Header',
+    required: true,
+    description:
+      'Fixed row containing optional header content and the close button.',
+  },
+  {
+    name: 'Content',
+    required: true,
+    description: 'Scrollable region containing the navigation content.',
+  },
+  {
+    name: 'Close button',
+    required: true,
+    description: 'Button that closes the navigation drawer.',
+  },
+  {
+    name: 'Toggle button',
+    required: false,
+    description:
+      'AppShell-aware Button that opens or closes the drawer on mobile viewports.',
+  },
+];
+
 /** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 
 export const docs = {
@@ -8,12 +46,24 @@ export const docs = {
   group: 'Navigation',
   category: 'Navigation',
   isHiddenFromOverview: true,
-  keywords: ["mobilenav","drawer","sidebar","navigation","hamburger","menu","offcanvas","slideout","navdrawer","toggle"],
+  keywords: [
+    'mobilenav',
+    'drawer',
+    'sidebar',
+    'navigation',
+    'hamburger',
+    'menu',
+    'offcanvas',
+    'slideout',
+    'navdrawer',
+    'toggle',
+  ],
   components: [
     {
       name: 'MobileNav',
       displayName: 'Mobile Nav',
-      description: 'A slide-out drawer for mobile navigation. Accepts SideNav children.',
+      description:
+        'A slide-out drawer for mobile navigation. Accepts SideNav children.',
       // The drawer opens via showModal() and renders nothing while closed —
       // overlay mode gives the Properties preview an open trigger instead of
       // an empty stage (#2706). Declared on this entry (not the directory
@@ -27,7 +77,10 @@ export const docs = {
             __element: 'SideNavSection',
             props: {title: 'Main'},
             children: [
-              {__element: 'SideNavItem', props: {label: 'Dashboard', isSelected: true}},
+              {
+                __element: 'SideNavItem',
+                props: {label: 'Dashboard', isSelected: true},
+              },
               {__element: 'SideNavItem', props: {label: 'Projects'}},
               {__element: 'SideNavItem', props: {label: 'Settings'}},
             ],
@@ -38,7 +91,8 @@ export const docs = {
         {
           name: 'isOpen',
           type: 'boolean',
-          description: 'Whether the drawer is open. Inside AppShell, this is managed automatically via context. Outside AppShell, provide this prop to control the drawer yourself.',
+          description:
+            'Whether the drawer is open. Inside AppShell, this is managed automatically via context. Outside AppShell, provide this prop to control the drawer yourself.',
         },
         {
           name: 'onOpenChange',
@@ -56,7 +110,8 @@ export const docs = {
         {
           name: 'header',
           type: 'ReactNode',
-          description: 'Header content for the drawer. Rendered next to the close button. Pass a string for a simple text heading, or a ReactNode for custom content (logo, search bar, etc.).',
+          description:
+            'Header content for the drawer. Rendered next to the close button. Pass a string for a simple text heading, or a ReactNode for custom content (logo, search bar, etc.).',
         },
         {
           name: 'width',
@@ -77,7 +132,8 @@ export const docs = {
     {
       name: 'MobileNavToggle',
       displayName: 'Mobile Nav Toggle',
-      description: 'Hamburger button that opens/closes the mobile nav drawer. Reads open state from AppShell context automatically: does NOT accept isOpen or onOpenChange props. Renders nothing above the mobile breakpoint.',
+      description:
+        'Hamburger button that opens/closes the mobile nav drawer. Reads open state from AppShell context automatically: does NOT accept isOpen or onOpenChange props. Renders nothing above the mobile breakpoint.',
       // The toggle renders null unless AppShell mobile context reports an
       // enabled mobile viewport — the default context outside AppShell never
       // does, so the Properties preview was an empty stage. appShellMobile
@@ -89,7 +145,8 @@ export const docs = {
         {
           name: 'children',
           type: 'ReactNode',
-          description: 'Custom content to render instead of the default hamburger icon.',
+          description:
+            'Custom content to render instead of the default hamburger icon.',
         },
         {
           name: 'label',
@@ -101,18 +158,33 @@ export const docs = {
     },
   ],
   theming: {
-    targets: [
-      {className: 'astryx-mobile-nav', visualProps: ['side']},
-    ],
+    targets: [{className: 'astryx-mobile-nav', visualProps: ['side']}],
   },
   usage: {
+    anatomy,
     description:
       'A slide-out drawer for mobile navigation. MobileNav is the mobile counterpart to SideNav and accepts the same children. Use it on narrow viewports where a persistent sidebar is not practical. Inside AppShell, use MobileNavToggle as the trigger; it reads state from context automatically.',
     bestPractices: [
-      { guidance: true, description: 'Share the same nav items between MobileNav and SideNav by extracting them into a variable.' },
-      { guidance: true, description: 'Provide a header when the drawer\'s purpose is not obvious from its content.' },
-      { guidance: true, description: 'Inside AppShell, use MobileNavToggle to open the drawer; it reads state from context. Do not pass isOpen/onOpenChange to the toggle.' },
-      { guidance: false, description: 'Use MobileNav on desktop: use a persistent SideNav instead.' },
+      {
+        guidance: true,
+        description:
+          'Share the same nav items between MobileNav and SideNav by extracting them into a variable.',
+      },
+      {
+        guidance: true,
+        description:
+          "Provide a header when the drawer's purpose is not obvious from its content.",
+      },
+      {
+        guidance: true,
+        description:
+          'Inside AppShell, use MobileNavToggle to open the drawer; it reads state from context. Do not pass isOpen/onOpenChange to the toggle.',
+      },
+      {
+        guidance: false,
+        description:
+          'Use MobileNav on desktop: use a persistent SideNav instead.',
+      },
     ],
   },
 };
@@ -144,13 +216,13 @@ export const docsZh = {
     {
       name: 'header',
       type: 'ReactNode',
-      description: '抽屉的头部内容。渲染在关闭按钮旁边。传入字符串作为简单文本标题，或传入 ReactNode 作为自定义内容。',
+      description:
+        '抽屉的头部内容。渲染在关闭按钮旁边。传入字符串作为简单文本标题，或传入 ReactNode 作为自定义内容。',
     },
     {
       name: 'width',
       type: 'number',
-      description:
-        '抽屉宽度（像素）。上限为 85vw 以防止在小屏幕上溢出。',
+      description: '抽屉宽度（像素）。上限为 85vw 以防止在小屏幕上溢出。',
       default: '320',
     },
     {
@@ -162,18 +234,33 @@ export const docsZh = {
     },
   ],
   theming: {
-    targets: [
-      {className: 'astryx-mobile-nav', visualProps: ['side']},
-    ],
+    targets: [{className: 'astryx-mobile-nav', visualProps: ['side']}],
   },
   usage: {
+    anatomy,
     description:
       'A slide-out drawer for mobile navigation. MobileNav is the mobile counterpart to SideNav and accepts the same children. Use it on narrow viewports where a persistent sidebar is not practical.',
     bestPractices: [
-      { guidance: true, description: 'Share the same nav items between MobileNav and SideNav by extracting them into a variable.' },
-      { guidance: true, description: 'Provide a header when the drawer\'s purpose is not obvious from its content.' },
-      { guidance: true, description: 'Inside AppShell, use MobileNavToggle to open the drawer; it reads state from context. Do not pass isOpen/onOpenChange to the toggle.' },
-      { guidance: false, description: 'Use MobileNav on desktop: use a persistent SideNav instead.' },
+      {
+        guidance: true,
+        description:
+          'Share the same nav items between MobileNav and SideNav by extracting them into a variable.',
+      },
+      {
+        guidance: true,
+        description:
+          "Provide a header when the drawer's purpose is not obvious from its content.",
+      },
+      {
+        guidance: true,
+        description:
+          'Inside AppShell, use MobileNavToggle to open the drawer; it reads state from context. Do not pass isOpen/onOpenChange to the toggle.',
+      },
+      {
+        guidance: false,
+        description:
+          'Use MobileNav on desktop: use a persistent SideNav instead.',
+      },
     ],
   },
 };
@@ -183,23 +270,42 @@ export const docsDense = {
   description:
     'Slide-out drawer overlay for mobile navigation. Mobile counterpart to SideNav; accepts same children (SideNavSection, SideNavItem, or any ReactNode).',
   usage: {
+    anatomy,
     description:
       'A slide-out drawer for mobile navigation. MobileNav is the mobile counterpart to SideNav and accepts the same children. Use it on narrow viewports where a persistent sidebar is not practical.',
     bestPractices: [
-      { guidance: true, description: 'Share nav items between MobileNav and SideNav by extracting into a variable.' },
-      { guidance: true, description: 'Provide a header when the drawer purpose is not obvious from content.' },
-      { guidance: true, description: 'Inside AppShell, use MobileNavToggle to open the drawer; it reads state from context. Do not pass isOpen/onOpenChange to the toggle.' },
-      { guidance: false, description: 'Use MobileNav on desktop; use a persistent SideNav instead.' },
+      {
+        guidance: true,
+        description:
+          'Share nav items between MobileNav and SideNav by extracting into a variable.',
+      },
+      {
+        guidance: true,
+        description:
+          'Provide a header when the drawer purpose is not obvious from content.',
+      },
+      {
+        guidance: true,
+        description:
+          'Inside AppShell, use MobileNavToggle to open the drawer; it reads state from context. Do not pass isOpen/onOpenChange to the toggle.',
+      },
+      {
+        guidance: false,
+        description:
+          'Use MobileNav on desktop; use a persistent SideNav instead.',
+      },
     ],
   },
   components: [
     {
       name: 'MobileNav',
-      description: 'Slide-out drawer for mobile navigation. Accepts SideNav children.',
+      description:
+        'Slide-out drawer for mobile navigation. Accepts SideNav children.',
     },
     {
       name: 'MobileNavToggle',
-      description: 'Hamburger button that opens/closes mobile nav drawer. Reads open state from AppShell context automatically. Renders nothing above mobile breakpoint.',
+      description:
+        'Hamburger button that opens/closes mobile nav drawer. Reads open state from AppShell context automatically. Renders nothing above mobile breakpoint.',
     },
   ],
   propDescriptions: {
@@ -208,8 +314,10 @@ export const docsDense = {
       'called when drawer visibility changes (backdrop click, Escape, close button)',
     children:
       'drawer content; typically SideNavSection/SideNavItem or any ReactNode',
-    header: 'header content (string or ReactNode), rendered next to close button',
-    width: 'drawer width px; capped at 85vw to prevent overflow on small screens',
+    header:
+      'header content (string or ReactNode), rendered next to close button',
+    width:
+      'drawer width px; capped at 85vw to prevent overflow on small screens',
     side: 'slide direction; start=left LTR, right RTL',
   },
 };

package/src/MobileNav/MobileNav.spec.md

@@ -0,0 +1,208 @@
+---
+schema_version: 1
+template_version: 3
+kind: component
+id: component:MobileNav
+authority: draft
+archive_reason: null
+superseded_by: null
+approved_by: null
+approved_at: null
+owners: [cixzhang]
+review_triggers: [behavior, theming, accessibility]
+verified_by:
+  [
+    packages/core/src/MobileNav/MobileNav.test.tsx,
+    packages/core/src/MobileNav/MobileNavToggle.test.tsx,
+    packages/core/src/MobileNav/MobileNavCloseEdgeCases.test.tsx,
+    packages/core/src/theme/themingTargets.test.ts,
+    scripts/check-knowledge.mjs,
+  ]
+families: [family:overlay-dismissal]
+design_specs: []
+architecture:
+  [
+    architecture:component-theming-surface,
+    architecture:layer-runtime,
+    architecture:public-component-api,
+  ]
+contributing: []
+system_specs: []
+---
+
+# MobileNav component contract
+
+## Intent
+
+MobileNav presents mobile navigation in a modal drawer and exports an AppShell-
+aware Toggle button for opening and closing it. This draft records the aggregate
+consumer anatomy and theming ownership of both exports without changing runtime
+behavior, styling, targets, or public API.
+
+## Compatibility and migration
+
+- Released default preserved: `yes`
+- Compatibility class: additive documentation only; runtime, DOM, styling,
+  targets, aliases, and public API remain unchanged
+- Controlled/uncontrolled behavior: unchanged
+- Migration decision: none
+
+Consumer migration instructions belong in consumer docs and release notes.
+
+## Ownership boundary
+
+**Owns**
+
+- The Navigation overlay and its current `mobile-nav` target.
+- Drawer placement and motion, the stable Header and Content regions, and the
+  connection between AppShell state, MobileNav, and MobileNavToggle.
+- Canonical anatomy for both exported components. `component:MobileNav` is the
+  parent owner; MobileNavToggle does not have a separate component contract.
+
+**Does not own / non-goals**
+
+- The Close and Toggle button surfaces — delegated to `component:Button`.
+- Header or navigation content supplied by the caller.
+- A public target for the painted Drawer, Header, or Content region; none exists
+  on current `main`.
+- AppShell responsive policy or shared layer and dismissal policy.
+
+## Public concepts
+
+No new public concept is introduced. Consumer props, exports, and usage remain
+documented in `MobileNav.doc.mjs`.
+
+## Behavioral and layout contract
+
+| ID  | Candidate invariant                                                                                                                                                               | Basis                           | Draft review state                                 |
+| --- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------- | -------------------------------------------------- |
+| FR1 | MobileNav renders one Navigation overlay containing a Drawer with a stable Header, Close button, and scrollable Content region.                                                   | Current source, docs, and tests | Verified current behavior; no new behavior decided |
+| FR2 | Navigation overlay carries the current `mobile-nav` target. Drawer, Header, and Content carry no MobileNav public target.                                                         | Current source and public docs  | Verified current reachability; no target change    |
+| FR3 | Close button and the separately exported Toggle button use Button's `button` target; Toggle renders only when AppShell mobile context enables it and references the drawer by ID. | Current source, docs, and tests | Verified current delegation; no ownership change   |
+
+### Allowed variation
+
+- **AV1 — Drawer edge.** The Drawer may resolve to logical start or end through
+  the current explicit or trigger-derived side behavior.
+- **AV2 — Header content.** Header may contain a string rendered through Heading,
+  caller-provided content, or only the Close button.
+- **AV3 — Navigation content.** Caller-provided navigation content may vary
+  without becoming MobileNav-owned anatomy.
+- **AV4 — Toggle presence.** Toggle button is absent outside an enabled AppShell
+  mobile context.
+
+### Representative states
+
+| State                    | Required invariant                                                     | Allowed variation                                  |
+| ------------------------ | ---------------------------------------------------------------------- | -------------------------------------------------- |
+| Standalone drawer        | Navigation overlay contains Drawer, Header, Close button, and Content. | Caller controls open state and may choose an edge. |
+| AppShell drawer          | The same drawer anatomy consumes AppShell mobile state.                | Header and navigation content remain caller-owned. |
+| AppShell mobile toggle   | Toggle button controls and references the current drawer.              | Custom button content may replace the menu glyph.  |
+| Non-mobile/disabled host | Toggle button does not render.                                         | MobileNav remains owned by the parent contract.    |
+
+### Transformation and precedence order
+
+- No new side resolution, open-state, close timing, or styling precedence rule is
+  introduced.
+
+### Performance and resources
+
+- No new performance or resource rule is introduced.
+
+## Accessibility contract
+
+This draft does not change or extend MobileNav's existing dialog naming, focus,
+Toggle relationship, Button labels, modal behavior, or dismissal behavior.
+
+## Design relationships
+
+| Anatomy or state   | Design requirement                                                    | Representation authority       | Hierarchy role | Component contract |
+| ------------------ | --------------------------------------------------------------------- | ------------------------------ | -------------- | ------------------ |
+| Navigation overlay | Hosts the modal navigation layer and its backdrop.                    | Current source and public docs | Supporting     | FR1, FR2           |
+| Drawer             | Paints the sliding mobile navigation surface.                         | Current source and public docs | Prominent      | FR1, FR2           |
+| Header             | Arranges optional header content with the persistent Close button.    | Current source and public docs | Supporting     | FR1, FR2           |
+| Content            | Provides the scrolling region for caller-supplied navigation content. | Current source and public docs | Prominent      | FR1, FR2           |
+| Close button       | Dismisses the current drawer.                                         | `component:Button`             | Supporting     | FR1, FR3           |
+| Toggle button      | Opens or closes the AppShell-owned mobile drawer state.               | `component:Button`             | Supporting     | FR3                |
+
+Drawer is the primary painted surface, but the only current MobileNav target is
+on the full-viewport dialog overlay. Its `none` disposition is a factual
+reachability gap, not a decision that the Drawer must remain unthemeable. Header
+and Content likewise have no current local target. Close and Toggle retain Button
+ownership.
+
+### Theming anatomy
+
+<!-- anatomy-theming:v1 -->
+
+```json
+{
+  "Navigation overlay": {"target": "mobile-nav"},
+  "Drawer": {
+    "none": {
+      "reason": "reachability-gap: No current public target is applied to the painted drawer panel"
+    }
+  },
+  "Header": {
+    "none": {
+      "reason": "reachability-gap: No current public target is applied to the stable header row"
+    }
+  },
+  "Content": {
+    "none": {
+      "reason": "reachability-gap: No current public target is applied to the scrollable content region"
+    }
+  },
+  "Close button": {
+    "delegatesTo": {"owner": "component:Button", "target": "button"}
+  },
+  "Toggle button": {
+    "delegatesTo": {"owner": "component:Button", "target": "button"}
+  }
+}
+```
+
+## Family and system relationships
+
+- `architecture:component-theming-surface` owns anatomy qualification, target
+  mapping, delegation, and factual `none` dispositions.
+- `architecture:layer-runtime` owns the current native-dialog host and shared
+  layer plumbing; MobileNav retains its current drawer motion and backdrop path.
+- `family:overlay-dismissal` owns shared Escape and platform-close ordering and
+  records MobileNav as a current adopter.
+- `architecture:public-component-api` owns the shared API boundary; this draft
+  changes neither MobileNav nor MobileNavToggle API.
+- AppShell remains the higher-level responsive owner. This parent component
+  record owns the two MobileNav exports' shared anatomy only.
+
+## Verification map
+
+| Contract            | Verification                                                                  | Representative states                       | Mutation or failure expectation                                                                                  | Audit section              |
+| ------------------- | ----------------------------------------------------------------------------- | ------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- | -------------------------- |
+| FR1                 | `MobileNav.test.tsx` content/header/close assertions plus source inspection   | Standalone open and closed drawer           | Removing dialog content or the Close action fails tests; distinct Drawer/Header/Content wrappers rely on review. | `audit:MobileNav/anatomy`  |
+| FR2                 | Source inspection and `themingTargets.test.ts`                                | Overlay, Drawer, Header, and Content        | Removing the root target or documenting an unshipped child target fails evidence or inventory.                   | `audit:MobileNav/theming`  |
+| FR3                 | `MobileNavToggle.test.tsx`, `MobileNavReopen.test.tsx`, and source inspection | Closed/open AppShell drawer and toggle      | Breaking Button delegation or the ID/state relationship fails focused toggle coverage.                           | `audit:MobileNav/anatomy`  |
+| Close lifecycle     | `MobileNavCloseEdgeCases.test.tsx` and related close/visibility suites        | Escape, backdrop, close, reopen, unmount    | Leaving the modal open or disconnecting state fails existing lifecycle assertions.                               | `audit:MobileNav/behavior` |
+| Theming anatomy map | `scripts/check-knowledge.mjs`                                                 | Canonical parent anatomy and current target | Missing, extra, prefixed, stale, or multiply assigned mappings fail repository validation.                       | `audit:MobileNav/theming`  |
+
+Current tests find header and navigation content by text and the Close action by
+role, but do not identify the distinct Drawer, Header, or Content elements. Their
+existence and nesting are source-inspected; merging or reordering those wrappers
+currently lacks focused regression evidence.
+
+## Decision log
+
+None. This draft records current facts and introduces no component-local design,
+API, theming, responsive, or layer-system decision.
+
+## Open questions
+
+- **OQ1 — Should Drawer gain a stable public theming target?** (`human-api`) The
+  current target reaches the Navigation overlay rather than the primary painted
+  drawer surface; this is an audit gap, not settled intent.
+
+## Content boundary
+
+This file does not duplicate consumer prop tables/examples, AppShell responsive
+policy, close-timing mechanics, shared layer rules, current audit results, or
+implementation steps. It links to their owners.

package/src/MoreMenu/MoreMenu.doc.mjs

@@ -1,5 +1,45 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
+/** @type {import('@astryxdesign/cli/authoring').ComponentAnatomyElement[]} */
+const anatomy = [
+  {
+    name: 'Trigger button',
+    required: true,
+    description:
+      'Icon-only Button that provides the visible overflow-menu entry point.',
+  },
+  {
+    name: 'Icon-resolved trigger icon',
+    required: false,
+    description:
+      'Default semantic three-dot artwork resolved from the active Icon registry.',
+  },
+  {
+    name: 'Caller-rendered trigger content',
+    required: false,
+    description:
+      'Arbitrary React content supplied directly as the trigger icon override.',
+  },
+  {
+    name: 'Menu surface',
+    required: true,
+    description:
+      'DropdownMenu panel that also carries MoreMenu’s current public target.',
+  },
+  {
+    name: 'Pointer action row',
+    required: false,
+    description:
+      'Action or nested-action trigger row rendered by DropdownMenu in the anchored presentation.',
+  },
+  {
+    name: 'Touch action row',
+    required: false,
+    description:
+      'ListItem button rendered by DropdownMenu in the BottomSheet presentation.',
+  },
+];
+
 /** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 
 export const docs = {
@@ -61,6 +101,12 @@ export const docs = {
         "Alignment along the placement axis. Use 'end' to align the menu with the trigger's trailing edge, which is usually what an overflow menu wants.",
       default: "'start'",
     },
+    {
+      name: 'presentation',
+      type: "'popover' | 'bottom-sheet' | 'adaptive'",
+      description: 'Presentation policy forwarded to DropdownMenu. `adaptive` keeps the anchored popover on pointer-based layouts and uses a BottomSheet at 768px and below when the primary pointer is coarse.',
+      default: "'popover'",
+    },
     {
       name: 'onOpenChange',
       type: '(isOpen: boolean) => void',
@@ -88,11 +134,13 @@ export const docs = {
     ],
   },
   usage: {
+    anatomy,
     description:
       'MoreMenu is a three-dot button that opens a list of actions. Use it for secondary actions that don\'t need to be always visible, like in table rows, card headers, or toolbars.',
     bestPractices: [
       { guidance: true, description: 'Use for overflow or secondary actions; keep primary actions visible outside the menu.' },
       { guidance: true, description: 'Use dividers or sections to group related actions when the menu has many items.' },
+      { guidance: true, description: 'Use `presentation="adaptive"` when the visible overflow trigger should open a thumb-reachable BottomSheet on compact touch devices.' },
       { guidance: false, description: 'Hide primary actions inside a MoreMenu; they should be directly visible.' },
     ],
   },
@@ -153,6 +201,12 @@ export const docsZh = {
         "沿放置轴的对齐方式。使用 'end' 让菜单与触发器的尾部边缘对齐，这通常是溢出菜单所需的效果。",
       default: "'start'",
     },
+    {
+      name: 'presentation',
+      type: "'popover' | 'bottom-sheet' | 'adaptive'",
+      description: '菜单呈现策略。`adaptive` 在指针布局中使用锚定浮层，在主指针为粗略指针且宽度不超过 768px 时使用 BottomSheet。',
+      default: "'popover'",
+    },
     {
       name: 'xstyle',
       type: 'StyleXStyles',
@@ -171,6 +225,7 @@ export const docsZh = {
     bestPractices: [
       { guidance: true, description: 'Use for overflow or secondary actions; keep primary actions visible outside the menu.' },
       { guidance: true, description: 'Use dividers or sections to group related actions when the menu has many items.' },
+      { guidance: true, description: 'Use `presentation="adaptive"` when the visible overflow trigger should open a thumb-reachable BottomSheet on compact touch devices.' },
       { guidance: false, description: 'Hide primary actions inside a MoreMenu; they should be directly visible.' },
     ],
   },
@@ -181,11 +236,13 @@ export const docsDense = {
   description:
     'Overflow menu w/ three-dot icon trigger. Convenience wrapper composing icon-only Button w/ dropdown menu, eliminating boilerplate for state management, positioning, accessibility.',
   usage: {
+    anatomy,
     description:
       'MoreMenu is a three-dot button that opens a list of actions. Use it for secondary actions that don\'t need to be always visible, like in table rows, card headers, or toolbars.',
     bestPractices: [
       { guidance: true, description: 'Use for overflow or secondary actions; keep primary actions visible outside the menu.' },
       { guidance: true, description: 'Use dividers or sections to group related actions when the menu has many items.' },
+      { guidance: true, description: 'Use `presentation="adaptive"` when the visible overflow trigger should open a thumb-reachable BottomSheet on compact touch devices.' },
       { guidance: false, description: 'Hide primary actions inside a MoreMenu; they should be directly visible.' },
     ],
   },
@@ -199,6 +256,8 @@ export const docsDense = {
     placement: 'Menu position relative to trigger. Logical (RTL mirrors).',
     alignment:
       "Alignment along the placement axis. 'end' aligns with the trigger's trailing edge.",
+    presentation:
+      'Popover, BottomSheet, or adaptive compact-touch presentation.',
     xstyle:
       'StyleX styles for layout customization (margins, positioning, sizing). Must be stylex.create() value.',
   },