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.tsxindex 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.mjsindex 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.mdindex 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