An open source design system that's fully customizable and agent ready
TypeScript
docs(core): record factual anatomy batch 8 (#5751)
Cindy Zhangf994ddba0780
diff --git a/packages/core/src/Lightbox/Lightbox.doc.mjs b/packages/core/src/Lightbox/Lightbox.doc.mjsindex aa21aa1dfa..44e9cc55bc 100644--- a/packages/core/src/Lightbox/Lightbox.doc.mjs+++ b/packages/core/src/Lightbox/Lightbox.doc.mjs@@ -1,12 +1,63 @@// Copyright (c) Meta Platforms, Inc. and affiliates.+/** @type {import('@astryxdesign/cli/authoring').ComponentAnatomyElement[]} */+const anatomy = [+ {+ name: 'Viewer overlay',+ required: true,+ description:+ 'Full-viewport dialog overlay that contains the active media and controls.',+ },+ {+ name: 'Media',+ required: true,+ description: 'Active image or video presented inside the viewer.',+ },+ {+ name: 'Close button',+ required: true,+ description: 'Button that closes the viewer.',+ },+ {+ name: 'Previous button',+ required: false,+ description: 'Gallery button that moves to the previous media item.',+ },+ {+ name: 'Next button',+ required: false,+ description: 'Gallery button that moves to the next media item.',+ },+ {+ name: 'Caption',+ required: false,+ description: 'Caller-provided caption displayed below the active media.',+ },+ {+ name: 'Counter',+ required: false,+ description: 'Current position and total shown in gallery mode.',+ },+];+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */export const docs = {name: 'Lightbox',displayName: 'Lightbox',category: 'Overlay',- keywords: ["lightbox","image","video","viewer","gallery","zoom","fullscreen","media","photo","preview"],+ keywords: [+ 'lightbox',+ 'image',+ 'video',+ 'viewer',+ 'gallery',+ 'zoom',+ 'fullscreen',+ 'media',+ 'photo',+ 'preview',+ ],props: [{name: 'isOpen',@@ -28,7 +79,8 @@ export const docs = {// where a media object belongs. The shape and its legal values live in// the description instead (#1645).type: 'LightboxMedia | LightboxMedia[]',- description: "Media to display. Pass a single object for one item, or an array for gallery mode with prev/next navigation. Each item is {src: string, alt: string, caption?: ReactNode, type?: 'image' | 'video'}; type defaults to 'image', and zoom/pan is disabled for 'video'.",+ description:+ "Media to display. Pass a single object for one item, or an array for gallery mode with prev/next navigation. Each item is {src: string, alt: string, caption?: ReactNode, type?: 'image' | 'video'}; type defaults to 'image', and zoom/pan is disabled for 'video'.",required: true,},{@@ -39,46 +91,70 @@ export const docs = {{name: 'onIndexChange',type: '(index: number) => void',- description: 'Callback when the gallery index changes via prev/next navigation.',+ description:+ 'Callback when the gallery index changes via prev/next navigation.',},{name: 'hasZoom',type: 'boolean',- description: 'Enable zoom on double-click, or Enter/Space/+/- via keyboard (images only). When zoomed, drag or use arrow keys to pan.',+ description:+ 'Enable zoom on double-click, or Enter/Space/+/- via keyboard (images only). When zoomed, drag or use arrow keys to pan.',default: 'false',},{name: 'defaultIndex',type: 'number',- description: 'Initial image index in gallery mode for uncontrolled usage.',+ description:+ 'Initial image index in gallery mode for uncontrolled usage.',default: '0',},{name: 'hasAutoPlay',type: 'boolean',- description: 'Automatically start video playback when a video media item is shown.',+ description:+ 'Automatically start video playback when a video media item is shown.',default: 'false',},{name: 'xstyle',type: 'StyleXStyles',- description: 'StyleX styles for layout customization. Must be stylex.create() value.',+ description:+ 'StyleX styles for layout customization. Must be stylex.create() value.',},],theming: {- targets: [- {className: 'astryx-lightbox', visualProps: []},- ],+ targets: [{className: 'astryx-lightbox', visualProps: []}],},usage: {+ anatomy,description:'A fullscreen overlay for viewing images and videos at full resolution. Supports single-item and gallery modes with prev/next navigation, optional zoom and pan for images, and native video controls.',bestPractices: [- { guidance: true, description: 'Always provide alt text for every image for screen reader accessibility.' },- { guidance: true, description: 'Use gallery mode with onIndexChange for multi-image sets.' },- { guidance: true, description: 'Enable hasZoom only when viewing high-resolution images that benefit from close inspection.' },- { guidance: false, description: 'Use the lightbox for non-image content; it is specialized for images.' },- { guidance: false, description: 'Nest interactive content inside captions; keep them plain text.' },+ {+ guidance: true,+ description:+ 'Always provide alt text for every image for screen reader accessibility.',+ },+ {+ guidance: true,+ description:+ 'Use gallery mode with onIndexChange for multi-image sets.',+ },+ {+ guidance: true,+ description:+ 'Enable hasZoom only when viewing high-resolution images that benefit from close inspection.',+ },+ {+ guidance: false,+ description:+ 'Use the lightbox for non-image content; it is specialized for images.',+ },+ {+ guidance: false,+ description:+ 'Nest interactive content inside captions; keep them plain text.',+ },],},// The lightbox opens via showModal() and renders nothing while closed —@@ -91,7 +167,8 @@ export const docs = {media: {src: '/template-assets/light-scene-horizontal-1.png',alt: 'Coastal shoreline with ocean waves',- caption: 'A scenic coastline with waves rolling onto a sandy beach beneath a clear sky.',+ caption:+ 'A scenic coastline with waves rolling onto a sandy beach beneath a clear sky.',},},},@@ -117,7 +194,8 @@ export const docsZh = {{name: 'media',type: 'LightboxMedia | LightboxMedia[]',- description: "要显示的媒体。传入单个对象或数组(用于画廊模式的上一张/下一张导航)。每项为 {src, alt, caption?, type?: 'image' | 'video'};type 默认为 'image','video' 禁用缩放/平移。",+ description:+ "要显示的媒体。传入单个对象或数组(用于画廊模式的上一张/下一张导航)。每项为 {src, alt, caption?, type?: 'image' | 'video'};type 默认为 'image','video' 禁用缩放/平移。",required: true,},{@@ -139,39 +217,76 @@ export const docsZh = {{name: 'xstyle',type: 'StyleXStyles',- description: '用于布局自定义的 StyleX 样式。必须是 stylex.create() 的值。',+ description:+ '用于布局自定义的 StyleX 样式。必须是 stylex.create() 的值。',},],theming: {- targets: [- {className: 'astryx-lightbox', visualProps: []},- ],+ targets: [{className: 'astryx-lightbox', visualProps: []}],},usage: {+ anatomy,description:'A fullscreen overlay for viewing images and videos at full resolution. Supports single-item and gallery modes with prev/next navigation, optional zoom and pan for images, and native video controls.',bestPractices: [- { guidance: true, description: 'Always provide alt text for every image for screen reader accessibility.' },- { guidance: true, description: 'Use gallery mode with onIndexChange for multi-image sets.' },- { guidance: true, description: 'Enable hasZoom only when viewing high-resolution images that benefit from close inspection.' },- { guidance: false, description: 'Use the lightbox for non-image content; it is specialized for images.' },- { guidance: false, description: 'Nest interactive content inside captions; keep them plain text.' },+ {+ guidance: true,+ description:+ 'Always provide alt text for every image for screen reader accessibility.',+ },+ {+ guidance: true,+ description:+ 'Use gallery mode with onIndexChange for multi-image sets.',+ },+ {+ guidance: true,+ description:+ 'Enable hasZoom only when viewing high-resolution images that benefit from close inspection.',+ },+ {+ guidance: false,+ description:+ 'Use the lightbox for non-image content; it is specialized for images.',+ },+ {+ guidance: false,+ description:+ 'Nest interactive content inside captions; keep them plain text.',+ },],},};/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */export const docsDense = {- description: 'Fullscreen overlay for viewing images and videos at full resolution with gallery navigation and zoom.',+ description:+ 'Fullscreen overlay for viewing images and videos at full resolution with gallery navigation and zoom.',usage: {+ anatomy,description:'A fullscreen overlay for viewing images and videos at full resolution. Supports single-item and gallery modes with prev/next navigation, optional zoom and pan for images, and native video controls.',bestPractices: [- { guidance: true, description: 'Always provide alt text for every image.' },- { guidance: true, description: 'Use gallery mode with onIndexChange for multi-image sets.' },- { guidance: true, description: 'Enable hasZoom only when viewing high-resolution images that benefit from close inspection.' },- { guidance: false, description: 'Use for non-image content; specialized for images.' },- { guidance: false, description: 'Nest interactive content inside captions; keep them plain text.' },+ {guidance: true, description: 'Always provide alt text for every image.'},+ {+ guidance: true,+ description:+ 'Use gallery mode with onIndexChange for multi-image sets.',+ },+ {+ guidance: true,+ description:+ 'Enable hasZoom only when viewing high-resolution images that benefit from close inspection.',+ },+ {+ guidance: false,+ description: 'Use for non-image content; specialized for images.',+ },+ {+ guidance: false,+ description:+ 'Nest interactive content inside captions; keep them plain text.',+ },],},propDescriptions: {@@ -180,7 +295,8 @@ export const docsDense = {media: 'Single media object or array for gallery mode.',index: 'Current index in gallery mode.',onIndexChange: 'Callback when gallery index changes.',- hasZoom: 'Enable zoom (double-click, Enter/Space, or +/-) and pan (drag or arrow keys) for images.',+ hasZoom:+ 'Enable zoom (double-click, Enter/Space, or +/-) and pan (drag or arrow keys) for images.',xstyle: 'StyleX styles for layout customization.',},};diff --git a/packages/core/src/Lightbox/Lightbox.spec.md b/packages/core/src/Lightbox/Lightbox.spec.mdnew file mode 100644index 0000000000..ae4a60fffb--- /dev/null+++ b/packages/core/src/Lightbox/Lightbox.spec.md@@ -0,0 +1,197 @@+---+schema_version: 1+template_version: 3+kind: component+id: component:Lightbox+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/Lightbox/Lightbox.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:interaction-modality,+ architecture:layer-runtime,+ architecture:public-component-api,+ ]+contributing: []+system_specs: []+---++# Lightbox component contract++## Intent++Lightbox presents one active image or video in a full-viewport viewer and may+add gallery navigation, a caption, and a position counter. This draft records+current consumer anatomy and theming ownership 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 Viewer overlay and its current `lightbox` target.+- Media presentation, optional Caption and Counter placement, gallery navigation,+ and current image zoom and pan behavior.++**Does not own / non-goals**++- The Close, Previous, and Next button surfaces — delegated to+ `component:Button` through IconButton.+- Caller-provided Caption content.+- New targets for Media, Caption, or Counter; none exist on current `main`.+- Shared layer hosting or dismissal policy.++## Public concepts++No new public concept is introduced. Consumer props and usage remain documented+in `Lightbox.doc.mjs`.++## Behavioral and layout contract++| ID | Candidate invariant | Basis | Draft review state |+| --- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------- | -------------------------------------------------- |+| FR1 | The current viewer contains one active Media item and a Close button; galleries additionally contain Previous and Next buttons plus a Counter, and Caption renders only when supplied. | Current source, docs, and tests | Verified current behavior; no new behavior decided |+| FR2 | Viewer overlay carries the current `lightbox` target. Media, Caption, and Counter carry no Lightbox public target. | Current source and public docs | Verified current reachability; no target change |+| FR3 | Close, Previous, and Next button surfaces use Button's `button` target through IconButton rather than Lightbox-owned button targets. | Current source and target docs | Verified current delegation; no ownership change |++### Allowed variation++- **AV1 — Media mode.** Media may be an image or video; zoom and pan are available+ only on the current image path.+- **AV2 — Gallery mode.** Previous, Next, and Counter are absent for a single+ item. Navigation button disabled state follows the current gallery boundary.+- **AV3 — Caption content.** Caller-provided Caption content may vary without+ becoming a Lightbox-owned target.++### Representative states++| State | Required invariant | Allowed variation |+| ---------------- | ------------------------------------------------------------------- | --------------------------------------------- |+| Single image | Viewer overlay, Media, and Close button render. | Caption and zoom may be absent or present. |+| Gallery boundary | Both navigation buttons and Counter remain rendered. | Previous or Next is disabled at its boundary. |+| Video | Media renders native video controls without image zoom interaction. | Autoplay follows the existing consumer prop. |+| Captioned media | Caption follows the active Media inside the centered media group. | Caption content remains caller-provided. |++### Transformation and precedence order++- No new index, zoom, pan, media, 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 Lightbox's existing dialog naming, focus,+media alternatives, announcements, button labels, keyboard behavior, or+dismissal behavior.++## Design relationships++| Anatomy or state | Design requirement | Representation authority | Hierarchy role | Component contract |+| ---------------- | -------------------------------------------------------------------- | ------------------------------ | ----------------- | ------------------ |+| Viewer overlay | Presents the full-viewport dialog and surrounding overlay treatment. | Current source and public docs | Supporting | FR1, FR2 |+| Media | Presents the active image or video. | Current source and public docs | Prominent | FR1, FR2 |+| Close button | Provides the persistent viewer dismissal action. | `component:Button` | Supporting | FR1, FR3 |+| Previous button | Moves gallery presentation to the preceding item. | `component:Button` | Supporting | FR1, FR3 |+| Next button | Moves gallery presentation to the following item. | `component:Button` | Supporting | FR1, FR3 |+| Caption | Presents caller-provided context below the active Media. | Current source and public docs | Context-dependent | FR1, FR2 |+| Counter | Presents current gallery position and total. | Current source and tests | Supporting | FR1, FR2 |++Media, Caption, and Counter are stable visible parts, but no current public+target reaches them. Their `none` dispositions record factual reachability, not+a decision that they must remain unthemeable.++### Theming anatomy++<!-- anatomy-theming:v1 -->++```json+{+ "Viewer overlay": {"target": "lightbox"},+ "Media": {+ "none": {+ "reason": "reachability-gap: No current public target is applied to the active image or video"+ }+ },+ "Close button": {+ "delegatesTo": {"owner": "component:Button", "target": "button"}+ },+ "Previous button": {+ "delegatesTo": {"owner": "component:Button", "target": "button"}+ },+ "Next button": {+ "delegatesTo": {"owner": "component:Button", "target": "button"}+ },+ "Caption": {+ "none": {+ "reason": "reachability-gap: No current public target is applied to the caption container"+ }+ },+ "Counter": {+ "none": {+ "reason": "reachability-gap: No current public target is applied to the gallery counter"+ }+ }+}+```++## 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; Lightbox retains its current media and local backdrop behavior.+- `family:overlay-dismissal` owns shared Escape and platform-close ordering and+ records Lightbox as a current adopter.+- `architecture:interaction-modality` and `architecture:public-component-api`+ own their shared modality and API boundaries; this draft changes neither.++## Verification map++| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |+| ------------------- | -------------------------------------------------------------------- | ------------------------------------------- | ---------------------------------------------------------------------------------------------- | ------------------------ |+| FR1 | `Lightbox.test.tsx` render, gallery, caption, media, and zoom suites | Single image, gallery edges, caption, video | Removing a documented part fails existing role, content, media, or navigation assertions. | `audit:Lightbox/anatomy` |+| FR2 | Source inspection and `themingTargets.test.ts` | Viewer overlay, Media, Caption, and Counter | Removing the root target or documenting an unshipped child target fails evidence or inventory. | `audit:Lightbox/theming` |+| FR3 | Source inspection plus Button and IconButton public composition | Close and gallery navigation controls | Re-owning a control surface requires the delegated owner and this map to change. | `audit:Lightbox/theming` |+| Theming anatomy map | `scripts/check-knowledge.mjs` | Canonical anatomy and current target | Missing, extra, prefixed, stale, or multiply assigned mappings fail repository validation. | `audit:Lightbox/theming` |++## Decision log++None. This draft records current facts and introduces no component-local design,+API, theming, or layer-system decision.++## Open questions++- **OQ1 — Should Media, Caption, or Counter gain a stable public theming target?**+ (`human-api`) Their current lack of reachability is an audit gap, not settled+ intent.++## Content boundary++This file does not duplicate consumer prop tables/examples, media algorithms,+shared layer rules, current audit results, or implementation steps. It links to+their owners.diff --git a/packages/core/src/MobileNav/MobileNav.doc.mjs b/packages/core/src/MobileNav/MobileNav.doc.mjsindex 6090f5cae4..2652044197 100644--- a/packages/core/src/MobileNav/MobileNav.doc.mjs+++ b/packages/core/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',},};diff --git a/packages/core/src/MobileNav/MobileNav.spec.md b/packages/core/src/MobileNav/MobileNav.spec.mdnew file mode 100644index 0000000000..470b8167aa--- /dev/null+++ b/packages/core/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.diff --git a/packages/core/src/Resizable/Resizable.doc.mjs b/packages/core/src/Resizable/Resizable.doc.mjsindex 7d9b06c5a0..55282a431b 100644--- a/packages/core/src/Resizable/Resizable.doc.mjs+++ b/packages/core/src/Resizable/Resizable.doc.mjs@@ -1,5 +1,27 @@// Copyright (c) Meta Platforms, Inc. and affiliates.+/** @type {import('@astryxdesign/cli/authoring').ComponentAnatomyElement[]} */+const anatomy = [+ {+ name: 'Handle',+ required: true,+ description:+ 'Focusable separator that owns pointer and keyboard resize interaction.',+ },+ {+ name: 'Grip pill',+ required: false,+ description:+ 'Default visible grip indicator; custom handle content can replace it.',+ },+ {+ name: 'Grab zone',+ required: true,+ description:+ 'Invisible enlarged pointer region aligned with the grip or divider.',+ },+];+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */export const docs = {name: 'Resizable',@@ -19,6 +41,7 @@ export const docs = {'grip',],usage: {+ anatomy,description:'Hook-based resizable panel system. useResizable() manages size state ' +'and ResizeHandle provides the interactive pill-grip separator. ' +@@ -86,8 +109,7 @@ export const docs = {{name: 'collapsedSize',type: 'number',- description:- 'Pixel threshold that triggers collapse during drag.',+ description: 'Pixel threshold that triggers collapse during drag.',default: '40',},{@@ -98,13 +120,13 @@ export const docs = {{name: 'shrinkOrder',type: 'number',- description:- 'Cascade priority: lower number shrinks first.',+ description: 'Cascade priority: lower number shrinks first.',},{name: 'autoSaveId',type: 'string',- description: 'Key for persisting sizes and collapse state to localStorage.',+ description:+ 'Key for persisting sizes and collapse state to localStorage.',},],},@@ -190,20 +212,35 @@ export const docs = {/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */export const docsDense = {- description: 'Hook-based resizable panel system. useResizable() manages size state; ResizeHandle provides interactive pill-grip separator.',+ description:+ 'Hook-based resizable panel system. useResizable() manages size state; ResizeHandle provides interactive pill-grip separator.',usage: {+ anatomy,description:'Hook-based resizable panel system. useResizable() manages size state; ResizeHandle provides interactive pill-grip separator. Pass resize props to existing layout components via their resizable prop.',bestPractices: [- {guidance: true, description: 'Use useResizable() w/ existing Astryx layout components. Pass returned props to resizable prop on LayoutPanel or SideNav.'},- {guidance: true, description: 'Provide accessible label on each ResizeHandle when multiple handles exist (e.g. "Resize sidebar", "Resize terminal").'},- {guidance: false, description: 'Wrap panels in extra container components for resize. Hook-first architecture avoids extra DOM; use it directly on existing components.'},+ {+ guidance: true,+ description:+ 'Use useResizable() w/ existing Astryx layout components. Pass returned props to resizable prop on LayoutPanel or SideNav.',+ },+ {+ guidance: true,+ description:+ 'Provide accessible label on each ResizeHandle when multiple handles exist (e.g. "Resize sidebar", "Resize terminal").',+ },+ {+ guidance: false,+ description:+ 'Wrap panels in extra container components for resize. Hook-first architecture avoids extra DOM; use it directly on existing components.',+ },],},components: [{name: 'useResizable',- description: 'Hook managing resize state for one or more panel regions. Returns size, isCollapsed, collapse/expand/resize methods, + props to pass to handles.',+ description:+ 'Hook managing resize state for one or more panel regions. Returns size, isCollapsed, collapse/expand/resize methods, + props to pass to handles.',propDescriptions: {defaultSize: 'initial size in px or % string (e.g. "20%")',minSizePx: 'minimum size in px',@@ -217,14 +254,20 @@ export const docsDense = {},{name: 'ResizeHandle',- description: 'Draggable separator between panels. Pill-grip: invisible at rest, visible on hover (0.6 opacity), fully opaque during drag (1.0). Keyboard-accessible.',+ description:+ 'Draggable separator between panels. Pill-grip: invisible at rest, visible on hover (0.6 opacity), fully opaque during drag (1.0). Keyboard-accessible.',propDescriptions: {- direction: 'layout direction: determines cursor + indicator orientation',- isReversed: 'reverse drag direction. Use when handle controls panel on end/right/bottom side',+ direction:+ 'layout direction: determines cursor + indicator orientation',+ isReversed:+ 'reverse drag direction. Use when handle controls panel on end/right/bottom side',isDisabled: 'handle interactive?',- hasDivider: 'show full-length 1px divider line through handle. Use when adjacent panels share same background',- isAlwaysVisible: 'show pill grip at rest instead of only on hover. Use when discoverability important',- pillPlacement: 'which side of divider pill sits on. auto = content side (derived from isReversed), flips when collapsed; start = left/top, end = right/bottom, center = centered on divider',+ hasDivider:+ 'show full-length 1px divider line through handle. Use when adjacent panels share same background',+ isAlwaysVisible:+ 'show pill grip at rest instead of only on hover. Use when discoverability important',+ pillPlacement:+ 'which side of divider pill sits on. auto = content side (derived from isReversed), flips when collapsed; start = left/top, end = right/bottom, center = centered on divider',label: 'accessible label for separator',resizable: 'resize props from useResizable: connects handle to panel',},diff --git a/packages/core/src/Resizable/Resizable.spec.md b/packages/core/src/Resizable/Resizable.spec.mdnew file mode 100644index 0000000000..88c7aff9ad--- /dev/null+++ b/packages/core/src/Resizable/Resizable.spec.md@@ -0,0 +1,194 @@+---+schema_version: 1+template_version: 3+kind: component+id: component:Resizable+authority: draft+archive_reason: null+superseded_by: null+approved_by: null+approved_at: null+owners: [cixzhang]+review_triggers: [behavior, layout, theming, accessibility]+verified_by:+ [+ packages/core/src/Resizable/ResizeHandle.test.tsx,+ packages/core/src/Resizable/useResizable.test.ts,+ packages/core/src/theme/themingTargets.test.ts,+ scripts/check-knowledge.mjs,+ ]+families: []+design_specs: []+architecture:+ [+ architecture:component-theming-surface,+ architecture:interaction-modality,+ architecture:public-component-api,+ ]+contributing: []+system_specs: []+---++# Resizable component contract++## Intent++Resizable combines the useResizable state and behavior hook with a focusable+ResizeHandle. The handle presents a default Grip pill over an enlarged invisible+Grab zone. This draft records current consumer anatomy and theming ownership+without changing resize semantics, 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**++- useResizable size, collapse, snapping, persistence, and resize lifecycle.+- ResizeHandle's separator semantics, pointer and keyboard interaction, and+ current `resize-handle` target.+- The default Grip pill and its current `resize-handle-pill` target, plus the+ aligned invisible Grab zone.++**Does not own / non-goals**++- The structural region being resized — owned by LayoutPanel, SideNav, or another+ caller.+- Layout-region topology, inset, divider, or scrolling rules.+- A public target for the Grab zone; none exists on current `main`.+- Fixing the missing runtime reflection for the documented Handle `direction`+ theming state in this documentation-only change.++## Public concepts++No new public concept is introduced. Consumer props, hook outputs, and usage+remain documented in `Resizable.doc.mjs` and `useResizable.doc.mjs`.++## Behavioral and layout contract++| ID | Candidate invariant | Basis | Draft review state |+| --- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------- | ------------------------------------------------------------- |+| FR1 | ResizeHandle renders one focusable Handle and one enlarged Grab zone; the default render also contains a Grip pill, while caller-provided children replace that pill. | Current source, docs, and tests | Verified current behavior; no new behavior decided |+| FR2 | Handle carries `resize-handle`, Grip pill carries `resize-handle-pill`, and Grab zone carries no public target. | Current source and public docs | Verified current target inventory; no target change |+| FR3 | Pointer, keyboard, collapse, snap, persistence, reversal, and size behavior remain owned by ResizeHandle and useResizable rather than layout-regions collaborators. | Current source, docs, and tests | Verified current ownership; resize semantics remain unchanged |+| FR4 | Resizable metadata advertises `direction` as a Handle visual state, but current runtime calls `themeProps('resize-handle')` without reflecting that value, so direction selectors cannot match. | Current source and public docs | Verified audit gap; deliberately not fixed in this change |++### Allowed variation++- **AV1 — Axis.** Handle may resize along the horizontal or vertical layout axis;+ separator orientation and cursor follow the current implementation.+- **AV2 — Placement.** Handle may participate inline or overlay its parent, and+ Grip pill may sit at start, end, center, or the current automatic side.+- **AV3 — Grip content.** Caller-provided children may replace Grip pill without+ changing Handle or Grab zone ownership.+- **AV4 — Divider.** Handle may paint its current divider treatment; a composing+ region remains responsible for avoiding a duplicate adjacent divider.++### Representative states++| State | Required invariant | Allowed variation |+| ---------------------- | --------------------------------------------------------------------- | -------------------------------------------------- |+| Default handle | Handle, Grab zone, and Grip pill render. | Divider and always-visible treatment may vary. |+| Custom handle content | Handle and Grab zone remain; caller content replaces Grip pill. | Caller content remains caller-owned. |+| Horizontal or vertical | Interaction follows the selected axis and current ARIA orientation. | Size, reversal, and pill placement may vary. |+| Collapsed or expanded | Handle preserves valid separator value semantics and resize controls. | Grip pill automatic side follows current behavior. |+| Disabled | Handle remains represented but is removed from interactive tab order. | Painted treatment follows existing styles. |++### Transformation and precedence order++- No new clamp, snap, collapse, persistence, reversal, pointer, or keyboard order+ is introduced.++### Performance and resources++- No new listener, storage, observer, or render requirement is introduced.++## Accessibility contract++This draft does not change or extend ResizeHandle's existing separator role,+label, orientation, value, collapsed value text, focus, pointer, or keyboard+behavior.++## Design relationships++| Anatomy or state | Design requirement | Representation authority | Hierarchy role | Component contract |+| ---------------- | ----------------------------------------------------------------------- | ------------------------------ | -------------- | ------------------ |+| Handle | Presents the focusable resize separator and optional divider treatment. | Current source and public docs | Prominent | FR1, FR2, FR3 |+| Grip pill | Presents the default visible resize affordance. | Current source and public docs | Supporting | FR1, FR2 |+| Grab zone | Enlarges pointer reach while remaining visually transparent. | Current source and tests | Supporting | FR1, FR2 |+| Direction state | Selects horizontal or vertical resize presentation. | Current public metadata | Supporting | FR3, FR4 |++Grab zone is interaction structure rather than a painted public theming seam. Its+`none` disposition records factual reachability. The missing Handle direction+reflection is a separate current audit gap: the target exists, but runtime does+not emit the documented target state.++### Theming anatomy++<!-- anatomy-theming:v1 -->++```json+{+ "Handle": {"target": "resize-handle"},+ "Grip pill": {"target": "resize-handle-pill"},+ "Grab zone": {+ "none": {+ "reason": "intentional: The invisible pointer hit area is nonvisual interaction structure and has no public target"+ }+ }+}+```++## Family and system relationships++- `architecture:component-theming-surface` owns anatomy qualification, target+ mapping, and target-state reflection requirements.+- `architecture:interaction-modality` and `architecture:public-component-api`+ own shared modality and API boundaries; this draft changes neither.+- `family:layout-regions` lists useResizable and ResizeHandle as collaborators+ that may drive a LayoutPanel's size. Resizable is not a layout-regions member,+ and that family does not own or redefine resize state, snapping, persistence,+ collapse, pointer, or keyboard semantics.++## Verification map++| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |+| ------------------- | -------------------------------------------------- | ----------------------------------------------- | --------------------------------------------------------------------------------------------------------------- | -------------------------- |+| FR1 | `ResizeHandle.test.tsx` plus source inspection | Default, custom, collapsed, disabled, both axes | Handle and Grab zone regressions fail focused tests; custom Grip replacement currently relies on source review. | `audit:Resizable/anatomy` |+| FR2 | Source inspection and `themingTargets.test.ts` | Handle, Grip pill, and Grab zone | Removing a target or documenting an unshipped Grab zone target fails evidence or inventory. | `audit:Resizable/theming` |+| FR3 | `ResizeHandle.test.tsx` and `useResizable.test.ts` | Pointer, keyboard, snap, collapse, persistence | Moving resize ownership or changing current transformations fails focused behavior coverage. | `audit:Resizable/behavior` |+| FR4 | Source and public metadata comparison | Horizontal and vertical Handle | No current test detects that documented `direction` is absent from runtime target-state reflection. | `audit:Resizable/theming` |+| Theming anatomy map | `scripts/check-knowledge.mjs` | Canonical anatomy and two current targets | Missing, extra, prefixed, stale, or multiply assigned mappings fail repository validation. | `audit:Resizable/theming` |++Current tests exercise Handle and Grab zone structure and behavior but do not+render `children` to prove that custom content replaces Grip pill. That branch is+source-inspected and lacks focused regression evidence. The documented+`direction` visual axis is a closed union, so `extensibleAxes.test.ts` does not+cover its missing runtime reflection; that mismatch is currently unguarded.++## Decision log++None. This draft records current facts and introduces no component-local design,+API, resize, layout-family, or theming decision.++## Open questions++- **OQ1 — Which follow-up should add and verify the missing Handle `direction`+ target-state reflection?** (`checkable`)+- **OQ2 — Which focused test should pin custom content replacing Grip pill?**+ (`checkable`)++## Content boundary++This file does not duplicate consumer prop tables/examples, resize algorithms,+layout-region rules, current audit results, or implementation steps. It links to+their owners.