@astryxdesign/core 0.5.2-canary.457de8d → 0.5.2-canary.51c960c

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astryxdesign/core",
-  "version": "0.5.2-canary.457de8d",
+  "version": "0.5.2-canary.51c960c",
   "displayName": "Astryx Core",
   "description": "The component library. Accessible, themeable React components with built-in spacing, dark mode, and StyleX styling.",
   "author": "Meta Open Source",
@@ -661,7 +661,7 @@
     "react-dom": ">=19.0.0"
   },
   "devDependencies": {
-    "@astryxdesign/cli": "0.5.2-canary.457de8d",
+    "@astryxdesign/cli": "0.5.2-canary.51c960c",
     "@babel/cli": "^8.0.4",
     "@babel/core": "^7.29.7",
     "@babel/preset-react": "^8.0.1",

package/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: [

package/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.

package/src/CheckboxList/CheckboxList.doc.mjs

@@ -1,5 +1,64 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
+/** @type {import('@astryxdesign/cli/authoring').ComponentAnatomyElement[]} */
+const anatomy = [
+  {
+    name: 'Group',
+    required: true,
+    description: 'Container for the labeled checkbox group.',
+  },
+  {
+    name: 'Group label',
+    required: true,
+    description: 'Text identifying what the checkbox options represent.',
+  },
+  {
+    name: 'Description',
+    required: false,
+    description: 'Helper text below the group label.',
+  },
+  {
+    name: 'Options list',
+    required: true,
+    description: 'List containing the available checkbox options.',
+  },
+  {
+    name: 'Option row',
+    required: true,
+    description: 'Selectable row containing one option.',
+  },
+  {
+    name: 'Checkbox',
+    required: true,
+    description: 'Selection indicator for an option.',
+  },
+  {
+    name: 'Option label',
+    required: true,
+    description: 'Primary content identifying an option.',
+  },
+  {
+    name: 'Option description',
+    required: false,
+    description: 'Secondary text below an option label.',
+  },
+  {
+    name: 'End content',
+    required: false,
+    description: 'Caller-provided content at the end of an option row.',
+  },
+  {
+    name: 'Spinner',
+    required: false,
+    description: 'Loading indicator shown inside the pending checkbox.',
+  },
+  {
+    name: 'Status message',
+    required: false,
+    description: 'Error, warning, or success message below the group.',
+  },
+];
+
 /** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 
 export const docs = {
@@ -8,13 +67,22 @@ export const docs = {
   group: 'Checkbox',
   category: 'Form Controls',
   isHiddenFromOverview: true,
-  keywords: ["checkboxlist","checkbox","checkboxgroup","multichoice","multiselect","checklist"],
-  description: 'Checkbox group container with field integration for label, description, and status.',
+  keywords: [
+    'checkboxlist',
+    'checkbox',
+    'checkboxgroup',
+    'multichoice',
+    'multiselect',
+    'checklist',
+  ],
+  description:
+    'Checkbox group container with field integration for label, description, and status.',
   props: [
     {
       name: 'label',
       type: 'string',
-      description: 'Label text for the checkbox group (always rendered for accessibility).',
+      description:
+        'Label text for the checkbox group (always rendered for accessibility).',
       required: true,
     },
     {
@@ -97,41 +165,89 @@ export const docs = {
     {
       name: 'xstyle',
       type: 'StyleXStyles',
-      description: 'StyleX styles for layout customization. Must be a stylex.create() value.',
+      description:
+        'StyleX styles for layout customization. Must be a stylex.create() value.',
     },
   ],
-  components: [
-    {name: 'CheckboxListItem'},
-  ],
+  components: [{name: 'CheckboxListItem'}],
   usage: {
-    description: 'CheckboxList shows a small group of checkboxes so users can turn several options on or off at once. Place it in settings pages, filter panels, or forms where every choice should be visible without scrolling. For a single standalone checkbox (like "I agree to the terms"), use CheckboxInput instead. If only one option can be picked, use RadioList. If the list is long enough to need searching or scrolling, use MultiSelector instead.',
+    anatomy,
+    description:
+      'CheckboxList shows a small group of checkboxes so users can turn several options on or off at once. Place it in settings pages, filter panels, or forms where every choice should be visible without scrolling. For a single standalone checkbox (like "I agree to the terms"), use CheckboxInput instead. If only one option can be picked, use RadioList. If the list is long enough to need searching or scrolling, use MultiSelector instead.',
     bestPractices: [
-      { guidance: true, description: 'Keep the list short: three to seven options is the sweet spot. Beyond that, switch to MultiSelector which adds search and scrolling.' },
-      { guidance: true, description: 'Turn on dividers (hasDividers) when items have helper text underneath; without them the labels and descriptions blur together.' },
-      { guidance: true, description: 'Write a group label that says what the choices represent: "Export formats" tells users more than "Options".' },
-      { guidance: false, description: 'Show a CheckboxList when the user can only pick one thing; that is what RadioList is for.' },
-      { guidance: false, description: 'Put buttons or links inside the trailing slot (endContent); the whole row is already tappable, so a nested button creates two competing click targets.' },
-      { guidance: false, description: 'Wrap a disabled CheckboxList in Tooltip to explain why it is disabled; disabled controls swallow the hover events the wrapper needs. Use the disabledMessage prop instead.' },
+      {
+        guidance: true,
+        description:
+          'Keep the list short: three to seven options is the sweet spot. Beyond that, switch to MultiSelector which adds search and scrolling.',
+      },
+      {
+        guidance: true,
+        description:
+          'Turn on dividers (hasDividers) when items have helper text underneath; without them the labels and descriptions blur together.',
+      },
+      {
+        guidance: true,
+        description:
+          'Write a group label that says what the choices represent: "Export formats" tells users more than "Options".',
+      },
+      {
+        guidance: false,
+        description:
+          'Show a CheckboxList when the user can only pick one thing; that is what RadioList is for.',
+      },
+      {
+        guidance: false,
+        description:
+          'Put buttons or links inside the trailing slot (endContent); the whole row is already tappable, so a nested button creates two competing click targets.',
+      },
+      {
+        guidance: false,
+        description:
+          'Wrap a disabled CheckboxList in Tooltip to explain why it is disabled; disabled controls swallow the hover events the wrapper needs. Use the disabledMessage prop instead.',
+      },
     ],
   },
   theming: {
-    targets: [
-      {className: 'astryx-checkbox-list'},
-    ],
+    targets: [{className: 'astryx-checkbox-list'}],
   },
 };
 
 /** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsZh = {
   usage: {
-    description: 'CheckboxList shows a small group of checkboxes so users can turn several options on or off at once. Place it in settings pages, filter panels, or forms where every choice should be visible without scrolling. For a single standalone checkbox (like "I agree to the terms"), use CheckboxInput instead. If only one option can be picked, use RadioList. If the list is long enough to need searching or scrolling, use MultiSelector instead.',
+    description:
+      'CheckboxList shows a small group of checkboxes so users can turn several options on or off at once. Place it in settings pages, filter panels, or forms where every choice should be visible without scrolling. For a single standalone checkbox (like "I agree to the terms"), use CheckboxInput instead. If only one option can be picked, use RadioList. If the list is long enough to need searching or scrolling, use MultiSelector instead.',
     bestPractices: [
-      { guidance: true, description: 'Keep the list short: three to seven options is the sweet spot. Beyond that, switch to MultiSelector which adds search and scrolling.' },
-      { guidance: true, description: 'Turn on dividers (hasDividers) when items have helper text underneath; without them the labels and descriptions blur together.' },
-      { guidance: true, description: 'Write a group label that says what the choices represent: "Export formats" tells users more than "Options".' },
-      { guidance: false, description: 'Show a CheckboxList when the user can only pick one thing; that is what RadioList is for.' },
-      { guidance: false, description: 'Put buttons or links inside the trailing slot (endContent); the whole row is already tappable, so a nested button creates two competing click targets.' },
-      { guidance: false, description: 'Wrap a disabled CheckboxList in Tooltip to explain why it is disabled; disabled controls swallow the hover events the wrapper needs. Use the disabledMessage prop instead.' },
+      {
+        guidance: true,
+        description:
+          'Keep the list short: three to seven options is the sweet spot. Beyond that, switch to MultiSelector which adds search and scrolling.',
+      },
+      {
+        guidance: true,
+        description:
+          'Turn on dividers (hasDividers) when items have helper text underneath; without them the labels and descriptions blur together.',
+      },
+      {
+        guidance: true,
+        description:
+          'Write a group label that says what the choices represent: "Export formats" tells users more than "Options".',
+      },
+      {
+        guidance: false,
+        description:
+          'Show a CheckboxList when the user can only pick one thing; that is what RadioList is for.',
+      },
+      {
+        guidance: false,
+        description:
+          'Put buttons or links inside the trailing slot (endContent); the whole row is already tappable, so a nested button creates two competing click targets.',
+      },
+      {
+        guidance: false,
+        description:
+          'Wrap a disabled CheckboxList in Tooltip to explain why it is disabled; disabled controls swallow the hover events the wrapper needs. Use the disabledMessage prop instead.',
+      },
     ],
   },
 };
@@ -141,14 +257,39 @@ export const docsDense = {
   description:
     'Checkbox group component for multi-value selection. Collection mode (parent state) + standalone mode (per-item state).',
   usage: {
-    description: 'CheckboxList shows a small group of checkboxes so users can turn several options on or off at once. Place it in settings pages, filter panels, or forms where every choice should be visible without scrolling. For a single standalone checkbox (like "I agree to the terms"), use CheckboxInput instead. If only one option can be picked, use RadioList. If the list is long enough to need searching or scrolling, use MultiSelector instead.',
+    description:
+      'CheckboxList shows a small group of checkboxes so users can turn several options on or off at once. Place it in settings pages, filter panels, or forms where every choice should be visible without scrolling. For a single standalone checkbox (like "I agree to the terms"), use CheckboxInput instead. If only one option can be picked, use RadioList. If the list is long enough to need searching or scrolling, use MultiSelector instead.',
     bestPractices: [
-      { guidance: true, description: 'Keep the list short: three to seven options is the sweet spot. Beyond that, switch to MultiSelector which adds search and scrolling.' },
-      { guidance: true, description: 'Turn on dividers (hasDividers) when items have helper text underneath; without them the labels and descriptions blur together.' },
-      { guidance: true, description: 'Write a group label that says what the choices represent: "Export formats" tells users more than "Options".' },
-      { guidance: false, description: 'Show a CheckboxList when the user can only pick one thing; that is what RadioList is for.' },
-      { guidance: false, description: 'Put buttons or links inside the trailing slot (endContent); the whole row is already tappable, so a nested button creates two competing click targets.' },
-      { guidance: false, description: 'Wrap a disabled CheckboxList in Tooltip to explain why it is disabled; disabled controls swallow the hover events the wrapper needs. Use the disabledMessage prop instead.' },
+      {
+        guidance: true,
+        description:
+          'Keep the list short: three to seven options is the sweet spot. Beyond that, switch to MultiSelector which adds search and scrolling.',
+      },
+      {
+        guidance: true,
+        description:
+          'Turn on dividers (hasDividers) when items have helper text underneath; without them the labels and descriptions blur together.',
+      },
+      {
+        guidance: true,
+        description:
+          'Write a group label that says what the choices represent: "Export formats" tells users more than "Options".',
+      },
+      {
+        guidance: false,
+        description:
+          'Show a CheckboxList when the user can only pick one thing; that is what RadioList is for.',
+      },
+      {
+        guidance: false,
+        description:
+          'Put buttons or links inside the trailing slot (endContent); the whole row is already tappable, so a nested button creates two competing click targets.',
+      },
+      {
+        guidance: false,
+        description:
+          'Wrap a disabled CheckboxList in Tooltip to explain why it is disabled; disabled controls swallow the hover events the wrapper needs. Use the disabledMessage prop instead.',
+      },
     ],
   },
 };