@eocrm/design-system 0.0.0-stage → 0.6.17

package/src/components/Split/Split.module.scss

@@ -0,0 +1,158 @@
+@use './Split.tokens';
+@use '../_internal/collapse' as bp;
+
+.split {
+  display: grid;
+}
+
+// Column templates. The aside track is driven by --split-aside-width (set
+// inline from the asideWidth prop; defaults to `auto` = intrinsic). `1fr` and
+// `auto` are intrinsic grid keywords, not raw lengths (same as Grid).
+.sideStart {
+  grid-template-columns: var(--split-aside-width, auto) 1fr;
+}
+
+.sideEnd {
+  grid-template-columns: 1fr var(--split-aside-width, auto);
+}
+
+// Collapsible splits use shrink-safe tracks: the pinned aside width holds
+// while space is available, then both tracks can contract without overflow as
+// the container narrows. The container query cannot re-template its own query
+// container, so this must be set before the children span every track.
+.sideStart.collapsible {
+  grid-template-columns:
+    minmax(0, var(--split-aside-width, auto))
+    minmax(0, 1fr);
+}
+
+.sideEnd.collapsible {
+  grid-template-columns:
+    minmax(0, 1fr)
+    minmax(0, var(--split-aside-width, auto));
+}
+
+// No aside cell: one full-width track. Same specificity as `.sideX.collapsible`
+// and declared after it, so it wins.
+.split.noAside {
+  grid-template-columns: minmax(0, 1fr);
+}
+
+// Aside cell — intrinsic width comes from the grid track; min-width:0 lets very
+// long aside content shrink rather than blow out the `auto` track. (Also gives
+// the class a real declaration so CSS Modules emits it for the `.aside` hook.)
+.aside {
+  min-width: 0;
+}
+
+// The main pane shrinks instead of overflowing or pushing the aside wider.
+.main {
+  min-width: 0;
+}
+
+// Gap presets — mirror Stack/Cluster/Grid scale + camelCase naming.
+.gapXs {
+  gap: var(--split-gap-xs);
+}
+
+.gapSm {
+  gap: var(--split-gap-sm);
+}
+
+.gapMd {
+  gap: var(--split-gap-md);
+}
+
+.gapLg {
+  gap: var(--split-gap-lg);
+}
+
+.gapXl {
+  gap: var(--split-gap-xl);
+}
+
+.gap2xl {
+  gap: var(--split-gap-2xl);
+}
+
+// Cross-axis alignment of the two panes.
+.alignStart {
+  align-items: start;
+}
+
+.alignStretch {
+  align-items: stretch;
+}
+
+.alignCenter {
+  align-items: center;
+}
+
+// --- collapseBelow -----------------------------------------------------
+// Only splits with `collapseBelow` become size containers, so existing splits
+// get zero containment changes (container-type: inline-size zeroes the
+// element's intrinsic-width contribution — see Split.tsx's anti-pattern note).
+.collapsible {
+  container-type: inline-size;
+}
+
+// Below the container threshold both panes span every track, so the split
+// renders as one stacked column — in DOM order (aside-then-main for
+// side="start", main-then-aside for side="end"; no `order` flip, so visual
+// order stays in sync with tab order). Same mechanism as Grid's collapseBelow:
+// the query targets the CHILDREN, because an element can never query its own
+// size container — a rule on `.collapsible` itself would resolve against the
+// nearest ANCESTOR container instead and silently never match. Spanning the
+// children also neutralizes .sideStart / .sideEnd (grid-template-columns is
+// the only thing those set) for both side values at once.
+// Double class (.collapsible.collapseXx) keeps specificity above any
+// single-class consumer rule regardless of CSS bundle emission order.
+
+// A <Sticky> that IS the aside (the documented record-detail composition) is
+// neutralized to a plain block once stacked (#558): pinned + viewport-capped
+// + overscroll-contained, it would become a near-viewport-tall inner scroll
+// box on a phone that traps the swipe. Matched by Sticky's `data-sticky` hook
+// (CSS Modules hashes its class names). Direct child only — Stickies nested
+// deeper in the aside (e.g. a list's sticky header) keep working.
+@mixin unstick-aside {
+  > .aside > [data-sticky] {
+    // stylelint-disable-next-line property-disallowed-list -- undoing Sticky's own position when Split stacks, not placing a component
+    position: static;
+    max-height: none;
+    overflow-y: visible;
+    overscroll-behavior: auto;
+  }
+}
+
+@container (max-width: #{bp.$collapse-sm}) {
+  .collapsible.collapseSm > * {
+    // stylelint-disable-next-line property-disallowed-list -- collapse override is Split's own internal grid placement, same sanction as Grid's collapse rules
+    grid-column: 1 / -1;
+  }
+
+  .collapsible.collapseSm {
+    @include unstick-aside;
+  }
+}
+
+@container (max-width: #{bp.$collapse-md}) {
+  .collapsible.collapseMd > * {
+    // stylelint-disable-next-line property-disallowed-list -- collapse override is Split's own internal grid placement, same sanction as Grid's collapse rules
+    grid-column: 1 / -1;
+  }
+
+  .collapsible.collapseMd {
+    @include unstick-aside;
+  }
+}
+
+@container (max-width: #{bp.$collapse-lg}) {
+  .collapsible.collapseLg > * {
+    // stylelint-disable-next-line property-disallowed-list -- collapse override is Split's own internal grid placement, same sanction as Grid's collapse rules
+    grid-column: 1 / -1;
+  }
+
+  .collapsible.collapseLg {
+    @include unstick-aside;
+  }
+}

