@eocrm/design-system 0.6.23 → 0.6.24

package/src/components/FunnelChart/funnelModel.ts

@@ -0,0 +1,124 @@
+/** Chart-palette slot (`--chart-series-N`). */
+export type FunnelSlot = 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8;
+
+/** Silhouette between stages: hold then a short straight taper, or a full-column trapezoid. */
+export type FunnelShape = 'taper' | 'sharp';
+
+/** One funnel stage as supplied by the consumer. */
+export interface FunnelStage {
+  /** Stable identity (React key). */
+  key: string;
+  /** Human name shown in labels, tooltip and data table. */
+  label: string;
+  /** Count for this stage. Non-finite or negative values are treated as 0. */
+  value: number;
+  /** Palette slot to highlight this stage with (e.g. Won in green); omit to follow the one-hue ramp. */
+  color?: FunnelSlot;
+}
+
+/** A stage with sanitised value, resolved colour slot and derived ratios. */
+export interface ResolvedStage {
+  key: string;
+  label: string;
+  /** Sanitised: non-finite or negative becomes 0. */
+  value: number;
+  /** The explicit `color` slot, or null for the ramp colour. */
+  slot: FunnelSlot | null;
+  /** `value / max(values)`; 0 when the max is 0. */
+  heightRatio: number;
+  /** `value / previous value`; null for the first stage or when the previous is <= 0. */
+  stepRatio: number | null;
+  /** `value / first value`; null when the first is <= 0. */
+  shareRatio: number | null;
+}
+
+/** Per-stage width in px below which the layout goes vertical. */
+export const MIN_STAGE_WIDTH = 96;
+/** Minimum drawn height in px of a stage, so zero values stay hoverable. */
+export const MIN_THICKNESS = 6;
+/** Taper shape: fraction of the column held at the stage's height before the diagonal starts. */
+export const TAPER_HOLD = 0.75;
+
+/** Sanitise values and compute ratios. */
+export function resolveStages(stages: readonly FunnelStage[]): ResolvedStage[] {
+  const values = stages.map((s) => (Number.isFinite(s.value) && s.value > 0 ? s.value : 0));
+  const max = Math.max(0, ...values);
+  const first = values[0] ?? 0;
+  return stages.map((s, i) => ({
+    key: s.key,
+    label: s.label,
+    value: values[i],
+    slot: s.color ?? null,
+    heightRatio: max > 0 ? values[i] / max : 0,
+    stepRatio: i > 0 && values[i - 1] > 0 ? values[i] / values[i - 1] : null,
+    shareRatio: first > 0 ? values[i] / first : null,
+  }));
+}
+
+/** Horizontal while each stage gets at least `MIN_STAGE_WIDTH` px, otherwise vertical. */
+export function orientationFor(width: number, count: number): 'horizontal' | 'vertical' {
+  return width / Math.max(count, 1) >= MIN_STAGE_WIDTH ? 'horizontal' : 'vertical';
+}
+
+/** Path and anchor points of one stage, in SVG user units. */
+export interface StageGeometry {
+  /** SVG path of the stage's closed outline. */
+  d: string;
+  /** Column centre x. */
+  cx: number;
+  /** Vertical centre (shared by all stages). */
+  cy: number;
+  /** Column left edge. */
+  x0: number;
+  /** Column right edge. */
+  x1: number;
+}
+
+const r2 = (n: number) => Math.round(n * 100) / 100;
+
+/** Outline of each stage, vertically centred; each stage tapers into the next one's height. */
+export function stageGeometry(args: {
+  stages: readonly ResolvedStage[];
+  width: number;
+  height: number;
+  shape: FunnelShape;
+}): StageGeometry[] {
+  const { stages, width, height, shape } = args;
+  const colW = width / stages.length;
+  const mid = height / 2;
+  const half = (s: ResolvedStage) => Math.max(MIN_THICKNESS / 2, (s.heightRatio * height) / 2);
+
+  return stages.map((s, i) => {
+    const x0 = i * colW;
+    const x1 = (i + 1) * colW;
+    const a = half(s);
+    const last = i === stages.length - 1;
+    const b = last ? a : half(stages[i + 1]);
+    const [t0, t1, b0, b1] = [mid - a, mid - b, mid + b, mid + a].map(r2);
+    const p = (x: number, y: number) => `${r2(x)},${y}`;
+    let d: string;
+    if (shape === 'sharp' || last) {
+      d = `M ${p(x0, t0)} L ${p(x1, t1)} L ${p(x1, b0)} L ${p(x0, b1)} Z`;
+    } else {
+      const xh = x0 + colW * TAPER_HOLD;
+      d =
+        `M ${p(x0, t0)} L ${p(xh, t0)} L ${p(x1, t1)}` +
+        ` L ${p(x1, b0)} L ${p(xh, b1)} L ${p(x0, b1)} Z`;
+    }
+    return { d, cx: r2(x0 + colW / 2), cy: mid, x0: r2(x0), x1: r2(x1) };
+  });
+}
+
+/** Column index under `x`, or null outside `[0, width)`. */
+export function stageIndexAt(width: number, count: number, x: number): number | null {
+  if (!(x >= 0 && x < width) || count <= 0) return null;
+  return Math.min(count - 1, Math.floor((x / width) * count));
+}
+
+/** Percent string; one decimal for ratios under 1%, otherwise whole percent. */
+export function formatPercent(ratio: number, locale: string): string {
+  return new Intl.NumberFormat(locale, {
+    style: 'percent',
+    maximumFractionDigits: ratio > 0 && ratio < 0.01 ? 1 : 0,
+  }).format(ratio);
+}

package/src/components/FunnelChart/index.ts

