Skip to content

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.mjs
index 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.md
new file mode 100644
index 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.mjs
index 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.md
new file mode 100644
index 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.