@eocrm/design-system 0.0.0-stage → 0.6.17

package/src/components/Accordion/Accordion.module.scss

@@ -0,0 +1,304 @@
+@use '../../styles/mixins' as *;
+@use './Accordion.tokens';
+
+.accordion {
+  display: flex;
+  flex-direction: column;
+  border: var(--border-width) solid var(--accordion-border-color);
+  border-radius: var(--accordion-radius);
+  background: var(--accordion-bg);
+  overflow: hidden;
+
+  // How a closed item's `.actions` render — resolved through inherited custom props
+  // so the NEAREST accordion wins (a nested accordion with a different
+  // `actionsWhenClosed` is unaffected by an ancestor's). Default: visible.
+  --accordion-actions-closed-opacity: var(--opacity-visible);
+  --accordion-actions-closed-visibility: visible;
+  --accordion-actions-closed-pointer-events: auto;
+}
+
+// Borderless variant: strip the outer chrome. Item dividing lines also
+// disappear so the accordion blends into the surrounding container.
+.accordion[data-variant='borderless'] {
+  border: 0;
+  border-radius: 0;
+  background: transparent;
+  overflow: visible;
+}
+
+.item {
+  border-bottom: var(--border-width) solid var(--accordion-item-border-color);
+}
+
+.item:last-child {
+  border-bottom: 0;
+}
+
+.accordion[data-variant='borderless'] .item {
+  border-bottom: 0;
+}
+
+// ─── Gap → separated "card" look ─────────────────────────────────────────
+// When `gap` is set, drop the joined container chrome and give each item its own
+// border + radius, separated vertically by the gap. Placed AFTER the variant
+// rules so it wins on equal specificity → cards regardless of `variant`.
+.accordion[data-gap] {
+  gap: var(--accordion-gap-md);
+  border: 0;
+  border-radius: 0;
+  background: transparent;
+  overflow: visible;
+}
+
+.accordion[data-gap='sm'] {
+  gap: var(--accordion-gap-sm);
+}
+
+.accordion[data-gap='lg'] {
+  gap: var(--accordion-gap-lg);
+}
+
+.accordion[data-gap] .item {
+  // Fill each card with the accordion surface so gapped items read as real cards
+  // on a tinted page background — not transparent outlined boxes. (The joined root
+  // carries this fill normally; in gap mode the root is transparent, so it moves
+  // to the items.)
+  background: var(--accordion-bg);
+  border: var(--border-width) solid var(--accordion-item-border-color);
+  border-radius: var(--accordion-radius);
+  overflow: hidden;
+}
+
+// Header ROW: the heading (toggle button) and an optional actions slot, side by
+// side, separated by a gap (no-op when there's no actions slot).
+.header {
+  display: flex;
+  align-items: center;
+  column-gap: var(--accordion-header-gap);
+  transition: background var(--transition-fast);
+}
+
+// Hover highlights the FULL header row — including the actions area — even when an
+// actions slot makes the toggle button itself shorter. Skipped for disabled items.
+.item:not([data-disabled]) .header:hover {
+  background: var(--accordion-trigger-bg-hover);
+}
+
+// The heading element (h2–h6) wrapping the toggle button. Grows to fill the row,
+// leaving the actions slot its intrinsic width on the right.
+.heading {
+  // stylelint-disable-next-line property-disallowed-list -- native heading margin reset
+  margin: 0;
+  flex: 1;
+  min-width: 0;
+  font-weight: var(--accordion-header-font-weight);
+  font-size: var(--accordion-header-font-size);
+}
+
+.trigger {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  width: 100%;
+
+  // Default padding belongs to size='md'; the per-size rules below override.
+  padding: var(--accordion-trigger-padding-y-md) var(--accordion-trigger-padding-x-md);
+  background: transparent;
+  border: 0;
+  font-family: inherit;
+  font-size: inherit;
+  font-weight: inherit;
+  color: var(--accordion-trigger-fg);
+  cursor: pointer;
+  text-align: left;
+
+  // Hover background lives on `.header` (the full row) so it spans full width even
+  // when an actions slot shortens this button. The trigger stays transparent.
+
+  // Inset: the ring sits inside the cell box rather than overlapping its
+  // neighbour.
+  &:focus-visible {
+    @include focus-ring(var(--accordion-trigger-ring), $offset: calc(-1 * var(--ring-offset)));
+  }
+
+  &:disabled {
+    cursor: not-allowed;
+    opacity: var(--accordion-trigger-opacity-disabled);
+  }
+}
+
+.label {
+  flex: 1;
+  min-width: 0;
+}
+
+// Wraps the indicator icon so its SIDE is controlled purely by CSS (root
+// data-indicator-side flips `order`), working for a custom `icon` too.
+.indicatorSlot {
+  display: inline-flex;
+  align-items: center;
+  flex-shrink: 0;
+}
+
+.indicator {
+  flex-shrink: 0;
+  transition: transform var(--transition-fast);
+  color: var(--accordion-indicator-fg);
+}
+
+.item[data-state='open'] .indicator {
+  transform: rotate(180deg);
+}
+
+// Indicator on the LEFT: pack the trigger to the start and move the icon slot
+// ahead of the label (a gap separates them). Default is right (space-between).
+.accordion[data-indicator-side='left'] .trigger {
+  justify-content: flex-start;
+  gap: var(--accordion-indicator-gap);
+}
+
+.accordion[data-indicator-side='left'] .indicatorSlot {
+  order: -1;
+}
+
+// Controls slot at the right of the header, OUTSIDE the toggle button. Its
+// inline-end padding mirrors the trigger's so controls align to the content edge.
+.actions {
+  display: flex;
+  align-items: center;
+  gap: var(--accordion-actions-gap);
+  flex-shrink: 0;
+  padding-inline-end: var(--accordion-trigger-padding-x-md);
+
+  // Bare-class transition (matches the reduced-motion reset's specificity so that
+  // override actually wins). Only fires when the values below change — i.e. in
+  // `actionsWhenClosed="hide"` mode as items toggle.
+  transition:
+    opacity var(--transition-fast),
+    visibility var(--transition-fast);
+}
+
+// actionsWhenClosed="hide": a closed item's actions fade out and leave the focus
+// order (visibility:hidden) — useful for dense sidebars of collapsed cards. The
+// values come from the nearest accordion's inherited props, so this also resolves
+// correctly for nested accordions. Layout space is kept (no reflow on toggle).
+.accordion[data-actions-when-closed='hide'] {
+  --accordion-actions-closed-opacity: var(--opacity-hidden);
+  --accordion-actions-closed-visibility: hidden;
+  --accordion-actions-closed-pointer-events: none;
+}
+
+.item[data-state='closed'] .actions {
+  opacity: var(--accordion-actions-closed-opacity);
+  visibility: var(--accordion-actions-closed-visibility);
+  pointer-events: var(--accordion-actions-closed-pointer-events);
+}
+
+.content {
+  display: grid;
+  grid-template-rows: 0fr;
+  transition: grid-template-rows var(--transition-base);
+
+  // Hint to the browser that grid-template-rows will animate, AND that this
+  // subtree's layout can be isolated from siblings (it can — only the
+  // accordion item itself reads .content's height). Same spirit as Drawer's
+  // will-change: transform hint — give the browser advance notice so it
+  // doesn't recompute layout from scratch on every frame.
+  will-change: grid-template-rows;
+  contain: layout style;
+}
+
+.content[data-state='open'] {
+  grid-template-rows: 1fr;
+}
+
+// The grid track from .content (0fr↔1fr) drives the height. .inner is
+// the grid item — overflow: hidden so the body inside clips during
+// collapse, min-height: 0 so the grid track's 0fr fully collapses (without
+// this, grid item's min-content baseline would keep the row at the
+// body's padding sum even when closed).
+.inner {
+  overflow: hidden;
+  min-height: 0;
+
+  // Promote to its own compositor layer. Combined with the parent's
+  // will-change + contain hints, this keeps the row-resize animation off
+  // the main-layout path and on the compositor.
+  transform: translateZ(0);
+}
+
+// The padded surface where children render. Padding lives HERE — not on
+// .inner — so it persists across the collapse transition. If the padding
+// were on .inner (the grid item), grid auto-sizing would keep the closed
+// row at min-content (padding sum) instead of zero. With padding on a
+// child .body inside .inner, the .inner can collapse to 0 cleanly, and
+// .body's padding only ever clips visually via overflow:hidden, never
+// snaps in or out — which is what causes the "content jumps" feel.
+// Default belongs to size='md'; the per-size rules below override.
+.body {
+  padding: var(--accordion-content-padding-y-md) var(--accordion-content-padding-x-md);
+}
+
+// ─── Size variants ─────────────────────────────────────────────────────
+// Drive both the trigger padding+font-size and the content padding from a
+// single data-size on the root. .heading also inherits font-size for the
+// heading element.
+
+.accordion[data-size='sm'] .heading {
+  font-size: var(--accordion-header-font-size-sm);
+}
+
+.accordion[data-size='sm'] .trigger {
+  padding: var(--accordion-trigger-padding-y-sm) var(--accordion-trigger-padding-x-sm);
+  font-size: var(--accordion-trigger-font-size-sm);
+}
+
+.accordion[data-size='sm'] .body {
+  padding: var(--accordion-content-padding-y-sm) var(--accordion-content-padding-x-sm);
+  font-size: var(--accordion-content-font-size-sm);
+}
+
+.accordion[data-size='md'] .heading {
+  font-size: var(--accordion-header-font-size-md);
+}
+
+.accordion[data-size='md'] .trigger {
+  padding: var(--accordion-trigger-padding-y-md) var(--accordion-trigger-padding-x-md);
+  font-size: var(--accordion-trigger-font-size-md);
+}
+
+.accordion[data-size='md'] .body {
+  padding: var(--accordion-content-padding-y-md) var(--accordion-content-padding-x-md);
+}
+
+.accordion[data-size='lg'] .heading {
+  font-size: var(--accordion-header-font-size-lg);
+}
+
+.accordion[data-size='lg'] .trigger {
+  padding: var(--accordion-trigger-padding-y-lg) var(--accordion-trigger-padding-x-lg);
+  font-size: var(--accordion-trigger-font-size-lg);
+}
+
+.accordion[data-size='lg'] .body {
+  padding: var(--accordion-content-padding-y-lg) var(--accordion-content-padding-x-lg);
+  font-size: var(--accordion-content-font-size-lg);
+}
+
+// Actions inline-end padding tracks the trigger's so controls stay aligned to
+// the content edge across sizes (md is the base on `.actions`).
+.accordion[data-size='sm'] .actions {
+  padding-inline-end: var(--accordion-trigger-padding-x-sm);
+}
+
+.accordion[data-size='lg'] .actions {
+  padding-inline-end: var(--accordion-trigger-padding-x-lg);
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .content,
+  .indicator,
+  .actions {
+    transition: none;
+  }
+}

