@pharos-ds/core 1.0.5 → 1.0.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pharos-ds/core",
-  "version": "1.0.5",
+  "version": "1.0.7",
   "displayName": "Pharos Core",
   "description": "Pharos component library. Accessible, themeable React components with spacing, dark mode, and StyleX styling.",
   "author": "Caio Silvestre",

package/src/SideNav/SideNav.doc.mjs

@@ -22,7 +22,7 @@ export const docs = {
       {className: 'pharos-side-nav', visualProps: ['mode']},
       {className: 'pharos-side-nav-heading'},
       {className: 'pharos-side-nav-item', visualProps: ['size'], states: ['selected']},
-      {className: 'pharos-side-nav-section'},
+      {className: 'pharos-side-nav-section', states: ['collapsed']},
     ],
   },
   description: 'Container with five zones: header, topContent, children (scrollable), footer, and footerIcons. Supports collapsible mode.',

package/src/SideNav/SideNav.test.tsx

@@ -918,6 +918,189 @@ describe('SideNavSection', () => {
   });
 });
 
+describe('SideNavSection — collapsible', () => {
+  const items = (
+    <>
+      <SideNavItem label="Dashboard" />
+      <SideNavItem label="Reports" />
+    </>
+  );
+
+  function getItemsRegion(button: HTMLElement) {
+    const id = button.getAttribute('aria-controls');
+    expect(id).toBeTruthy();
+    return document.getElementById(id!)!;
+  }
+
+  it('is not collapsible by default (no toggle button)', () => {
+    render(<SideNavSection title="Main">{items}</SideNavSection>);
+    expect(
+      screen.queryByRole('button', {name: 'Main'}),
+    ).not.toBeInTheDocument();
+    expect(document.querySelector('[aria-expanded]')).toBeNull();
+    expect(document.querySelector('[inert]')).toBeNull();
+  });
+
+  it('renders the title as a toggle button named by the title', () => {
+    render(
+      <SideNavSection title="Main" collapsible>
+        {items}
+      </SideNavSection>,
+    );
+    const button = screen.getByRole('button', {name: 'Main'});
+    expect(button).toHaveAttribute('type', 'button');
+    expect(button).toHaveAttribute('aria-expanded', 'true');
+    expect(button).not.toHaveAttribute('aria-label');
+    const region = getItemsRegion(button);
+    expect(region).toContainElement(screen.getByText('Dashboard'));
+    expect(region).not.toHaveAttribute('inert');
+    expect(region).not.toHaveAttribute('aria-hidden');
+  });
+
+  it('keeps role="group" labelled by the title', () => {
+    render(
+      <SideNavSection title="Main" collapsible>
+        {items}
+      </SideNavSection>,
+    );
+    const group = screen.getByRole('group');
+    const label = document.getElementById(
+      group.getAttribute('aria-labelledby')!,
+    );
+    expect(label).toHaveTextContent('Main');
+  });
+
+  it('toggles aria-expanded, inert and aria-hidden on click', async () => {
+    const user = userEvent.setup();
+    render(
+      <SideNavSection title="Main" collapsible data-testid="section">
+        {items}
+      </SideNavSection>,
+    );
+    const button = screen.getByRole('button', {name: 'Main'});
+    const region = getItemsRegion(button);
+
+    await user.click(button);
+    expect(button).toHaveAttribute('aria-expanded', 'false');
+    expect(region).toHaveAttribute('inert');
+    expect(region).toHaveAttribute('aria-hidden', 'true');
+    expect(screen.getByTestId('section')).toHaveAttribute(
+      'data-collapsed',
+      'collapsed',
+    );
+
+    await user.click(button);
+    expect(button).toHaveAttribute('aria-expanded', 'true');
+    expect(region).not.toHaveAttribute('inert');
+    expect(region).not.toHaveAttribute('aria-hidden');
+    expect(screen.getByTestId('section')).not.toHaveAttribute('data-collapsed');
+  });
+
+  it('starts collapsed with defaultIsCollapsed', () => {
+    render(
+      <SideNavSection title="Main" collapsible={{defaultIsCollapsed: true}}>
+        {items}
+      </SideNavSection>,
+    );
+    const button = screen.getByRole('button', {name: 'Main'});
+    expect(button).toHaveAttribute('aria-expanded', 'false');
+    expect(getItemsRegion(button)).toHaveAttribute('inert');
+  });
+
+  it('controlled mode calls onCollapsedChange and respects the prop', async () => {
+    const user = userEvent.setup();
+    const onCollapsedChange = vi.fn();
+    const {rerender} = render(
+      <SideNavSection
+        title="Main"
+        collapsible={{isCollapsed: false, onCollapsedChange}}>
+        {items}
+      </SideNavSection>,
+    );
+    const button = screen.getByRole('button', {name: 'Main'});
+
+    await user.click(button);
+    expect(onCollapsedChange).toHaveBeenCalledWith(true);
+    // Prop did not change, so the section stays expanded
+    expect(button).toHaveAttribute('aria-expanded', 'true');
+
+    rerender(
+      <SideNavSection
+        title="Main"
+        collapsible={{isCollapsed: true, onCollapsedChange}}>
+        {items}
+      </SideNavSection>,
+    );
+    expect(button).toHaveAttribute('aria-expanded', 'false');
+    expect(getItemsRegion(button)).toHaveAttribute('inert');
+
+    await user.click(button);
+    expect(onCollapsedChange).toHaveBeenLastCalledWith(false);
+  });
+
+  it('toggles with Enter and Space (native button)', async () => {
+    const user = userEvent.setup();
+    render(
+      <SideNavSection title="Main" collapsible>
+        {items}
+      </SideNavSection>,
+    );
+    const button = screen.getByRole('button', {name: 'Main'});
+    button.focus();
+
+    await user.keyboard('{Enter}');
+    expect(button).toHaveAttribute('aria-expanded', 'false');
+    await user.keyboard(' ');
+    expect(button).toHaveAttribute('aria-expanded', 'true');
+  });
+
+  it('keeps endContent outside the toggle button', () => {
+    render(
+      <SideNavSection
+        title="Main"
+        collapsible
+        endContent={
+          <button type="button" data-testid="section-action">
+            +
+          </button>
+        }>
+        {items}
+      </SideNavSection>,
+    );
+    const toggle = screen.getByRole('button', {name: 'Main'});
+    const action = screen.getByTestId('section-action');
+    expect(toggle).not.toContainElement(action);
+    expect(action.closest('button')).toBe(action);
+  });
+
+  it('is ignored when the SideNav is rail-collapsed', () => {
+    render(
+      <SideNavCollapseContext
+        value={{isCollapsed: true, toggle: () => {}, isCollapsible: true}}>
+        <SideNavSection title="Main" collapsible={{defaultIsCollapsed: true}}>
+          <SideNavItem label="Dashboard" icon={StubIcon} />
+        </SideNavSection>
+      </SideNavCollapseContext>,
+    );
+    expect(document.querySelector('[aria-expanded]')).toBeNull();
+    expect(document.querySelector('[inert]')).toBeNull();
+    expect(screen.getByLabelText('Dashboard')).toBeInTheDocument();
+  });
+
+  it('is ignored when the header is hidden', () => {
+    render(
+      <SideNavSection
+        title="Main"
+        isHeaderHidden
+        collapsible={{defaultIsCollapsed: true}}>
+        {items}
+      </SideNavSection>,
+    );
+    expect(document.querySelector('[aria-expanded]')).toBeNull();
+    expect(document.querySelector('[inert]')).toBeNull();
+  });
+});
+
 // =============================================================================
 // Resizable
 // =============================================================================

