An open source design system that's fully customizable and agent ready
TypeScript
feat(Collapsible): let the chevron lead the trigger (#5993)
Ernest409248619ffb
diff --git a/.changeset/collapsible-chevron-position.md b/.changeset/collapsible-chevron-position.mdnew file mode 100644index 0000000000..2cad5f39ce--- /dev/null+++ b/.changeset/collapsible-chevron-position.md@@ -0,0 +1,9 @@+---+'@astryxdesign/core': patch+---++[feat] `Collapsible` and `CollapsibleGroup` accept `chevronPosition="start" | "end"`. The default remains `end`, preserving the released trailing chevron. `start` moves the disclosure arrow ahead of the label for tree/file-browser-style rows: it points inward toward content when collapsed, mirrors under RTL, and turns downward when expanded.++Set the position on `CollapsibleGroup` when direct items should share it. An individual `Collapsible` may override the group, while a Collapsible nested inside an item's content starts a new presentation scope and keeps its own default.++@ernesttdiff --git a/apps/storybook/rtl-audit/verified-not-applicable.json b/apps/storybook/rtl-audit/verified-not-applicable.jsonindex 8e6d2cc5e6..1a1a4c3f70 100644--- a/apps/storybook/rtl-audit/verified-not-applicable.json+++ b/apps/storybook/rtl-audit/verified-not-applicable.json@@ -8,10 +8,6 @@"packages/core/src/Banner/index.ts": "sha256:64591b4c3a37ae382a910fc9314300c3045bf8d602b28cc60a681d7b8f3a17f6"}},- {- "component": "core/Collapsible",- "reason": "Nothing in the trigger or the panel is side-specific. The trigger is a `space-between` flex row, so the label hangs off the reading-start edge and the chevron off the reading-end edge in either direction, with no physical left or right anywhere in the styles. The chevron itself rotates between down and up \u2014 the one axis that does not mirror, because a panel opens downward in every locale \u2014 and it is a vertical glyph to begin with, so there is nothing in it to flip. The panel is a block-flow region whose only geometry is a height transition, and the group's dividers are horizontal rules. No inset, offset, order, transform, drag, scroll, or overlay."- },{"component": "core/ToggleButton","reason": "ToggleButton stories lay out label and optional icon in an inline flex row with logical gap only \u2014 no directional glyphs (the toolbar icons are non-directional), no side-specific placement, order, inset, or offset, no scrolling, dragging, or overlays. Elevation is a symmetric box-shadow, direction-independent by construction, so the LTR and RTL renders are mirror-identical."diff --git a/apps/storybook/stories/Collapsible.stories.tsx b/apps/storybook/stories/Collapsible.stories.tsxindex 1242693446..4b6e30d3af 100644--- a/apps/storybook/stories/Collapsible.stories.tsx+++ b/apps/storybook/stories/Collapsible.stories.tsx@@ -61,9 +61,12 @@ export default meta;type Story = StoryObj<typeof CollapsibleGroup>;export const SingleMode: Story = {- name: 'Single Mode (default)',+ name: 'Single Mode — Leading Chevron',render: () => (- <CollapsibleGroup type="single" defaultValue="general">+ <CollapsibleGroup+ type="single"+ defaultValue="general"+ chevronPosition="start"><VStack gap={2}><Card><Collapsible trigger="General Settings" value="general">diff --git a/packages/core/src/Collapsible/Collapsible.doc.mjs b/packages/core/src/Collapsible/Collapsible.doc.mjsindex dcf9ff1501..6805783d66 100644--- a/packages/core/src/Collapsible/Collapsible.doc.mjs+++ b/packages/core/src/Collapsible/Collapsible.doc.mjs@@ -66,6 +66,12 @@ export const docs = {type: '(isOpen: boolean) => void',description: 'Callback invoked when the open state changes.',},+ {+ name: 'chevronPosition',+ type: "'start' | 'end'",+ description: 'Logical position of Collapsible\'s disclosure chevron. `end` (default) follows the label, pointing down when collapsed and up when expanded. `start` precedes the label, pointing inward toward content when collapsed (mirrored under RTL) and down when expanded. Inside a CollapsibleGroup this defaults to the group\'s chevronPosition.',+ default: "'end'",+ },{name: 'value',type: 'string',@@ -89,7 +95,7 @@ export const docs = {],anatomy: [{ 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 arrow that rotates to show open or closed state.' },+ { 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.' },],},diff --git a/packages/core/src/Collapsible/Collapsible.test.tsx b/packages/core/src/Collapsible/Collapsible.test.tsxindex fb1c359708..ce046f896b 100644--- a/packages/core/src/Collapsible/Collapsible.test.tsx+++ b/packages/core/src/Collapsible/Collapsible.test.tsx@@ -487,4 +487,131 @@ describe('Collapsible', () => {expect(item).not.toHaveAttribute('data-density');});});++ describe('chevron position', () => {+ /**+ * Placement is a DOM order question. Both the label and the chevron render+ * as spans, so they are told apart by what they hold — the chevron is the+ * one carrying the svg — and compared by position rather than tag.+ */+ function triggerParts(testId: string) {+ const button = within(screen.getByTestId(testId)).getByRole('button');+ const children = [...button.children];+ return {+ chevronIndex: children.findIndex(el => el.querySelector('svg')),+ labelIndex: children.findIndex(el => el.textContent?.trim() !== ''),+ glyph: button.querySelector('svg')?.innerHTML,+ };+ }++ it('puts the chevron after the label by default', () => {+ render(+ <Collapsible trigger="A" data-testid="item">+ Body+ </Collapsible>,+ );+ const {chevronIndex, labelIndex} = triggerParts('item');+ expect(chevronIndex).toBeGreaterThan(labelIndex);+ });++ it('puts the chevron before the label when position is start', () => {+ render(+ <Collapsible trigger="A" chevronPosition="start" data-testid="item">+ Body+ </Collapsible>,+ );+ const {chevronIndex, labelIndex} = triggerParts('item');+ expect(chevronIndex).toBeLessThan(labelIndex);+ });++ it('swaps the glyph with the side, not just the position', () => {+ // A leading arrow points into the row and turns down; a trailing one+ // points down and flips up. Reusing one glyph for both would leave a+ // closed leading chevron pointing the wrong way, so the two positions+ // must not render the same art.+ render(+ <>+ <Collapsible trigger="A" data-testid="at-end">+ Body+ </Collapsible>+ <Collapsible+ trigger="A"+ chevronPosition="start"+ data-testid="at-start">+ Body+ </Collapsible>+ </>,+ );+ const endGlyph = triggerParts('at-end').glyph;+ const startGlyph = triggerParts('at-start').glyph;+ expect(endGlyph).toBeTruthy();+ expect(startGlyph).toBeTruthy();+ expect(startGlyph).not.toBe(endGlyph);+ });++ it('takes the position from the surrounding group', () => {+ render(+ <CollapsibleGroup type="single" chevronPosition="start">+ <Collapsible trigger="A" value="a" data-testid="item">+ Body+ </Collapsible>+ </CollapsibleGroup>,+ );+ const {chevronIndex, labelIndex} = triggerParts('item');+ expect(chevronIndex).toBeLessThan(labelIndex);+ });++ it('lets an item override the group position', () => {+ render(+ <CollapsibleGroup type="single" chevronPosition="start">+ <Collapsible+ trigger="A"+ value="a"+ chevronPosition="end"+ data-testid="item">+ Body+ </Collapsible>+ </CollapsibleGroup>,+ );+ const {chevronIndex, labelIndex} = triggerParts('item');+ expect(chevronIndex).toBeGreaterThan(labelIndex);+ });++ it('gives the label the rest of the row when the chevron leads', () => {+ // The trigger is `space-between`. With the chevron trailing that is what+ // separates the two, but with it leading there is nothing to absorb the+ // free space, so an unfilled label would be thrown to the far edge with+ // a gap behind the arrow. It also has to grow for a trigger that spreads+ // its own contents to have a row to spread across.+ render(+ <Collapsible trigger="A" chevronPosition="start" data-testid="item">+ Body+ </Collapsible>,+ );+ const button = within(screen.getByTestId('item')).getByRole('button');+ const label = [...button.children].find(+ el => el.textContent?.trim() !== '',+ );+ expect(label).toHaveStyle({flexGrow: 1});+ });++ it('does not leak the group position into a nested collapsible', () => {+ // Collapsible resets the presentation context around its children, so a+ // collapsible nested in an item's body keeps its own default.+ render(+ <CollapsibleGroup+ type="single"+ defaultValue="a"+ chevronPosition="start">+ <Collapsible trigger="A" value="a" data-testid="outer">+ <Collapsible trigger="B" data-testid="inner">+ Body+ </Collapsible>+ </Collapsible>+ </CollapsibleGroup>,+ );+ const {chevronIndex, labelIndex} = triggerParts('inner');+ expect(chevronIndex).toBeGreaterThan(labelIndex);+ });+ });});diff --git a/packages/core/src/Collapsible/Collapsible.tsx b/packages/core/src/Collapsible/Collapsible.tsxindex b3df63e975..e18c37c5e4 100644--- a/packages/core/src/Collapsible/Collapsible.tsx+++ b/packages/core/src/Collapsible/Collapsible.tsx@@ -42,6 +42,7 @@ import {import {useCollapsible} from './useCollapsible';import {CollapsibleGroupPresentationContext} from './CollapsibleGroupContext';+import type {CollapsibleChevronPosition} from './CollapsibleGroupContext';import {Icon} from '../Icon';import {mergeProps} from '../utils';import type {BaseProps} from '../BaseProps';@@ -124,6 +125,28 @@ const styles = stylex.create({chevronClosed: {transform: 'rotate(0deg)',},+ // Leading chevron. `space-between` puts nothing between the arrow and the+ // label — they are adjacent flex children — so the gap is the chevron's own.+ chevronStart: {+ marginInlineEnd: spacingVars['--spacing-2'],+ },+ // A leading arrow rotates a quarter turn rather than a half: it points into+ // the row when closed and turns down when open, which is the disclosure+ // convention TreeList already uses. RTL mirrors it so "into the row" still+ // means towards the content, and the mirror is spelled out per state because+ // a bare `transform` would otherwise overwrite the rotation.+ chevronStartOpen: {+ transform: {+ default: 'rotate(90deg)',+ ':is([dir="rtl"] *)': 'scaleX(-1) rotate(90deg)',+ },+ },+ chevronStartClosed: {+ transform: {+ default: 'rotate(0deg)',+ ':is([dir="rtl"] *)': 'scaleX(-1) rotate(0deg)',+ },+ },// Content areacontentHidden: {display: 'none',@@ -217,6 +240,21 @@ export interface CollapsibleProps extends BaseProps {*/onOpenChange?: (isOpen: boolean) => void;+ /**+ * Logical position of the disclosure chevron.+ *+ * - `end` (default): a trailing indicator that points down when collapsed and+ * up when expanded.+ * - `start`: a leading disclosure arrow ahead of the label. It points inward+ * toward the content when collapsed, mirrors under RTL, and points down when+ * expanded.+ *+ * Inside a CollapsibleGroup this defaults to the group's `chevronPosition`.+ *+ * @default 'end'+ */+ chevronPosition?: CollapsibleChevronPosition;+/*** Unique identifier for this collapsible within an CollapsibleGroup.* Required when using inside a group for coordination.@@ -273,6 +311,7 @@ export function Collapsible({isOpen: controlledIsOpen,isDisabled = false,onOpenChange,+ chevronPosition,value,ref,xstyle,@@ -305,11 +344,42 @@ export function Collapsible({const presentation = use(CollapsibleGroupPresentationContext);const isDivided = presentation?.hasDividers ?? false;const density = presentation?.density ?? null;+ // The item wins over the group so a single row can differ, but the group is+ // the level this is normally set at — mixed sides in one list read as a bug.+ const position = chevronPosition ?? presentation?.chevronPosition ?? 'end';+ const isChevronAtStart = position === 'start';// Links the trigger to the region it shows/hides so assistive tech can move// from the button to its controlled content (disclosure pattern).const contentId = useId();+ const chevron = (+ <Icon+ // The glyph is part of the placement, not a separate choice: a trailing+ // indicator points down and flips up, a leading one points into the row+ // and turns down. Rotating `chevronDown` by a quarter turn would leave+ // the closed state pointing the wrong way.+ icon={isChevronAtStart ? 'chevronRight' : 'chevronDown'}+ // Nearest size to the trigger's 17px type step; `chevron` re-pins the+ // exact box (see the style) so the glyph does not resize.+ size="sm"+ // Was `--color-icon-secondary` on the old wrapper span; `secondary`+ // is the same token, expressed as an Icon color.+ color="secondary"+ xstyle={[+ styles.chevron,+ isChevronAtStart && styles.chevronStart,+ isChevronAtStart+ ? isOpen+ ? styles.chevronStartOpen+ : styles.chevronStartClosed+ : isOpen+ ? styles.chevronOpen+ : styles.chevronClosed,+ ]}+ />+ );+return (<divref={ref}@@ -344,20 +414,9 @@ export function Collapsible({isDisabled && styles.triggerDisabled,),)}>+ {isChevronAtStart && chevron}<span {...stylex.props(styles.triggerLabel)}>{trigger}</span>- <Icon- icon="chevronDown"- // Nearest size to the trigger's 17px type step; `chevron` re-pins the- // exact box (see the style) so the glyph does not resize.- size="sm"- // Was `--color-icon-secondary` on the old wrapper span; `secondary`- // is the same token, expressed as an Icon color.- color="secondary"- xstyle={[- styles.chevron,- isOpen ? styles.chevronOpen : styles.chevronClosed,- ]}- />+ {!isChevronAtStart && chevron}</button><divid={contentId}diff --git a/packages/core/src/Collapsible/CollapsibleGroup.doc.mjs b/packages/core/src/Collapsible/CollapsibleGroup.doc.mjsindex 908fe03edf..f10a025156 100644--- a/packages/core/src/Collapsible/CollapsibleGroup.doc.mjs+++ b/packages/core/src/Collapsible/CollapsibleGroup.doc.mjs@@ -41,6 +41,12 @@ export const docs = {type: "'compact' | 'balanced' | 'spacious'",description: "Row density controlling trigger and content block padding on the group's items. Defaults to 'balanced' when dividers are shown; otherwise items keep their default unpadded look.",},+ {+ name: 'chevronPosition',+ type: "'start' | 'end'",+ description: "Logical position shared by the group's direct Collapsible items. `end` is the default trailing indicator; `start` is a leading disclosure arrow that points inward when collapsed (mirrored under RTL) and down when expanded. An individual Collapsible can still override it.",+ default: "'end'",+ },{name: 'children',type: 'ReactNode',@@ -97,6 +103,12 @@ export const docsZh = {type: "'compact' | 'balanced' | 'spacious'",description: "控制组内项目触发器和内容块内边距的行密度。显示分隔线时默认为 'balanced';否则项目保持默认的无内边距外观。",},+ {+ name: 'chevronPosition',+ type: "'start' | 'end'",+ description: "组内直接 Collapsible 项目的逻辑箭头位置。`end` 是默认的尾随指示器;`start` 是前置展开箭头,折叠时指向内容(RTL 下镜像),展开时向下。单个 Collapsible 仍可覆盖此设置。",+ default: "'end'",+ },{name: 'children',type: 'ReactNode',@@ -118,6 +130,7 @@ export const docsDense = {onChange: 'callback on open items change',hasDividers: "draw hairline dividers between items; enables wrapper div + 'balanced' density; use bare Collapsible children",density: "row padding 'compact' | 'balanced' | 'spacious'; defaults 'balanced' with dividers, else unpadded",+ chevronPosition: "logical chevron position for direct items: 'end' (default trailing, down/up) | 'start' (leading, inward/down with RTL mirroring); per-item prop wins",children: 'Collapsible instances to coordinate',},};diff --git a/packages/core/src/Collapsible/CollapsibleGroup.tsx b/packages/core/src/Collapsible/CollapsibleGroup.tsxindex 278ac59295..5753556fcc 100644--- a/packages/core/src/Collapsible/CollapsibleGroup.tsx+++ b/packages/core/src/Collapsible/CollapsibleGroup.tsx@@ -34,6 +34,7 @@ import {CollapsibleGroupPresentationContext,} from './CollapsibleGroupContext';import type {+ CollapsibleChevronPosition,CollapsibleGroupContextValue,CollapsibleGroupDensity,CollapsibleGroupPresentationValue,@@ -96,6 +97,14 @@ export interface CollapsibleGroupProps extends Omit<*/density?: CollapsibleGroupDensity;+ /**+ * Logical position of the items' disclosure chevrons. Set this on the group+ * when its direct items should share one position; an individual Collapsible+ * can still override it.+ * @default 'end'+ */+ chevronPosition?: CollapsibleChevronPosition;+/*** Children — any components that support isCollapsible + value.*@@ -175,6 +184,7 @@ export function CollapsibleGroup({onChange,hasDividers = false,density,+ chevronPosition,children,ref,xstyle,@@ -234,8 +244,12 @@ export function CollapsibleGroup({const resolvedDensity = density ?? (hasDividers ? 'balanced' : null);const presentationValue = useMemo<CollapsibleGroupPresentationValue>(- () => ({hasDividers, density: resolvedDensity}),- [hasDividers, resolvedDensity],+ () => ({+ hasDividers,+ density: resolvedDensity,+ chevronPosition: chevronPosition ?? null,+ }),+ [hasDividers, resolvedDensity, chevronPosition],);// The wrapper anchors divider chrome: it makes the items' :first-childdiff --git a/packages/core/src/Collapsible/CollapsibleGroupContext.tsx b/packages/core/src/Collapsible/CollapsibleGroupContext.tsxindex ed137fd42c..8dbfa24f57 100644--- a/packages/core/src/Collapsible/CollapsibleGroupContext.tsx+++ b/packages/core/src/Collapsible/CollapsibleGroupContext.tsx@@ -7,7 +7,7 @@* @input Uses React createContext* @output Exports CollapsibleGroupContext, CollapsibleGroupContextValue,* CollapsibleGroupPresentationContext, CollapsibleGroupPresentationValue,- * and CollapsibleGroupDensity types+ * CollapsibleGroupDensity, and CollapsibleChevronPosition types* @position Context definitions for collapsible group coordination and presentation** SYNC: When modified, update these files to stay in sync:@@ -43,6 +43,15 @@ CollapsibleGroupContext.displayName = 'CollapsibleGroupContext';*/export type CollapsibleGroupDensity = 'compact' | 'balanced' | 'spacious';+/**+ * Logical position of Collapsible's disclosure chevron.+ *+ * `end` is the default trailing indicator: down when collapsed, up when+ * expanded. `start` is the leading disclosure pattern: inward toward content+ * when collapsed (mirrored under RTL), down when expanded.+ */+export type CollapsibleChevronPosition = 'start' | 'end';+/*** Presentation value provided by CollapsibleGroup so each Collapsible can* draw its own group chrome (StyleX has no child selectors, so the group@@ -53,6 +62,13 @@ export interface CollapsibleGroupPresentationValue {hasDividers: boolean;/** Resolved row density, or null to keep the default (unpadded) look. */density: CollapsibleGroupDensity | null;+ /**+ * Chevron position for the group's direct items, or null to leave each item on+ * its own default. An item's own `chevronPosition` still wins, but mixing+ * positions within one group reads as a mistake, so the group is the usual+ * place to set it.+ */+ chevronPosition: CollapsibleChevronPosition | null;}/**diff --git a/packages/core/src/Collapsible/index.ts b/packages/core/src/Collapsible/index.tsindex 1f10052f4b..dda1f9160a 100644--- a/packages/core/src/Collapsible/index.ts+++ b/packages/core/src/Collapsible/index.ts@@ -16,7 +16,10 @@ export type {CollapsibleProps} from './Collapsible';export {CollapsibleGroup} from './CollapsibleGroup';export type {CollapsibleGroupProps} from './CollapsibleGroup';-export type {CollapsibleGroupDensity} from './CollapsibleGroupContext';+export type {+ CollapsibleChevronPosition,+ CollapsibleGroupDensity,+} from './CollapsibleGroupContext';export {useCollapsible} from './useCollapsible';export type {