Skip to content

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

TypeScript

feat(collapsible): add dividers and density props to CollapsibleGroup (#3487) (#3499)

AKf5fcc516e55a
diff --git a/.changeset/collapsiblegroup-dividers.md b/.changeset/collapsiblegroup-dividers.md
new file mode 100644
index 0000000000..9f9a047d12
--- /dev/null
+++ b/.changeset/collapsiblegroup-dividers.md
@@ -0,0 +1,6 @@
+---
+'@astryxdesign/core': patch
+---
+
+[feat] CollapsibleGroup: add `dividers` prop (`'between' | 'all' | 'none'`, default `'none'`) so FAQ-style accordions get built-in row hairlines instead of hand-rolled borders, plus a `density` prop (`'compact' | 'balanced' | 'spacious'`) controlling row padding. When dividers are enabled the group renders a wrapper div (`astryx-collapsible-group`, with `data-dividers`/`data-density` reflection) that anchors the outer borders and items default to `'balanced'` density; without dividers the group keeps its DOM-less contract and existing renders are unchanged. Borders use the themed `--border-width`/`--color-border` tokens, and nested collapsibles never inherit row chrome (#3487).
+@AKnassa
diff --git a/apps/storybook/stories/Collapsible.stories.tsx b/apps/storybook/stories/Collapsible.stories.tsx
index c27278d5d8..540af9a323 100644
--- a/apps/storybook/stories/Collapsible.stories.tsx
+++ b/apps/storybook/stories/Collapsible.stories.tsx
@@ -28,12 +28,27 @@ const styles = stylex.create({
fontFamily: typographyVars['--font-family-body'],
margin: 0,
},
+ dividedContainer: {
+ maxWidth: 480,
+ },
});
const meta: Meta<typeof CollapsibleGroup> = {
title: 'Core/Collapsible',
component: CollapsibleGroup,
tags: ['autodocs'],
+ argTypes: {
+ dividers: {
+ control: 'select',
+ options: ['between', 'all', 'none'],
+ description: "Divider style around the group's items",
+ },
+ density: {
+ control: 'select',
+ options: ['compact', 'balanced', 'spacious'],
+ description: 'Row density for trigger and content padding',
+ },
+ },
decorators: [
Story => (
<div {...stylex.props(styles.pageWrapper)}>
@@ -87,7 +102,8 @@ export const MultipleMode: Story = {
<Card>
<Collapsible trigger="What is Astryx?" value="faq1">
<p {...stylex.props(styles.text)}>
- Astryx is a design system for building internal tools and products.
+ Astryx is a design system for building internal tools and
+ products.
</p>
</Collapsible>
</Card>
@@ -171,7 +187,6 @@ export const WithoutCard: Story = {
<VStack gap={2}>
<Collapsible trigger="Show more details">
<p {...stylex.props(styles.text)}>
-
Collapsible works anywhere; it doesn't require a card wrapper.
</p>
</Collapsible>
@@ -182,6 +197,84 @@ export const WithoutCard: Story = {
),
};
+export const DividersBetween: Story = {
+ name: 'Dividers — Between',
+ args: {type: 'single', dividers: 'between', defaultValue: 'q1'},
+ render: args => (
+ <div {...stylex.props(styles.dividedContainer)}>
+ <CollapsibleGroup {...args}>
+ <Collapsible trigger="How do I reset my password?" value="q1">
+ <p {...stylex.props(styles.text)}>
+ Go to Settings → Security → Change Password. You'll receive a
+ confirmation email.
+ </p>
+ </Collapsible>
+ <Collapsible trigger="Can I change my username?" value="q2">
+ <p {...stylex.props(styles.text)}>
+ Usernames can be changed once every 30 days from your profile
+ settings.
+ </p>
+ </Collapsible>
+ <Collapsible trigger="How do I delete my account?" value="q3">
+ <p {...stylex.props(styles.text)}>
+ Account deletion is permanent. Your data will be removed within 30
+ days.
+ </p>
+ </Collapsible>
+ </CollapsibleGroup>
+ </div>
+ ),
+};
+
+export const DividersAll: Story = {
+ name: 'Dividers — All',
+ args: {type: 'multiple', dividers: 'all', defaultValue: ['a']},
+ render: args => (
+ <div {...stylex.props(styles.dividedContainer)}>
+ <CollapsibleGroup {...args}>
+ <Collapsible trigger="Deployment Details" value="a">
+ <p {...stylex.props(styles.text)}>
+ Deployed 2 hours ago from the main branch.
+ </p>
+ </Collapsible>
+ <Collapsible trigger="Environment Variables" value="b">
+ <p {...stylex.props(styles.text)}>
+ 12 variables configured for this environment.
+ </p>
+ </Collapsible>
+ <Collapsible trigger="Build Logs" value="c">
+ <p {...stylex.props(styles.text)}>Build completed in 43 seconds.</p>
+ </Collapsible>
+ </CollapsibleGroup>
+ </div>
+ ),
+};
+
+export const DividersDensity: Story = {
+ name: 'Dividers — Density',
+ render: () => (
+ <VStack gap={6} xstyle={styles.dividedContainer}>
+ {(['compact', 'balanced', 'spacious'] as const).map(density => (
+ <CollapsibleGroup
+ key={density}
+ type="multiple"
+ dividers="between"
+ density={density}
+ defaultValue={['one']}>
+ <Collapsible trigger={`First section (${density})`} value="one">
+ <p {...stylex.props(styles.text)}>
+ Row padding scales with density.
+ </p>
+ </Collapsible>
+ <Collapsible trigger="Second section" value="two">
+ <p {...stylex.props(styles.text)}>Collapsed by default.</p>
+ </Collapsible>
+ </CollapsibleGroup>
+ ))}
+ </VStack>
+ ),
+};
+
export const FAQ: Story = {
name: 'FAQ Page',
render: () => (
@@ -212,9 +305,7 @@ export const FAQ: Story = {
</Collapsible>
</Card>
<Card>
- <Collapsible
- trigger="What payment methods are accepted?"
- value="q4">
+ <Collapsible trigger="What payment methods are accepted?" value="q4">
<p {...stylex.props(styles.text)}>
We accept Visa, Mastercard, American Express, and PayPal.
</p>
diff --git a/packages/cli/templates/blocks/components/Collapsible/CollapsibleDividedAccordion.doc.mjs b/packages/cli/templates/blocks/components/Collapsible/CollapsibleDividedAccordion.doc.mjs
new file mode 100644
index 0000000000..ae025916e4
--- /dev/null
+++ b/packages/cli/templates/blocks/components/Collapsible/CollapsibleDividedAccordion.doc.mjs
@@ -0,0 +1,13 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
+export const doc = {
+ type: 'block',
+ exampleFor: 'Collapsible',
+ name: 'Collapsible — Divided Accordion',
+ displayName: 'Collapsible — Divided Accordion',
+ description: 'FAQ-style accordion using the dividers prop on CollapsibleGroup: built-in row hairlines and density padding with zero custom CSS. Use for FAQs, settings lists, and nav sections.',
+ isReady: true,
+ aspectRatio: 4 / 3,
+ componentsUsed: ['Collapsible', 'CollapsibleGroup', 'Text'],
+};
diff --git a/packages/cli/templates/blocks/components/Collapsible/CollapsibleDividedAccordion.tsx b/packages/cli/templates/blocks/components/Collapsible/CollapsibleDividedAccordion.tsx
new file mode 100644
index 0000000000..b8883b844a
--- /dev/null
+++ b/packages/cli/templates/blocks/components/Collapsible/CollapsibleDividedAccordion.tsx
@@ -0,0 +1,33 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import {Collapsible, CollapsibleGroup} from '@astryxdesign/core/Collapsible';
+import {Text} from '@astryxdesign/core/Text';
+
+export default function CollapsibleDividedAccordion() {
+ return (
+ <div style={{width: '100%', maxWidth: 400}}>
+ <CollapsibleGroup type="single" dividers="between" defaultValue="reset">
+ <Collapsible trigger="How do I reset my password?" value="reset">
+ <Text type="body">
+ Go to Settings → Security → Change Password. You'll receive a
+ confirmation email within a few minutes.
+ </Text>
+ </Collapsible>
+ <Collapsible trigger="Can I change my username?" value="username">
+ <Text type="body">
+ Usernames can be changed once every 30 days from your profile
+ settings.
+ </Text>
+ </Collapsible>
+ <Collapsible trigger="How do I delete my account?" value="delete">
+ <Text type="body">
+ Account deletion is permanent. Your data will be removed within 30
+ days.
+ </Text>
+ </Collapsible>
+ </CollapsibleGroup>
+ </div>
+ );
+}
diff --git a/packages/core/src/Collapsible/Collapsible.doc.mjs b/packages/core/src/Collapsible/Collapsible.doc.mjs
index fcd9833825..acc902e9d6 100644
--- a/packages/core/src/Collapsible/Collapsible.doc.mjs
+++ b/packages/core/src/Collapsible/Collapsible.doc.mjs
@@ -16,7 +16,8 @@ export const docs = {
},
theming: {
targets: [
- {className: 'astryx-collapsible'},
+ {className: 'astryx-collapsible', visualProps: ['dividers', 'density']},
+ {className: 'astryx-collapsible-group', visualProps: ['dividers', 'density']},
],
},
description: 'A primitive that makes any content collapsible: a trigger button toggles visibility of the content area, managing its own state or deferring to a parent CollapsibleGroup.',
@@ -69,7 +70,8 @@ export const docs = {
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. For custom collapsible components, use the `useCollapsible` hook directly (`astryx hook useCollapsible`).',
bestPractices: [
- { guidance: true, description: 'Wrap each Collapsible in an Card for visual separation in accordion layouts.' },
+ { guidance: true, description: 'Use dividers="between" 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 dividers 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.' },
{ guidance: true, description: 'Use type="multiple" when users need to compare content across sections, like feature lists or pricing tiers.' },
{ guidance: true, description: 'Start sections open (defaultIsOpen) when the content is likely needed on first view; don\'t make users click to see essential info.' },
@@ -90,7 +92,8 @@ 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: 'Wrap each Collapsible in an Card for visual separation in accordion layouts.' },
+ { guidance: true, description: 'Use dividers="between" 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 dividers 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.' },
{ guidance: true, description: 'Use type="multiple" when users need to compare content across sections, like feature lists or pricing tiers.' },
{ guidance: true, description: 'Start sections open (defaultIsOpen) when the content is likely needed on first view; don\'t make users click to see essential info.' },
@@ -107,7 +110,8 @@ 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: 'Wrap each Collapsible in an Card for visual separation in accordion layouts.' },
+ { guidance: true, description: 'Use dividers="between" 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 dividers 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.' },
{ guidance: true, description: 'Use type="multiple" when users need to compare across sections.' },
{ guidance: true, description: 'Start sections open (defaultIsOpen) when content is needed on first view.' },
diff --git a/packages/core/src/Collapsible/Collapsible.tsx b/packages/core/src/Collapsible/Collapsible.tsx
index 76ec7a2c21..d41a0b50ff 100644
--- a/packages/core/src/Collapsible/Collapsible.tsx
+++ b/packages/core/src/Collapsible/Collapsible.tsx
@@ -4,7 +4,7 @@
/**
* @file Collapsible.tsx
- * @input Uses React, StyleX, useCollapsible hook, getIcon, theme tokens
+ * @input Uses React, StyleX, useCollapsible hook, CollapsibleGroupPresentationContext, getIcon, theme tokens
* @output Exports Collapsible component and CollapsibleProps
* @position Collapsible content primitive — trigger toggles visibility of children
*
@@ -13,6 +13,11 @@
* Handles state management, accessibility (aria-expanded), and chevron indicator.
*
* Works standalone or coordinated by CollapsibleGroup via the `value` prop.
+ * When the surrounding CollapsibleGroup enables `dividers`, each Collapsible
+ * draws its own row chrome (borderBlockStart suppressed on :first-child, plus
+ * density padding) from CollapsibleGroupPresentationContext — StyleX has no
+ * child selectors, so the group cannot draw it from outside. The presentation
+ * context is reset around children so nested collapsibles stay chrome-free.
*
* SYNC: When modified, update these files to stay in sync:
* - /packages/core/src/Collapsible/index.ts (exports)
@@ -21,9 +26,10 @@
* - /packages/cli/templates/blocks/components/Collapsible/ (showcase blocks)
*/
-import type {ReactNode} from 'react';
+import {use, type ReactNode} from 'react';
import * as stylex from '@stylexjs/stylex';
import {
+ borderVars,
colorVars,
typographyVars,
fontWeightVars,
@@ -33,6 +39,7 @@ import {
easeVars,
} from '../theme/tokens.stylex';
import {useCollapsible} from './useCollapsible';
+import {CollapsibleGroupPresentationContext} from './CollapsibleGroupContext';
import {getIcon} from '../Icon/globalIconRegistry';
import {mergeProps} from '../utils';
import type {BaseProps} from '../BaseProps';
@@ -87,8 +94,42 @@ const styles = stylex.create({
content: {
paddingBlockStart: spacingVars['--spacing-1'],
},
+ // Group divider chrome — a hairline above every item except the first.
+ // The group's wrapper (or 'all' mode) owns the outer edges.
+ divided: {
+ borderBlockStartWidth: {
+ default: borderVars['--border-width'],
+ ':first-child': '0',
+ },
+ borderBlockStartStyle: 'solid',
+ borderBlockStartColor: colorVars['--color-border'],
+ },
+});
+
+// Density padding for divided/padded accordion rows. paddingBlock mapping
+// follows Table's density scale (spacing-1/2/3); content only pads its end
+// so text doesn't sit on the divider below (block-start stays spacing-1).
+const densityStyles = stylex.create({
+ triggerCompact: {paddingBlock: spacingVars['--spacing-1']},
+ triggerBalanced: {paddingBlock: spacingVars['--spacing-2']},
+ triggerSpacious: {paddingBlock: spacingVars['--spacing-3']},
+ contentCompact: {paddingBlockEnd: spacingVars['--spacing-1']},
+ contentBalanced: {paddingBlockEnd: spacingVars['--spacing-2']},
+ contentSpacious: {paddingBlockEnd: spacingVars['--spacing-3']},
});
+const triggerDensity = {
+ compact: densityStyles.triggerCompact,
+ balanced: densityStyles.triggerBalanced,
+ spacious: densityStyles.triggerSpacious,
+} as const;
+
+const contentDensity = {
+ compact: densityStyles.contentCompact,
+ balanced: densityStyles.contentBalanced,
+ spacious: densityStyles.contentSpacious,
+} as const;
+
export interface CollapsibleProps extends BaseProps {
/** Ref forwarded to the root element */
ref?: React.Ref<HTMLDivElement>;
@@ -192,14 +233,21 @@ export function Collapsible({
value,
});
+ const presentation = use(CollapsibleGroupPresentationContext);
+ const isDivided = presentation != null && presentation.dividers !== 'none';
+ const density = presentation?.density ?? null;
+
const chevronIcon = getIcon('chevronDown');
return (
<div
ref={ref}
{...mergeProps(
- themeProps('collapsible'),
- stylex.props(styles.root, xstyle),
+ themeProps('collapsible', {
+ dividers: isDivided ? presentation.dividers : undefined,
+ density: density ?? undefined,
+ }),
+ stylex.props(styles.root, isDivided && styles.divided, xstyle),
className,
style,
)}
@@ -208,7 +256,10 @@ export function Collapsible({
type="button"
onClick={toggle}
aria-expanded={isOpen}
- {...stylex.props(styles.trigger)}>
+ {...stylex.props(
+ styles.trigger,
+ density != null && triggerDensity[density],
+ )}>
<span {...stylex.props(styles.triggerLabel)}>{trigger}</span>
<span
{...stylex.props(
@@ -219,10 +270,18 @@ export function Collapsible({
</span>
</button>
<div
- {...(isOpen
- ? stylex.props(styles.content)
- : stylex.props(styles.content, styles.contentHidden))}>
- {children}
+ {...stylex.props(
+ styles.content,
+ density != null && contentDensity[density],
+ !isOpen && styles.contentHidden,
+ )}>
+ {presentation != null ? (
+ <CollapsibleGroupPresentationContext value={null}>
+ {children}
+ </CollapsibleGroupPresentationContext>
+ ) : (
+ children
+ )}
</div>
</div>
);
diff --git a/packages/core/src/Collapsible/CollapsibleGroup.doc.mjs b/packages/core/src/Collapsible/CollapsibleGroup.doc.mjs
index 6c3067126e..ac82e0b1c7 100644
--- a/packages/core/src/Collapsible/CollapsibleGroup.doc.mjs
+++ b/packages/core/src/Collapsible/CollapsibleGroup.doc.mjs
@@ -7,7 +7,7 @@ export const docs = {
subComponentOf: 'Collapsible',
displayName: 'Collapsible Group',
isHiddenFromOverview: true,
- description: 'Coordinates multiple Collapsible instances so only one (single mode) or any number (multiple mode) can be open at a time. Renders no wrapper DOM element.',
+ description: 'Coordinates multiple Collapsible instances so only one (single mode) or any number (multiple mode) can be open at a time. Renders no wrapper DOM element unless dividers are enabled.',
props: [
{
name: 'type',
@@ -30,6 +30,17 @@ export const docs = {
type: '(value: string | string[]) => void',
description: 'Callback invoked when the set of open items changes.',
},
+ {
+ name: 'dividers',
+ type: "'between' | 'all' | 'none'",
+ description: "Divider style rendered around the group's items. 'between' draws hairlines between adjacent items; 'all' adds the group's top and bottom edges. When enabled, the group renders a wrapper div and items default to 'balanced' density. Pair with bare Collapsible children; Card-wrapped items provide their own separation.",
+ default: "'none'",
+ },
+ {
+ name: 'density',
+ 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: 'children',
type: 'ReactNode',
@@ -52,7 +63,7 @@ export const docsZh = {
name: 'CollapsibleGroup',
isHiddenFromOverview: true,
displayName: 'Collapsible Group',
- description: '协调多个 Collapsible 实例,使同一时间只有一个(single 模式)或任意数量(multiple 模式)可以展开。不渲染包裹 DOM 元素。',
+ description: '协调多个 Collapsible 实例,使同一时间只有一个(single 模式)或任意数量(multiple 模式)可以展开。除非启用 dividers,否则不渲染包裹 DOM 元素。',
props: [
{
name: 'type',
@@ -75,6 +86,17 @@ export const docsZh = {
type: '(value: string | string[]) => void',
description: '展开项目集合变更时调用的回调。',
},
+ {
+ name: 'dividers',
+ type: "'between' | 'all' | 'none'",
+ description: "渲染在组项目周围的分隔线样式。'between' 仅在相邻项目之间绘制细线;'all' 额外绘制组的顶部和底部边缘。启用后组会渲染一个包裹 div,且项目默认使用 'balanced' 密度。适合搭配裸 Collapsible 子项使用;用 Card 包裹的项目自带视觉分隔。",
+ default: "'none'",
+ },
+ {
+ name: 'density',
+ type: "'compact' | 'balanced' | 'spacious'",
+ description: "控制组内项目触发器和内容块内边距的行密度。显示分隔线时默认为 'balanced';否则项目保持默认的无内边距外观。",
+ },
{
name: 'children',
type: 'ReactNode',
@@ -88,12 +110,14 @@ export const docsDense = {
name: 'CollapsibleGroup',
isHiddenFromOverview: true,
displayName: 'Collapsible Group',
- description: 'coordinates multiple Collapsible instances; single or multiple open. no wrapper DOM.',
+ description: 'coordinates multiple Collapsible instances; single or multiple open. no wrapper DOM unless dividers enabled.',
propDescriptions: {
type: 'one or many items open simultaneously',
defaultValue: 'default open item(s) (uncontrolled); string for single, array for multiple',
value: 'controlled open item(s)',
onChange: 'callback on open items change',
+ dividers: "row hairlines: 'between' items only, 'all' adds outer edges, 'none' (default); enables wrapper div + 'balanced' density; use bare Collapsible children",
+ density: "row padding 'compact' | 'balanced' | 'spacious'; defaults 'balanced' with dividers, else unpadded",
children: 'Collapsible instances to coordinate',
},
};
diff --git a/packages/core/src/Collapsible/CollapsibleGroup.test.tsx b/packages/core/src/Collapsible/CollapsibleGroup.test.tsx
index c9b93d728a..e1885ddcf1 100644
--- a/packages/core/src/Collapsible/CollapsibleGroup.test.tsx
+++ b/packages/core/src/Collapsible/CollapsibleGroup.test.tsx
@@ -397,4 +397,276 @@ describe('CollapsibleGroup', () => {
expect(trigger).toHaveAttribute('aria-expanded', 'true');
});
});
+
+ describe('dividers', () => {
+ function getItem(name: RegExp): HTMLElement {
+ const root = screen
+ .getByRole('button', {name})
+ .closest('.astryx-collapsible');
+ expect(root).not.toBeNull();
+ return root as HTMLElement;
+ }
+
+ it('renders no wrapper DOM by default and with dividers="none"', () => {
+ const {container, rerender} = render(
+ <CollapsibleGroup>
+ <Collapsible trigger="Item A" value="a">
+ <p>Content A</p>
+ </Collapsible>
+ </CollapsibleGroup>,
+ );
+ expect(container.querySelector('.astryx-collapsible-group')).toBeNull();
+
+ rerender(
+ <CollapsibleGroup dividers="none">
+ <Collapsible trigger="Item A" value="a">
+ <p>Content A</p>
+ </Collapsible>
+ </CollapsibleGroup>,
+ );
+ expect(container.querySelector('.astryx-collapsible-group')).toBeNull();
+ });
+
+ it('renders a wrapper with data attributes when dividers are enabled', () => {
+ const {container} = render(
+ <CollapsibleGroup dividers="between">
+ <Collapsible trigger="Item A" value="a">
+ <p>Content A</p>
+ </Collapsible>
+ <Collapsible trigger="Item B" value="b">
+ <p>Content B</p>
+ </Collapsible>
+ </CollapsibleGroup>,
+ );
+
+ const wrapper = container.querySelector('.astryx-collapsible-group');
+ expect(wrapper).not.toBeNull();
+ expect(wrapper).toHaveAttribute('data-dividers', 'between');
+ // Divided groups default to balanced density
+ expect(wrapper).toHaveAttribute('data-density', 'balanced');
+ expect(wrapper).toContainElement(getItem(/Item A/));
+ expect(wrapper).toContainElement(getItem(/Item B/));
+ });
+
+ it('reflects dividers and density on each item', () => {
+ render(
+ <CollapsibleGroup dividers="all" density="compact">
+ <Collapsible trigger="Item A" value="a">
+ <p>Content A</p>
+ </Collapsible>
+ </CollapsibleGroup>,
+ );
+
+ const item = getItem(/Item A/);
+ expect(item).toHaveAttribute('data-dividers', 'all');
+ expect(item).toHaveAttribute('data-density', 'compact');
+ });
+
+ it('does not reflect divider chrome on items without dividers', () => {
+ render(
+ <CollapsibleGroup>
+ <Collapsible trigger="Item A" value="a">
+ <p>Content A</p>
+ </Collapsible>
+ </CollapsibleGroup>,
+ );
+
+ const item = getItem(/Item A/);
+ expect(item).not.toHaveAttribute('data-dividers');
+ expect(item).not.toHaveAttribute('data-density');
+ });
+
+ it('applies density without dividers (and without a wrapper)', () => {
+ const {container} = render(
+ <CollapsibleGroup density="spacious">
+ <Collapsible trigger="Item A" value="a">
+ <p>Content A</p>
+ </Collapsible>
+ </CollapsibleGroup>,
+ );
+
+ expect(container.querySelector('.astryx-collapsible-group')).toBeNull();
+ expect(getItem(/Item A/)).toHaveAttribute('data-density', 'spacious');
+ });
+
+ it('does not leak divider chrome into nested collapsibles', () => {
+ render(
+ <CollapsibleGroup dividers="between" defaultValue="outer">
+ <Collapsible trigger="Outer" value="outer">
+ <Collapsible trigger="Nested">
+ <p>Nested content</p>
+ </Collapsible>
+ </Collapsible>
+ </CollapsibleGroup>,
+ );
+
+ expect(getItem(/Outer/)).toHaveAttribute('data-dividers', 'between');
+ expect(getItem(/Nested/)).not.toHaveAttribute('data-dividers');
+ expect(getItem(/Nested/)).not.toHaveAttribute('data-density');
+ });
+
+ it('keeps group coordination working with dividers enabled', async () => {
+ const user = userEvent.setup();
+ render(
+ <CollapsibleGroup type="single" dividers="between" defaultValue="a">
+ <Collapsible trigger="Item A" value="a">
+ <p>Content A</p>
+ </Collapsible>
+ <Collapsible trigger="Item B" value="b">
+ <p>Content B</p>
+ </Collapsible>
+ </CollapsibleGroup>,
+ );
+
+ expect(screen.getByText('Content A')).toBeVisible();
+ await user.click(screen.getByRole('button', {name: /Item B/}));
+ expect(screen.getByText('Content A')).not.toBeVisible();
+ expect(screen.getByText('Content B')).toBeVisible();
+ });
+
+ it('applies xstyle/className/style to the wrapper in divider mode', () => {
+ const {container} = render(
+ <CollapsibleGroup
+ dividers="between"
+ className="custom-class"
+ data-testid="group">
+ <Collapsible trigger="Item A" value="a">
+ <p>Content A</p>
+ </Collapsible>
+ </CollapsibleGroup>,
+ );
+
+ const wrapper = container.querySelector('.astryx-collapsible-group');
+ expect(wrapper).toHaveClass('custom-class');
+ expect(wrapper).toHaveAttribute('data-testid', 'group');
+ });
+
+ it('forwards ref to the wrapper in divider mode', () => {
+ const ref = {current: null as HTMLElement | null};
+ const {container} = render(
+ <CollapsibleGroup dividers="between" ref={ref}>
+ <Collapsible trigger="Item A" value="a">
+ <p>Content A</p>
+ </Collapsible>
+ </CollapsibleGroup>,
+ );
+
+ expect(ref.current).toBe(
+ container.querySelector('.astryx-collapsible-group'),
+ );
+ });
+
+ it('explicit density overrides the divider default', () => {
+ const {container} = render(
+ <CollapsibleGroup dividers="between" density="spacious">
+ <Collapsible trigger="Item A" value="a">
+ <p>Content A</p>
+ </Collapsible>
+ </CollapsibleGroup>,
+ );
+
+ const wrapper = container.querySelector('.astryx-collapsible-group');
+ expect(wrapper).toHaveAttribute('data-density', 'spacious');
+ expect(getItem(/Item A/)).toHaveAttribute('data-density', 'spacious');
+ });
+
+ it('tolerates interleaved non-Collapsible children', async () => {
+ const user = userEvent.setup();
+ render(
+ <CollapsibleGroup type="single" dividers="between" defaultValue="a">
+ <Collapsible trigger="Item A" value="a">
+ <p>Content A</p>
+ </Collapsible>
+ <hr data-testid="separator" />
+ <Collapsible trigger="Item B" value="b">
+ <p>Content B</p>
+ </Collapsible>
+ </CollapsibleGroup>,
+ );
+
+ expect(screen.getByTestId('separator')).toBeInTheDocument();
+ expect(getItem(/Item A/)).toHaveAttribute('data-dividers', 'between');
+ expect(getItem(/Item B/)).toHaveAttribute('data-dividers', 'between');
+ await user.click(screen.getByRole('button', {name: /Item B/}));
+ expect(screen.getByText('Content A')).not.toBeVisible();
+ expect(screen.getByText('Content B')).toBeVisible();
+ });
+
+ it('lets a nested group define its own chrome instead of inheriting', () => {
+ render(
+ <CollapsibleGroup dividers="between" defaultValue="outer">
+ <Collapsible trigger="Outer" value="outer">
+ <CollapsibleGroup type="multiple" dividers="all">
+ <Collapsible trigger="Inner divided" value="in-a">
+ <p>Inner content</p>
+ </Collapsible>
+ </CollapsibleGroup>
+ <CollapsibleGroup type="multiple">
+ <Collapsible trigger="Inner plain" value="in-b">
+ <p>Inner content</p>
+ </Collapsible>
+ </CollapsibleGroup>
+ </Collapsible>
+ </CollapsibleGroup>,
+ );
+
+ expect(getItem(/Outer/)).toHaveAttribute('data-dividers', 'between');
+ expect(getItem(/Inner divided/)).toHaveAttribute('data-dividers', 'all');
+ expect(getItem(/Inner plain/)).not.toHaveAttribute('data-dividers');
+ });
+
+ it('keeps controlled coordination and onChange shape with dividers', async () => {
+ const user = userEvent.setup();
+ const onChange = vi.fn();
+ const {rerender} = render(
+ <CollapsibleGroup
+ type="single"
+ dividers="all"
+ value="a"
+ onChange={onChange}>
+ <Collapsible trigger="Item A" value="a">
+ <p>Content A</p>
+ </Collapsible>
+ <Collapsible trigger="Item B" value="b">
+ <p>Content B</p>
+ </Collapsible>
+ </CollapsibleGroup>,
+ );
+
+ await user.click(screen.getByRole('button', {name: /Item B/}));
+ expect(onChange).toHaveBeenCalledWith('b');
+ // Controlled: nothing opens until the parent passes the new value
+ expect(screen.getByText('Content B')).not.toBeVisible();
+
+ rerender(
+ <CollapsibleGroup
+ type="single"
+ dividers="all"
+ value="b"
+ onChange={onChange}>
+ <Collapsible trigger="Item A" value="a">
+ <p>Content A</p>
+ </Collapsible>
+ <Collapsible trigger="Item B" value="b">
+ <p>Content B</p>
+ </Collapsible>
+ </CollapsibleGroup>,
+ );
+ expect(screen.getByText('Content A')).not.toBeVisible();
+ expect(screen.getByText('Content B')).toBeVisible();
+ });
+
+ it('renders standalone Collapsible without any group chrome', () => {
+ render(
+ <Collapsible trigger="Alone">
+ <p>Standalone content</p>
+ </Collapsible>,
+ );
+
+ const item = getItem(/Alone/);
+ expect(item).not.toHaveAttribute('data-dividers');
+ expect(item).not.toHaveAttribute('data-density');
+ expect(item.querySelector('.astryx-collapsible-group')).toBeNull();
+ });
+ });
});
diff --git a/packages/core/src/Collapsible/CollapsibleGroup.tsx b/packages/core/src/Collapsible/CollapsibleGroup.tsx
index 745fe0fb6e..923d5a74f5 100644
--- a/packages/core/src/Collapsible/CollapsibleGroup.tsx
+++ b/packages/core/src/Collapsible/CollapsibleGroup.tsx
@@ -4,13 +4,18 @@
/**
* @file CollapsibleGroup.tsx
- * @input Uses React useState, useCallback, CollapsibleGroupContext
+ * @input Uses React useState, useCallback, CollapsibleGroupContext, StyleX, theme tokens
* @output Exports CollapsibleGroup component and CollapsibleGroupProps
- * @position Core collapsible group coordination provider — renders no wrapper DOM
+ * @position Core collapsible group coordination provider — renders no wrapper
+ * DOM unless `dividers` is enabled
*
* CollapsibleGroup groups collapsible components (Card, etc.) with
- * coordinated open/close behavior. It renders only `{children}` — no wrapper
- * DOM element.
+ * coordinated open/close behavior. By default it renders only `{children}` —
+ * no wrapper DOM element. When `dividers` is 'between' or 'all' it renders a
+ * wrapper div that anchors the divider chrome (outer borders, reliable
+ * :first-child suppression) and provides dividers/density to items via
+ * CollapsibleGroupPresentationContext — each Collapsible draws its own
+ * borders since StyleX has no child selectors.
*
* In "single" mode (default), only one item can be open at a time.
* In "multiple" mode, any number of items can be open simultaneously.
@@ -24,10 +29,35 @@
*/
import React, {useCallback, useMemo, useState, type ReactNode} from 'react';
-import {CollapsibleGroupContext} from './CollapsibleGroupContext';
-import type {CollapsibleGroupContextValue} from './CollapsibleGroupContext';
+import * as stylex from '@stylexjs/stylex';
+import {borderVars, colorVars} from '../theme/tokens.stylex';
+import {
+ CollapsibleGroupContext,
+ CollapsibleGroupPresentationContext,
+} from './CollapsibleGroupContext';
+import type {
+ CollapsibleGroupContextValue,
+ CollapsibleGroupDensity,
+ CollapsibleGroupDividers,
+ CollapsibleGroupPresentationValue,
+} from './CollapsibleGroupContext';
+import {mergeProps} from '../utils';
+import {themeProps} from '../utils/themeProps';
import type {BaseProps} from '../BaseProps';
+const styles = stylex.create({
+ // 'all' draws the group's outer top/bottom edges; between-item lines are
+ // drawn by each Collapsible (borderBlockStart, suppressed on :first-child)
+ wrapperAll: {
+ borderBlockStartWidth: borderVars['--border-width'],
+ borderBlockStartStyle: 'solid',
+ borderBlockStartColor: colorVars['--color-border'],
+ borderBlockEndWidth: borderVars['--border-width'],
+ borderBlockEndStyle: 'solid',
+ borderBlockEndColor: colorVars['--color-border'],
+ },
+});
+
export interface CollapsibleGroupProps extends Omit<
BaseProps<HTMLElement>,
'onChange'
@@ -56,6 +86,24 @@ export interface CollapsibleGroupProps extends Omit<
*/
onChange?: (value: string | string[]) => void;
+ /**
+ * Divider style rendered around the group's items — the accordion row
+ * chrome. 'between' draws hairlines between adjacent items; 'all' adds the
+ * group's top and bottom edges. When enabled, the group renders a wrapper
+ * div (it otherwise renders no DOM) and items get 'balanced' density unless
+ * `density` says otherwise. Pair with bare Collapsible children; Card-wrapped
+ * items provide their own separation.
+ * @default "none"
+ */
+ dividers?: CollapsibleGroupDividers;
+
+ /**
+ * 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.
+ */
+ density?: CollapsibleGroupDensity;
+
/**
* Children — any components that support isCollapsible + value.
*
@@ -92,16 +140,26 @@ function normalizeToArray(value: string | string[] | undefined): string[] {
/**
* Groups collapsible components with coordinated open/close behavior.
- * Renders no wrapper DOM.
+ * Renders no wrapper DOM unless `dividers` is enabled.
*
* In "single" mode (default), opening one item closes the others.
* In "multiple" mode, items toggle independently.
*
* @compositionHint Wrap Collapsible instances to coordinate their open/close state.
- * Each Collapsible needs a `value` prop to participate.
+ * Each Collapsible needs a `value` prop to participate. For FAQ-style lists,
+ * use `dividers` with bare Collapsible children instead of wrapping each item
+ * in Card.
*
* @example
* ```
+ * <CollapsibleGroup type="single" dividers="between" defaultValue="faq1">
+ * <Collapsible trigger="What is Astryx?" value="faq1">
+ * Astryx is a design system for building internal tools.
+ * </Collapsible>
+ * <Collapsible trigger="How do I start?" value="faq2">
+ * Install the package and import components.
+ * </Collapsible>
+ * </CollapsibleGroup>
* <CollapsibleGroup type="single" defaultValue="faq1">
* <VStack gap={2}>
* <Card>
@@ -123,7 +181,14 @@ export function CollapsibleGroup({
defaultValue,
value: controlledValue,
onChange,
+ dividers = 'none',
+ density,
children,
+ ref,
+ xstyle,
+ className,
+ style,
+ ...props
}: CollapsibleGroupProps) {
const isControlled = controlledValue !== undefined;
const [internalValue, setInternalValue] = useState<string[]>(() =>
@@ -174,9 +239,42 @@ export function CollapsibleGroup({
[isOpen, toggle],
);
+ const hasDividers = dividers !== 'none';
+ const resolvedDensity = density ?? (hasDividers ? 'balanced' : null);
+
+ const presentationValue = useMemo<CollapsibleGroupPresentationValue>(
+ () => ({dividers, density: resolvedDensity}),
+ [dividers, resolvedDensity],
+ );
+
+ // The wrapper anchors divider chrome: 'all' outer borders live here, and it
+ // makes the items' :first-child suppression independent of surrounding
+ // siblings. Without dividers the group stays DOM-less (documented contract),
+ // so ref/xstyle/className/style only take effect in wrapper mode.
+ const content = hasDividers ? (
+ <div
+ ref={ref as React.Ref<HTMLDivElement>}
+ {...mergeProps(
+ themeProps('collapsible-group', {
+ dividers,
+ density: resolvedDensity ?? undefined,
+ }),
+ stylex.props(dividers === 'all' && styles.wrapperAll, xstyle),
+ className,
+ style,
+ )}
+ {...props}>
+ {children}
+ </div>
+ ) : (
+ children
+ );
+
return (
<CollapsibleGroupContext value={contextValue}>
- {children}
+ <CollapsibleGroupPresentationContext value={presentationValue}>
+ {content}
+ </CollapsibleGroupPresentationContext>
</CollapsibleGroupContext>
);
}
diff --git a/packages/core/src/Collapsible/CollapsibleGroupContext.tsx b/packages/core/src/Collapsible/CollapsibleGroupContext.tsx
index 0e155b879a..c48f50ba94 100644
--- a/packages/core/src/Collapsible/CollapsibleGroupContext.tsx
+++ b/packages/core/src/Collapsible/CollapsibleGroupContext.tsx
@@ -5,8 +5,10 @@
/**
* @file CollapsibleGroupContext.tsx
* @input Uses React createContext
- * @output Exports CollapsibleGroupContext and CollapsibleGroupContextValue type
- * @position Context definition for collapsible group coordination
+ * @output Exports CollapsibleGroupContext, CollapsibleGroupContextValue,
+ * CollapsibleGroupPresentationContext, CollapsibleGroupPresentationValue,
+ * CollapsibleGroupDividers, and CollapsibleGroupDensity types
+ * @position Context definitions for collapsible group coordination and presentation
*
* SYNC: When modified, update these files to stay in sync:
* - /packages/core/src/Collapsible/CollapsibleGroup.tsx (provider)
@@ -33,3 +35,41 @@ export interface CollapsibleGroupContextValue {
export const CollapsibleGroupContext =
createContext<CollapsibleGroupContextValue | null>(null);
CollapsibleGroupContext.displayName = 'CollapsibleGroupContext';
+
+/**
+ * Divider style rendered around the items of a CollapsibleGroup.
+ * - 'between': hairlines between adjacent items only.
+ * - 'all': hairlines between items plus the group's top and bottom edges.
+ * - 'none': no dividers (default).
+ */
+export type CollapsibleGroupDividers = 'between' | 'all' | 'none';
+
+/**
+ * Row density for the items of a CollapsibleGroup, controlling trigger and
+ * content block padding. Shares the repo-wide density vocabulary
+ * (Table, List, Item).
+ */
+export type CollapsibleGroupDensity = 'compact' | 'balanced' | 'spacious';
+
+/**
+ * Presentation value provided by CollapsibleGroup so each Collapsible can
+ * draw its own group chrome (StyleX has no child selectors, so the group
+ * cannot style items from the outside).
+ */
+export interface CollapsibleGroupPresentationValue {
+ /** Resolved divider style for the group's items. */
+ dividers: CollapsibleGroupDividers;
+ /** Resolved row density, or null to keep the default (unpadded) look. */
+ density: CollapsibleGroupDensity | null;
+}
+
+/**
+ * Context for collapsible group presentation (dividers, density).
+ * Kept separate from CollapsibleGroupContext so the public useCollapsible
+ * state API is unaffected. Collapsible resets this context around its
+ * children so nested collapsibles never inherit row chrome.
+ */
+export const CollapsibleGroupPresentationContext =
+ createContext<CollapsibleGroupPresentationValue | null>(null);
+CollapsibleGroupPresentationContext.displayName =
+ 'CollapsibleGroupPresentationContext';
diff --git a/packages/core/src/Collapsible/index.ts b/packages/core/src/Collapsible/index.ts
index 289073d37f..b88501987f 100644
--- a/packages/core/src/Collapsible/index.ts
+++ b/packages/core/src/Collapsible/index.ts
@@ -16,6 +16,10 @@ export type {CollapsibleProps} from './Collapsible';
export {CollapsibleGroup} from './CollapsibleGroup';
export type {CollapsibleGroupProps} from './CollapsibleGroup';
+export type {
+ CollapsibleGroupDividers,
+ CollapsibleGroupDensity,
+} from './CollapsibleGroupContext';
export {useCollapsible} from './useCollapsible';
export type {