@astryxdesign/core 0.1.4 → 0.1.5-canary.76e6697

package/src/Collapsible/Collapsible.test.tsx

@@ -0,0 +1,403 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Collapsible.test.tsx
+ * @input Uses vitest, @testing-library/react, Collapsible + CollapsibleGroup
+ * @output Characterization coverage for Collapsible behavior
+ * @position Testing; validates Collapsible.tsx (disclosure primitive)
+ *
+ * SYNC: When Collapsible.tsx changes, update tests to match new behavior
+ */
+
+import {describe, it, expect, vi} from 'vitest';
+import {render, screen, within} from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import {Collapsible} from './Collapsible';
+import {CollapsibleGroup} from './CollapsibleGroup';
+
+/**
+ * Resolves the content region a trigger controls via aria-controls, so tests
+ * assert the real disclosure linkage rather than guessing at DOM structure.
+ */
+function contentFor(trigger: HTMLElement): HTMLElement {
+  const id = trigger.getAttribute('aria-controls');
+  expect(id).toBeTruthy();
+  const el = document.getElementById(id as string);
+  expect(el).not.toBeNull();
+  return el as HTMLElement;
+}
+
+describe('Collapsible', () => {
+  describe('structure and rendering', () => {
+    it('renders the trigger content inside a button', () => {
+      render(
+        <Collapsible trigger="Details">
+          <p>Body</p>
+        </Collapsible>,
+      );
+      const button = screen.getByRole('button');
+      expect(button).toHaveTextContent('Details');
+      expect(button.tagName).toBe('BUTTON');
+    });
+
+    it('renders the trigger button with an explicit type="button"', () => {
+      // Prevents implicit form submission when used inside a <form>.
+      render(<Collapsible trigger="T">c</Collapsible>);
+      expect(screen.getByRole('button')).toHaveAttribute('type', 'button');
+    });
+
+    it('renders children inside the controlled content region', () => {
+      render(
+        <Collapsible trigger="Section">
+          <span data-testid="child">Hello</span>
+        </Collapsible>,
+      );
+      const content = contentFor(screen.getByRole('button'));
+      expect(within(content).getByTestId('child')).toBeInTheDocument();
+    });
+
+    it('links the trigger to its content via aria-controls', () => {
+      render(<Collapsible trigger="T">Body</Collapsible>);
+      const button = screen.getByRole('button');
+      const content = contentFor(button);
+      expect(button.getAttribute('aria-controls')).toBe(content.id);
+    });
+
+    it('renders the stable astryx-collapsible class on the root', () => {
+      render(
+        <Collapsible trigger="T" data-testid="root">
+          c
+        </Collapsible>,
+      );
+      expect(screen.getByTestId('root')).toHaveClass('astryx-collapsible');
+    });
+
+    it('renders a ReactNode trigger, not just a string', () => {
+      render(
+        <Collapsible trigger={<span data-testid="rich">Rich</span>}>
+          c
+        </Collapsible>,
+      );
+      expect(screen.getByTestId('rich')).toBeInTheDocument();
+    });
+  });
+
+  describe('uncontrolled open state', () => {
+    it('is open by default (aria-expanded="true")', () => {
+      render(<Collapsible trigger="T">Body</Collapsible>);
+      expect(screen.getByRole('button')).toHaveAttribute(
+        'aria-expanded',
+        'true',
+      );
+    });
+
+    it('honors defaultIsOpen={false} (starts collapsed)', () => {
+      render(
+        <Collapsible trigger="T" defaultIsOpen={false}>
+          Body
+        </Collapsible>,
+      );
+      expect(screen.getByRole('button')).toHaveAttribute(
+        'aria-expanded',
+        'false',
+      );
+    });
+
+    it('toggles open/closed when the trigger is clicked', async () => {
+      const user = userEvent.setup();
+      render(<Collapsible trigger="T">Body</Collapsible>);
+      const button = screen.getByRole('button');
+
+      expect(button).toHaveAttribute('aria-expanded', 'true');
+      await user.click(button);
+      expect(button).toHaveAttribute('aria-expanded', 'false');
+      await user.click(button);
+      expect(button).toHaveAttribute('aria-expanded', 'true');
+    });
+
+    it('opens a default-collapsed instance on click', async () => {
+      const user = userEvent.setup();
+      render(
+        <Collapsible trigger="T" defaultIsOpen={false}>
+          Body
+        </Collapsible>,
+      );
+      const button = screen.getByRole('button');
+      await user.click(button);
+      expect(button).toHaveAttribute('aria-expanded', 'true');
+    });
+
+    it('toggles via keyboard activation (Enter and Space)', async () => {
+      const user = userEvent.setup();
+      render(<Collapsible trigger="T">Body</Collapsible>);
+      const button = screen.getByRole('button');
+
+      button.focus();
+      expect(button).toHaveFocus();
+
+      await user.keyboard('{Enter}');
+      expect(button).toHaveAttribute('aria-expanded', 'false');
+      await user.keyboard(' ');
+      expect(button).toHaveAttribute('aria-expanded', 'true');
+    });
+
+    it('hides the content region (display:none) only when collapsed', async () => {
+      const user = userEvent.setup();
+      render(<Collapsible trigger="T">Body</Collapsible>);
+      const button = screen.getByRole('button');
+      const content = contentFor(button);
+
+      // Open: not display:none.
+      expect(content).not.toHaveStyle({display: 'none'});
+      await user.click(button);
+      // Collapsed: hidden via the contentHidden style.
+      expect(content).toHaveStyle({display: 'none'});
+    });
+
+    it('rotates the chevron indicator between open and closed states', async () => {
+      const user = userEvent.setup();
+      render(<Collapsible trigger="T">Body</Collapsible>);
+      const button = screen.getByRole('button');
+      // The chevron lives in the last span of the trigger button.
+      const chevron = button.querySelectorAll('span')[1];
+      const openClass = chevron.getAttribute('class');
+
+      await user.click(button);
+      const closedClass = chevron.getAttribute('class');
+      expect(closedClass).not.toEqual(openClass);
+    });
+  });
+
+  describe('controlled open state', () => {
+    it('reflects the isOpen prop', () => {
+      const {rerender} = render(
+        <Collapsible trigger="T" isOpen={false}>
+          Body
+        </Collapsible>,
+      );
+      expect(screen.getByRole('button')).toHaveAttribute(
+        'aria-expanded',
+        'false',
+      );
+
+      rerender(
+        <Collapsible trigger="T" isOpen={true}>
+          Body
+        </Collapsible>,
+      );
+      expect(screen.getByRole('button')).toHaveAttribute(
+        'aria-expanded',
+        'true',
+      );
+    });
+
+    it('calls onOpenChange with the negated state on click', async () => {
+      const user = userEvent.setup();
+      const onOpenChange = vi.fn();
+      render(
+        <Collapsible trigger="T" isOpen={false} onOpenChange={onOpenChange}>
+          Body
+        </Collapsible>,
+      );
+      await user.click(screen.getByRole('button'));
+      expect(onOpenChange).toHaveBeenCalledTimes(1);
+      expect(onOpenChange).toHaveBeenCalledWith(true);
+    });
+
+    it('does not self-update when controlled without onOpenChange', async () => {
+      // A controlled instance is driven entirely by the isOpen prop; a click
+      // must not flip the visual state on its own.
+      const user = userEvent.setup();
+      render(
+        <Collapsible trigger="T" isOpen={false}>
+          Body
+        </Collapsible>,
+      );
+      const button = screen.getByRole('button');
+      await user.click(button);
+      expect(button).toHaveAttribute('aria-expanded', 'false');
+    });
+
+    it('stays put until the parent updates isOpen', async () => {
+      const user = userEvent.setup();
+      const onOpenChange = vi.fn();
+      const {rerender} = render(
+        <Collapsible trigger="T" isOpen={false} onOpenChange={onOpenChange}>
+          Body
+        </Collapsible>,
+      );
+      const button = screen.getByRole('button');
+      await user.click(button);
+      // Still closed — parent hasn't re-rendered with the new value yet.
+      expect(button).toHaveAttribute('aria-expanded', 'false');
+
+      rerender(
+        <Collapsible trigger="T" isOpen={true} onOpenChange={onOpenChange}>
+          Body
+        </Collapsible>,
+      );
+      expect(button).toHaveAttribute('aria-expanded', 'true');
+    });
+  });
+
+  describe('prop forwarding', () => {
+    it('forwards a ref to the root element', () => {
+      const ref = vi.fn();
+      render(
+        <Collapsible ref={ref} trigger="T">
+          c
+        </Collapsible>,
+      );
+      expect(ref).toHaveBeenCalledWith(expect.any(HTMLDivElement));
+    });
+
+    it('passes through data-testid and other DOM props to the root', () => {
+      render(
+        <Collapsible trigger="T" data-testid="root" data-custom="x">
+          c
+        </Collapsible>,
+      );
+      const root = screen.getByTestId('root');
+      expect(root).toHaveAttribute('data-custom', 'x');
+    });
+
+    it('exposes a displayName for devtools', () => {
+      expect(Collapsible.displayName).toBe('Collapsible');
+    });
+  });
+
+  describe('inside CollapsibleGroup (single mode)', () => {
+    it('opens the item matching defaultValue and closes the rest', () => {
+      render(
+        <CollapsibleGroup type="single" defaultValue="b">
+          <Collapsible trigger="A" value="a">
+            Body A
+          </Collapsible>
+          <Collapsible trigger="B" value="b">
+            Body B
+          </Collapsible>
+        </CollapsibleGroup>,
+      );
+      const [a, b] = screen.getAllByRole('button');
+      expect(a).toHaveAttribute('aria-expanded', 'false');
+      expect(b).toHaveAttribute('aria-expanded', 'true');
+    });
+
+    it('opening one item closes the previously open item', async () => {
+      const user = userEvent.setup();
+      render(
+        <CollapsibleGroup type="single" defaultValue="a">
+          <Collapsible trigger="A" value="a">
+            Body A
+          </Collapsible>
+          <Collapsible trigger="B" value="b">
+            Body B
+          </Collapsible>
+        </CollapsibleGroup>,
+      );
+      const [a, b] = screen.getAllByRole('button');
+      expect(a).toHaveAttribute('aria-expanded', 'true');
+
+      await user.click(b);
+      expect(a).toHaveAttribute('aria-expanded', 'false');
+      expect(b).toHaveAttribute('aria-expanded', 'true');
+    });
+
+    it('clicking the open item closes it (single mode allows all-closed)', async () => {
+      const user = userEvent.setup();
+      render(
+        <CollapsibleGroup type="single" defaultValue="a">
+          <Collapsible trigger="A" value="a">
+            Body A
+          </Collapsible>
+        </CollapsibleGroup>,
+      );
+      const a = screen.getByRole('button');
+      await user.click(a);
+      expect(a).toHaveAttribute('aria-expanded', 'false');
+    });
+
+    it('fires the group onChange with the newly opened value', async () => {
+      const user = userEvent.setup();
+      const onChange = vi.fn();
+      render(
+        <CollapsibleGroup type="single" onChange={onChange}>
+          <Collapsible trigger="A" value="a">
+            Body A
+          </Collapsible>
+        </CollapsibleGroup>,
+      );
+      await user.click(screen.getByRole('button'));
+      expect(onChange).toHaveBeenCalledWith('a');
+    });
+  });
+
+  describe('inside CollapsibleGroup (multiple mode)', () => {
+    it('allows several items open at once', async () => {
+      const user = userEvent.setup();
+      render(
+        <CollapsibleGroup type="multiple" defaultValue={['a']}>
+          <Collapsible trigger="A" value="a">
+            Body A
+          </Collapsible>
+          <Collapsible trigger="B" value="b">
+            Body B
+          </Collapsible>
+        </CollapsibleGroup>,
+      );
+      const [a, b] = screen.getAllByRole('button');
+      expect(a).toHaveAttribute('aria-expanded', 'true');
+      expect(b).toHaveAttribute('aria-expanded', 'false');
+
+      await user.click(b);
+      // Opening B does not close A in multiple mode.
+      expect(a).toHaveAttribute('aria-expanded', 'true');
+      expect(b).toHaveAttribute('aria-expanded', 'true');
+    });
+
+    it('fires onChange with the full array of open values', async () => {
+      const user = userEvent.setup();
+      const onChange = vi.fn();
+      render(
+        <CollapsibleGroup
+          type="multiple"
+          defaultValue={['a']}
+          onChange={onChange}>
+          <Collapsible trigger="A" value="a">
+            Body A
+          </Collapsible>
+          <Collapsible trigger="B" value="b">
+            Body B
+          </Collapsible>
+        </CollapsibleGroup>,
+      );
+      const [, b] = screen.getAllByRole('button');
+      await user.click(b);
+      expect(onChange).toHaveBeenCalledWith(['a', 'b']);
+    });
+  });
+
+  describe('group presentation (dividers + density)', () => {
+    it('reflects group density as a data attribute on items when dividers are enabled', () => {
+      render(
+        <CollapsibleGroup type="single" hasDividers density="compact">
+          <Collapsible trigger="A" value="a" data-testid="item-a">
+            Body A
+          </Collapsible>
+        </CollapsibleGroup>,
+      );
+      const item = screen.getByTestId('item-a');
+      expect(item).toHaveAttribute('data-density', 'compact');
+    });
+
+    it('omits density data attribute when standalone (no group)', () => {
+      render(
+        <Collapsible trigger="A" data-testid="item">
+          Body
+        </Collapsible>,
+      );
+      const item = screen.getByTestId('item');
+      expect(item).not.toHaveAttribute('data-density');
+    });
+  });
+});

