@eocrm/design-system 0.0.0-stage → 0.6.17

package/src/components/Table/Table.tsx

@@ -0,0 +1,381 @@
+import {
+  forwardRef,
+  type ComponentPropsWithoutRef,
+  type ComponentPropsWithRef,
+  type ElementType,
+  type ForwardedRef,
+  type HTMLAttributes,
+  type KeyboardEvent,
+  type ReactElement,
+  type ReactNode,
+  type TdHTMLAttributes,
+  type ThHTMLAttributes,
+} from 'react';
+import clsx from 'clsx';
+import { ChevronDown, ChevronUp, ChevronsUpDown } from 'lucide-react';
+import styles from './Table.module.scss';
+
+/** Row height + cell padding scale. */
+export type TableDensity = 'comfortable' | 'dense';
+
+/** Header-cell text alignment. */
+export type TableCellAlign = 'start' | 'center' | 'end';
+
+/** Sort state for a header cell. */
+export type TableSortDirection = 'asc' | 'desc' | 'none';
+
+/** Column-layout algorithm for the `<table>`. */
+export type TableLayout = 'auto' | 'fixed';
+
+/** Background tint + text colour for a cell or header cell. */
+export type TableCellTone = 'danger' | 'accent';
+
+export interface TableProps extends Omit<HTMLAttributes<HTMLTableElement>, 'children'> {
+  /**
+   * Row height + cell padding scale. Defaults to `'comfortable'`.
+   * - `'comfortable'` — 32px row, 12px horiz padding, font-size-md.
+   * - `'dense'`       — 24px row, 8px horiz padding, font-size-sm.
+   */
+  density?: TableDensity;
+  /** Zebra-striped body rows (even rows tinted). Defaults to `false`. */
+  striped?: boolean;
+  /**
+   * Full-grid borders — outer border + vertical borders between every cell
+   * on top of the existing horizontal row dividers. Defaults to `false`
+   * (Atlassian-style minimal: header underline + row dividers only).
+   */
+  bordered?: boolean;
+  /**
+   * Hover highlight on body rows. Defaults to `false` — turn on when the
+   * table represents a list of clickable / selectable items (a row a user
+   * is likely to act on). Leave off for read-only data displays where the
+   * hover affordance would suggest interactivity that isn't there.
+   */
+  hover?: boolean;
+  /**
+   * `position: sticky` on the header so it stays visible while body
+   * scrolls. Requires a scrollable ancestor — the default `scroll`
+   * wrapper provides one. Defaults to `false`.
+   */
+  stickyHeader?: boolean;
+  /**
+   * When `true` (default), the `<table>` is wrapped in a `<div>` with
+   * `overflow-x: auto` so wide tables scroll horizontally inside their
+   * container. Set to `false` to render a bare `<table>` — the consumer
+   * manages their own scroll context.
+   */
+  scroll?: boolean;
+  /**
+   * Column-layout algorithm. Defaults to `'auto'`.
+   * - `'auto'`  — columns size to their content (native default).
+   * - `'fixed'` — `table-layout: fixed`: widths come from a native
+   *   `<colgroup><col style={{ width }} /></colgroup>` (or the first row), and
+   *   unsized columns split the rest equally. Use for grids of equal-width
+   *   number columns.
+   */
+  layout?: TableLayout;
+  /** Compound-subcomponent children. */
+  children?: ReactNode;
+}
+
+export interface TableCaptionProps extends HTMLAttributes<HTMLTableCaptionElement> {
+  children: ReactNode;
+}
+
+export interface TableSectionProps extends HTMLAttributes<HTMLTableSectionElement> {
+  children: ReactNode;
+}
+
+export interface TableRowProps extends HTMLAttributes<HTMLTableRowElement> {
+  /**
+   * Visual selected state. Pair with the consumer's own selection logic.
+   * Adds `aria-selected="true"` and a subtle accent tint that wins over
+   * hover/striped.
+   */
+  selected?: boolean;
+  children: ReactNode;
+}
+
+export interface TableHeaderCellProps extends Omit<
+  ThHTMLAttributes<HTMLTableCellElement>,
+  'align' | 'scope'
+> {
+  /** Text alignment. Defaults to `'start'`. */
+  align?: TableCellAlign;
+  /**
+   * Native HTML `<th scope>` attribute. Defaults to `'col'` (the cell labels
+   * its column). Use `'row'` for the leftmost cell that labels its row when
+   * rendering row-headers inside `<Table.Body>`. `'colgroup'` / `'rowgroup'`
+   * are valid HTML but rarely needed in practice.
+   */
+  scope?: 'col' | 'row' | 'colgroup' | 'rowgroup';
+  /**
+   * When set, the cell renders a sort indicator (up/down/unsorted chevron)
+   * and sets `aria-sort`. The consumer drives interactivity via `onClick`;
+   * this primitive only paints the indicator. Sortable headers also become
+   * keyboard-reachable (`tabIndex={0}` + Enter/Space → `onClick`).
+   * - `'asc'`  → up chevron + `aria-sort="ascending"`.
+   * - `'desc'` → down chevron + `aria-sort="descending"`.
+   * - `'none'` → muted up/down chevron + `aria-sort="none"`.
+   * Omit to render a non-sortable header (no chevron, no `aria-sort`).
+   */
+  sortDirection?: TableSortDirection;
+  /**
+   * Tints the header cell (top corners rounded, square under `bordered`) so a toned column reads as one
+   * band with its toned body cells. Exposed as `data-tone`. Default: none.
+   * - `'danger'` — overdue / at-risk column.
+   * - `'accent'` — the current / highlighted column (e.g. "Today").
+   */
+  tone?: TableCellTone;
+  children?: ReactNode;
+}
+
+export interface TableCellProps extends Omit<TdHTMLAttributes<HTMLTableCellElement>, 'align'> {
+  /** Text alignment. Defaults to `'start'`. */
+  align?: TableCellAlign;
+  /**
+   * Suppress wrapping and ellipsize on overflow. Requires a constrained
+   * cell width (column-level CSS or `style={{ maxWidth: … }}`).
+   */
+  truncate?: boolean;
+  /**
+   * Tints the cell background and colours its text. Exposed as `data-tone`.
+   * Default: none. Set it on every cell of the column (header included).
+   * - `'danger'` — overdue / at-risk column.
+   * - `'accent'` — the current / highlighted column (e.g. "Today").
+   */
+  tone?: TableCellTone;
+  children?: ReactNode;
+}
+
+interface TableCellLinkOwnProps {
+  children?: ReactNode;
+}
+
+/**
+ * Public `Table.CellLink` prop type. Generic `C` defaults to `'a'`; pass
+ * `as={RouterLink}` to get that component's props (`to`, …) with inference.
+ */
+export type TableCellLinkProps<C extends ElementType = 'a'> = TableCellLinkOwnProps & {
+  /** Element or component to render. Defaults to `'a'`; use for router links. */
+  as?: C;
+} & Omit<ComponentPropsWithoutRef<C>, keyof TableCellLinkOwnProps | 'as'>;
+
+type TableCellLinkComponent = <C extends ElementType = 'a'>(
+  props: TableCellLinkProps<C> & { ref?: ComponentPropsWithRef<C>['ref'] },
+) => ReactElement | null;
+
+const sortAriaFor: Record<TableSortDirection, 'ascending' | 'descending' | 'none'> = {
+  asc: 'ascending',
+  desc: 'descending',
+  none: 'none',
+};
+
+/**
+ * Tabular data primitive with a compound API (`Table.Header`, `Table.Body`, `Table.Row`, `Table.Cell`, ...) over native table elements.
+ * @see docs/components/Table.md
+ */
+const TableRoot = forwardRef<HTMLTableElement, TableProps>(function TableRoot(
+  {
+    density = 'comfortable',
+    striped,
+    bordered,
+    hover = false,
+    stickyHeader,
+    scroll = true,
+    layout = 'auto',
+    className,
+    children,
+    ...props
+  },
+  ref,
+) {
+  const table = (
+    <table
+      ref={ref}
+      className={clsx(
+        styles.table,
+        styles[`density-${density}`],
+        striped && styles.striped,
+        bordered && styles.bordered,
+        hover && styles.hover,
+        stickyHeader && styles.stickyHeader,
+        layout === 'fixed' && styles.layoutFixed,
+        className,
+      )}
+      // {...props} last so consumer overrides win (Pattern A).
+      {...props}
+    >
+      {children}
+    </table>
+  );
+
+  if (!scroll) return table;
+  return <div className={styles.scrollWrap}>{table}</div>;
+});
+
+const TableCaption = forwardRef<HTMLTableCaptionElement, TableCaptionProps>(function TableCaption(
+  { className, children, ...props },
+  ref,
+) {
+  return (
+    <caption ref={ref} className={clsx(styles.caption, className)} {...props}>
+      {children}
+    </caption>
+  );
+});
+
+const TableHeader = forwardRef<HTMLTableSectionElement, TableSectionProps>(function TableHeader(
+  { className, children, ...props },
+  ref,
+) {
+  return (
+    <thead ref={ref} className={clsx(styles.thead, className)} {...props}>
+      {children}
+    </thead>
+  );
+});
+
+const TableBody = forwardRef<HTMLTableSectionElement, TableSectionProps>(function TableBody(
+  { className, children, ...props },
+  ref,
+) {
+  return (
+    <tbody ref={ref} className={clsx(styles.tbody, className)} {...props}>
+      {children}
+    </tbody>
+  );
+});
+
+const TableFooter = forwardRef<HTMLTableSectionElement, TableSectionProps>(function TableFooter(
+  { className, children, ...props },
+  ref,
+) {
+  return (
+    <tfoot ref={ref} className={clsx(styles.tfoot, className)} {...props}>
+      {children}
+    </tfoot>
+  );
+});
+
+const TableRow = forwardRef<HTMLTableRowElement, TableRowProps>(function TableRow(
+  { selected, className, children, ...props },
+  ref,
+) {
+  return (
+    <tr
+      ref={ref}
+      aria-selected={selected || undefined}
+      className={clsx(styles.tr, selected && styles.selected, className)}
+      {...props}
+    >
+      {children}
+    </tr>
+  );
+});
+
+const TableHeaderCell = forwardRef<HTMLTableCellElement, TableHeaderCellProps>(
+  function TableHeaderCell(
+    {
+      align = 'start',
+      sortDirection,
+      tone,
+      scope = 'col',
+      className,
+      children,
+      onKeyDown,
+      tabIndex,
+      ...props
+    },
+    ref,
+  ) {
+    const sortable = sortDirection != null;
+    const SortIcon =
+      sortDirection === 'asc' ? ChevronUp : sortDirection === 'desc' ? ChevronDown : ChevronsUpDown;
+
+    // Sortable headers are keyboard-reachable: `<th>` is not natively
+    // focusable, so we add `tabIndex={0}` when sortable and forward
+    // Enter/Space to a synthetic click so the consumer's `onClick`
+    // handler fires. Consumer-supplied tabIndex/onKeyDown still win.
+    const handleKeyDown = (e: KeyboardEvent<HTMLTableCellElement>) => {
+      onKeyDown?.(e);
+      if (!sortable || e.defaultPrevented) return;
+      if (e.key === 'Enter' || e.key === ' ') {
+        e.preventDefault();
+        e.currentTarget.click();
+      }
+    };
+
+    return (
+      <th
+        ref={ref}
+        scope={scope}
+        data-tone={tone}
+        aria-sort={sortable ? sortAriaFor[sortDirection] : undefined}
+        tabIndex={sortable ? (tabIndex ?? 0) : tabIndex}
+        onKeyDown={sortable ? handleKeyDown : onKeyDown}
+        className={clsx(
+          styles.th,
+          styles[`align-${align}`],
+          sortable && styles.sortable,
+          sortable && sortDirection === 'none' && styles.sortableInactive,
+          className,
+        )}
+        {...props}
+      >
+        <span className={styles.thInner}>
+          {children != null && <span>{children}</span>}
+          {sortable && <SortIcon size={12} aria-hidden="true" className={styles.sortIcon} />}
+        </span>
+      </th>
+    );
+  },
+);
+
+const TableCell = forwardRef<HTMLTableCellElement, TableCellProps>(function TableCell(
+  { align = 'start', truncate, tone, className, children, ...props },
+  ref,
+) {
+  return (
+    <td
+      ref={ref}
+      data-tone={tone}
+      className={clsx(styles.td, styles[`align-${align}`], truncate && styles.truncate, className)}
+      {...props}
+    >
+      {children}
+    </td>
+  );
+});
+
+/**
+ * Full-cell link inside `Table.Cell`: takes over the cell's padding so the whole cell is the hit area.
+ * @see docs/components/Table.md
+ */
+const TableCellLink = forwardRef(function TableCellLink<C extends ElementType = 'a'>(
+  { as, className, children, ...props }: TableCellLinkProps<C>,
+  ref: ForwardedRef<Element>,
+) {
+  const Component = (as || 'a') as ElementType;
+  return (
+    // {...props} first so the cellLink class (the cell's padding hook) is always kept.
+    <Component ref={ref} {...props} className={clsx(styles.cellLink, className)}>
+      {children}
+    </Component>
+  );
+}) as TableCellLinkComponent;
+
+/**
+ * Compound `<Table>` family; subcomponents are attached as `Table.Body` etc.
+ * @see docs/components/Table.md
+ */
+export const Table = Object.assign(TableRoot, {
+  Caption: TableCaption,
+  Header: TableHeader,
+  Body: TableBody,
+  Footer: TableFooter,
+  Row: TableRow,
+  HeaderCell: TableHeaderCell,
+  Cell: TableCell,
+  CellLink: TableCellLink,
+});