package/src/components/Accordion/Accordion.tokens.scss

@@ -0,0 +1,64 @@
+// Accordion.tokens.scss — Component-scoped tokens for <Accordion>. Covers the
+// outer chrome (border, radius, bg), per-item divider, trigger surface +
+// hover/focus, indicator color + rotation, and per-size padding/font scale.
+:root {
+  // Outer chrome
+  --accordion-bg: var(--color-bg);
+  --accordion-border-color: var(--color-border);
+  --accordion-radius: var(--radius-md);
+
+  // Item divider
+  --accordion-item-border-color: var(--color-border);
+
+  // Header
+  --accordion-header-font-weight: var(--font-weight-medium);
+  --accordion-header-font-size: var(--font-size-md);
+
+  // Trigger
+  --accordion-trigger-fg: var(--color-fg);
+  --accordion-trigger-bg-hover: var(--color-bg-muted);
+  --accordion-trigger-ring: var(--ring-accent);
+  --accordion-trigger-opacity-disabled: var(--opacity-disabled);
+
+  // Indicator (chevron)
+  --accordion-indicator-fg: var(--color-fg-muted);
+
+  // Gap between the indicator and the label when the indicator sits on the left.
+  --accordion-indicator-gap: var(--space-2);
+
+  // Header actions slot — gap between the trigger and the controls, and between
+  // adjacent action controls.
+  --accordion-header-gap: var(--space-3);
+  --accordion-actions-gap: var(--space-1);
+
+  // Gap between items when `gap` is set (separated "card" look).
+  --accordion-gap-sm: var(--space-2);
+  --accordion-gap-md: var(--space-3);
+  --accordion-gap-lg: var(--space-4);
+
+  // Size: sm
+  --accordion-header-font-size-sm: var(--font-size-sm);
+  --accordion-trigger-padding-y-sm: var(--space-2);
+  --accordion-trigger-padding-x-sm: var(--space-3);
+  --accordion-trigger-font-size-sm: var(--font-size-sm);
+  --accordion-content-padding-y-sm: var(--space-2);
+  --accordion-content-padding-x-sm: var(--space-3);
+  --accordion-content-font-size-sm: var(--font-size-sm);
+
+  // Size: md
+  --accordion-header-font-size-md: var(--font-size-md);
+  --accordion-trigger-padding-y-md: var(--space-3);
+  --accordion-trigger-padding-x-md: var(--space-4);
+  --accordion-trigger-font-size-md: var(--font-size-md);
+  --accordion-content-padding-y-md: var(--space-3);
+  --accordion-content-padding-x-md: var(--space-4);
+
+  // Size: lg
+  --accordion-header-font-size-lg: var(--font-size-lg);
+  --accordion-trigger-padding-y-lg: var(--space-4);
+  --accordion-trigger-padding-x-lg: var(--space-5);
+  --accordion-trigger-font-size-lg: var(--font-size-lg);
+  --accordion-content-padding-y-lg: var(--space-4);
+  --accordion-content-padding-x-lg: var(--space-5);
+  --accordion-content-font-size-lg: var(--font-size-md);
+}