package/src/components/Split/Split.tokens.scss

@@ -0,0 +1,10 @@
+// Split.tokens.scss — Component-scoped tokens for <Split>. Gap mirrors the
+// shared space scale (same values as Stack/Cluster/Grid).
+:root {
+  --split-gap-xs: var(--space-1);
+  --split-gap-sm: var(--space-2);
+  --split-gap-md: var(--space-3);
+  --split-gap-lg: var(--space-4);
+  --split-gap-xl: var(--space-6);
+  --split-gap-2xl: var(--space-8);
+}

package/src/components/Split/Split.tsx

@@ -0,0 +1,231 @@
+import {
+  forwardRef,
+  useLayoutEffect,
+  useRef,
+  useState,
+  type CSSProperties,
+  type HTMLAttributes,
+  type ReactNode,
+} from 'react';
+import clsx from 'clsx';
+import styles from './Split.module.scss';
+import { COLLAPSE_BREAKPOINT_PX, type CollapseBreakpoint } from '../_internal/collapse';
+import { mergeRefs } from '../_internal/refs';
+
+/** Which side the `aside` pane sits on. RTL-aware (DOM + column order flip together). */
+export type SplitSide = 'start' | 'end';
+
+/** Gap between the two panes. Same scale as Stack/Cluster/Grid. */
+export type SplitGap = 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl';
+
+/** Cross-axis (vertical) alignment of the two panes. */
+export type SplitAlign = 'start' | 'stretch' | 'center';
+
+export interface SplitProps extends HTMLAttributes<HTMLDivElement> {
+  /**
+   * The narrow, intrinsic-width pane — a vertical `Tabs` rail, filter list, or nav column.
+   * `null` / `false` / `undefined` renders no aside cell at all (no empty track or gap),
+   * so content can be conditionally moved out of the aside; `main` then fills the split.
+   */
+  aside?: ReactNode;
+  /**
+   * Which side `aside` sits on.
+   * - `'start'` (default) — leading edge (left in LTR).
+   * - `'end'` — trailing edge (right in LTR).
+   */
+  side?: SplitSide;
+  /**
+   * `aside` column width.
+   * - `'auto'` (default) — intrinsic; sizes to the pane's content.
+   * - a CSS length (e.g. `'240px'`) — pins the column so `main` doesn't reflow
+   *   when `aside` content changes width.
+   */
+  asideWidth?: string;
+  /**
+   * Gap between the two panes, in pixels:
+   * `xs` (4) / `sm` (8) / `md` (12, default) / `lg` (16) / `xl` (24) / `2xl` (32).
+   * Same scale as Stack, Cluster, and Grid.
+   */
+  gap?: SplitGap;
+  /**
+   * Cross-axis (vertical) alignment of the panes.
+   * - `'start'` (default) — panes hug the top.
+   * - `'stretch'` — `aside` matches `main`'s height (full-height bordered rail).
+   * - `'center'` — panes vertically centered.
+   */
+  align?: SplitAlign;
+  /**
+   * Stack the two panes vertically when the SPLIT'S OWN width (container
+   * query, not viewport) drops below the preset: `sm` 480px / `md` 640px /
+   * `lg` 768px. Same scale as `Grid`'s `collapseBelow`. Without it a pinned
+   * `asideWidth` rail squeezes `main` to nothing on narrow screens.
+   *
+   * A pinned `asideWidth` is preserved while the panes are side-by-side and
+   * space is available, but can shrink as the container narrows so the stacked
+   * panes stay within the split.
+   *
+   * Collapsed panes stack in **DOM order**, not always aside-first: with
+   * the default `side="start"` that's aside → main; with `side="end"` it's
+   * main → aside, because that's the order the panes are in the DOM. Forcing
+   * aside-first when collapsed would need CSS `order`, which desynchronizes
+   * visual order from tab order — an a11y defect. If you need the aside on top
+   * when stacked, use `side="start"`.
+   *
+   * A `<Sticky>` passed as the `aside` stops pinning (and drops its `scroll`
+   * height cap) while stacked, so it can't trap the page scroll on a phone.
+   *
+   * ❌ Anti-pattern: a `collapseBelow` split must get its width from its
+   * parent. `container-type: inline-size` zeroes the split's contribution to
+   * intrinsic sizing, so in an intrinsic-width context (another `Split`'s
+   * default `auto` aside track, a `Cluster` item, `width: max-content`) it
+   * renders at width 0 — give the parent a concrete width instead. The split
+   * also becomes the containing block for absolutely-positioned descendants
+   * (layout containment). Splits without the prop pay none of this.
+   */
+  collapseBelow?: CollapseBreakpoint;
+  /**
+   * Called with `true` when a `collapseBelow` split stacks and `false` when it
+   * goes back side by side — on mount with the initial state (twice under
+   * React StrictMode in development), then on
+   * every change. Ignored without `collapseBelow`.
+   *
+   * Use it to move content you own between placements so DOM order matches
+   * visual order in both states, instead of CSS `order` — e.g. render a
+   * comment thread at the end of `main` while side by side and after the
+   * `<Split>` once stacked, or a status switcher at the top of the aside vs.
+   * above the split.
+   *
+   * It measures the SPLIT'S OWN content width against the same inclusive
+   * threshold its container query uses (a `ResizeObserver`, read
+   * synchronously on mount so the first paint is already right), so it agrees
+   * with the CSS where `useBelowBreakpoint` — which measures the viewport —
+   * would not beside an app sidebar. The same state is on the root as
+   * `data-collapsed="true" | "false"`.
+   */
+  onCollapsedChange?: (collapsed: boolean) => void;
+}
+
+/**
+ * Content-box inline size — what `container-type: inline-size` queries. Read
+ * from the computed (layout) width, not `getBoundingClientRect()`, which a
+ * CSS transform scales: a Split inside a Modal mid-`scale(0.96)` entrance
+ * measured ~4% narrow, and a ResizeObserver never re-fires for transforms.
+ */
+function contentWidth(el: HTMLElement): number {
+  const cs = getComputedStyle(el);
+  const px = (v: string) => parseFloat(v) || 0;
+  const width = px(cs.width);
+  if (cs.boxSizing !== 'border-box') return width;
+  return (
+    width -
+    px(cs.paddingLeft) -
+    px(cs.paddingRight) -
+    px(cs.borderLeftWidth) -
+    px(cs.borderRightWidth)
+  );
+}
+
+const gapClass: Record<SplitGap, string> = {
+  xs: styles.gapXs,
+  sm: styles.gapSm,
+  md: styles.gapMd,
+  lg: styles.gapLg,
+  xl: styles.gapXl,
+  '2xl': styles.gap2xl,
+};
+
+const collapseClass: Record<CollapseBreakpoint, string> = {
+  sm: styles.collapseSm,
+  md: styles.collapseMd,
+  lg: styles.collapseLg,
+};
+
+const alignClass: Record<SplitAlign, string> = {
+  start: styles.alignStart,
+  stretch: styles.alignStretch,
+  center: styles.alignCenter,
+};
+
+/**
+ * Master-detail layout: an intrinsic-width `aside` pane beside a filling main pane, via CSS grid.
+ * @see docs/components/Split.md
+ */
+export const Split = forwardRef<HTMLDivElement, SplitProps>(function Split(
+  {
+    aside,
+    children,
+    side = 'start',
+    asideWidth = 'auto',
+    gap = 'md',
+    align = 'start',
+    collapseBelow,
+    onCollapsedChange,
+    className,
+    style,
+    ...props
+  },
+  ref,
+) {
+  const rootRef = useRef<HTMLDivElement>(null);
+  const [collapsed, setCollapsed] = useState<boolean>();
+  const onChangeRef = useRef(onCollapsedChange);
+  onChangeRef.current = onCollapsedChange;
+
+  useLayoutEffect(() => {
+    const el = rootRef.current;
+    if (!collapseBelow || !el) {
+      setCollapsed(undefined);
+      return;
+    }
+    let last: boolean | undefined;
+    const measure = () => {
+      // Inclusive, like `@container (max-width: …)`.
+      const next = contentWidth(el) <= COLLAPSE_BREAKPOINT_PX[collapseBelow];
+      if (next === last) return;
+      last = next;
+      setCollapsed(next);
+      onChangeRef.current?.(next);
+    };
+    measure();
+    if (typeof ResizeObserver === 'undefined') return;
+    const observer = new ResizeObserver(measure);
+    observer.observe(el);
+    return () => observer.disconnect();
+  }, [collapseBelow]);
+
+  const hasAside = aside !== null && aside !== undefined && aside !== false;
+  const asideCell = hasAside ? <div className={styles.aside}>{aside}</div> : null;
+  const mainCell = <div className={styles.main}>{children}</div>;
+  return (
+    <div
+      ref={mergeRefs(ref, rootRef)}
+      data-collapsed={collapsed === undefined ? undefined : String(collapsed)}
+      className={clsx(
+        styles.split,
+        side === 'end' ? styles.sideEnd : styles.sideStart,
+        gapClass[gap],
+        alignClass[align],
+        !hasAside && styles.noAside,
+        collapseBelow && styles.collapsible,
+        collapseBelow && collapseClass[collapseBelow],
+        className,
+      )}
+      // asideWidth → custom property the SCSS grid template reads. Consumer
+      // `style` spread AFTER so they can still override anything.
+      style={{ '--split-aside-width': asideWidth, ...style } as CSSProperties}
+      {...props}
+    >
+      {side === 'end' ? (
+        <>
+          {mainCell}
+          {asideCell}
+        </>
+      ) : (
+        <>
+          {asideCell}
+          {mainCell}
+        </>
+      )}
+    </div>
+  );
+});