package/src/components/Table/index.ts

@@ -0,0 +1,15 @@
+export { Table } from './Table';
+export type {
+  TableProps,
+  TableCaptionProps,
+  TableSectionProps,
+  TableRowProps,
+  TableHeaderCellProps,
+  TableCellProps,
+  TableCellLinkProps,
+  TableCellTone,
+  TableLayout,
+  TableDensity,
+  TableCellAlign,
+  TableSortDirection,
+} from './Table';

package/src/components/TableOfContents/TableOfContents.module.scss

@@ -0,0 +1,83 @@
+@use '../../styles/mixins' as *;
+
+.root {
+  display: flex;
+  flex-direction: column;
+  gap: var(--table-of-contents-gap);
+}
+
+// Resolves --table-of-contents-scroll-offset to px for the script (offsetHeight).
+// Absolute so it takes no space; translated above its own start so its height
+// never adds scrollable overflow below a short (collapsed) nav.
+// Hard rule 4: `position` is allowed here because this is an internal, visually
+// hidden measurement probe that never affects layout (cf. Avatar/Lightbox).
+.probe {
+  position: absolute;
+  inline-size: 0;
+  block-size: var(--table-of-contents-scroll-offset);
+  visibility: hidden;
+  pointer-events: none;
+  transform: translateY(-100%);
+}
+
+.list {
+  display: flex;
+  flex-direction: column;
+  padding: 0;
+  list-style: none;
+}
+
+.link {
+  display: block;
+  padding-block: var(--table-of-contents-link-padding-y);
+  padding-inline: var(--table-of-contents-link-padding-x);
+  border-inline-start: var(--table-of-contents-bar-width) solid var(--table-of-contents-rail-color);
+  font-size: var(--table-of-contents-link-font-size);
+  color: var(--table-of-contents-link-fg);
+  text-decoration: none;
+
+  &:hover {
+    color: var(--table-of-contents-link-fg-hover);
+  }
+
+  &:focus-visible {
+    @include focus-ring;
+  }
+
+  &[aria-current='location'] {
+    border-inline-start-color: var(--table-of-contents-bar-color);
+    color: var(--table-of-contents-link-fg-active);
+  }
+}
+
+.nested {
+  padding-inline-start: calc(
+    var(--table-of-contents-link-padding-x) + var(--table-of-contents-nested-indent)
+  );
+}
+
+.summary {
+  padding-block: var(--table-of-contents-link-padding-y);
+  font-size: var(--table-of-contents-link-font-size);
+  font-weight: var(--font-weight-semibold);
+  color: var(--table-of-contents-summary-fg);
+  cursor: pointer;
+
+  &:focus-visible {
+    @include focus-ring;
+  }
+}
+
+.details[open] > .summary {
+  padding-block-end: var(--table-of-contents-gap);
+}
+
+// Forced colors replaces author colours, so the transparent rail would paint on
+// every link and the accent would become LinkText. System colours survive.
+@media (forced-colors: active) {
+  .root {
+    --table-of-contents-bar-color: Highlight;
+    --table-of-contents-link-fg-active: Highlight;
+    --table-of-contents-rail-color: Canvas;
+  }
+}