package/src/SideNav/SideNavSection.doc.mjs

@@ -59,6 +59,12 @@ export const docs = {
       description: 'Visually hides the section header while keeping it accessible to screen readers.',
       default: 'false',
     },
+    {
+      name: 'collapsible',
+      type: 'boolean | { defaultIsCollapsed?: boolean; isCollapsed?: boolean; onCollapsedChange?: (isCollapsed: boolean) => void }',
+      description: 'Lets users collapse the section items by clicking the title. The title area becomes a toggle button (aria-expanded, chevron) and endContent stays outside it. true for uncontrolled (starts expanded), or an object with defaultIsCollapsed, or isCollapsed + onCollapsedChange for controlled mode. Ignored when isHeaderHidden is set or the SideNav is collapsed to its icon rail.',
+      default: 'false',
+    },
     {
       name: 'xstyle',
       type: 'StyleXStyles',
@@ -100,6 +106,12 @@ export const docsZh = {
       description: '视觉上隐藏分组头部，同时保持屏幕阅读器可访问。',
       default: 'false',
     },
+    {
+      name: 'collapsible',
+      type: 'boolean | { defaultIsCollapsed?: boolean; isCollapsed?: boolean; onCollapsedChange?: (isCollapsed: boolean) => void }',
+      description: '允许点击标题折叠分组项目。标题区域变为切换按钮（aria-expanded，带箭头），endContent 保持在按钮之外。true 为非受控模式（默认展开），或传入对象：defaultIsCollapsed，或 isCollapsed + onCollapsedChange 受控模式。设置 isHeaderHidden 或 SideNav 折叠为图标栏时忽略。',
+      default: 'false',
+    },
   ],
 };
 