package/src/components/Accordion/Accordion.tsx

@@ -0,0 +1,272 @@
+import {
+  forwardRef,
+  useCallback,
+  useMemo,
+  useState,
+  type HTMLAttributes,
+  type ReactNode,
+} from 'react';
+import clsx from 'clsx';
+import { AccordionContext, type AccordionContextValue } from './context';
+import { AccordionItem } from './AccordionItem';
+import { AccordionTrigger } from './AccordionTrigger';
+import { AccordionContent } from './AccordionContent';
+import styles from './Accordion.module.scss';
+
+/** Selection mode. */
+export type AccordionMode = 'single' | 'multiple';
+
+/** Heading level wrapping the trigger button. Defaults to 'h3'. */
+export type AccordionHeaderLevel = 'h2' | 'h3' | 'h4' | 'h5' | 'h6';
+
+/**
+ * Visual variant. Defaults to `'bordered'`.
+ * - `'bordered'` — outer border + radius + dividing lines between items. Standard standalone look.
+ * - `'borderless'` — no outer border, no item borders, transparent background. Use when the accordion sits inside another bordered container (e.g., a Card) or as a section divider.
+ */
+export type AccordionVariant = 'bordered' | 'borderless';
+
+/**
+ * Trigger size — controls font-size + padding. Defaults to `'md'`.
+ * - `'sm'` — `--font-size-sm`, tighter padding. Dense settings panels.
+ * - `'md'` — `--font-size-md`, default padding. Most use cases.
+ * - `'lg'` — `--font-size-lg`, larger padding. Hero FAQ sections.
+ */
+export type AccordionSize = 'sm' | 'md' | 'lg';
+
+/**
+ * Spacing between items. When set, items render as separated **cards** (each gets
+ * its own border + radius) and the joined container chrome (outer border + item
+ * dividers) is dropped. Omit for the default joined look. `'sm'`/`'md'`/`'lg'`
+ * step the gap. Applies regardless of `variant`.
+ */
+export type AccordionGap = 'sm' | 'md' | 'lg';
+
+/** Which side the trigger indicator (chevron) sits on. Defaults to `'right'`. */
+export type AccordionIndicatorSide = 'left' | 'right';
+
+/**
+ * Whether a `<Accordion.Trigger actions>` slot stays visible when its item is
+ * collapsed. `'show'` (default) keeps controls always visible; `'hide'` fades them
+ * out (and removes them from focus order) while the item is closed — useful for a
+ * dense sidebar of collapsed blocks whose controls act on hidden body content.
+ */
+export type AccordionActionsWhenClosed = 'show' | 'hide';
+
+interface AccordionBaseProps extends Omit<
+  HTMLAttributes<HTMLDivElement>,
+  'defaultValue' | 'onChange'
+> {
+  /** Visual variant. Defaults to `'bordered'`. */
+  variant?: AccordionVariant;
+  /** Trigger size (font + padding). Defaults to `'md'`. */
+  size?: AccordionSize;
+  /**
+   * Gap between items → separated "card" look (each item gets its own border +
+   * radius; the outer container chrome is dropped). Omit for the joined default.
+   */
+  gap?: AccordionGap;
+  /** Which side the chevron indicator sits on. Defaults to `'right'`. */
+  indicatorSide?: AccordionIndicatorSide;
+  /**
+   * Whether `Accordion.Trigger` `actions` stay visible when the item is collapsed.
+   * Defaults to `'show'`; `'hide'` fades them out (and drops them from focus order)
+   * while closed.
+   */
+  actionsWhenClosed?: AccordionActionsWhenClosed;
+  children: ReactNode;
+}
+
+/** Root props — `type='single'` variant. */
+interface AccordionSingleProps {
+  type: 'single';
+  /** Controlled open item value. `''` = nothing open (only meaningful when `collapsible`). */
+  value?: string;
+  /** Initial open item for uncontrolled use. */
+  defaultValue?: string;
+  /** Fires when the open item changes. */
+  onValueChange?: (next: string) => void;
+  /**
+   * When true, clicking the currently-open item closes it. Default: `false`
+   * (matches Radix; prevents accidentally closing the only available content).
+   */
+  collapsible?: boolean;
+}
+
+/** Root props — `type='multiple'` variant. */
+interface AccordionMultipleProps {
+  type: 'multiple';
+  /** Controlled open items array. */
+  value?: string[];
+  /** Initial open items for uncontrolled use. */
+  defaultValue?: string[];
+  /** Fires when the set of open items changes. */
+  onValueChange?: (next: string[]) => void;
+  collapsible?: never;
+}
+
+/** Discriminated union — `type` drives which variant of value/onValueChange is required. */
+export type AccordionProps = AccordionBaseProps & (AccordionSingleProps | AccordionMultipleProps);
+
+/**
+ * Vertically-stacked collapsible panels. Compound component with `Item`, `Trigger` and `Content`.
+ * @see docs/components/Accordion.md
+ */
+const AccordionRoot = forwardRef<HTMLDivElement, AccordionProps>(
+  function AccordionRoot(props, ref) {
+    if (props.type === 'single') {
+      return <AccordionSingleImpl {...props} ref={ref} />;
+    }
+    return <AccordionMultipleImpl {...props} ref={ref} />;
+  },
+);
+
+interface SingleImplProps extends AccordionBaseProps, AccordionSingleProps {}
+
+const AccordionSingleImpl = forwardRef<HTMLDivElement, SingleImplProps>(
+  function AccordionSingleImpl(
+    {
+      type: _type,
+      value,
+      defaultValue,
+      onValueChange,
+      collapsible = false,
+      variant = 'bordered',
+      size = 'md',
+      gap,
+      indicatorSide = 'right',
+      actionsWhenClosed = 'show',
+      children,
+      className,
+      ...rest
+    },
+    ref,
+  ) {
+    const [internalValue, setInternalValue] = useState<string>(defaultValue ?? '');
+    const isControlled = value !== undefined;
+    const currentValue = isControlled ? value : internalValue;
+
+    const isOpen = useCallback((itemValue: string) => currentValue === itemValue, [currentValue]);
+
+    const toggle = useCallback(
+      (itemValue: string) => {
+        if (currentValue === itemValue) {
+          if (collapsible) {
+            if (!isControlled) setInternalValue('');
+            onValueChange?.('');
+          }
+        } else {
+          if (!isControlled) setInternalValue(itemValue);
+          onValueChange?.(itemValue);
+        }
+      },
+      [currentValue, collapsible, isControlled, onValueChange],
+    );
+
+    const ctx = useMemo<AccordionContextValue>(
+      () => ({ mode: 'single', isOpen, toggle }),
+      [isOpen, toggle],
+    );
+
+    return (
+      <AccordionContext.Provider value={ctx}>
+        {/* Pattern A — consumer props reach the div, but data-accordion /
+            data-variant / data-size / className are set AFTER the spread so
+            the keyboard-scope marker, variant, size, and component class
+            can't be overridden by a consumer. */}
+        <div
+          ref={ref}
+          {...rest}
+          data-accordion=""
+          data-variant={variant}
+          data-size={size}
+          data-gap={gap}
+          data-indicator-side={indicatorSide}
+          data-actions-when-closed={actionsWhenClosed}
+          className={clsx(styles.accordion, className)}
+        >
+          {children}
+        </div>
+      </AccordionContext.Provider>
+    );
+  },
+);
+
+interface MultipleImplProps extends AccordionBaseProps, AccordionMultipleProps {}
+
+const AccordionMultipleImpl = forwardRef<HTMLDivElement, MultipleImplProps>(
+  function AccordionMultipleImpl(
+    {
+      type: _type,
+      value,
+      defaultValue,
+      onValueChange,
+      variant = 'bordered',
+      size = 'md',
+      gap,
+      indicatorSide = 'right',
+      actionsWhenClosed = 'show',
+      children,
+      className,
+      ...rest
+    },
+    ref,
+  ) {
+    const [internalValue, setInternalValue] = useState<string[]>(defaultValue ?? []);
+    const isControlled = value !== undefined;
+    const currentValue = isControlled ? value : internalValue;
+
+    const isOpen = useCallback(
+      (itemValue: string) => currentValue.includes(itemValue),
+      [currentValue],
+    );
+
+    const toggle = useCallback(
+      (itemValue: string) => {
+        const next = currentValue.includes(itemValue)
+          ? currentValue.filter((v) => v !== itemValue)
+          : [...currentValue, itemValue];
+        if (!isControlled) setInternalValue(next);
+        onValueChange?.(next);
+      },
+      [currentValue, isControlled, onValueChange],
+    );
+
+    const ctx = useMemo<AccordionContextValue>(
+      () => ({ mode: 'multiple', isOpen, toggle }),
+      [isOpen, toggle],
+    );
+
+    return (
+      <AccordionContext.Provider value={ctx}>
+        {/* Pattern A — consumer props reach the div, but data-accordion /
+            data-variant / data-size / className are set AFTER the spread so
+            the keyboard-scope marker, variant, size, and component class
+            can't be overridden by a consumer. */}
+        <div
+          ref={ref}
+          {...rest}
+          data-accordion=""
+          data-variant={variant}
+          data-size={size}
+          data-gap={gap}
+          data-indicator-side={indicatorSide}
+          data-actions-when-closed={actionsWhenClosed}
+          className={clsx(styles.accordion, className)}
+        >
+          {children}
+        </div>
+      </AccordionContext.Provider>
+    );
+  },
+);
+
+/**
+ * Compound export.
+ * @see docs/components/Accordion.md
+ */
+export const Accordion = Object.assign(AccordionRoot, {
+  Item: AccordionItem,
+  Trigger: AccordionTrigger,
+  Content: AccordionContent,
+});