package/src/components/TableOfContents/TableOfContents.tokens.scss

@@ -0,0 +1,26 @@
+// TableOfContents.tokens.scss — Component-scoped tokens for <TableOfContents>. Link colours, the active bar, level-3 indent and the scroll offset the spy and click-scroll measure from.
+// Emitted from the stable styles/tokens.scss entry (not the lazy component module), like Sticky's, which it @uses.
+@use '../Sticky/Sticky.tokens';
+
+:root {
+  // Links
+  --table-of-contents-link-fg: var(--color-fg-muted);
+  --table-of-contents-link-fg-hover: var(--color-fg);
+  --table-of-contents-link-fg-active: var(--color-accent);
+  --table-of-contents-link-font-size: var(--font-size-sm);
+  --table-of-contents-link-padding-y: var(--space-1);
+  --table-of-contents-link-padding-x: var(--space-3);
+  --table-of-contents-gap: var(--space-2);
+  --table-of-contents-summary-fg: var(--color-fg);
+
+  // Active bar — the rail is the same width, transparent, so the label never shifts
+  --table-of-contents-bar-width: var(--border-width-emphasis);
+  --table-of-contents-bar-color: var(--color-accent);
+  --table-of-contents-rail-color: transparent;
+
+  // Level 3 indent, added to the link's own inline padding
+  --table-of-contents-nested-indent: var(--space-3);
+
+  // Sticky-topbar clearance: a heading counts as reached at this y, and a click scrolls it here
+  --table-of-contents-scroll-offset: var(--sticky-top-topbar);
+}