@@ -114,6 +126,7 @@ export const docsDense = {
     children: 'Section items.',
     endContent: 'Right-side content in section header.',
     isHeaderHidden: 'Visually hides section header while keeping accessible to screen readers.',
+    collapsible: 'true | {defaultIsCollapsed?, isCollapsed?, onCollapsedChange?}. Title becomes toggle button collapsing items; endContent stays outside. Ignored if header hidden or nav rail-collapsed.',
     xstyle: 'StyleX styles for layout customization.',
   },
 };

package/src/SideNav/SideNavSection.tsx

@@ -18,17 +18,27 @@
  * - /packages/cli/templates/blocks/components/SideNav/ (showcase blocks)
  */
 
-import React, {useId, type ReactNode} from 'react';
+import React, {
+  useCallback,
+  useId,
+  useMemo,
+  useState,
+  type ReactNode,
+} from 'react';
 import * as stylex from '@stylexjs/stylex';
 import {
   colorVars,
   spacingVars,
   fontWeightVars,
   typeScaleVars,
+  durationVars,
+  easeVars,
+  radiusVars,
 } from '../theme/tokens.stylex';
 import {mergeProps} from '../utils';
 import type {BaseProps} from '../BaseProps';
 import {useSideNavCollapse} from './SideNavCollapseContext';
+import {getIcon} from '../Icon/globalIconRegistry';
 import {themeProps} from '../utils/themeProps';
 // =============================================================================
 // Styles