@@ -0,0 +1,2 @@
+export { FunnelChart } from './FunnelChart';
+export type { FunnelChartProps, FunnelShape, FunnelSlot, FunnelStage } from './FunnelChart';

package/src/components/_internal/useSize.ts

@@ -0,0 +1,23 @@
+import { useLayoutEffect, useState } from 'react';
+
+/** Callback ref plus the element's floored size, kept current by a ResizeObserver. */
+export function useSize<T extends HTMLElement>() {
+  const [el, setEl] = useState<T | null>(null);
+  const [size, setSize] = useState({ width: 0, height: 0 });
+  useLayoutEffect(() => {
+    if (!el || typeof ResizeObserver === 'undefined') return;
+    const measure = () => {
+      const { width, height } = el.getBoundingClientRect();
+      setSize((prev) =>
+        prev.width === Math.floor(width) && prev.height === Math.floor(height)
+          ? prev
+          : { width: Math.floor(width), height: Math.floor(height) },
+      );
+    };
+    measure();
+    const ro = new ResizeObserver(measure);
+    ro.observe(el);
+    return () => ro.disconnect();
+  }, [el]);
+  return [setEl, size, el] as const;
+}

package/src/components.manifest.json

@@ -149,7 +149,9 @@
       "LiveRegion",
       "VisuallyHidden"
     ],
-    "composedBy": []
+    "composedBy": [
+      "FunnelChart"
+    ]
   },
   "ChatBubble": {
     "tier": "composition",
@@ -392,7 +394,8 @@
     "composedBy": [
       "CatalogPicker",
       "Chart",
-      "DataTable"
+      "DataTable",
+      "FunnelChart"
     ]
   },
   "EntityChip": {
@@ -461,6 +464,17 @@
     ],
     "composedBy": []
   },
+  "FunnelChart": {
+    "tier": "composition",
+    "cluster": "Display",
+    "composes": [
+      "Chart",
+      "EmptyState",
+      "LiveRegion",
+      "VisuallyHidden"
+    ],
+    "composedBy": []
+  },
   "Grid": {
     "tier": "primitive",
     "cluster": "Layout",
@@ -609,6 +623,7 @@
       "Chart",
       "CodeBlock",
       "DateStrip",
+      "FunnelChart",
       "RichTextEditor",
       "TopBar",
       "TreeView"
@@ -1122,6 +1137,7 @@
       "ChatBubble",
       "DashboardWidget",
       "DateStrip",
+      "FunnelChart",
       "LiveRegion",
       "StagePath",
       "StatGroup",

package/src/i18n/en.ts

@@ -477,6 +477,16 @@ export const en: Messages = {
     noData: 'No data',
     markers: 'Markers',
   },
+  funnelChart: {
+    keyboardHint: 'Use arrow keys to inspect stages. All values are also in the data table.',
+    stage: 'Stage',
+    value: 'Value',
+    stepConversion: 'Conversion from previous stage',
+    shareOfFirst: 'Share of first stage',
+    ofStage: ({ percent, stage }) => `${percent as string} of ${stage as string}`,
+    noData: '—',
+    vsPrevious: 'vs previous',
+  },
   treeView: {
     loading: 'Loading…',
     loadError: "Couldn't load",

package/src/i18n/messages.ts

@@ -900,6 +900,24 @@ export interface Messages {
     /** Header of the data table's marker column (labels of the annotations covering each category). */
     markers: string;
   };
+  funnelChart: {
+    /** Accessible description of the focusable plot (its name is the chart label); says arrow keys inspect stages and that the data table lists every value. */
+    keyboardHint: string;
+    /** Header of the data table's stage column. */
+    stage: string;
+    /** Header of the data table's value column and the tooltip's value row label. */
+    value: string;
+    /** Header of the data table's step-conversion column (this stage / previous stage). */
+    stepConversion: string;
+    /** Header of the data table's share column (this stage / first stage). */
+    shareOfFirst: string;
+    /** A ratio relative to a named stage, e.g. "40% of Proposal" (tooltip, announcement). `percent` is already formatted. */
+    ofStage: (params: { percent: string; stage: string }) => string;
+    /** Data-table cell for an undefined ratio (first stage's step, or a previous stage of 0). */
+    noData: string;
+    /** Header of the vertical layout's visible step-conversion column ("vs previous"). */
+    vsPrevious: string;
+  };
   sparkline: {
     /** Accessible name of a Sparkline with data: label plus the series summary. */
     summary: (params: {

package/src/i18n/ru.ts

@@ -484,6 +484,17 @@ export const ru: Messages = {
     noData: 'Нет данных',
     markers: 'Отметки',
   },
+  funnelChart: {
+    keyboardHint:
+      'Используйте стрелки для просмотра этапов. Все значения также есть в таблице данных.',
+    stage: 'Этап',
+    value: 'Значение',
+    stepConversion: 'Конверсия из предыдущего этапа',
+    shareOfFirst: 'Доля от первого этапа',
+    ofStage: ({ percent, stage }) => `${percent as string} от «${stage as string}»`,
+    noData: '—',
+    vsPrevious: 'к предыдущему',
+  },
   treeView: {
     loading: 'Загрузка…',
     loadError: 'Не удалось загрузить',

package/src/index.ts

@@ -894,6 +894,13 @@ export type {
   StatTrend,
 } from './components/StatGroup';
 export { Chart } from './components/Chart';
+export { FunnelChart } from './components/FunnelChart';
+export type {
+  FunnelChartProps,
+  FunnelShape,
+  FunnelSlot,
+  FunnelStage,
+} from './components/FunnelChart';
 export { Sparkline } from './components/Sparkline';
 export type { SparklineProps, SparklineType } from './components/Sparkline';
 export { TreeView } from './components/TreeView';