@eocrm/design-system 0.0.0-stage → 0.6.17

package/src/components/StagePath/StagePath.module.scss

@@ -0,0 +1,255 @@
+@use './StagePath.tokens';
+
+// Shapes. Each stage's box is clipped to a chevron; the next stage overlaps it
+// by the arrow depth (minus the gap) so the tip nests into the next notch.
+// RTL mirrors the polygons (x -> 100% - x); padding/radius already use logical
+// properties.
+// chevron($shape, $d) is the outer chevron offset inward by $d, in the frame of
+// a box itself inset $d on every side (the focus layers' ::before / ::after), so
+// a band is $d thick on the slants too, not just on the flat edges. $d = 0 is
+// the stage's own shape.
+// ponytail: 0.5 / 0.25 come from the slant's length factor k = √(1 + (a / (h/2))²)
+// = 1.25 for the 12px arrow on the 32px height (tip x 100% - 1.25d, tip-side
+// top x 100% - a - 0.5d, notch apex a + 1.25d, notch top 2d in the stage frame;
+// minus the d inset). Holds for any $d; recompute the factors if
+// --stage-path-arrow or --stage-path-height changes.
+$a: var(--stage-path-arrow);
+$r: var(--ring-width);
+
+@function chevron($shape, $d: 0px, $rtl: false) {
+  $tip-top: calc(100% - #{$a} + 0.5 * #{$d});
+  $tip: calc(100% - 0.25 * #{$d});
+  $notch-top: $d;
+  $notch: calc(#{$a} + 0.25 * #{$d});
+  $start: 0;
+  $end: 100%;
+
+  @if $rtl {
+    $tip-top: calc(#{$a} - 0.5 * #{$d});
+    $tip: calc(0.25 * #{$d});
+    $notch-top: calc(100% - #{$d});
+    $notch: calc(100% - #{$a} - 0.25 * #{$d});
+    $start: 100%;
+    $end: 0;
+  }
+
+  @if $shape == middle {
+    @return polygon($notch-top 0, $tip-top 0, $tip 50%, $tip-top 100%, $notch-top 100%, $notch 50%);
+  }
+
+  @if $shape == first {
+    @return polygon($start 0, $tip-top 0, $tip 50%, $tip-top 100%, $start 100%);
+  }
+
+  @return polygon($notch-top 0, $end 0, $end 100%, $notch-top 100%, $notch 50%);
+}
+
+// --sp-inner / --sp-inner-2: the shape offset by one and two ring widths.
+@mixin shape($shape, $rtl: false) {
+  --sp-shape: #{chevron($shape, 0px, $rtl)};
+  --sp-inner: #{chevron($shape, $r, $rtl)};
+  --sp-inner-2: #{chevron($shape, calc(2 * #{$r}), $rtl)};
+}
+
+.path {
+  // Per-tone palette, read by the stage states below.
+  --sp-done-bg: var(--stage-path-done-bg);
+  --sp-done-fg: var(--stage-path-done-fg);
+  --sp-current-bg: var(--stage-path-current-bg);
+  --sp-current-fg: var(--stage-path-current-fg);
+  --sp-ring: var(--stage-path-ring);
+
+  // lets the path shrink in a flex row (e.g. a non-wrapping Cluster) so labels truncate instead of overflowing
+  min-width: 0;
+  display: flex;
+  width: 100%;
+  list-style: none;
+  /* stylelint-disable-next-line property-disallowed-list -- native <ol> margin reset */
+  margin: 0;
+  padding: 0;
+  font-size: var(--stage-path-font-size);
+  font-weight: var(--stage-path-font-weight);
+}
+
+.path[data-tone='success'] {
+  --sp-done-bg: var(--stage-path-done-bg-success);
+  --sp-done-fg: var(--stage-path-done-fg-success);
+  --sp-current-bg: var(--stage-path-current-bg-success);
+  --sp-current-fg: var(--stage-path-current-fg-success);
+  --sp-ring: var(--stage-path-ring-success);
+}
+
+.path[data-tone='danger'] {
+  --sp-done-bg: var(--stage-path-done-bg-danger);
+  --sp-done-fg: var(--stage-path-done-fg-danger);
+  --sp-current-bg: var(--stage-path-current-bg-danger);
+  --sp-current-fg: var(--stage-path-current-fg-danger);
+  --sp-ring: var(--stage-path-ring-danger);
+}
+
+// Internal row distribution: equal shares, shrinkable so labels can ellipsize.
+.stage {
+  display: flex;
+  flex: 1 1 0;
+  min-width: 0;
+}
+
+.stage + .stage {
+  /* stylelint-disable-next-line property-disallowed-list -- internal interlock: each chevron overlaps its predecessor by the arrow depth so the tip nests into this stage's notch; not placement of the component */
+  margin-inline-start: calc(var(--stage-path-gap) - var(--stage-path-arrow));
+}
+
+.done {
+  --sp-fill: var(--sp-done-bg);
+  --sp-fg: var(--sp-done-fg);
+}
+
+.current {
+  --sp-fill: var(--sp-current-bg);
+  --sp-fg: var(--sp-current-fg);
+
+  font-weight: var(--stage-path-current-font-weight);
+}
+
+.upcoming {
+  --sp-fill: var(--stage-path-upcoming-bg);
+  --sp-fg: var(--stage-path-upcoming-fg);
+}
+
+// The painted chevron: a <button> (interactive) or <span> (read-only).
+.target {
+  @include shape(middle);
+
+  --sp-bg: var(--sp-fill);
+
+  position: relative;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  width: 100%;
+  min-width: 0;
+  height: var(--stage-path-height);
+  padding-inline: calc(var(--stage-path-arrow) + var(--stage-path-padding-x));
+  border: 0;
+  background: var(--sp-bg);
+  color: var(--sp-fg);
+  font: inherit;
+  white-space: nowrap;
+  clip-path: var(--sp-shape);
+}
+
+.stage:first-child .target {
+  @include shape(first);
+
+  padding-inline-start: var(--stage-path-padding-x);
+  border-start-start-radius: var(--stage-path-radius);
+  border-end-start-radius: var(--stage-path-radius);
+}
+
+.stage:last-child .target {
+  @include shape(last);
+
+  padding-inline-end: var(--stage-path-padding-x);
+  border-start-end-radius: var(--stage-path-radius);
+  border-end-end-radius: var(--stage-path-radius);
+}
+
+// A single stage is both first and last: a plain rounded box.
+.stage:only-child .target {
+  --sp-shape: none;
+  --sp-inner: none;
+  --sp-inner-2: none;
+}
+
+// Direction comes from the nearest `dir` attribute (or the path's own). Not
+// `:dir(rtl)`: production CSS minifiers lower it to a `:lang(ar, he, …)` list,
+// which never matches `dir="rtl"` on a page in a non-RTL language. An LTR island
+// inside an RTL page gets its own reset below.
+// ponytail: one LTR-island level only — RTL re-nested inside that island
+// (rtl > ltr > rtl) renders LTR shapes, and `dir="auto"` is ignored (the
+// nearest explicit `dir` wins). If a consumer needs either, read
+// `getComputedStyle(ol).direction` into a `data-dir` on the <ol> and key these
+// rules on it.
+$rtl: ':is([dir="rtl"] .path, .path[dir="rtl"])';
+$ltr-in-rtl: ':is([dir="rtl"] [dir="ltr"] .path, [dir="rtl"] .path[dir="ltr"])';
+
+#{$rtl} .target {
+  @include shape(middle, true);
+}
+
+#{$rtl} .stage:first-child .target {
+  @include shape(first, true);
+}
+
+#{$rtl} .stage:last-child .target {
+  @include shape(last, true);
+}
+
+#{$ltr-in-rtl} .target {
+  @include shape(middle);
+}
+
+#{$ltr-in-rtl} .stage:first-child .target {
+  @include shape(first);
+}
+
+#{$ltr-in-rtl} .stage:last-child .target {
+  @include shape(last);
+}
+
+:is(#{$rtl}, #{$ltr-in-rtl}) .stage:only-child .target {
+  --sp-shape: none;
+  --sp-inner: none;
+  --sp-inner-2: none;
+}
+
+.button {
+  cursor: pointer;
+}
+
+.button:hover {
+  --sp-bg: color-mix(in srgb, var(--sp-fill), var(--sp-fg) var(--stage-path-hover-mix));
+}
+
+// Chevron-shaped focus ring. clip-path would cut off any outline, so the ring
+// is the stage's own background in the ring colour, with the fill redrawn
+// ring-width inside it on ::before, clipped to the same shape.
+.button:focus-visible,
+.target:focus-visible {
+  background: var(--sp-ring);
+}
+
+.button:focus-visible::before,
+.target:focus-visible::before,
+.current .target:focus-visible::after {
+  position: absolute;
+  inset: var(--ring-width);
+  border-radius: inherit;
+  background: var(--sp-bg);
+  clip-path: var(--sp-inner);
+  content: '';
+}
+
+// The current stage's fill IS the ring colour in every tone, so a plain ring
+// would vanish. Instead: fill, then a ring-width band in its text colour (an
+// AA pair with the fill), then the fill again on ::after.
+.current .target:focus-visible {
+  background: var(--sp-bg);
+}
+
+.current .target:focus-visible::before {
+  background: var(--sp-fg);
+}
+
+.current .target:focus-visible::after {
+  inset: calc(2 * var(--ring-width));
+  clip-path: var(--sp-inner-2);
+}
+
+.label {
+  position: relative; // above the focus ::before / ::after
+  z-index: 1;
+  min-width: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}

package/src/components/StagePath/StagePath.tokens.scss

@@ -0,0 +1,43 @@
+// StagePath.tokens.scss — Component-scoped tokens for <StagePath>: the chevron
+// row of ordered record stages. Done/current fills follow `tone`; upcoming is
+// neutral in every tone.
+:root {
+  --stage-path-height: var(--size-md);
+
+  // Horizontal depth of each chevron's tip (and of the next stage's notch).
+  --stage-path-arrow: var(--space-3);
+
+  // Visible gap between interlocked chevrons.
+  --stage-path-gap: var(--space-05);
+  --stage-path-padding-x: var(--space-2);
+  --stage-path-radius: var(--radius-md);
+  --stage-path-font-size: var(--font-size-md);
+  --stage-path-font-weight: var(--font-weight-medium);
+  --stage-path-current-font-weight: var(--font-weight-semibold);
+
+  // How far a hovered stage's fill moves toward its text colour. 8% keeps every
+  // tone's text at or above AA on the hovered fill (tightest: light danger);
+  // pinned for every hoverable fill in both themes by contrast.test.ts.
+  --stage-path-hover-mix: 8%;
+
+  --stage-path-upcoming-bg: var(--color-tone-neutral-bg);
+  --stage-path-upcoming-fg: var(--color-tone-neutral-fg);
+
+  --stage-path-done-bg: var(--color-accent-subtle-bg);
+  --stage-path-done-fg: var(--color-fg);
+  --stage-path-current-bg: var(--color-accent);
+  --stage-path-current-fg: var(--color-accent-fg);
+  --stage-path-ring: var(--ring-accent);
+
+  --stage-path-done-bg-success: var(--color-tone-success-bg);
+  --stage-path-done-fg-success: var(--color-tone-success-fg);
+  --stage-path-current-bg-success: var(--color-success);
+  --stage-path-current-fg-success: var(--color-success-fg);
+  --stage-path-ring-success: var(--ring-success);
+
+  --stage-path-done-bg-danger: var(--color-tone-danger-bg);
+  --stage-path-done-fg-danger: var(--color-tone-danger-fg);
+  --stage-path-current-bg-danger: var(--color-danger);
+  --stage-path-current-fg-danger: var(--color-danger-fg);
+  --stage-path-ring-danger: var(--ring-danger);
+}

package/src/components/StagePath/StagePath.tsx

@@ -0,0 +1,176 @@
+import {
+  forwardRef,
+  useEffect,
+  useLayoutEffect,
+  useRef,
+  type HTMLAttributes,
+  type ReactNode,
+  type RefObject,
+} from 'react';
+import clsx from 'clsx';
+import { Tooltip } from '../Tooltip';
+import { VisuallyHidden } from '../VisuallyHidden';
+import { useClippedTooltip } from '../_internal/useClippedTooltip';
+import { useTranslation } from '../../i18n/useTranslation';
+import styles from './StagePath.module.scss';
+
+/**
+ * Outcome colour for the done + current stages. Upcoming stages stay neutral.
+ * - `'default'` — blue; the record is in progress.
+ * - `'success'` — green; the record reached a positive outcome (deal won).
+ * - `'danger'` — red; the record reached a negative outcome (deal lost).
+ */
+export type StagePathTone = 'default' | 'success' | 'danger';
+
+export interface StagePathStage {
+  /** Stable id: matched against `value` and passed to `onValueChange`. */
+  id: string;
+  /** Visible stage name. Ellipsizes when space runs out; the full label shows in a tooltip only when clipped. */
+  label: ReactNode;
+}
+
+export interface StagePathProps extends Omit<HTMLAttributes<HTMLOListElement>, 'children'> {
+  /** Ordered stages, first to last. */
+  stages: StagePathStage[];
+  /**
+   * Id of the current stage. Stages before it render as done, after it as
+   * upcoming. An id not in `stages` renders every stage as upcoming (and warns
+   * in development) rather than throwing.
+   */
+  value: string;
+  /** Outcome colour for done + current stages. See `StagePathTone`. @default 'default' */
+  tone?: StagePathTone;
+  /**
+   * Makes the path interactive: every non-current stage renders as a button
+   * that calls this with its id. The current stage is never a button.
+   * Omit for a read-only path. Whether a move is allowed (e.g. backwards) is
+   * the consumer's rule — confirm or ignore inside the handler.
+   */
+  onValueChange?: (id: string) => void;
+}
+
+type StageState = 'done' | 'current' | 'upcoming';
+
+interface StageProps {
+  stage: StagePathStage;
+  state: StageState;
+  onValueChange?: (id: string) => void;
+  /** Set on the current stage only: where focus lands when its button is replaced. */
+  currentRef?: RefObject<HTMLSpanElement | null>;
+}
+
+function Stage({ stage, state, onValueChange, currentRef }: StageProps) {
+  const t = useTranslation();
+  const tip = useClippedTooltip<HTMLSpanElement>(stage.label);
+  const content = (
+    <>
+      <span ref={tip.ref} className={styles.label}>
+        {stage.label}
+      </span>
+      {state !== 'current' && (
+        <VisuallyHidden>
+          , {t(state === 'done' ? 'stagePath.completed' : 'stagePath.upcoming')}
+        </VisuallyHidden>
+      )}
+    </>
+  );
+  const target =
+    onValueChange != null && state !== 'current' ? (
+      <button
+        type="button"
+        className={clsx(styles.target, styles.button)}
+        onClick={() => onValueChange(stage.id)}
+      >
+        {content}
+      </button>
+    ) : (
+      // Interactive current stage: focusable by script only (tabIndex -1, never a
+      // Tab stop) so a keyboard user's focus survives their button becoming this span.
+      <span
+        ref={currentRef}
+        className={styles.target}
+        tabIndex={onValueChange != null && state === 'current' ? -1 : undefined}
+        aria-current={state === 'current' ? 'step' : undefined}
+      >
+        {content}
+      </span>
+    );
+  return (
+    <li className={clsx(styles.stage, styles[state])} data-state={state}>
+      <Tooltip content={tip.content} open={tip.open} onOpenChange={tip.onOpenChange}>
+        {target}
+      </Tooltip>
+    </li>
+  );
+}
+
+/**
+ * Chevron row of a record's ordered stages — done, current, upcoming; optionally clickable.
+ * @see docs/components/StagePath.md
+ */
+export const StagePath = forwardRef<HTMLOListElement, StagePathProps>(function StagePath(
+  { stages, value, tone = 'default', onValueChange, className, onFocus, onBlur, ...rest },
+  ref,
+) {
+  const currentRef = useRef<HTMLSpanElement>(null);
+  // Was focus inside the list? Set on focusin; on focusout re-checked after the
+  // current commit, because removing a focused button may or may not fire blur.
+  const focusInside = useRef(false);
+  const currentIndex = stages.findIndex((s) => s.id === value);
+  const unknown = currentIndex === -1;
+
+  useEffect(() => {
+    if (process.env.NODE_ENV === 'production' || !unknown) return;
+    console.warn(
+      `<StagePath> value "${value}" is not the id of any stage; every stage renders as upcoming.`,
+    );
+  }, [unknown, value]);
+
+  // Activating a stage remounts it as the current <span>, dropping focus to <body>
+  // (WCAG 2.4.3). Put it back on the current stage — never steal it from elsewhere.
+  useLayoutEffect(() => {
+    const active = document.activeElement;
+    if (focusInside.current && (active == null || active === document.body || !active.isConnected))
+      currentRef.current?.focus();
+  }, [value]);
+
+  return (
+    <ol
+      ref={ref}
+      className={clsx(styles.path, className)}
+      // {...rest} before data-tone: the tone attribute is the component's styling contract.
+      {...rest}
+      data-tone={tone}
+      onFocus={(e) => {
+        focusInside.current = true;
+        onFocus?.(e);
+      }}
+      onBlur={(e) => {
+        const list = e.currentTarget;
+        queueMicrotask(() => {
+          focusInside.current = list.contains(document.activeElement);
+        });
+        onBlur?.(e);
+      }}
+    >
+      {stages.map((stage, i) => {
+        const state: StageState = unknown
+          ? 'upcoming'
+          : i < currentIndex
+            ? 'done'
+            : i === currentIndex
+              ? 'current'
+              : 'upcoming';
+        return (
+          <Stage
+            key={stage.id}
+            stage={stage}
+            state={state}
+            onValueChange={onValueChange}
+            currentRef={state === 'current' ? currentRef : undefined}
+          />
+        );
+      })}
+    </ol>
+  );
+});

package/src/components/StagePath/index.ts

@@ -0,0 +1,2 @@
+export { StagePath } from './StagePath';
+export type { StagePathProps, StagePathStage, StagePathTone } from './StagePath';

package/src/components/StatGroup/StatGroup.module.scss

@@ -0,0 +1,6 @@
+.root {
+  list-style: none;
+  // stylelint-disable-next-line property-disallowed-list -- native <ul> margin reset
+  margin: 0;
+  padding: 0;
+}

package/src/components/StatGroup/StatGroup.tsx

@@ -0,0 +1,70 @@
+import { forwardRef, useMemo, type HTMLAttributes, type ReactNode, type Ref } from 'react';
+import clsx from 'clsx';
+import { Grid, type GridGap } from '../Grid';
+import { StatGroupContext, type StatGroupVariant } from './StatGroupContext';
+import styles from './StatGroup.module.scss';
+
+export type { StatGroupVariant };
+
+export interface StatGroupProps extends HTMLAttributes<HTMLUListElement> {
+  /**
+   * Minimum tile width before the grid drops a column (auto-fit). Any CSS length.
+   * Clamped to the group's width, so in a cell narrower than one column a single
+   * tile shrinks instead of overflowing. Default `'11rem'`.
+   */
+  minColumnWidth?: string;
+  /** Gap between tiles. `xs` (4) / `sm` (8) / `md` (12, default) / `lg` (16) / `xl` (24) / `2xl` (32). */
+  gap?: GridGap;
+  /**
+   * Loading state for every tile: labels and icons stay; each value and trend becomes a
+   * skeleton with visually hidden "Loading…" in the value slot, and footnotes hide.
+   * Deliberately NO live region: a dashboard loads many widgets at once, so announcements
+   * would flood screen readers. No `aria-busy`: the per-tile hidden text already carries the state.
+   * Default `false`.
+   */
+  loading?: boolean;
+  /**
+   * Surface of every tile, so a group stays consistent. Default `'filled'`.
+   * - `'filled'` — muted fill, no border. Use inside a `Card` / `DashboardWidget`.
+   * - `'card'` — card background, border and shadow, matching `Card`s on a page background; avoid inside a Card (card-in-card).
+   */
+  variant?: StatGroupVariant;
+  /** `StatTile` elements. */
+  children?: ReactNode;
+}
+
+/**
+ * Responsive grid of KPI tiles (`StatTile`) with a shared loading state.
+ * @see docs/components/StatGroup.md
+ */
+// {...rest} last (Pattern A) so the consumer's aria-label / data-* / className reach the <ul>.
+export const StatGroup = forwardRef<HTMLUListElement, StatGroupProps>(function StatGroup(
+  {
+    minColumnWidth = '11rem',
+    gap = 'md',
+    loading = false,
+    variant = 'filled',
+    className,
+    children,
+    ...rest
+  },
+  ref,
+) {
+  const ctx = useMemo(() => ({ loading, variant }), [loading, variant]);
+  return (
+    <StatGroupContext.Provider value={ctx}>
+      <Grid
+        ref={ref as Ref<HTMLElement>}
+        as="ul"
+        // role="list": Safari drops list semantics from list-style:none lists.
+        role="list"
+        minColumnWidth={`min(${minColumnWidth}, 100%)`}
+        gap={gap}
+        className={clsx(styles.root, className)}
+        {...rest}
+      >
+        {children}
+      </Grid>
+    </StatGroupContext.Provider>
+  );
+});

package/src/components/StatGroup/StatGroupContext.ts

@@ -0,0 +1,10 @@
+import { createContext } from 'react';
+
+/** StatGroup surface for every tile. See `StatGroupProps.variant`. */
+export type StatGroupVariant = 'filled' | 'card';
+
+/** Internal: StatGroup's `loading` + `variant`, read by each StatTile. */
+export const StatGroupContext = createContext<{ loading: boolean; variant: StatGroupVariant }>({
+  loading: false,
+  variant: 'filled',
+});

package/src/components/StatGroup/StatTile.module.scss

@@ -0,0 +1,99 @@
+@use './StatTile.tokens';
+
+.root {
+  // Size container for the narrow rule below. Safe: the Grid track sizes the tile, not its content.
+  container-type: inline-size;
+  display: flex;
+  flex-direction: column;
+  gap: var(--stat-tile-gap);
+  min-width: 0;
+  padding: var(--stat-tile-padding);
+  border-radius: var(--stat-tile-radius);
+  background: var(--stat-tile-bg);
+
+  // Skeleton defaults to bg-muted, the tile's own fill; one step darker keeps the loading bars visible.
+  --skeleton-bg: var(--stat-tile-skeleton-bg);
+}
+
+.label {
+  display: flex;
+  align-items: center;
+  gap: var(--stat-tile-label-gap);
+  min-width: 0;
+  color: var(--stat-tile-label-fg);
+  font-size: var(--stat-tile-label-size);
+}
+
+.icon {
+  display: inline-flex;
+  flex-shrink: 0;
+}
+
+.value {
+  color: var(--stat-tile-value-fg);
+  font-size: var(--stat-tile-value-size);
+  font-weight: var(--stat-tile-value-weight);
+  line-height: var(--stat-tile-value-line-height);
+  font-variant-numeric: tabular-nums;
+  overflow-wrap: anywhere;
+}
+
+.trend {
+  display: flex;
+  align-items: center;
+  gap: var(--stat-tile-trend-gap);
+  font-size: var(--stat-tile-trend-size);
+}
+
+.trend[data-sentiment='positive'] {
+  color: var(--stat-tile-trend-positive);
+}
+
+.trend[data-sentiment='negative'] {
+  color: var(--stat-tile-trend-negative);
+}
+
+.trend[data-sentiment='neutral'] {
+  color: var(--stat-tile-trend-neutral);
+}
+
+.card {
+  border: var(--border-width) solid var(--stat-tile-card-border-color);
+  border-radius: var(--stat-tile-card-radius);
+  background: var(--stat-tile-card-bg);
+  box-shadow: var(--stat-tile-card-shadow);
+
+  --skeleton-bg: var(--stat-tile-card-skeleton-bg);
+}
+
+.sparkline {
+  min-width: 0;
+}
+
+// The bar is a pill; its placeholder should be one too.
+.progressSkeleton {
+  --skeleton-radius-rectangular: var(--radius-full);
+}
+
+.footnote {
+  color: var(--stat-tile-footnote-fg);
+  font-size: var(--stat-tile-footnote-size);
+}
+
+// SCSS constant because container-query conditions can't read custom properties.
+// Container queries measure the content box: 136px content = 160px tile width
+// minus 2 x --stat-tile-padding (12px); variant="card" adds a 1px border each side,
+// so there it fires at a 162px tile.
+// ponytail: fixed threshold; make it a prop if a widget needs another.
+$narrow-below: 136px;
+
+@container (max-width: #{$narrow-below}) {
+  .value {
+    font-size: var(--stat-tile-value-size-narrow);
+  }
+
+  // Decorative (the consumer's IconTile is aria-hidden by default), so display:none loses nothing.
+  .icon {
+    display: none;
+  }
+}