Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

docs: map Selector theming anatomy (#5781)

Cindy Zhang9eeb4abcd27f
diff --git a/apps/storybook/stories/Selector.stories.tsx b/apps/storybook/stories/Selector.stories.tsx
index 14060a11c8..b2c9c8e6ab 100644
--- a/apps/storybook/stories/Selector.stories.tsx
+++ b/apps/storybook/stories/Selector.stories.tsx
@@ -969,10 +969,11 @@ export const StatusVariantComparison: Story = {
/**
* Theme the clear and chevron glyphs precisely via `defineTheme`.
*
- * - `components['selector-clear-icon'].base` scopes overrides to the clear icon
- * itself (via the `astryx-selector-clear-icon` target), so a theme can
- * recolor it, morph its color on hover, and resize it — without a fragile
- * descendant selector or raw CSS.
+ * - `components['input-clear-icon'].base` scopes overrides to the clear icon
+ * itself (via the shared canonical `astryx-input-clear-icon` target), so a
+ * theme can recolor it, morph its color on hover, and resize it — without a
+ * fragile descendant selector or raw CSS. Selector still emits
+ * `astryx-selector-clear-icon` only as a deprecated compatibility alias.
* - `components['selector-indicator-icon']` scopes overrides to the chevron,
* and its `state:expanded` restyles the open state, which the icon reflects
* as a `data-state` attribute.
@@ -983,7 +984,7 @@ export const StatusVariantComparison: Story = {
const iconTheme = defineTheme({
name: 'selector-icon-demo',
components: {
- 'selector-clear-icon': {
+ 'input-clear-icon': {
base: {
width: '12px',
height: '12px',
diff --git a/packages/core/src/Selector/Selector.doc.mjs b/packages/core/src/Selector/Selector.doc.mjs
index d8d62937bc..e73456886e 100644
--- a/packages/core/src/Selector/Selector.doc.mjs
+++ b/packages/core/src/Selector/Selector.doc.mjs
@@ -1,5 +1,127 @@
// Copyright (c) Meta Platforms, Inc. and affiliates.
+/** @type {import('@astryxdesign/cli/authoring').ComponentAnatomyElement[]} */
+const anatomy = [
+ {
+ name: 'Field',
+ required: false,
+ description:
+ 'Standalone Field shell that provides the label and optional supporting content; omitted inside InputGroup.',
+ },
+ {
+ name: 'Trigger',
+ required: true,
+ description:
+ 'Painted control that displays the current selection or placeholder and opens the selection surface.',
+ },
+ {
+ 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: 'Trigger clear button',
+ required: false,
+ description:
+ 'Shared clear action that removes the selected value when hasClear is enabled.',
+ },
+ {
+ name: 'Status icon',
+ required: false,
+ description:
+ 'Status glyph shown in place of the disclosure indicator for attached or tooltip status.',
+ },
+ {
+ name: 'Indicator icon',
+ required: false,
+ description:
+ 'Trailing chevron shown when status presentation does not replace it; reflects collapsed or expanded state.',
+ },
+ {
+ name: 'Search row',
+ required: false,
+ description:
+ 'Panel header with a borderless search input and optional clear action.',
+ },
+ {
+ name: 'Search icon',
+ required: false,
+ description:
+ 'Leading magnifier rendered through Icon inside the search row.',
+ },
+ {
+ name: 'Search clear button',
+ required: false,
+ description:
+ 'Shared clear action shown in the search row while a query is present.',
+ },
+ {
+ name: 'Option row',
+ required: false,
+ description: 'Selectable row for one supplied option.',
+ },
+ {
+ name: 'SelectorOption-rendered content',
+ required: false,
+ description:
+ 'Option content rendered with SelectorOption, either by the default renderer or by renderOption when it returns SelectorOption.',
+ },
+ {
+ name: 'Bare caller-rendered option content',
+ required: false,
+ description:
+ 'Arbitrary content returned directly by renderOption without opting into SelectorOption.',
+ },
+ {
+ name: 'Option selection indicator',
+ required: false,
+ description:
+ 'Resolved selection mark rendered for each option in its checked or unchecked state.',
+ },
+ {
+ name: 'Option divider',
+ required: false,
+ description:
+ 'Divider supplied in the public options data to separate adjacent option groups.',
+ },
+ {
+ name: 'Section heading',
+ required: false,
+ description: 'Visible heading for a labeled group of option rows.',
+ },
+ {
+ name: 'Empty state',
+ required: false,
+ description:
+ 'Message shown when the shared panel content has no options or no search matches.',
+ },
+ {
+ name: 'Pointer popup',
+ required: false,
+ description:
+ 'Anchored painted surface that hosts the shared panel content for popover presentation.',
+ },
+ {
+ name: 'Touch sheet heading',
+ required: false,
+ description:
+ 'Heading above the shared panel content in bottom-sheet presentation.',
+ },
+ {
+ name: 'Touch sheet',
+ required: false,
+ description:
+ 'BottomSheet surface that hosts the same panel content for bottom-sheet presentation.',
+ },
+];
+
/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
export const docs = {
@@ -296,38 +418,7 @@ export const docs = {
'Wrap a disabled Selector in Tooltip to explain why it is disabled; disabled triggers swallow the hover events the wrapper needs. Use the disabledMessage prop instead.',
},
],
- anatomy: [
- {
- name: 'Label',
- required: false,
- description: 'Text label displayed above the selector.',
- },
- {
- name: 'Placeholder',
- required: false,
- description: 'Hint text shown when no value is selected.',
- },
- {
- name: 'Description',
- required: false,
- description: 'Helper text providing additional context.',
- },
- {
- name: 'Left Icon',
- required: false,
- description: 'Icon displayed to the left of the selected value.',
- },
- {
- name: 'Value',
- required: true,
- description: 'The currently selected item displayed in the selector.',
- },
- {
- name: 'List',
- required: true,
- description: 'The dropdown list of selectable options.',
- },
- ],
+ anatomy,
},
};
@@ -388,38 +479,7 @@ export const docsZh = {
'Wrap a disabled Selector in Tooltip to explain why it is disabled; disabled triggers swallow the hover events the wrapper needs. Use the disabledMessage prop instead.',
},
],
- anatomy: [
- {
- name: 'Label',
- required: false,
- description: 'Text label displayed above the selector.',
- },
- {
- name: 'Placeholder',
- required: false,
- description: 'Hint text shown when no value is selected.',
- },
- {
- name: 'Description',
- required: false,
- description: 'Helper text providing additional context.',
- },
- {
- name: 'Left Icon',
- required: false,
- description: 'Icon displayed to the left of the selected value.',
- },
- {
- name: 'Value',
- required: true,
- description: 'The currently selected item displayed in the selector.',
- },
- {
- name: 'List',
- required: true,
- description: 'The dropdown list of selectable options.',
- },
- ],
+ anatomy,
},
};
@@ -490,37 +550,6 @@ export const docsDense = {
'Wrap a disabled Selector in Tooltip to explain why it is disabled; disabled triggers swallow the hover events the wrapper needs. Use the disabledMessage prop instead.',
},
],
- anatomy: [
- {
- name: 'Label',
- required: false,
- description: 'Text label displayed above the selector.',
- },
- {
- name: 'Placeholder',
- required: false,
- description: 'Hint text shown when no value is selected.',
- },
- {
- name: 'Description',
- required: false,
- description: 'Helper text providing additional context.',
- },
- {
- name: 'Left Icon',
- required: false,
- description: 'Icon displayed to the left of the selected value.',
- },
- {
- name: 'Value',
- required: true,
- description: 'The currently selected item displayed in the selector.',
- },
- {
- name: 'List',
- required: true,
- description: 'The dropdown list of selectable options.',
- },
- ],
+ anatomy,
},
};
diff --git a/packages/core/src/Selector/Selector.spec.md b/packages/core/src/Selector/Selector.spec.md
index 2ec55e8503..e736be185f 100644
--- a/packages/core/src/Selector/Selector.spec.md
+++ b/packages/core/src/Selector/Selector.spec.md
@@ -164,6 +164,82 @@ No current design spec is linked.
The approved but unimplemented replacement for the first row is owned by
`spec:AST-004/DEC-1`.
+### Theming anatomy
+
+<!-- anatomy-theming:v1 -->
+
+```json
+{
+ "Field": {"delegatesTo": {"owner": "component:Field", "target": "field"}},
+ "Trigger": {"target": "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 Selector target."
+ }
+ },
+ "Trigger clear button": {
+ "delegatesTo": {
+ "owner": "component:Field",
+ "target": "input-clear-button"
+ }
+ },
+ "Status icon": {
+ "delegatesTo": {"owner": "component:Icon", "target": "icon"}
+ },
+ "Indicator icon": {"target": "selector-indicator-icon"},
+ "Search row": {"target": "selector-search"},
+ "Search icon": {
+ "delegatesTo": {"owner": "component:Icon", "target": "icon"}
+ },
+ "Search clear button": {
+ "delegatesTo": {
+ "owner": "component:Field",
+ "target": "input-clear-button"
+ }
+ },
+ "Option row": {"target": "selector-option-row"},
+ "SelectorOption-rendered content": {"target": "selector-option"},
+ "Bare caller-rendered option content": {
+ "none": {
+ "reason": "intentional: Bare custom renderOption content is caller-owned and does not receive the SelectorOption target."
+ }
+ },
+ "Option selection indicator": {"target": "selector-check"},
+ "Option divider": {
+ "delegatesTo": {"owner": "component:Divider", "target": "divider"}
+ },
+ "Section heading": {"target": "selector-section-heading"},
+ "Empty state": {"target": "selector-empty-state"},
+ "Pointer popup": {"target": "selector-popup"},
+ "Touch sheet heading": {
+ "delegatesTo": {"owner": "component:Text", "target": "heading"}
+ },
+ "Touch sheet": {
+ "delegatesTo": {
+ "owner": "component:BottomSheet",
+ "target": "bottom-sheet"
+ }
+ }
+}
+```
+
+`Field` is conditional: standalone Selector renders it, while InputGroup owns
+that surrounding shell. `Pointer popup` and the two touch-sheet parts are
+alternative presentations of the same panel content, not simultaneous anatomy.
+Icon-rendered start content delegates to Icon; arbitrary `ReactNode` start content
+is caller-owned. The default renderer and custom `renderOption` functions that
+return `SelectorOption` retain its target; only bare caller-rendered option
+content stays outside that target, while the targeted option row remains.
+`selector-clear-icon` remains a deprecated compatibility alias and does not own a
+current anatomy row.
+
+This map records only shipped reachability. It does not treat the accepted,
+unimplemented option-source behavior in `spec:AST-001` or indicator-space change
+in `spec:AST-004` as current runtime behavior.
+
## Family and system relationships
- The current architecture links in frontmatter own public API, theming, icon