An open source design system that's fully customizable and agent ready
TypeScript
fix(Collapsible): expose theme states and document ownership (#6933)
Cindy Zhang6802a9fde0a7
diff --git a/.changeset/collapsible-audit-theming.md b/.changeset/collapsible-audit-theming.mdnew file mode 100644index 0000000000..38a497f77e--- /dev/null+++ b/.changeset/collapsible-audit-theming.md@@ -0,0 +1,7 @@+---+'@astryxdesign/core': patch+---++[fix] Expose Collapsible open, disabled, position, and divided states to themes, and document grouped state ownership and root customization.++@cixzhangdiff --git a/packages/core/src/Collapsible/Collapsible.doc.mjs b/packages/core/src/Collapsible/Collapsible.doc.mjsindex 998b6ea398..55a13f2758 100644--- a/packages/core/src/Collapsible/Collapsible.doc.mjs+++ b/packages/core/src/Collapsible/Collapsible.doc.mjs@@ -16,9 +16,21 @@ export const docs = {},theming: {targets: [- {className: 'astryx-collapsible', visualProps: ['density']},- {className: 'astryx-collapsible-trigger', visualProps: ['density']},- {className: 'astryx-collapsible-content', visualProps: ['density']},+ {+ className: 'astryx-collapsible',+ visualProps: ['density'],+ states: ['divided'],+ },+ {+ className: 'astryx-collapsible-trigger',+ visualProps: ['density', 'chevronPosition'],+ states: ['open', 'disabled'],+ },+ {+ className: 'astryx-collapsible-content',+ visualProps: ['density'],+ states: ['open'],+ },{className: 'astryx-collapsible-group', visualProps: ['density']},],},@@ -47,13 +59,15 @@ export const docs = {{name: 'defaultIsOpen',type: 'boolean',- description: 'Default open state (uncontrolled).',+ description:+ 'Default open state for standalone uncontrolled usage. Ignored when value binds the item to a surrounding CollapsibleGroup.',default: 'true',},{name: 'isOpen',type: 'boolean',- description: 'Controlled open state.',+ description:+ 'Controlled open state for standalone usage. Ignored when value binds the item to a surrounding CollapsibleGroup.',},{name: 'isDisabled',@@ -64,7 +78,8 @@ export const docs = {{name: 'onOpenChange',type: '(isOpen: boolean) => void',- description: 'Callback invoked when the open state changes.',+ description:+ 'Callback invoked when standalone open state changes. A surrounding CollapsibleGroup owns grouped state and calls its onChange instead.',},{name: 'chevronPosition',@@ -75,7 +90,36 @@ export const docs = {{name: 'value',type: 'string',- description: 'Identifier used for group coordination. Required when placed inside an CollapsibleGroup.',+ description:+ 'Identifier used for group coordination. When set inside a CollapsibleGroup, the group owns open state and its onChange is the notification callback.',+ },+ {+ name: 'ref',+ type: 'React.Ref<HTMLDivElement>',+ description: 'Ref forwarded to the root collapsible element.',+ },+ {+ name: 'xstyle',+ type: 'StyleXStyles',+ description:+ 'StyleX styles for layout customization. Must be a stylex.create() value.',+ },+ {+ name: 'className',+ type: 'string',+ description:+ 'CSS class name for the root element. Prefer xstyle for styling.',+ },+ {+ name: 'style',+ type: 'CSSProperties',+ description:+ 'Inline styles. Prefer xstyle for StyleX-optimized styling.',+ },+ {+ name: 'data-testid',+ type: 'string',+ description: 'Test selector for automated testing frameworks.',},],components: [@@ -95,6 +139,7 @@ export const docs = {],description: 'Collapsible hides and reveals content behind a trigger button. Use it in settings panels, FAQ pages, or detail views to keep the page scannable while letting users drill into sections they care about. Wrap multiple collapsibles in CollapsibleGroup for accordion behavior. For custom collapsible components, use the `useCollapsible` hook directly (`astryx hook useCollapsible`).',bestPractices: [+ { guidance: true, description: 'Give every trigger a meaningful accessible name. Visible text usually supplies it; custom trigger content should include VisuallyHidden text when its visuals do not.' },{ guidance: true, description: 'Use hasDividers on CollapsibleGroup for FAQ-style lists: built-in row hairlines with themed border tokens, no hand-rolled borders.' },{ guidance: true, description: 'Wrap each Collapsible in an Card for visual separation in accordion layouts, or use CollapsibleGroup\'s hasDividers for flat lists; don\'t combine both.' },{ guidance: true, description: 'Use CollapsibleGroup with type="single" for settings or FAQ pages where only one section should be open at a time.' },@@ -105,9 +150,11 @@ export const docs = {{ guidance: false, description: 'Use a collapsible for a single short paragraph; just show the text directly instead.' },],anatomy: [+ { name: 'Container', required: true, description: 'The root that contains one trigger and its controlled content and, in a divided group, paints the item divider.' },{ name: 'Trigger', required: true, description: 'The always-visible button that toggles the content. Shows a label and a chevron indicator.' },{ name: 'Chevron', required: false, description: 'Animated disclosure arrow. It follows the label by default; chevronPosition="start" moves it ahead of the label, points inward when collapsed (mirrored under RTL), and turns down when expanded.' },{ name: 'Content', required: false, description: 'The area that hides or reveals when the trigger is clicked.' },+ { name: 'Group container', required: false, description: 'The CollapsibleGroup wrapper rendered when dividers are enabled. It contains the coordinated items and carries their density.' },],},};@@ -117,6 +164,7 @@ export const docsZh = {usage: {description: 'Collapsible hides and reveals content behind a trigger button. Use it in settings panels, FAQ pages, or detail views to keep the page scannable while letting users drill into sections they care about. Wrap multiple collapsibles in CollapsibleGroup for accordion behavior.',bestPractices: [+ { guidance: true, description: '确保每个触发器都有有意义的无障碍名称。可见文本通常可提供名称;若自定义视觉内容无法提供名称,请加入 VisuallyHidden 文本。' },{ guidance: true, description: 'Use hasDividers on CollapsibleGroup for FAQ-style lists: built-in row hairlines with themed border tokens, no hand-rolled borders.' },{ guidance: true, description: 'Wrap each Collapsible in an Card for visual separation in accordion layouts, or use CollapsibleGroup\'s hasDividers for flat lists; don\'t combine both.' },{ guidance: true, description: 'Use CollapsibleGroup with type="single" for settings or FAQ pages where only one section should be open at a time.' },@@ -135,6 +183,7 @@ export const docsDense = {usage: {description: 'Collapsible hides and reveals content behind a trigger button. Use in settings, FAQs, or detail views. Wrap in CollapsibleGroup for accordion behavior.',bestPractices: [+ { guidance: true, description: 'Give every trigger a meaningful accessible name; add VisuallyHidden text when custom visuals do not.' },{ guidance: true, description: 'Use hasDividers on CollapsibleGroup for FAQ-style lists: built-in row hairlines, no hand-rolled borders.' },{ guidance: true, description: 'Wrap each Collapsible in an Card for visual separation, or use CollapsibleGroup\'s hasDividers for flat lists; not both.' },{ guidance: true, description: 'Use CollapsibleGroup with type="single" for settings or FAQ pages where only one section should be open at a time.' },diff --git a/packages/core/src/Collapsible/Collapsible.spec.md b/packages/core/src/Collapsible/Collapsible.spec.mdindex 4698bff1cc..79a6a6061d 100644--- a/packages/core/src/Collapsible/Collapsible.spec.md+++ b/packages/core/src/Collapsible/Collapsible.spec.md@@ -9,19 +9,24 @@ superseded_by: nullapproved_by: cixzhangapproved_at: 2026-09-07owners: [cixzhang, imdreamrunner]-review_triggers: [public-api, behavior, layout, accessibility]+review_triggers: [public-api, behavior, layout, accessibility, theming]verified_by:[packages/core/src/Collapsible/Collapsible.test.tsx,packages/core/src/Collapsible/CollapsibleGroup.test.tsx,packages/core/src/Collapsible/__tests__/Collapsible.a11y.test.tsx,packages/core/src/Collapsible/__tests__/Collapsible.a11y.chromium.spec.ts,+ packages/core/src/theme/themingTargets.test.ts,]modules: []families: []design_specs: []architecture:- [architecture:public-component-api, architecture:react-component-runtime]+ [+ architecture:public-component-api,+ architecture:react-component-runtime,+ architecture:component-theming-surface,+ ]contributing: [contributing:api-conventions]system_specs: [spec:AST-002/DEC-1, spec:AST-020, spec:AST-021]---@@ -150,8 +155,32 @@ This contract chooses those relationships but does not expose arbitrary icon orselection. Themes may style the owning Collapsible target without changing thesemantic direction or position states.+## Theming anatomy++<!-- anatomy-theming:v1 -->++```json+{+ "Container": {"target": "collapsible"},+ "Trigger": {"target": "collapsible-trigger"},+ "Chevron": {+ "delegatesTo": {"owner": "component:Icon", "target": "icon"}+ },+ "Content": {"target": "collapsible-content"},+ "Group container": {"target": "collapsible-group"}+}+```++The container owns divided-row chrome, while the trigger and content own their+independent paint and open-state selector surfaces. The chevron keeps Icon's+target; Collapsible owns its semantic position and direction. CollapsibleGroup is+an aggregate subcomponent of this contract, so its conditional wrapper target maps+to the Group container anatomy here.+## Family and system relationships+- `architecture:component-theming-surface` owns anatomy qualification, target+ placement, visual-axis and state reflection, and delegated Icon ownership.- The public `useCollapsible` hook retains its existing state behavior and consumerdocumentation. This component owns the rendered trigger, chevron, and aggregatecomponent/group protocol.@@ -171,6 +200,7 @@ semantic direction or position states.| FR6 | composed trigger layout and geometry tests | plain text; composed label with trailing content; start/end | label becomes shrink-wrapped/stranded or composed content cannot use remaining row | audit:Collapsible/layout || FR7–FR8, ORD1 | group inheritance, item override, and nested reset tests | group start/end; item override; nested omission | group value is ignored, item cannot override, or position leaks into nested content | audit:Collapsible/behavior || FR9, AR1–AR3, ORD2 | disclosure semantics via `DISCLOSURE_PATTERN`, plus component-owned chevron and real RTL rendering | collapsed/expanded; controlled/uncontrolled; enabled/disabled; start/end; LTR/RTL | position changes state behavior, the trigger loses its controlled-content relationship, content visibility diverges from state, accessible output duplicates, or leading direction fails to mirror | audit:Collapsible/accessibility |+| Theming anatomy | focused target-reflection assertions plus `themingTargets.test.ts` | standalone/grouped; open/closed; enabled/disabled; start/end; divided/density | a style-driving axis or state disappears from its owning target, a target loses its anatomy owner, or the chevron stops delegating to Icon | audit:Collapsible/theming |## Decision logdiff --git a/packages/core/src/Collapsible/Collapsible.test.tsx b/packages/core/src/Collapsible/Collapsible.test.tsxindex 6394130222..2426a0b88d 100644--- a/packages/core/src/Collapsible/Collapsible.test.tsx+++ b/packages/core/src/Collapsible/Collapsible.test.tsx@@ -409,6 +409,66 @@ describe('Collapsible', () => {const item = screen.getByTestId('item');expect(item).not.toHaveAttribute('data-density');});++ it('reflects the visual axes and states on their owning theme targets', () => {+ render(+ <>+ <CollapsibleGroup+ type="single"+ hasDividers+ density="compact"+ chevronPosition="start"+ defaultValue="open">+ <Collapsible trigger="Open" value="open" data-testid="open-item">+ Open body+ </Collapsible>+ <Collapsible+ trigger="Disabled"+ value="disabled"+ isDisabled+ data-testid="disabled-item">+ Disabled body+ </Collapsible>+ </CollapsibleGroup>+ <Collapsible+ trigger="Standalone"+ defaultIsOpen={false}+ data-testid="standalone-item">+ Standalone body+ </Collapsible>+ </>,+ );++ const openRoot = screen.getByTestId('open-item');+ const openTrigger = within(openRoot).getByRole('button');+ const openContent = contentFor(openTrigger);+ expect(openRoot).toHaveAttribute('data-density', 'compact');+ expect(openRoot).toHaveAttribute('data-divided', 'divided');+ expect(openTrigger).toHaveAttribute('data-density', 'compact');+ expect(openTrigger).toHaveAttribute('data-chevron-position', 'start');+ expect(openTrigger).toHaveAttribute('data-open', 'open');+ expect(openTrigger).not.toHaveAttribute('data-disabled');+ expect(openContent).toHaveAttribute('data-density', 'compact');+ expect(openContent).toHaveAttribute('data-open', 'open');++ const disabledRoot = screen.getByTestId('disabled-item');+ const disabledTrigger = within(disabledRoot).getByRole('button');+ expect(disabledTrigger).toHaveAttribute('data-disabled', 'disabled');+ expect(disabledTrigger).not.toHaveAttribute('data-open');+ expect(contentFor(disabledTrigger)).not.toHaveAttribute('data-open');++ const standaloneRoot = screen.getByTestId('standalone-item');+ const standaloneTrigger = within(standaloneRoot).getByRole('button');+ const standaloneContent = contentFor(standaloneTrigger);+ expect(standaloneRoot).not.toHaveAttribute('data-density');+ expect(standaloneRoot).not.toHaveAttribute('data-divided');+ expect(standaloneTrigger).toHaveAttribute('data-chevron-position', 'end');+ expect(standaloneTrigger).not.toHaveAttribute('data-density');+ expect(standaloneTrigger).not.toHaveAttribute('data-open');+ expect(standaloneTrigger).not.toHaveAttribute('data-disabled');+ expect(standaloneContent).not.toHaveAttribute('data-density');+ expect(standaloneContent).not.toHaveAttribute('data-open');+ });});describe('chevron position', () => {diff --git a/packages/core/src/Collapsible/Collapsible.tsx b/packages/core/src/Collapsible/Collapsible.tsxindex 9f59a8a9ac..efb3ac295f 100644--- a/packages/core/src/Collapsible/Collapsible.tsx+++ b/packages/core/src/Collapsible/Collapsible.tsx@@ -213,13 +213,15 @@ export interface CollapsibleProps extends BaseProps {children?: ReactNode;/**- * Default open state for uncontrolled usage.+ * Default open state for standalone uncontrolled usage. Ignored when `value`+ * binds this item to a surrounding CollapsibleGroup.* @default true*/defaultIsOpen?: boolean;/**- * Controlled open state. When provided, the component is fully controlled.+ * Controlled open state for standalone usage. Ignored when `value` binds this+ * item to a surrounding CollapsibleGroup.*/isOpen?: boolean;@@ -235,7 +237,8 @@ export interface CollapsibleProps extends BaseProps {isDisabled?: boolean;/**- * Callback when the open state changes.+ * Callback when standalone open state changes. A surrounding+ * CollapsibleGroup owns grouped state and calls its `onChange` instead.*/onOpenChange?: (isOpen: boolean) => void;@@ -255,8 +258,9 @@ export interface CollapsibleProps extends BaseProps {chevronPosition?: CollapsibleChevronPosition;/**- * Unique identifier for this collapsible within an CollapsibleGroup.- * Required when using inside a group for coordination.+ * Unique identifier for this collapsible within a CollapsibleGroup. When set+ * inside a group, the group owns open state and its `onChange` is the+ * notification callback.*/value?: string;@@ -385,6 +389,7 @@ export function Collapsible({{...mergeProps(themeProps('collapsible', {density: density ?? undefined,+ divided: isDivided ? 'divided' : null,}),stylex.props(styles.root, isDivided && styles.divided, xstyle),className,@@ -406,6 +411,9 @@ export function Collapsible({{...mergeProps(themeProps('collapsible-trigger', {density: density ?? undefined,+ chevronPosition: position,+ open: isOpen ? 'open' : null,+ disabled: isDisabled ? 'disabled' : null,}),focusOutlineProps.focusVisible(styles.trigger,@@ -426,6 +434,7 @@ export function Collapsible({{...mergeProps(themeProps('collapsible-content', {density: density ?? undefined,+ open: isOpen ? 'open' : null,}),stylex.props(styles.content,diff --git a/packages/core/src/Collapsible/CollapsibleGroup.doc.mjs b/packages/core/src/Collapsible/CollapsibleGroup.doc.mjsindex f10a025156..91451972ae 100644--- a/packages/core/src/Collapsible/CollapsibleGroup.doc.mjs+++ b/packages/core/src/Collapsible/CollapsibleGroup.doc.mjs@@ -62,6 +62,36 @@ export const docs = {},],},+ {+ name: 'ref',+ type: 'React.Ref<HTMLElement>',+ description:+ 'Ref forwarded to the group wrapper when hasDividers renders one.',+ },+ {+ name: 'xstyle',+ type: 'StyleXStyles',+ description:+ 'StyleX styles for the group wrapper when hasDividers renders one. Must be a stylex.create() value.',+ },+ {+ name: 'className',+ type: 'string',+ description:+ 'CSS class name for the group wrapper when hasDividers renders one. Prefer xstyle for styling.',+ },+ {+ name: 'style',+ type: 'CSSProperties',+ description:+ 'Inline styles for the group wrapper when hasDividers renders one. Prefer xstyle for StyleX-optimized styling.',+ },+ {+ name: 'data-testid',+ type: 'string',+ description:+ 'Test selector forwarded to the group wrapper when hasDividers renders one.',+ },],};diff --git a/packages/core/src/Collapsible/useCollapsible.doc.mjs b/packages/core/src/Collapsible/useCollapsible.doc.mjsindex c9284d7ed4..d2ba8a6364 100644--- a/packages/core/src/Collapsible/useCollapsible.doc.mjs+++ b/packages/core/src/Collapsible/useCollapsible.doc.mjs@@ -40,6 +40,7 @@ export const docs = {bestPractices: [{guidance: true, description: 'Use the hook directly when building custom collapsible components that need Astryx collapsible behavior without Collapsible wrapper.'},{guidance: true, description: 'For accordion behavior, wrap items in CollapsibleGroup and pass unique value props.'},+ {guidance: false, description: 'Pass local isOpen, defaultIsOpen, or onOpenChange expecting them to run for a value-bound group item; the group owns that state and notification path.'},{guidance: false, description: 'Implement your own open/close state when useCollapsible already provides it; the hook handles group coordination automatically.'},],},@@ -66,6 +67,7 @@ export const docsDense = {bestPractices: [{guidance: true, description: 'Use directly when building custom collapsible components needing Astryx collapsible behavior w/o Collapsible wrapper.'},{guidance: true, description: 'For accordion behavior, wrap items in CollapsibleGroup + pass unique value props.'},+ {guidance: false, description: 'Pass local open state or callbacks expecting them to run for a value-bound group item; the group owns state + notifications.'},{guidance: false, description: 'Implement your own open/close state when useCollapsible already provides it; hook handles group coordination automatically.'},],},