@@ -84,6 +94,92 @@ const styles = stylex.create({
     flexDirection: 'column',
     gap: spacingVars['--spacing-0-5'],
   },
+
+  // ── Collapsible section ──
+  // The header row loses its own padding so the toggle button can own it
+  // (giving the hover overlay the full title area) while the text stays
+  // aligned exactly where the static header puts it.
+  headerCollapsible: {
+    paddingInline: 0,
+    paddingBlock: 0,
+  },
+  headerToggle: {
+    display: 'flex',
+    alignItems: 'center',
+    gap: spacingVars['--spacing-2'],
+    flex: 1,
+    minWidth: 0,
+    width: '100%',
+    paddingInline: spacingVars['--spacing-2'],
+    paddingBlock: spacingVars['--spacing-1'],
+    margin: 0,
+    borderWidth: 0,
+    borderStyle: 'none',
+    borderRadius: radiusVars['--radius-element'],
+    backgroundColor: 'transparent',
+    color: 'inherit',
+    fontFamily: 'inherit',
+    fontSize: 'inherit',
+    fontWeight: 'inherit',
+    lineHeight: 'inherit',
+    textAlign: 'start',
+    cursor: 'pointer',
+    userSelect: 'none',
+    ':hover': {
+      '@media (hover: hover)': {
+        backgroundColor: colorVars['--color-overlay-hover'],
+      },
+    },
+    ':active': {
+      backgroundColor: colorVars['--color-overlay-pressed'],
+    },
+    outline: {
+      default: 'none',
+      ':focus-visible': `2px solid ${colorVars['--color-accent']}`,
+    },
+    outlineOffset: {
+      default: '0',
+      ':focus-visible': '-2px',
+    },
+  },
+  endContentCollapsible: {
+    paddingInlineEnd: spacingVars['--spacing-2'],
+  },
+  expandChevron: {
+    display: 'inline-flex',
+    alignItems: 'center',
+    justifyContent: 'center',
+    width: spacingVars['--spacing-6'],
+    height: spacingVars['--spacing-6'],
+    color: colorVars['--color-text-secondary'],
+    transitionProperty: 'transform',
+    transitionDuration: {
+      default: durationVars['--duration-fast'],
+      '@media (prefers-reduced-motion: reduce)': '0s',
+    },
+    transitionTimingFunction: easeVars['--ease-standard'],
+    flexShrink: 0,
+  },
+  expandChevronExpanded: {
+    transform: 'rotate(180deg)',
+  },
+  itemsCollapsible: {
+    display: 'grid',
+    gridTemplateRows: '1fr',
+    transitionProperty: 'grid-template-rows',
+    transitionDuration: {
+      default: durationVars['--duration-medium'],
+      '@media (prefers-reduced-motion: reduce)': '0s',
+    },
+    transitionTimingFunction: easeVars['--ease-standard'],
+  },
+  itemsCollapsed: {
+    gridTemplateRows: '0fr',
+  },
+  itemsInner: {
+    overflow: 'hidden',
+    minHeight: 0,
+  },
 });
 
 // =============================================================================
@@ -114,6 +210,28 @@ export interface SideNavSectionProps extends BaseProps<HTMLDivElement> {
    * @default false
    */
   isHeaderHidden?: boolean;
+  /**
+   * Lets the user collapse the section's items by clicking its title.
+   * The title area becomes a toggle button (`aria-expanded`) with a chevron;
+   * `endContent` stays outside the button.
+   *
+   * - `true` — collapsible with defaults (starts expanded)
+   * - Object — controlled/configured:
+   *   - `defaultIsCollapsed` — start collapsed (default: false)
+   *   - `isCollapsed` + `onCollapsedChange` — controlled mode
+   *
+   * Ignored when `isHeaderHidden` is set or the SideNav itself is collapsed
+   * to its icon rail (items stay visible so their icons remain reachable).
+   *
+   * @default false
+   */
+  collapsible?:
+    | boolean
+    | {
+        defaultIsCollapsed?: boolean;
+        isCollapsed?: boolean;
+        onCollapsedChange?: (isCollapsed: boolean) => void;
+      };
 }
 
 // =============================================================================