package/src/components/TableOfContents/TableOfContents.tsx

@@ -0,0 +1,192 @@
+import {
+  forwardRef,
+  useEffect,
+  useRef,
+  useState,
+  type HTMLAttributes,
+  type MouseEvent,
+} from 'react';
+import clsx from 'clsx';
+import { useTranslation } from '../../i18n';
+import { Text } from '../Text';
+import { pickActiveSection } from './activeSection';
+import styles from './TableOfContents.module.scss';
+
+/** One entry: a heading already on the page, found by `id`. */
+export interface TableOfContentsItem {
+  /** The heading element's `id`. The link is `#id`; a missing element still renders and falls back to native hash navigation. */
+  id: string;
+  /** Visible link text — usually the heading's own text. */
+  label: string;
+  /** Heading level. `2` sits flush; `3` is indented under the `2` before it. */
+  level: 2 | 3;
+}
+
+export interface TableOfContentsProps extends Omit<HTMLAttributes<HTMLElement>, 'children'> {
+  /** Entries in document order. An empty list renders nothing. */
+  items: readonly TableOfContentsItem[];
+  /**
+   * Render a `<details>` disclosure (summary "On this page · <active>") instead
+   * of the heading + list. Use where there is no room for a side rail, e.g. on
+   * narrow viewports above the content. Default `false`.
+   */
+  collapsed?: boolean;
+}
+
+function prefersReducedMotion(): boolean {
+  return (
+    typeof window !== 'undefined' &&
+    typeof window.matchMedia === 'function' &&
+    window.matchMedia('(prefers-reduced-motion: reduce)').matches
+  );
+}
+
+/**
+ * "On this page" navigation for a long page's h2/h3 headings, with scroll-spy and offset-aware click-scroll.
+ * @see docs/components/TableOfContents.md
+ */
+export const TableOfContents = forwardRef<HTMLElement, TableOfContentsProps>(
+  function TableOfContents({ items, collapsed = false, className, ...props }, ref) {
+    const t = useTranslation();
+    const [activeId, setActiveId] = useState<string>();
+    const probeRef = useRef<HTMLSpanElement>(null);
+    const detailsRef = useRef<HTMLDetailsElement>(null);
+    const offsetRef = useRef(0);
+    const pausedRef = useRef(false);
+    const resumeRef = useRef<() => void>(undefined);
+    // Ids are whitespace-free in HTML, so the joined string is a stable effect key.
+    const idKey = items.map((item) => item.id).join(' ');
+
+    useEffect(() => {
+      if (!idKey) return;
+      const ids = idKey.split(' ');
+      let frame = 0;
+      const readOffset = () => {
+        offsetRef.current = probeRef.current?.offsetHeight ?? 0;
+      };
+      // Resolved every pass, so headings that mount after the TOC are picked up.
+      const update = () => {
+        frame = 0;
+        if (pausedRef.current) return;
+        const headings = ids.flatMap((id) => {
+          const el = document.getElementById(id);
+          return el ? [{ id, top: el.getBoundingClientRect().top }] : [];
+        });
+        const atBottom =
+          window.innerHeight + window.scrollY >= document.documentElement.scrollHeight - 2;
+        setActiveId(pickActiveSection(headings, offsetRef.current + 1, atBottom));
+      };
+      const onScroll = () => {
+        if (!frame) frame = requestAnimationFrame(update);
+      };
+      const onResize = () => {
+        readOffset();
+        onScroll();
+      };
+      readOffset();
+      update();
+      window.addEventListener('scroll', onScroll, { passive: true });
+      window.addEventListener('resize', onResize);
+      return () => {
+        cancelAnimationFrame(frame);
+        window.removeEventListener('scroll', onScroll);
+        window.removeEventListener('resize', onResize);
+      };
+    }, [idKey]);
+
+    useEffect(() => () => resumeRef.current?.(), []);
+
+    if (items.length === 0) return null;
+
+    const onLinkClick = (event: MouseEvent<HTMLAnchorElement>, id: string) => {
+      if (
+        event.defaultPrevented ||
+        event.button !== 0 ||
+        event.metaKey ||
+        event.ctrlKey ||
+        event.shiftKey ||
+        event.altKey
+      )
+        return;
+      if (detailsRef.current) detailsRef.current.open = false;
+      const target = document.getElementById(id);
+      if (!target) return;
+      event.preventDefault();
+      window.scrollTo({
+        top: target.getBoundingClientRect().top + window.scrollY - offsetRef.current,
+        behavior: prefersReducedMotion() ? 'auto' : 'smooth',
+      });
+      // Re-clicking the current entry must not stack history entries.
+      // location.hash is percent-encoded for non-ASCII ids, so compare decoded.
+      let same = false;
+      try {
+        same = decodeURIComponent(location.hash.slice(1)) === id;
+      } catch {
+        // malformed % escape: treat as a different hash
+      }
+      if (same) history.replaceState(null, '', `#${id}`);
+      else history.pushState(null, '', `#${id}`);
+      setActiveId(id);
+
+      // Hold the clicked entry while the smooth scroll passes the others.
+      resumeRef.current?.();
+      pausedRef.current = true;
+      const resume = () => {
+        pausedRef.current = false;
+        window.clearTimeout(timer);
+        window.removeEventListener('scrollend', resume);
+        resumeRef.current = undefined;
+      };
+      const timer = window.setTimeout(resume, 1000);
+      window.addEventListener('scrollend', resume);
+      resumeRef.current = resume;
+
+      if (target.tabIndex < 0 && !target.hasAttribute('tabindex')) {
+        target.setAttribute('tabindex', '-1');
+      }
+      target.focus({ preventScroll: true });
+    };
+
+    const label = t('tableOfContents.label');
+    const activeLabel = items.find((item) => item.id === activeId)?.label;
+    const list = (
+      <ul className={styles.list}>
+        {items.map((item) => (
+          <li key={item.id}>
+            <a
+              href={`#${item.id}`}
+              className={clsx(styles.link, item.level === 3 && styles.nested)}
+              aria-current={item.id === activeId ? 'location' : undefined}
+              onClick={(event) => onLinkClick(event, item.id)}
+            >
+              {item.label}
+            </a>
+          </li>
+        ))}
+      </ul>
+    );
+
+    return (
+      // {...props} last so a consumer can rename the nav (e.g. two TOCs on one page).
+      <nav ref={ref} aria-label={label} className={clsx(styles.root, className)} {...props}>
+        <span ref={probeRef} className={styles.probe} aria-hidden />
+        {collapsed ? (
+          <details ref={detailsRef} className={styles.details}>
+            <summary className={styles.summary}>
+              {label}
+              {activeLabel ? ` · ${activeLabel}` : null}
+            </summary>
+            {list}
+          </details>
+        ) : (
+          <>
+            <Text size="xs" weight="semibold" tone="muted" aria-hidden>
+              {label}
+            </Text>
+            {list}
+          </>
+        )}
+      </nav>
+    );
+  },
+);