package/src/components/Split/index.ts

@@ -0,0 +1,2 @@
+export { Split } from './Split';
+export type { SplitProps, SplitSide, SplitGap, SplitAlign } from './Split';

package/src/components/Stack/Stack.module.scss

@@ -0,0 +1,67 @@
+@use './Stack.tokens';
+
+.stack {
+  display: flex;
+  flex-direction: column;
+}
+
+// Opt-in, via the `minWidth0` prop. As a flex or grid ITEM a Stack keeps the
+// default `min-width: auto`, which floors it at its content's min-content size —
+// so a `<Text truncate>` inside never gets the chance to ellipsize and a clipping
+// ancestor hard-cuts it instead (issue #475).
+// This only means anything while `.stack`'s overflow is non-scrollable: per CSS
+// Flexbox §4.5 a flex item keeps its automatic minimum size until its computed
+// overflow becomes scrollable. Giving `.stack` `overflow: hidden`/`auto`/`scroll`
+// would therefore remove the floor by itself and make this prop dead code — but
+// `overflow: clip` would NOT, because clip is non-scrollable and still floors.
+// Measured; do not assume any overflow value will do.
+// Deliberately NOT on the base `.stack` class: that would let every Stack in the
+// codebase shrink below its content, changing layout for existing consumers. It
+// was tried and reverted. The measurement that settled it was taken on Cluster
+// (see Cluster.module.scss) rather than here, but the mechanism is the same one
+// both share: a container permitted to shrink volunteers for shrink, and any
+// non-truncatable content inside it then overflows and is clipped by the
+// nearest `overflow: hidden` ancestor.
+.minWidth0 {
+  min-width: 0;
+}
+
+.gapXs {
+  gap: var(--stack-gap-xs);
+}
+
+.gapSm {
+  gap: var(--stack-gap-sm);
+}
+
+.gapMd {
+  gap: var(--stack-gap-md);
+}
+
+.gapLg {
+  gap: var(--stack-gap-lg);
+}
+
+.gapXl {
+  gap: var(--stack-gap-xl);
+}
+
+.gap2xl {
+  gap: var(--stack-gap-2xl);
+}
+
+.alignStart {
+  align-items: flex-start;
+}
+
+.alignCenter {
+  align-items: center;
+}
+
+.alignEnd {
+  align-items: flex-end;
+}
+
+.alignStretch {
+  align-items: stretch;
+}