package/src/Collapsible/Collapsible.tsx

@@ -4,15 +4,21 @@
 
 /**
  * @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
  *
  * Collapsible is a standalone primitive that makes any content collapsible.
  * It renders a trigger area (always visible) and a content area that toggles.
- * Handles state management, accessibility (aria-expanded), and chevron indicator.
+ * Handles state management, accessibility (aria-expanded + aria-controls linking
+ * the trigger to its content region), and chevron indicator.
  *
  * Works standalone or coordinated by CollapsibleGroup via the `value` prop.
+ * When the surrounding CollapsibleGroup sets `hasDividers`, 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 +27,10 @@
  * - /packages/cli/templates/blocks/components/Collapsible/ (showcase blocks)
  */
 
-import type {ReactNode} from 'react';
+import {use, useId, type ReactNode} from 'react';
 import * as stylex from '@stylexjs/stylex';
 import {
+  borderVars,
   colorVars,
   typographyVars,
   fontWeightVars,
@@ -33,6 +40,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';
@@ -57,6 +65,16 @@ const styles = stylex.create({
     color: colorVars['--color-text-primary'],
     textAlign: 'start',
     paddingBlock: 0,
+    // `all: unset` above wipes the UA focus outline; restore a keyboard-only
+    // focus ring using the standard token/offset (WCAG 2.4.7).
+    outline: {
+      default: null,
+      ':focus-visible': `2px solid ${colorVars['--color-accent']}`,
+    },
+    outlineOffset: {
+      default: '0',
+      ':focus-visible': '2px',
+    },
   },
   // Capsize: trim leading from text triggers
   triggerLabel: {
@@ -87,8 +105,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 +244,24 @@ export function Collapsible({
     value,
   });
 
+  const presentation = use(CollapsibleGroupPresentationContext);
+  const isDivided = presentation?.hasDividers ?? false;
+  const density = presentation?.density ?? null;
+
   const chevronIcon = getIcon('chevronDown');
 
+  // 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();
+
   return (
     <div
       ref={ref}
       {...mergeProps(
-        themeProps('collapsible'),
-        stylex.props(styles.root, xstyle),
+        themeProps('collapsible', {
+          density: density ?? undefined,
+        }),
+        stylex.props(styles.root, isDivided && styles.divided, xstyle),
         className,
         style,
       )}
@@ -208,7 +270,11 @@ export function Collapsible({
         type="button"
         onClick={toggle}
         aria-expanded={isOpen}
-        {...stylex.props(styles.trigger)}>
+        aria-controls={contentId}
+        {...stylex.props(
+          styles.trigger,
+          density != null && triggerDensity[density],
+        )}>
         <span {...stylex.props(styles.triggerLabel)}>{trigger}</span>
         <span
           {...stylex.props(
@@ -219,10 +285,19 @@ export function Collapsible({
         </span>
       </button>
       <div
-        {...(isOpen
-          ? stylex.props(styles.content)
-          : stylex.props(styles.content, styles.contentHidden))}>
-        {children}
+        id={contentId}
+        {...stylex.props(
+          styles.content,
+          density != null && contentDensity[density],
+          !isOpen && styles.contentHidden,
+        )}>
+        {presentation != null ? (
+          <CollapsibleGroupPresentationContext value={null}>
+            {children}
+          </CollapsibleGroupPresentationContext>
+        ) : (
+          children
+        )}
       </div>
     </div>
   );

package/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: 'hasDividers',
+      type: 'boolean',
+      description: "Whether to draw hairline dividers between the group's items. When set, 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: 'false',
+    },
+    {
+      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: 'hasDividers',
+      type: 'boolean',
+      description: "是否在组项目之间绘制细线分隔线。启用后组会渲染一个包裹 div，且项目默认使用 'balanced' 密度。适合搭配裸 Collapsible 子项使用；用 Card 包裹的项目自带视觉分隔。",
+      default: 'false',
+    },
+    {
+      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',
+    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",
     children: 'Collapsible instances to coordinate',
   },
 };