An open source design system that's fully customizable and agent ready
TypeScript
docs(core): record ComplexSelector and BottomSheet anatomy (#5749)
Cindy Zhang425c803e7518
diff --git a/packages/core/src/BottomSheet/BottomSheet.doc.mjs b/packages/core/src/BottomSheet/BottomSheet.doc.mjsindex b273433628..86e6a59c5c 100644--- a/packages/core/src/BottomSheet/BottomSheet.doc.mjs+++ b/packages/core/src/BottomSheet/BottomSheet.doc.mjs@@ -1,4 +1,33 @@// Copyright (c) Meta Platforms, Inc. and affiliates.++/** @type {import('@astryxdesign/cli/authoring').ComponentAnatomyElement[]} */+const anatomy = [+ {+ name: 'Sheet panel',+ required: true,+ description:+ 'Painted surface that rises from the bottom edge and contains the sheet.',+ },+ {+ name: 'Content area',+ required: true,+ description:+ 'Scrollable area that presents the caller-provided sheet content.',+ },+ {+ name: 'Handle',+ required: true,+ description:+ 'Decorative grab affordance and drag region at the top of the panel.',+ },+ {+ name: 'Scrim',+ required: false,+ description:+ 'Backdrop that dims and blocks the page in a scrim-backed presentation.',+ },+];+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */export const docs = {@@ -126,6 +155,7 @@ export const docs = {},],usage: {+ anatomy,description:'A mobile touch surface for filters, actions, forms, and detail views that should rise from the bottom of the viewport; use BottomSheetSwitcher for multi-step flows.',bestPractices: [@@ -277,6 +307,7 @@ export const docsDense = {description:'mobile touch sheet rising from the bottom edge (native <dialog>): grab handle, opt-in transform-based drag-to-resize snap points (snapPoints: viewport fraction, percent or px length), scrolling area resizes to the snapped visible height on release (a peek stop, a quarter of the sheet or less, keeps the full height and slides instead), Dialog-aligned dismissal purpose (info/form/required), purpose-gated swipe-to-dismiss, fully-expanded Tall visual-viewport mobile-keyboard handling, named height scale, modal (default) or non-modal (hasScrim={false}) presentation',usage: {+ anatomy,description:'Mobile touch surface for filters, actions, forms, and detail views that should rise from the bottom of the viewport; use BottomSheetSwitcher for multi-step flows.',bestPractices: [diff --git a/packages/core/src/BottomSheet/BottomSheet.spec.md b/packages/core/src/BottomSheet/BottomSheet.spec.mdnew file mode 100644index 0000000000..8478109404--- /dev/null+++ b/packages/core/src/BottomSheet/BottomSheet.spec.md@@ -0,0 +1,177 @@+---+schema_version: 1+template_version: 3+kind: component+id: component:BottomSheet+authority: draft+archive_reason: null+superseded_by: null+approved_by: null+approved_at: null+owners: [cixzhang]+review_triggers: [theming]+verified_by:+ [+ packages/core/src/BottomSheet/BottomSheet.test.tsx,+ packages/core/src/BottomSheet/BottomSheetPanel.test.tsx,+ scripts/check-knowledge.mjs,+ ]+families: [family:overlay-dismissal]+design_specs: []+architecture:+ [architecture:component-theming-surface, architecture:layer-runtime]+contributing: []+system_specs: []+---++# BottomSheet component contract++## Intent++BottomSheet presents caller-provided content in a panel that rises from the+bottom edge. This draft records current consumer anatomy and theming reachability+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, 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 visual Sheet panel and its current `bottom-sheet` target.+- The scrolling Content area and decorative Handle inside the panel.+- Standalone sheet presentation, including its optional native-dialog Scrim.++**Does not own / non-goals**++- Caller-provided content rendered inside the Content area.+- A separate target for Content area, Handle, or Scrim; none exists on current+ `main`.+- A shared switcher dialog or scrim — owned by BottomSheetSwitcher when the sheet+ participates in that host.+- Shared layer hosting or dismissal policy.++## Public concepts++No new public concept is introduced. Consumer props and usage remain documented+in `BottomSheet.doc.mjs`.++## Behavioral and layout contract++| ID | Candidate invariant | Basis | Draft review state |+| --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------- | -------------------------------------------------- |+| FR1 | The current presented sheet contains one Sheet panel, one scrolling Content area, and one decorative Handle; a Scrim is present only in scrim-backed presentation. | Current source, docs, and tests | Verified current behavior; no new behavior decided |+| FR2 | The Sheet panel carries `bottom-sheet`; Content area, Handle, and Scrim carry no BottomSheet public target. | Current source, docs, and tests | Verified current behavior; no target change |++### Allowed variation++- Caller-provided children may vary without becoming BottomSheet-owned anatomy.+- Height, snap points, motion phase, and standalone versus switcher hosting may+ vary without changing the four-part anatomy recorded here.++### Representative states++- A standalone modal sheet renders Sheet panel, Content area, Handle, and Scrim.+- A standalone non-modal sheet renders Sheet panel, Content area, and Handle+ without a Scrim.+- A switcher-managed sheet renders the same panel anatomy while+ BottomSheetSwitcher owns the shared dialog and optional Scrim.++### Transformation and precedence order++- No new height, gesture, motion, 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 BottomSheet's existing dialog naming,+focus, Handle, keyboard, or dismissal behavior.++## Design relationships++| Anatomy or state | Design requirement | Representation authority | Hierarchy role | Component contract |+| ---------------- | ------------------------------------------------------------------------------------- | ------------------------------ | -------------- | ------------------ |+| Sheet panel | Presents the painted bottom-edge surface and owns panel geometry and motion. | Current source and public docs | Prominent | FR1, FR2 |+| Content area | Provides the scrolling area for caller-provided sheet content. | Current source and tests | Prominent | FR1, FR2 |+| Handle | Presents the decorative grab affordance and owns the panel's drag interaction region. | Current source and tests | Supporting | FR1, FR2 |+| Scrim | Dims and blocks the page in a scrim-backed host. | Current source and public docs | Supporting | FR1, FR2 |++Content area, Handle, and Scrim 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+{+ "Sheet panel": {"target": "bottom-sheet"},+ "Content area": {+ "none": {+ "reason": "reachability-gap: No current public target reaches the scrolling content area."+ }+ },+ "Handle": {+ "none": {+ "reason": "reachability-gap: No current public target reaches the handle bar or pill."+ }+ },+ "Scrim": {+ "none": {+ "reason": "reachability-gap: No BottomSheet public target reaches the native dialog backdrop or switcher-owned scrim."+ }+ }+}+```++## Family and system relationships++- `architecture:component-theming-surface` owns anatomy qualification, target+ mapping, and factual `none` dispositions.+- `architecture:layer-runtime` owns the current native-dialog host distinction+ and records that sheets retain local scrim and swipe behavior.+- `family:overlay-dismissal` owns shared Escape and platform-close ordering and+ records BottomSheet's current local-only adoption gap. This anatomy backfill+ does not migrate that runtime behavior.++## Verification map++| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |+| ------------------- | ------------------------------------------------------------------------- | ---------------------------------------------- | ----------------------------------------------------------------------------------------------- | --------------------------- |+| FR1 | `BottomSheet.test.tsx` render, content, Handle, and scrim behavior suites | Modal, non-modal, and switcher presentations | Removing a documented part fails existing content, structure, or dismissal assertions. | `audit:BottomSheet/anatomy` |+| FR2 | Panel target assertion, source inspection, and theming target inventories | Sheet panel, Content area, Handle, and Scrim | Removing the panel target or documenting an unshipped child target fails evidence or inventory. | `audit:BottomSheet/theming` |+| Layout evidence | `BottomSheetPanel.test.tsx` | Floating Handle and scrolling Content area | Reordering or merging the stable parts fails existing panel structure and style assertions. | `audit:BottomSheet/anatomy` |+| Theming anatomy map | `scripts/check-knowledge.mjs` | Canonical anatomy and current target inventory | Missing, extra, prefixed, stale, or multiply assigned mappings fail repository validation. | `audit:BottomSheet/theming` |++Existing tests directly assert the Sheet panel target, Content area placement,+Handle structure, and scrim behavior. Source and public target metadata confirm+that the other three parts have no public target.++## Decision log++None. This draft records current facts and introduces no component-local design,+API, theming, or layer-system decision.++## Open questions++- **OQ1 — Should Content area, Handle, or Scrim 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, gesture algorithms,+implementation steps, or shared layer and theming rules. It links to their+owners.diff --git a/packages/core/src/ComplexSelector/ComplexSelector.doc.mjs b/packages/core/src/ComplexSelector/ComplexSelector.doc.mjsindex 711218f55b..00404ad6d2 100644--- a/packages/core/src/ComplexSelector/ComplexSelector.doc.mjs+++ b/packages/core/src/ComplexSelector/ComplexSelector.doc.mjs@@ -9,6 +9,46 @@* SYNC: When modified, update ComplexSelector.tsx, tests, and stories.*/+/** @type {import('@astryxdesign/cli/authoring').ComponentAnatomyElement[]} */+const anatomy = [+ {+ name: 'Field',+ required: true,+ description:+ 'Field shell that provides the label and optional supporting field content.',+ },+ {+ name: 'Trigger',+ required: true,+ description:+ 'Control that displays the current value or placeholder and opens the popup.',+ },+ {+ name: 'Icon-rendered start icon',+ required: false,+ description:+ 'Optional leading semantic icon or icon component rendered through Icon.',+ },+ {+ name: 'Caller-rendered start content',+ required: false,+ description:+ 'Optional arbitrary React content rendered directly at the start of the trigger.',+ },+ {+ name: 'Indicator icon',+ required: true,+ description:+ 'Trailing chevron that rotates to reflect whether the popup is open.',+ },+ {+ name: 'Popup',+ required: true,+ description:+ 'Mounted dialog surface that is painted and shown while open and hidden while closed.',+ },+];+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */export const docs = {@@ -158,6 +198,7 @@ export const docs = {},],usage: {+ anatomy,description:'Use ComplexSelector when a selection needs richer custom content than a Selector option row. It is intentionally one component: ComplexSelector owns the field, trigger, popover, focus restore, and changeAction flow, while the content render prop owns the selector-specific accessible structure.',bestPractices: [@@ -218,6 +259,7 @@ export const docsDense = {description:'Input/ghost trigger + dialog-popover shell for rich custom selectors. Content gets value/onChange/close/state; content owns semantics. Use focus hooks and evaluate custom content against WCAG 2.2.',usage: {+ anatomy,description:'Use when a selection needs richer custom content than a Selector row. One component: it owns field, trigger, popover, focus restore, and changeAction; the render prop owns the selector-specific accessible structure.',bestPractices: [diff --git a/packages/core/src/ComplexSelector/ComplexSelector.spec.md b/packages/core/src/ComplexSelector/ComplexSelector.spec.mdnew file mode 100644index 0000000000..0b9a3f6051--- /dev/null+++ b/packages/core/src/ComplexSelector/ComplexSelector.spec.md@@ -0,0 +1,189 @@+---+schema_version: 1+template_version: 3+kind: component+id: component:ComplexSelector+authority: draft+archive_reason: null+superseded_by: null+approved_by: null+approved_at: null+owners: [cixzhang]+review_triggers: [theming]+verified_by:+ [+ packages/core/src/ComplexSelector/ComplexSelector.test.tsx,+ packages/core/src/Field/Field.test.tsx,+ packages/core/src/Icon/Icon.test.tsx,+ scripts/check-knowledge.mjs,+ ]+families: [family:overlay-dismissal]+design_specs: []+architecture:+ [architecture:component-theming-surface, architecture:layer-runtime]+contributing: []+system_specs: []+---++# ComplexSelector component contract++## Intent++ComplexSelector renders a field-owned shell, an owned trigger, and a dialog+popup for caller-provided rich selection content. 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, 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 trigger and its current `complex-selector` target.+- The trailing indicator icon and its current+ `complex-selector-indicator-icon` target.+- The painted popup surface and its current `complex-selector-popup` target.++**Does not own / non-goals**++- Field-shell presentation — rendered by Field and themed through Field's+ current `field` target.+- General Icon presentation — rendered by Icon for semantic icon names and icon+ component types and themed through Icon's current `icon` target.+- Arbitrary ReactNode content supplied through `startIcon` — rendered directly+ and owned by the product callsite.+- The selector-specific structure supplied through `children` — owned by the+ product callsite.+- Shared layer lifecycle, positioning, and dismissal behavior.++## Public concepts++No new public concept is introduced. Consumer props and usage remain documented+in `ComplexSelector.doc.mjs`.++## Behavioral and layout contract++| ID | Candidate invariant | Basis | Draft review state |+| --- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------- | -------------------------------------------------- |+| FR1 | The current render contains a Field, Trigger, Indicator icon, and mounted Popup; one optional start slot may contain either an Icon-rendered start icon or caller-rendered start content. | Current source, docs, and tests | Verified current behavior; no new behavior decided |+| FR2 | Trigger, Indicator icon, and Popup carry `complex-selector`, `complex-selector-indicator-icon`, and `complex-selector-popup`, respectively. | Current source, docs, and tests | Verified current behavior; no target change |+| FR3 | Field delegates to Field's `field` target, and a semantic name or icon component in the start slot delegates to Icon's `icon` target. | Current source and owner tests | Verified current behavior; no target change |+| FR4 | Arbitrary ReactNode start content renders directly and carries no ComplexSelector-owned target. | Current source | Verified current behavior; no target change |++### Allowed variation++- Caller-provided popup content may vary without becoming a new+ ComplexSelector-owned anatomy part or target.+- The optional start slot has two factual branches: semantic names and icon+ component types render through Icon, while arbitrary ReactNode content renders+ directly under caller ownership.++### Representative states++- Input and ghost variants use the same six-part anatomy and current targets.+- The start slot is absent when `startIcon` is omitted. When present, exactly+ one of Icon-rendered start icon or Caller-rendered start content applies.+- The Popup remains mounted in both states: it is hidden while closed and shown+ while open. The Indicator icon remains present and reflects collapsed or+ expanded state on its current target.++### Transformation and precedence order++- No new value, open-state, positioning, or style precedence rule is introduced.++### Performance and resources++- No new performance or resource rule is introduced.++## Accessibility contract++This draft does not change or extend ComplexSelector's existing field, trigger,+dialog, focus, or keyboard behavior.++## Design relationships++| Anatomy or state | Design requirement | Representation authority | Hierarchy role | Component contract |+| ----------------------------- | -------------------------------------------------------------------------------- | ------------------------------ | ----------------- | ------------------ |+| Field | Provides the field shell around the owned trigger. | Field component | Supporting | FR1, FR3 |+| Trigger | Displays the current value or placeholder and opens the popup. | Current source and public docs | Prominent | FR1, FR2 |+| Icon-rendered start icon | Optionally presents a semantic or component icon through Icon. | Icon component | Supporting | FR1, FR3 |+| Caller-rendered start content | Optionally presents arbitrary React content directly in the start slot. | Caller-supplied content | Context-dependent | FR1, FR4 |+| Indicator icon | Presents the trailing disclosure glyph and reflects collapsed or expanded state. | Current source and public docs | Supporting | FR1, FR2 |+| Popup | Keeps the dialog surface mounted, hidden while closed and painted while open. | Current source and public docs | Prominent | FR1, FR2 |++The Field and Icon delegations preserve their existing owners. Arbitrary+ReactNode start content remains caller-owned and receives no local target. The+local Indicator icon target remains distinct because it carries the selector's+expanded/collapsed state and rotation on the glyph itself. Caller-provided popup+content remains outside the owned anatomy inventory.++### Theming anatomy++<!-- anatomy-theming:v1 -->++```json+{+ "Field": {"delegatesTo": {"owner": "component:Field", "target": "field"}},+ "Trigger": {"target": "complex-selector"},+ "Icon-rendered start icon": {+ "delegatesTo": {"owner": "component:Icon", "target": "icon"}+ },+ "Caller-rendered start content": {+ "none": {+ "reason": "intentional: Arbitrary ReactNode content is caller-owned and receives no ComplexSelector target."+ }+ },+ "Indicator icon": {"target": "complex-selector-indicator-icon"},+ "Popup": {"target": "complex-selector-popup"}+}+```++## Family and system relationships++- `architecture:component-theming-surface` owns anatomy qualification, local+ target mapping, and delegation rules.+- `architecture:layer-runtime` owns the current `usePopover` host, positioning,+ native light-dismiss, and visibility reconciliation used by the Popup.+- `family:overlay-dismissal` owns shared Escape and platform-close ordering;+ ComplexSelector participates through its composed Popover owner.+- Field and Icon retain ownership of their delegated targets and presentation.++## Verification map++| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |+| ------------------- | -------------------------------------------------------------------------- | ------------------------------------------------ | --------------------------------------------------------------------------------------------- | ------------------------------- |+| FR1 | `ComplexSelector.test.tsx` render, ghost-trigger, and popup suites | Default closed, ghost start branches, open Popup | Removing a documented part fails existing role, content, or structure assertions. | `audit:ComplexSelector/anatomy` |+| FR2 | Component target suites, source inspection, and theming target inventories | Closed/open Popup; expanded Indicator icon | Removing or renaming a current local target fails component assertions or target inventories. | `audit:ComplexSelector/theming` |+| FR3, FR4 | Icon owner tests and `renderIconSlot` source inspection | Semantic/component icon; arbitrary ReactNode | A branch gains the wrong owner, loses its target, or receives an invented local target. | `audit:ComplexSelector/theming` |+| Theming anatomy map | `scripts/check-knowledge.mjs` | Canonical anatomy and current local targets | Missing, extra, prefixed, stale, or multiply assigned mappings fail repository validation. | `audit:ComplexSelector/theming` |++Current component tests directly assert the Trigger and Popup targets. Source+inspection confirms that non-lazy `useLayer` keeps the Popup mounted while+closed. The Indicator icon target is covered by source inspection and shared+target inventories rather than a dedicated component assertion. `renderIconSlot`+and Icon owner tests distinguish the Icon-rendered branch from arbitrary+caller-owned ReactNode content.++## Decision log++None. This draft records current facts and introduces no component-local design,+API, theming, or layer-system decision.++## Open questions++None.++## Content boundary++This file does not duplicate consumer prop tables, examples, caller-provided+popup structure, implementation steps, or shared layer and theming rules. It+links to their owners.