@@ -141,6 +259,7 @@ export function SideNavSection({
   children,
   endContent,
   isHeaderHidden = false,
+  collapsible,
   xstyle,
   className,
   style,
@@ -150,23 +269,83 @@ export function SideNavSection({
   const {isCollapsed} = useSideNavCollapse();
   const id = useId();
   const titleId = `${id}-title`;
+  const itemsId = `${id}-items`;
+
+  // Section collapse state (mirrors SideNavItem's `collapsible`)
+  const collapsibleConfig = useMemo(
+    () => (typeof collapsible === 'object' ? collapsible : {}),
+    [collapsible],
+  );
+  const controlledCollapsed = collapsibleConfig.isCollapsed;
+  const isControlled = controlledCollapsed !== undefined;
+  const [uncontrolledCollapsed, setUncontrolledCollapsed] = useState(
+    collapsibleConfig.defaultIsCollapsed ?? false,
+  );
+  const isSectionCollapsed = isControlled
+    ? controlledCollapsed
+    : uncontrolledCollapsed;
 
-  const headerContent = (
+  const toggleSectionCollapse = useCallback(() => {
+    const next = !isSectionCollapsed;
+    if (!isControlled) {
+      setUncontrolledCollapsed(next);
+    }
+    collapsibleConfig.onCollapsedChange?.(next);
+  }, [isSectionCollapsed, isControlled, collapsibleConfig]);
+
+  const shouldHideHeader = isHeaderHidden || isCollapsed;
+  // Collapse only applies while the header is visible: a hidden header has
+  // no toggle, and the icon rail must keep every item reachable.
+  const isSectionCollapsible =
+    collapsible != null && collapsible !== false && !shouldHideHeader;
+  const isItemsCollapsed = isSectionCollapsible && isSectionCollapsed;
+
+  const titleContent = (
+    <span {...stylex.props(styles.titleContainer)}>
+      <span id={titleId} {...stylex.props(styles.title)}>
+        {title}
+      </span>
+      {subtitle && <span {...stylex.props(styles.subtitle)}>{subtitle}</span>}
+    </span>
+  );
+
+  const endContentElement = endContent && (
+    <span
+      {...stylex.props(
+        styles.endContent,
+        isSectionCollapsible && styles.endContentCollapsible,
+      )}>
+      {endContent}
+    </span>
+  );
+
+  const headerContent = isSectionCollapsible ? (
     <>
-      <span {...stylex.props(styles.titleContainer)}>
-        <span id={titleId} {...stylex.props(styles.title)}>
-          {title}
+      <button
+        type="button"
+        onClick={toggleSectionCollapse}
+        aria-expanded={!isSectionCollapsed}
+        aria-controls={itemsId}
+        {...stylex.props(styles.headerToggle)}>
+        {titleContent}
+        <span
+          aria-hidden
+          {...stylex.props(
+            styles.expandChevron,
+            !isSectionCollapsed && styles.expandChevronExpanded,
+          )}>
+          {getIcon('chevronDown')}
         </span>
-        {subtitle && <span {...stylex.props(styles.subtitle)}>{subtitle}</span>}
-      </span>
-      {endContent && (
-        <span {...stylex.props(styles.endContent)}>{endContent}</span>
-      )}
+      </button>
+      {endContentElement}
+    </>
+  ) : (
+    <>
+      {titleContent}
+      {endContentElement}
     </>
   );
 
-  const shouldHideHeader = isHeaderHidden || isCollapsed;
-
   const visuallyHiddenStyle: React.CSSProperties = shouldHideHeader
     ? {
         position: 'absolute',
@@ -185,7 +364,12 @@ export function SideNavSection({
     <div
       ref={ref}
       {...mergeProps(
-        themeProps('side-nav-section'),
+        themeProps(
+          'side-nav-section',
+          isSectionCollapsible
+            ? {collapsed: isSectionCollapsed ? 'collapsed' : null}
+            : undefined,
+        ),
         stylex.props(styles.root, xstyle),
         className,
         style,
@@ -195,12 +379,33 @@ export function SideNavSection({
       aria-labelledby={titleId}
       data-testid={testId}>
       <div
-        {...mergeProps(stylex.props(styles.header), {
-          style: shouldHideHeader ? visuallyHiddenStyle : undefined,
-        })}>
+        {...mergeProps(
+          stylex.props(
+            styles.header,
+            isSectionCollapsible && styles.headerCollapsible,
+          ),
+          {
+            style: shouldHideHeader ? visuallyHiddenStyle : undefined,
+          },
+        )}>
         {headerContent}
       </div>
-      <div {...stylex.props(styles.items)}>{children}</div>
+      {isSectionCollapsible ? (
+        <div
+          id={itemsId}
+          aria-hidden={isItemsCollapsed || undefined}
+          inert={isItemsCollapsed ? true : undefined}
+          {...stylex.props(
+            styles.itemsCollapsible,
+            isItemsCollapsed && styles.itemsCollapsed,
+          )}>
+          <div {...stylex.props(styles.itemsInner)}>
+            <div {...stylex.props(styles.items)}>{children}</div>
+          </div>
+        </div>
+      ) : (
+        <div {...stylex.props(styles.items)}>{children}</div>
+      )}
     </div>
   );
 }