package/src/components/Accordion/AccordionContent.tsx

@@ -0,0 +1,36 @@
+import { forwardRef, type HTMLAttributes, type ReactNode } from 'react';
+import clsx from 'clsx';
+import { useAccordionItemContext } from './context';
+import styles from './Accordion.module.scss';
+
+export interface AccordionContentProps extends HTMLAttributes<HTMLDivElement> {
+  children: ReactNode;
+}
+
+/**
+ * Collapsible region announced via `role="region"` + `aria-labelledby` pointing at the trigger.
+ * @see docs/components/Accordion.md
+ */
+export const AccordionContent = forwardRef<HTMLDivElement, AccordionContentProps>(
+  function AccordionContent({ children, className, ...props }, ref) {
+    const { isOpen, triggerId, contentId } = useAccordionItemContext('Content');
+
+    return (
+      // Pattern B — {...props} first so component-owned id/role/
+      // aria-labelledby/data-state/className win.
+      <div
+        {...props}
+        ref={ref}
+        id={contentId}
+        role="region"
+        aria-labelledby={triggerId}
+        data-state={isOpen ? 'open' : 'closed'}
+        className={clsx(styles.content, className)}
+      >
+        <div className={styles.inner}>
+          <div className={styles.body}>{children}</div>
+        </div>
+      </div>
+    );
+  },
+);