package/src/components/Stack/Stack.tokens.scss

@@ -0,0 +1,11 @@
+// Stack.tokens.scss — Component-scoped tokens for <Stack>. Each token
+// defaults to the primitive the SCSS used before this migration.
+:root {
+  // Gap per size
+  --stack-gap-xs: var(--space-1);
+  --stack-gap-sm: var(--space-2);
+  --stack-gap-md: var(--space-3);
+  --stack-gap-lg: var(--space-4);
+  --stack-gap-xl: var(--space-6);
+  --stack-gap-2xl: var(--space-8);
+}

package/src/components/Stack/Stack.tsx

@@ -0,0 +1,100 @@
+import { forwardRef, type HTMLAttributes } from 'react';
+import clsx from 'clsx';
+import styles from './Stack.module.scss';
+
+/** Vertical gap between children. Values in pixels: 4 / 8 / 12 / 16 / 24 / 32. */
+export type StackGap = 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl';
+
+/** Cross-axis (horizontal) alignment of children inside the stack. */
+export type StackAlign = 'start' | 'center' | 'end' | 'stretch';
+
+export interface StackProps extends HTMLAttributes<HTMLDivElement> {
+  /**
+   * Gap between children, in pixels:
+   * `xs` (4) / `sm` (8) / `md` (12, default) / `lg` (16) / `xl` (24) / `2xl` (32).
+   */
+  gap?: StackGap;
+  /**
+   * Cross-axis alignment.
+   * - `stretch` (default) — children fill the stack's horizontal width.
+   * - `start` / `center` / `end` — left, center, right alignment.
+   */
+  align?: StackAlign;
+  /**
+   * Lets the container shrink below its content's intrinsic width
+   * (`min-width: 0`), so a `<Text truncate>` inside can ellipsize instead of
+   * being hard-cut by a clipping ancestor.
+   *
+   * Only bites when the Stack is itself an item of a **row** flex container (or
+   * a grid item) that clips — what decides is the PARENT's main axis, not the
+   * Stack's own direction. That is the two-line label beside a fixed badge, or
+   * a detail column in a squeezed toolbar. Without it the flex default
+   * (`min-width: auto`) floors the Stack at its widest line and the ellipsis
+   * never appears. That floor applies because a Stack sets no `overflow` — per CSS
+   * Flexbox §4.5 a flex item keeps its automatic minimum size while its computed
+   * `overflow` is non-scrollable (`visible` or `clip`); the scrollable values
+   * (`hidden`/`auto`/`scroll`) drop it to `0`.
+   *
+   * It is a **no-op** when the Stack sits in another `Stack` (the automatic
+   * minimum size applies only on the flex MAIN axis, so there is no horizontal
+   * floor), or in a plain block or table cell (that minimum applies to flex and
+   * grid ITEMS only, so `min-width: auto` is just `0` there). A table cell is
+   * a no-op for a different reason than it looks: auto table layout floors the
+   * cell at its content's min-content width regardless, so what makes text
+   * truncate there is `table-layout: fixed` or a `max-width` on the cell — not
+   * this prop.
+   *
+   * Opt-in rather than the default on purpose: a container that CAN shrink
+   * also VOLUNTEERS for shrink, so turning it on where the content is NOT
+   * truncatable (buttons, badges, icons) lets that content be clipped
+   * instead. Set it on the container whose text should give way, not on one
+   * holding controls.
+   *
+   * Related: `<Constrain flex="grow">` applies the same `min-width: 0` but
+   * also forces `flex: 1 1 0`, and renders a `<div>` — reach for this prop
+   * when you want only the shrink permission, or when you are inside a
+   * `<button>`/`<a>`/`<label>` where a `<div>` is invalid HTML.
+   *
+   * @default false
+   */
+  minWidth0?: boolean;
+}
+
+const gapClass: Record<StackGap, string> = {
+  xs: styles.gapXs,
+  sm: styles.gapSm,
+  md: styles.gapMd,
+  lg: styles.gapLg,
+  xl: styles.gapXl,
+  '2xl': styles.gap2xl,
+};
+
+const alignClass: Record<StackAlign, string> = {
+  start: styles.alignStart,
+  center: styles.alignCenter,
+  end: styles.alignEnd,
+  stretch: styles.alignStretch,
+};
+
+/**
+ * Vertical layout primitive that stacks children with consistent spacing.
+ * @see docs/components/Stack.md
+ */
+export const Stack = forwardRef<HTMLDivElement, StackProps>(function Stack(
+  { gap = 'md', align = 'stretch', minWidth0 = false, className, ...props },
+  ref,
+) {
+  return (
+    <div
+      ref={ref}
+      className={clsx(
+        styles.stack,
+        gapClass[gap],
+        alignClass[align],
+        minWidth0 && styles.minWidth0,
+        className,
+      )}
+      {...props}
+    />
+  );
+});

package/src/components/Stack/index.ts

@@ -0,0 +1,2 @@
+export { Stack } from './Stack';
+export type { StackProps, StackGap, StackAlign } from './Stack';