@eocrm/design-system 0.6.23 → 0.6.24

package/src/components/FunnelChart/FunnelChart.tsx

@@ -0,0 +1,607 @@
+import {
+  forwardRef,
+  useEffect,
+  useId,
+  useLayoutEffect,
+  useMemo,
+  useRef,
+  useState,
+  type FocusEvent,
+  type CSSProperties,
+  type HTMLAttributes,
+  type KeyboardEvent,
+  type MouseEvent,
+  type PointerEvent,
+  type ReactNode,
+} from 'react';
+import clsx from 'clsx';
+import { EmptyState } from '../EmptyState';
+import { LiveRegion } from '../LiveRegion';
+import { VisuallyHidden } from '../VisuallyHidden';
+import { ChartTooltip } from '../Chart/ChartTooltip';
+import { useTranslation } from '../../i18n/useTranslation';
+import { useLocale } from '../../i18n/useLocale';
+import { mergeRefs } from '../_internal/refs';
+import { useSize } from '../_internal/useSize';
+import {
+  formatPercent,
+  MIN_THICKNESS,
+  orientationFor,
+  resolveStages,
+  stageGeometry,
+  stageIndexAt,
+  TAPER_HOLD,
+  type FunnelShape,
+  type FunnelStage,
+  type ResolvedStage,
+} from './funnelModel';
+import styles from './FunnelChart.module.scss';
+
+export type { FunnelShape, FunnelSlot, FunnelStage } from './funnelModel';
+
+export interface FunnelChartProps extends Omit<HTMLAttributes<HTMLElement>, 'children'> {
+  /** Accessible name of the figure and caption of its data table, e.g. "Sales pipeline". Required. */
+  label: string;
+  /**
+   * Stages, top of the funnel first. Heights are relative to the largest value. Colour is a one-hue ramp
+   * from `--chart-series-1` (first stage) toward the surface (paler toward the foreground in dark); a stage's `color` slot overrides it.
+   */
+  stages: FunnelStage[];
+  /** Formats a stage value for the footer, tooltip and data table (the app owns i18n and currency). Required. */
+  formatValue: (n: number) => string;
+  /**
+   * Silhouette between stages, in both layouts (vertical slices follow the same geometry turned on
+   * its side). Default `'taper'`.
+   * - `'taper'` — each stage holds its height for most of its column, then a short straight diagonal
+   *   leads into the next one's height.
+   * - `'sharp'` — full-column trapezoids from one stage's height to the next.
+   */
+  shape?: FunnelShape;
+  /**
+   * Makes every stage a button that calls this with the consumer's original stage object and its index,
+   * e.g. to drill through to the deals in that stage. Omit for a read-only funnel.
+   */
+  onStageClick?: (stage: FunnelStage, index: number) => void;
+  /**
+   * Called with the hovered or focused stage (the consumer's original object), or `null` when none is
+   * active, e.g. so a surrounding headline can follow along.
+   */
+  onActiveStageChange?: (stage: FunnelStage | null) => void;
+  /** EmptyState title when there are no stages or every value is 0. Default: translated "No data for this period". */
+  emptyMessage?: ReactNode;
+  /**
+   * Short note under the funnel, e.g. "Closed deals only". Takes its own row (wraps, never truncates);
+   * also describes the plot for screen readers. Shown in the empty state too.
+   */
+  footnote?: ReactNode;
+}
+
+/** Pill box height and text-width estimate (SVG text can't be measured before paint). */
+const PILL_HEIGHT = 20;
+const PILL_PADDING_X = 8;
+// ponytail: per-character width estimate for the pill; measure with getBBox if wide glyphs overflow it.
+const PILL_CHAR_WIDTH = 7;
+
+/** Hero (first stage's value and label inside its band): px estimates, as for the pill. */
+const HERO_PADDING = 8;
+// ponytail: sizes mirror --funnel-chart-hero-*-size (24px / 20px bold) at line-height 1.2; measure with getBBox if those tokens change.
+const HERO_MIN_HEIGHT = 72;
+const HERO_VALUE_CHAR_WIDTH = 15;
+const HERO_LABEL_CHAR_WIDTH = 12;
+
+/** Stage colour: the `color` slot, else step `i` of `n` on the one-hue ramp (computed by CSS). */
+const stageColor = (s: ResolvedStage, i: number, n: number) =>
+  s.slot !== null
+    ? `var(--chart-series-${s.slot})`
+    : `color-mix(in oklab, var(--funnel-chart-ramp-color), var(--funnel-chart-ramp-target) calc(var(--funnel-chart-ramp-max-mix) * ${n > 1 ? Math.round((i / (n - 1)) * 1000) / 1000 : 0}))`;
+const colorStyle = (color: string) => ({ '--chart-series-color': color }) as CSSProperties;
+
+/**
+ * Stage funnel (pipeline, campaign) showing drop-off by height and step conversion by pill.
+ * @see docs/components/FunnelChart.md
+ */
+// {...rest} FIRST (Pattern B) so the figure's role and accessible name (incl. aria-labelledby) always win.
+export const FunnelChart = forwardRef<HTMLElement, FunnelChartProps>(function FunnelChart(
+  {
+    label,
+    stages,
+    formatValue,
+    shape = 'taper',
+    onStageClick,
+    onActiveStageChange,
+    emptyMessage,
+    footnote,
+    className,
+    ...rest
+  },
+  ref,
+) {
+  const t = useTranslation();
+  const locale = useLocale();
+  const resolved = useMemo(() => resolveStages(stages), [stages]);
+  const empty = resolved.every((s) => s.value === 0);
+
+  const hintId = useId();
+  const footnoteId = useId();
+  const hasFootnote = footnote != null && footnote !== false && footnote !== '';
+  const footnoteEl = hasFootnote && (
+    <div id={footnoteId} className={styles.footnote}>
+      {footnote}
+    </div>
+  );
+
+  const [plotEl, setPlotEl] = useState<HTMLDivElement | null>(null);
+  const [setShapesEl, size, shapesEl] = useSize<HTMLDivElement>();
+  const [setRootEl, rootSize] = useSize<HTMLElement>();
+  const figureRef = useMemo(
+    () => mergeRefs(ref, (el: HTMLElement | null) => setRootEl(el)),
+    [ref, setRootEl],
+  );
+  const n = resolved.length;
+  // Unmeasured (first paint, SSR): assume horizontal rather than flash the narrow layout.
+  const orientation = rootSize.width > 0 ? orientationFor(rootSize.width, n) : 'horizontal';
+  const vertical = orientation === 'vertical';
+
+  const geometry = useMemo(
+    () =>
+      !empty && !vertical && size.width > 0 && size.height > 0
+        ? stageGeometry({ stages: resolved, width: size.width, height: size.height, shape })
+        : null,
+    [empty, vertical, resolved, size.width, size.height, shape],
+  );
+  // Hero: the first stage's value and label inside its band, centred in its column, when the band is
+  // tall enough at the text's right edge (the band narrows there) and the text fits the column. Not
+  // over a `color` slot: the hero colour is only checked against the ramp's first stage.
+  const heroValue = n > 0 ? formatValue(resolved[0].value) : '';
+  const hero = (() => {
+    if (!geometry || resolved[0].slot !== null) return null;
+    const g = geometry[0];
+    const colW = g.x1 - g.x0;
+    const thick = (s: ResolvedStage) => Math.max(MIN_THICKNESS, s.heightRatio * size.height);
+    const a = thick(resolved[0]);
+    const b = n > 1 ? thick(resolved[1]) : a;
+    const hold = shape === 'taper' ? colW * TAPER_HOLD : 0;
+    const textW = Math.max(
+      heroValue.length * HERO_VALUE_CHAR_WIDTH,
+      resolved[0].label.length * HERO_LABEL_CHAR_WIDTH,
+    );
+    const edge = colW / 2 + textW / 2 + HERO_PADDING;
+    const f = Math.min(1, Math.max(0, (edge - hold) / (colW - hold || 1)));
+    const fits = textW + 2 * HERO_PADDING <= colW && a + (b - a) * f >= HERO_MIN_HEIGHT;
+    return fits ? { x: g.cx, y: g.cy } : null;
+  })();
+
+  // Vertical: the same outline in a 100-unit box per stage (flow x ∈ [100i, 100i+100], cross y ∈
+  // [0, 100]); each row's SVG views its slice with the axes swapped and stretches it to the row.
+  // MIN_THICKNESS (px in the horizontal strip) becomes 6% of the band track here.
+  const bands = useMemo(
+    () =>
+      !empty && vertical
+        ? stageGeometry({ stages: resolved, width: 100 * n, height: 100, shape })
+        : null,
+    [empty, vertical, resolved, n, shape],
+  );
+
+  const [active, setActive] = useState<number | null>(null);
+  // 'focus' = a stage button has focus; its accessible name already says what the live region would.
+  const [activeSource, setActiveSource] = useState<'pointer' | 'keyboard' | 'focus' | null>(null);
+  // Stages shrank past the active index: drop it (during render, React's "adjust state on prop
+  // change" pattern), or regrowing would revive it with no user action.
+  if (active !== null && active >= n) {
+    setActive(null);
+    setActiveSource(null);
+  }
+  const current = active !== null && active < n ? active : null;
+  const clickable = onStageClick !== undefined;
+
+  // Fire once per change of the active stage's key (not on mount, not for a new-but-equal stages array).
+  const activeKey = current === null ? null : resolved[current].key;
+  const lastKey = useRef<string | null>(null);
+  useEffect(() => {
+    if (activeKey === lastKey.current) return;
+    lastKey.current = activeKey;
+    onActiveStageChange?.(current === null ? null : stages[current]);
+  });
+
+  const inspect = (index: number | null, source: 'pointer' | 'keyboard' | 'focus' | null) => {
+    setActive(index);
+    setActiveSource(index === null ? null : source);
+  };
+
+  const onKeyDown = (e: KeyboardEvent<HTMLDivElement>) => {
+    // Clickable: buttons are the tab stops and own their keys; only Escape (dismiss tooltip) applies.
+    if (clickable && e.key !== 'Escape') return;
+    let next: number | null;
+    switch (e.key) {
+      case 'ArrowDown':
+      case 'ArrowUp':
+        // Horizontal: leave Up/Down to page scrolling.
+        if (!vertical) return;
+        next =
+          e.key === 'ArrowDown'
+            ? current === null
+              ? 0
+              : Math.min(n - 1, current + 1)
+            : current === null
+              ? n - 1
+              : Math.max(0, current - 1);
+        break;
+      case 'ArrowRight':
+        next = current === null ? 0 : Math.min(n - 1, current + 1);
+        break;
+      case 'ArrowLeft':
+        next = current === null ? n - 1 : Math.max(0, current - 1);
+        break;
+      case 'Home':
+        next = 0;
+        break;
+      case 'End':
+        next = n - 1;
+        break;
+      case 'Escape':
+        if (current === null) return; // let a surrounding dialog close
+        next = null;
+        break;
+      default:
+        return;
+    }
+    e.preventDefault();
+    inspect(next, 'keyboard');
+  };
+
+  // A tap leaves the tooltip open (touch fires pointerleave right after pointerup, which we
+  // ignore); dismiss it on the next press outside the plot, as Chart does.
+  const pointerActive = activeSource === 'pointer' && current !== null;
+  useEffect(() => {
+    if (!pointerActive || !plotEl) return;
+    const dismiss = (e: Event) => {
+      // composedPath, not target: inside a shadow root the target is retargeted to the host.
+      if (e.composedPath().includes(plotEl)) return;
+      setActive(null);
+      setActiveSource(null);
+    };
+    document.addEventListener('pointerdown', dismiss, true);
+    return () => document.removeEventListener('pointerdown', dismiss, true);
+  }, [pointerActive, plotEl]);
+
+  const onPointer = (e: PointerEvent<HTMLDivElement>) => {
+    if (!geometry || !shapesEl) return;
+    const rect = shapesEl.getBoundingClientRect();
+    inspect(stageIndexAt(size.width, n, e.clientX - rect.left), 'pointer');
+  };
+
+  const onStripClick = (e: MouseEvent<HTMLDivElement>) => {
+    if (!onStageClick || !shapesEl) return;
+    const rect = shapesEl.getBoundingClientRect();
+    const i = stageIndexAt(size.width, n, e.clientX - rect.left);
+    if (i !== null) onStageClick(stages[i], i);
+  };
+
+  // Moving focus between stage buttons must not clear (and re-fire onActiveStageChange) in between.
+  const onBlur = (e: FocusEvent<HTMLDivElement>) => {
+    if (!(e.relatedTarget instanceof Node && plotEl?.contains(e.relatedTarget)))
+      inspect(null, null);
+  };
+
+  const pct = (ratio: number | null) =>
+    ratio === null ? t('funnelChart.noData') : formatPercent(ratio, locale);
+  const ofStage = (ratio: number | null, i: number) =>
+    t('funnelChart.ofStage', { percent: pct(ratio), stage: resolved[i].label });
+  const notesFor = (i: number) =>
+    i === 0
+      ? [ofStage(resolved[0].shareRatio, 0)]
+      : [ofStage(resolved[i].stepRatio, i - 1), ofStage(resolved[i].shareRatio, 0)];
+  // Button name: like the notes, but undefined ratios are left out rather than read as "—".
+  const buttonName = (i: number) => {
+    const s = resolved[i];
+    const parts = [`${s.label}: ${formatValue(s.value)}`];
+    if (i > 0 && s.stepRatio !== null) parts.push(ofStage(s.stepRatio, i - 1));
+    if (s.shareRatio !== null) parts.push(ofStage(s.shareRatio, 0));
+    return `${parts.join('. ')}.`;
+  };
+
+  // One cell per stage (horizontal: footer column; vertical: a table-like row with its funnel slice); a
+  // button when clickable. Spans, not divs, since the cell may be a <button>. With the hero shown, the
+  // first footer cell keeps its content invisibly (CSS) for alignment, hover and a normal-size focus
+  // ring. Read-only cells are aria-hidden: the hidden data table is the screen reader's copy.
+  const renderCell = (s: ResolvedStage, i: number) => {
+    const content = vertical ? (
+      <>
+        <span className={styles.bandTrack} data-band="">
+          {bands && (
+            <svg
+              className={styles.svg}
+              viewBox={`0 ${100 * i} 100 100`}
+              preserveAspectRatio="none"
+              aria-hidden="true"
+              focusable="false"
+            >
+              {/* Swap x/y so the funnel flows top to bottom. */}
+              <path className={styles.shape} d={bands[i].d} transform="matrix(0 1 1 0 0 0)" />
+            </svg>
+          )}
+        </span>
+        <span className={styles.swatch} data-swatch="" />
+        <span className={styles.label}>{s.label}</span>
+        <span className={styles.value}>{formatValue(s.value)}</span>
+        <span className={styles.step}>
+          {i > 0 && s.stepRatio !== null ? (
+            <span className={styles.rowPill}>{pct(s.stepRatio)}</span>
+          ) : (
+            t('funnelChart.noData')
+          )}
+        </span>
+      </>
+    ) : (
+      <>
+        <span className={styles.value}>{formatValue(s.value)}</span>
+        <span className={styles.label}>{s.label}</span>
+      </>
+    );
+    const common = {
+      className: styles.cell,
+      style: colorStyle(stageColor(s, i, n)),
+      'data-stage-cell': s.key,
+      'data-dimmed': dimmed(i),
+      'data-hero-cell': i === 0 && hero ? '' : undefined,
+      // Vertical rows are hit-tested per row; horizontal uses the plot's x position (stageIndexAt).
+      onPointerEnter: vertical ? () => inspect(i, 'pointer') : undefined,
+    };
+    return onStageClick ? (
+      <button
+        key={s.key}
+        {...common}
+        type="button"
+        aria-label={buttonName(i)}
+        onFocus={() => inspect(i, 'focus')}
+        onClick={() => onStageClick(stages[i], i)}
+      >
+        {content}
+      </button>
+    ) : (
+      <div key={s.key} {...common} aria-hidden="true">
+        {content}
+      </div>
+    );
+  };
+
+  const stage = current === null ? null : resolved[current];
+  const notes = current === null ? [] : notesFor(current);
+  const rows = stage
+    ? [
+        {
+          key: 'value',
+          label: t('funnelChart.value'),
+          slot: 0,
+          color: stageColor(stage, current!, n),
+          comparison: false,
+          value: formatValue(stage.value),
+        },
+      ]
+    : [];
+
+  // The shapes strip sits at the plot's top-left, so geometry is plot-local; scalars keep `point` stable.
+  const anchorX = current !== null && geometry ? geometry[current].cx : undefined;
+  const anchorY =
+    stage && geometry
+      ? geometry[current!].cy - Math.max(MIN_THICKNESS / 2, (stage.heightRatio * size.height) / 2)
+      : undefined;
+  const horizontalPoint = useMemo(
+    () => (anchorX === undefined || anchorY === undefined ? null : { x: anchorX, y: anchorY }),
+    [anchorX, anchorY],
+  );
+
+  // Vertical: rows scroll inside the plot, so read the active band's position from the DOM
+  // (bounding rects already include the scroll offset), again on plot scroll and on resize.
+  // Keyboard inspection scrolls the row in first.
+  const [verticalPoint, setVerticalPoint] = useState<{ x: number; y: number } | null>(null);
+  useLayoutEffect(() => {
+    const row =
+      vertical && activeKey !== null && plotEl
+        ? plotEl.querySelector<HTMLElement>(`[data-stage-cell="${CSS.escape(activeKey)}"]`)
+        : null;
+    const band = row?.querySelector<HTMLElement>('[data-band]');
+    if (!row || !band || !plotEl) {
+      setVerticalPoint(null);
+      return;
+    }
+    const measure = () => {
+      const p = plotEl.getBoundingClientRect();
+      const b = band.getBoundingClientRect();
+      const x = b.left - p.left + b.width / 2;
+      const y = b.top - p.top;
+      setVerticalPoint((prev) => (prev && prev.x === x && prev.y === y ? prev : { x, y }));
+    };
+    if (activeSource === 'keyboard') row.scrollIntoView?.({ block: 'nearest' });
+    measure();
+    plotEl.addEventListener('scroll', measure, { passive: true });
+    return () => plotEl.removeEventListener('scroll', measure);
+  }, [vertical, activeKey, activeSource, plotEl, rootSize.width, rootSize.height]);
+  const point = vertical ? verticalPoint : horizontalPoint;
+
+  const liveText =
+    activeSource === 'keyboard' && stage
+      ? `${stage.label}: ${formatValue(stage.value)}. ${notes.join('. ')}.`
+      : '';
+  const dimmed = (i: number) => (current !== null && i !== current ? '' : undefined);
+
+  if (empty) {
+    return (
+      <figure
+        {...rest}
+        ref={ref}
+        role="figure"
+        aria-label={label}
+        aria-labelledby={undefined}
+        data-empty=""
+        data-footnote={hasFootnote || undefined}
+        className={clsx(styles.root, className)}
+      >
+        <EmptyState title={emptyMessage || t('chart.empty')} size="sm" />
+        {footnoteEl}
+      </figure>
+    );
+  }
+
+  return (
+    <figure
+      {...rest}
+      ref={figureRef}
+      role="figure"
+      aria-label={label}
+      aria-labelledby={undefined}
+      data-orientation={orientation}
+      data-shape={shape}
+      data-footnote={hasFootnote || undefined}
+      className={clsx(styles.root, className)}
+    >
+      {!clickable && <VisuallyHidden id={hintId}>{t('funnelChart.keyboardHint')}</VisuallyHidden>}
+      {/* Clickable: the stage buttons are the tab stops, so the plot isn't one and needs no hint. */}
+      <div
+        ref={setPlotEl}
+        className={styles.plot}
+        role="group"
+        aria-label={label}
+        aria-describedby={
+          [!clickable && hintId, hasFootnote && footnoteId].filter(Boolean).join(' ') || undefined
+        }
+        tabIndex={clickable ? undefined : 0}
+        data-clickable={clickable || undefined}
+        onKeyDown={onKeyDown}
+        onPointerMove={onPointer}
+        onPointerDown={onPointer}
+        // Touch fires pointerleave right after pointerup; keep the tapped tooltip (an outside press clears it).
+        onPointerLeave={(e) =>
+          e.pointerType !== 'touch' && activeSource === 'pointer' && inspect(null, null)
+        }
+        onBlur={onBlur}
+      >
+        {vertical ? (
+          <>
+            {/* Entering the header leaves the rows: clear a hovered stage, as leaving the plot does. */}
+            <div
+              className={styles.header}
+              aria-hidden="true"
+              data-funnel-header=""
+              onPointerEnter={() => activeSource === 'pointer' && inspect(null, null)}
+            >
+              <span />
+              <span />
+              <span>{t('funnelChart.stage')}</span>
+              <span className={styles.headerValue}>{t('funnelChart.value')}</span>
+              <span>{t('funnelChart.vsPrevious')}</span>
+            </div>
+            {resolved.map(renderCell)}
+          </>
+        ) : (
+          <>
+            <div ref={setShapesEl} className={styles.shapes} onClick={onStripClick}>
+              {geometry && (
+                <svg
+                  className={styles.svg}
+                  width={size.width}
+                  height={size.height}
+                  aria-hidden="true"
+                  focusable="false"
+                >
+                  {resolved.map((s, i) => {
+                    const g = geometry[i];
+                    const pill = i > 0 && s.stepRatio !== null ? pct(s.stepRatio) : null;
+                    const pillWidth = pill ? pill.length * PILL_CHAR_WIDTH + PILL_PADDING_X * 2 : 0;
+                    return (
+                      <g
+                        key={s.key}
+                        className={styles.stage}
+                        style={colorStyle(stageColor(s, i, n))}
+                        data-stage={s.key}
+                        data-dimmed={dimmed(i)}
+                      >
+                        <path className={styles.shape} d={g.d} />
+                        {i === 0 && hero && (
+                          <g data-hero="">
+                            <text
+                              className={styles.heroValue}
+                              x={hero.x}
+                              y={hero.y}
+                              dy="-0.15em"
+                              textAnchor="middle"
+                            >
+                              {heroValue}
+                            </text>
+                            <text
+                              className={styles.heroLabel}
+                              x={hero.x}
+                              y={hero.y}
+                              dy="1.1em"
+                              textAnchor="middle"
+                            >
+                              {s.label}
+                            </text>
+                          </g>
+                        )}
+                        {pill && (
+                          <>
+                            <rect
+                              className={styles.pill}
+                              x={g.cx - pillWidth / 2}
+                              y={g.cy - PILL_HEIGHT / 2}
+                              width={pillWidth}
+                              height={PILL_HEIGHT}
+                              rx={PILL_HEIGHT / 2}
+                            />
+                            <text
+                              className={styles.pillText}
+                              x={g.cx}
+                              y={g.cy}
+                              dy="0.35em"
+                              textAnchor="middle"
+                            >
+                              {pill}
+                            </text>
+                          </>
+                        )}
+                      </g>
+                    );
+                  })}
+                </svg>
+              )}
+            </div>
+            <div className={styles.footer}>{resolved.map(renderCell)}</div>
+          </>
+        )}
+      </div>
+      {footnoteEl}
+      <ChartTooltip
+        anchor={plotEl}
+        point={point}
+        title={stage?.label ?? ''}
+        rows={rows}
+        notes={notes}
+      />
+      <LiveRegion>{liveText}</LiveRegion>
+      <VisuallyHidden as="div">
+        <table>
+          <caption>{label}</caption>
+          <thead>
+            <tr>
+              <th scope="col">{t('funnelChart.stage')}</th>
+              <th scope="col">{t('funnelChart.value')}</th>
+              <th scope="col">{t('funnelChart.stepConversion')}</th>
+              <th scope="col">{t('funnelChart.shareOfFirst')}</th>
+            </tr>
+          </thead>
+          <tbody>
+            {resolved.map((s) => (
+              <tr key={s.key}>
+                <th scope="row">{s.label}</th>
+                <td>{formatValue(s.value)}</td>
+                <td>{pct(s.stepRatio)}</td>
+                <td>{pct(s.shareRatio)}</td>
+              </tr>
+            ))}
+          </tbody>
+        </table>
+      </VisuallyHidden>
+    </figure>
+  );
+});