@eocrm/design-system 0.6.22 → 0.6.24

package/docs/i18n.md

@@ -0,0 +1,74 @@
+# Localization (i18n)
+
+How library strings are translated, and how to pair `I18nProvider` with `LocaleProvider`.
+
+Every user-facing string the library renders — visible text, aria-labels, placeholders, default empty/loading copy — flows through a single React Context. Wrap your app once; every component picks up the right copy. There are NO `labels` / `cancelLabel` / `searchPlaceholder` props on any component.
+
+```tsx
+import { I18nProvider } from '@eocrm/design-system';
+
+<I18nProvider locale="ru">
+  <App />
+</I18nProvider>;
+```
+
+**Overrides** are a deep-partial of the messages tree:
+
+```tsx
+<I18nProvider
+  locale="ru"
+  overrides={{
+    pagination: { next: 'Дальше' },
+    badge: { modified: 'Изменено!' },
+  }}
+>
+  <App />
+</I18nProvider>
+```
+
+- Missing override keys fall back to the locale defaults.
+- Missing locale keys do NOT fall back to `en` — `I18nProvider` uses the one locale catalogue and `useTranslation` warns and returns the literal key string. The real guard is the type: `en` and `ru` are both annotated `: Messages` (total, not partial), so a missing key is a `tsc` error and cannot ship.
+- No provider at all = `en` defaults.
+
+**Available locales:** `'en'` (default), `'ru'`. v1.
+
+**`I18nProvider` vs `LocaleProvider` — pair them.** `I18nProvider` carries the message catalog (translated strings). `LocaleProvider` carries the BCP-47 tag used by `Intl.*` formatters inside Calendar / DatePicker / DateRangePicker (month names, weekday order, date-range formatting). They are independent — a Russian app should wrap with BOTH so visible strings AND Intl-rendered dates speak the right language:
+
+```tsx
+<I18nProvider locale="ru">
+  <LocaleProvider locale="ru-RU">
+    <App />
+  </LocaleProvider>
+</I18nProvider>
+```
+
+**Adding a new string in a library component**:
+
+1. Add the key to `src/i18n/messages.ts` (`Messages` interface).
+2. Add the English value to `src/i18n/en.ts`.
+3. Add the Russian value to `src/i18n/ru.ts` (use `ruPlural()` from `i18n/format.ts` for count-varying strings).
+4. In the component, `const t = useTranslation();` then `aria-label={t('component.key')}`. For array messages (months / weekdays), use `useTranslationArray()`.
+5. Never inline an English string — `aria-label="Close"` is a Hard rule 9 violation.
+
+**Drag-and-drop announcements** are localized too. Every drag surface (`Sortable`,
+`SortableGroup`, `Kanban`, `DataTable` column reorder, `RichTextEditor` block
+gutter) overrides dnd-kit's English defaults with the `drag.*` messages, and
+names what it drags by its **rendered text** rather than its id — "Amount due,
+position 3 of 7", not "col_amount was moved over droppable area col_name". Text
+is read from the DOM, so a closed `DropdownMenu` / `Tooltip` / `Popover` inside
+a card contributes nothing, and `aria-hidden` decoration is skipped.
+
+Two things are worth doing yourself:
+
+```tsx
+{/* Name the CONTAINER — the library can't invent one. Either attribute works. */}
+<Kanban.Column id="qualified" aria-label="Qualified">          {/* → "…in Qualified" */}
+<Kanban.Column id="qualified" aria-labelledby="qualified-h">   {/* same, from the heading */}
+<SortableGroup.Container id="review" items={ids} aria-label="In review" />
+
+{/* Override a chatty ITEM. Without this the whole card is read out. */}
+<Kanban.Card id="d-1" aria-label="Acme renewal">…title, owner, due date, badges…</Kanban.Card>
+<Sortable.Item id="f-1" aria-label="Company name">…</Sortable.Item>
+```
+
+An unnamed container falls back to its position ("column 2 of 3").

package/docs/typescript.md

@@ -0,0 +1,9 @@
+# TypeScript
+
+Getting prop types to resolve in your editor.
+
+Every prop and variant type is typed. If your editor shows no types:
+
+- Confirm `moduleResolution: "bundler"` (or `"node16"`) in your `tsconfig.json`.
+- Confirm your IDE's TS server is running.
+- The package's `types` field points at `./src/index.ts` — source distribution means the consumer's bundler compiles `.tsx`. Vite, Next.js, Webpack 5+ all support this; older configurations may need `transpilePackages: ['@eocrm/design-system']` (Next.js) or equivalent.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@eocrm/design-system",
-  "version": "0.6.22",
+  "version": "0.6.24",
   "description": "Design system for the EOCRM product — React 19 + SCSS modules + CSS custom properties.",
   "license": "Apache-2.0",
   "type": "module",
@@ -50,7 +50,7 @@
     "@dnd-kit/core": "^6.3.1",
     "@dnd-kit/sortable": "^10.0.0",
     "@dnd-kit/utilities": "^3.2.2",
-    "@eocrm/design-tokens": "0.6.22",
+    "@eocrm/design-tokens": "0.6.24",
     "@floating-ui/react-dom": "^2.1.8",
     "@types/d3-scale": "^4.0.9",
     "@types/d3-shape": "^3.2.0",

package/src/_meta/manifest.ts

@@ -127,6 +127,7 @@ const CLUSTERS: Record<string, string> = {
   DashboardWidget: 'Display',
   StatGroup: 'Display',
   Chart: 'Display',
+  FunnelChart: 'Display',
   Sparkline: 'Display',
   TreeView: 'Display',
   DataTable: 'Display',

package/src/components/Chart/Chart.tsx

@@ -2,7 +2,6 @@ import {
   forwardRef,
   useEffect,
   useId,
-  useLayoutEffect,
   useMemo,
   useState,
   type CSSProperties,
@@ -16,6 +15,7 @@ import { EmptyState } from '../EmptyState';
 import { useTranslation } from '../../i18n/useTranslation';
 import { useControllableState } from '../_internal/useControllableState';
 import { mergeRefs } from '../_internal/refs';
+import { useSize } from '../_internal/useSize';
 import { ChartLegend } from './ChartLegend';
 import { ChartTable } from './ChartTable';
 import { ChartTooltip } from './ChartTooltip';
@@ -131,27 +131,6 @@ function useDevWarnings(dropped: string[], overflowCount: number, droppedMarkers
   }, [overflowCount]);
 }
 
-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;
-}
-
 /**
  * Time-series chart (line, bar, stacked bar, area) that fills a `DashboardWidget variant="chart"` body.
  * @see docs/components/Chart.md

package/src/components/Chart/ChartTooltip.tsx

@@ -9,12 +9,14 @@ export interface ChartTooltipRow {
   slot: number;
   comparison: boolean;
   value: string;
+  /** CSS colour for the swatch; overrides `slot` (FunnelChart's ramp colours). */
+  color?: string;
 }
 
-const swatchStyle = (slot: number) =>
+const swatchStyle = (slot: number, color?: string) =>
   ({
     '--chart-series-color':
-      slot === 0 ? 'var(--chart-total-comparison)' : `var(--chart-series-${slot})`,
+      color ?? (slot === 0 ? 'var(--chart-total-comparison)' : `var(--chart-series-${slot})`),
   }) as CSSProperties;
 
 /**
@@ -72,7 +74,7 @@ export function ChartTooltip({
         <div key={r.key} className={styles.tooltipRow} data-nested={r.comparison || undefined}>
           <span
             className={styles.swatch}
-            style={swatchStyle(r.slot)}
+            style={swatchStyle(r.slot, r.color)}
             data-comparison={r.comparison || undefined}
           />
           <span className={styles.tooltipLabel}>{r.label}</span>

package/src/components/FunnelChart/FunnelChart.module.scss

@@ -0,0 +1,265 @@
+@use './FunnelChart.tokens';
+@use '../../styles/mixins' as *;
+
+.root {
+  display: grid;
+  grid-template-rows: minmax(0, 1fr);
+  gap: var(--funnel-chart-gap);
+  width: 100%;
+  height: 100%;
+  min-width: 0;
+  min-height: 0;
+}
+
+.root[data-empty] {
+  place-items: center;
+}
+
+// The footnote takes its own row; the plot (or EmptyState) fills the rest.
+.root[data-footnote] {
+  grid-template-rows: minmax(0, 1fr) auto;
+}
+
+.footnote {
+  color: var(--chart-footnote-fg);
+  font-size: var(--chart-footnote-size);
+  line-height: var(--chart-footnote-line-height);
+}
+
+.plot {
+  display: grid;
+  grid-template-rows: minmax(var(--funnel-chart-min-height), 1fr) auto;
+  gap: var(--funnel-chart-gap);
+  min-height: 0;
+  border-radius: var(--chart-plot-radius);
+  outline: none;
+  touch-action: pan-y;
+
+  &:focus-visible {
+    @include focus-ring(var(--funnel-chart-ring));
+  }
+}
+
+.shapes {
+  min-height: 0;
+  overflow: hidden;
+
+  // The SVG's explicit height must not feed back into the row size, or the strip only ever grows
+  // in an auto-height parent. Size containment makes the row fall back to min-height / parent height.
+  contain: size;
+}
+
+.plot[data-clickable] .shapes {
+  cursor: pointer;
+}
+
+.svg {
+  display: block;
+}
+
+.stage {
+  transition: opacity var(--funnel-chart-transition);
+
+  &[data-dimmed] {
+    opacity: var(--funnel-chart-dim-opacity);
+  }
+}
+
+.shape {
+  fill: var(--chart-series-color, currentColor);
+
+  // ponytail: CSS `d` transitions don't animate in Safari (it snaps). Use a JS tween only if Safari users notice.
+  transition: d var(--funnel-chart-transition);
+}
+
+.pill {
+  fill: var(--funnel-chart-pill-bg);
+}
+
+.heroValue,
+.heroLabel {
+  fill: var(--funnel-chart-hero-fg);
+}
+
+.heroValue {
+  font-size: var(--funnel-chart-hero-value-size);
+  font-weight: var(--font-weight-semibold);
+  font-variant-numeric: tabular-nums;
+}
+
+.heroLabel {
+  font-size: var(--funnel-chart-hero-label-size);
+  font-weight: var(--funnel-chart-hero-label-weight);
+}
+
+.pillText {
+  fill: var(--funnel-chart-pill-fg);
+  font-size: var(--funnel-chart-pill-size);
+  font-weight: var(--font-weight-semibold);
+  font-variant-numeric: tabular-nums;
+}
+
+// One column per stage, aligned with the shapes above; dashed rules between columns.
+.footer {
+  display: grid;
+  grid-auto-columns: minmax(0, 1fr);
+  grid-auto-flow: column;
+}
+
+.footer > .cell + .cell {
+  border-inline-start: var(--border-width) dashed var(--funnel-chart-separator);
+}
+
+.cell {
+  display: grid;
+  align-content: start;
+  justify-items: center;
+  padding-inline: var(--space-1);
+  text-align: center;
+  overflow-wrap: anywhere;
+  transition: opacity var(--funnel-chart-transition);
+
+  &[data-dimmed] {
+    opacity: var(--funnel-chart-dim-opacity);
+  }
+
+  // A focused stage hovered away from keeps its focus ring readable (WCAG 2.4.7).
+  &[data-dimmed]:focus-visible {
+    opacity: initial;
+  }
+
+  // Hero shown: the first cell keeps its value and label, invisible, so it is a normal footer-height
+  // box (and a full-size focus ring when it is a button) under the band that shows them.
+  &[data-hero-cell] > * {
+    visibility: hidden;
+  }
+
+  // Clickable stages render the cell as a <button> (reset.scss strips its chrome).
+  &:is(button) {
+    border-radius: var(--chart-plot-radius);
+    cursor: pointer;
+    outline: none;
+  }
+
+  &:is(button):focus-visible {
+    @include focus-ring(var(--funnel-chart-ring));
+  }
+}
+
+.value {
+  // Only labels break anywhere; numbers stay whole.
+  overflow-wrap: normal;
+  font-size: var(--funnel-chart-value-size);
+  font-weight: var(--funnel-chart-value-weight);
+  font-variant-numeric: tabular-nums;
+}
+
+.label {
+  color: var(--funnel-chart-label-fg);
+  font-size: var(--funnel-chart-label-size);
+}
+
+// Vertical layout: a slice of the funnel per row (same `shape`, turned on its side, thin gaps
+// between slices) beside a table-like grid; the rows scroll as a last resort.
+.root[data-orientation='vertical'] .plot {
+  grid-template-rows: none;
+  grid-auto-rows: min-content;
+
+  // One column template shared by the header and every row (subgrid): band track (flexible share, so
+  // band widths stay proportional), swatch, label (wraps when tight), value, step pill.
+  grid-template-columns:
+    minmax(var(--funnel-chart-row-track-min), 1fr) auto minmax(0, max-content)
+    max-content max-content;
+  align-content: start;
+  gap: var(--funnel-chart-slice-gap) var(--funnel-chart-gap);
+  overflow-y: auto;
+
+  // Room for the stage buttons' focus rings, which the scroll container would clip.
+  padding: calc(var(--ring-width) + var(--ring-offset));
+}
+
+// Header and rows span the plot's columns and inherit them (subgrid).
+.header,
+.root[data-orientation='vertical'] .cell {
+  // stylelint-disable-next-line property-disallowed-list -- internal row spanning the plot's own columns (subgrid), not consumer layout
+  grid-column: 1 / -1;
+  display: grid;
+  grid-template-columns: subgrid;
+}
+
+.header {
+  padding-block-end: var(--space-1);
+  color: var(--funnel-chart-header-fg);
+  font-size: var(--funnel-chart-header-size);
+}
+
+.headerValue {
+  text-align: end;
+}
+
+// Items stretch to the row (the band needs the full height); text items centre themselves.
+.root[data-orientation='vertical'] .cell {
+  align-content: stretch;
+  align-items: stretch;
+  justify-items: stretch;
+  min-block-size: var(--funnel-chart-row-min-height);
+  padding-inline: 0;
+  text-align: start;
+
+  .label,
+  .value,
+  .swatch,
+  .step {
+    display: grid;
+    align-content: center;
+  }
+
+  .value {
+    font-size: var(--funnel-chart-label-size);
+    text-align: end;
+  }
+}
+
+// The slice stretches to the row; size containment keeps the SVG's aspect ratio out of the row
+// height, which comes from the text (or the min height).
+.bandTrack {
+  display: block;
+  contain: size;
+
+  .svg {
+    inline-size: 100%;
+    block-size: 100%;
+  }
+}
+
+.swatch::before {
+  content: '';
+  inline-size: var(--chart-swatch);
+  block-size: var(--chart-swatch);
+  border-radius: var(--radius-sm);
+  background: var(--chart-series-color, currentColor);
+}
+
+.step {
+  justify-items: start;
+  color: var(--funnel-chart-label-fg);
+  font-size: var(--funnel-chart-pill-size);
+}
+
+.rowPill {
+  padding-inline: var(--space-2);
+  border-radius: var(--radius-full);
+  background: var(--funnel-chart-row-pill-bg);
+  color: var(--funnel-chart-pill-fg);
+  font-size: var(--funnel-chart-pill-size);
+  font-weight: var(--font-weight-semibold);
+  font-variant-numeric: tabular-nums;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .stage,
+  .shape,
+  .cell {
+    transition: none;
+  }
+}

package/src/components/FunnelChart/FunnelChart.tokens.scss

@@ -0,0 +1,72 @@
+// FunnelChart.tokens.scss — component tokens for <FunnelChart>. Stages are a one-hue ramp from
+// --chart-series-1 toward the surface (a stage's `color` slot uses --chart-series-N instead);
+// everything else defaults to primitives or chart tokens.
+@use '../Chart/Chart.tokens';
+
+:root {
+  --funnel-chart-gap: var(--space-2);
+
+  // Ramp: stage i of n is ramp-color mixed (oklab) toward ramp-target by max-mix * i / (n - 1). Light:
+  // target is the surface, 48% keeps the lightest step >= 2:1 against it. Dark (below): target is
+  // --color-fg so later stages get paler, not muddier; 65% passes validate_palette.js --ordinal
+  // --mode dark for 3-4 stages (6 stages: ΔL ~0.04), palest 4-stage step #a6c5eb is still clearly blue.
+  // ponytail: from 5 stages on, adjacent steps fall under the 0.06 OKLCH ΔL ideal (~0.03 at 8); labels,
+  // the vertical table and the tooltip carry identity. A wider ramp needs a darker first stage than series-1.
+  --funnel-chart-ramp-color: var(--chart-series-1);
+  --funnel-chart-surface: var(--color-bg);
+  --funnel-chart-ramp-target: var(--funnel-chart-surface);
+  --funnel-chart-ramp-max-mix: 48%;
+
+  // Hero: the first stage's value and label inside its band (horizontal). Paired with the band
+  // (--funnel-chart-ramp-color, i.e. --chart-series-1), not the accent: the surface colour knocked out
+  // of the band, the same pair the chart series are gated on (3:1). It misses 4.5:1 (only near-black,
+  // no neutral token, clears that in light), so both lines are WCAG large text (24px; 20px bold), 3:1:
+  // @contrast --color-bg on --color-chart-series-1 = 4.42:1 light
+  // @contrast --color-bg on --color-chart-series-1 = 4.45:1 dark
+  // Override --funnel-chart-ramp-color and this pair is yours to recheck; a stage-0 `color` slot hides the hero.
+  --funnel-chart-hero-fg: var(--color-bg);
+  --funnel-chart-hero-value-size: var(--font-size-2xl);
+  --funnel-chart-hero-label-size: var(--font-size-xl);
+  --funnel-chart-hero-label-weight: var(--font-weight-bold);
+
+  // Dashed rule between horizontal footer columns, from stage 2 on.
+  --funnel-chart-separator: var(--color-border);
+
+  // Intrinsic height of the shapes strip when the parent gives no height.
+  --funnel-chart-min-height: calc(var(--space-16) * 2);
+  --funnel-chart-pill-bg: var(--color-bg);
+  --funnel-chart-pill-fg: var(--color-fg);
+  --funnel-chart-pill-size: var(--font-size-xs);
+  --funnel-chart-value-size: var(--font-size-lg);
+  --funnel-chart-value-weight: var(--font-weight-semibold);
+  --funnel-chart-label-fg: var(--color-fg-muted);
+  --funnel-chart-label-size: var(--font-size-sm);
+  --funnel-chart-dim-opacity: var(--chart-dim-opacity);
+  --funnel-chart-ring: var(--chart-ring);
+  --funnel-chart-transition: var(--transition-slow);
+
+  // Vertical layout (narrow containers): rows of a funnel slice beside a table-like grid (swatch,
+  // stage, value, step pill). The min height keeps a short row's taper readable; the slice gap
+  // separates the slices with a thin line of surface.
+  --funnel-chart-row-min-height: var(--space-10);
+  --funnel-chart-slice-gap: var(--space-05);
+  --funnel-chart-header-fg: var(--color-fg-muted);
+  --funnel-chart-header-size: var(--font-size-xs);
+
+  // Narrowest the band track gets beside the table, so the band never vanishes.
+  --funnel-chart-row-track-min: var(--space-16);
+  --funnel-chart-row-pill-bg: var(--color-bg-muted);
+}
+
+// Dark ramp: same scopes as the generated dark.scss (forced dark, and OS dark unless forced light).
+:root[data-theme='dark'] {
+  --funnel-chart-ramp-target: var(--color-fg);
+  --funnel-chart-ramp-max-mix: 65%;
+}
+
+@media (prefers-color-scheme: dark) {
+  :root:not([data-theme='light']) {
+    --funnel-chart-ramp-target: var(--color-fg);
+    --funnel-chart-ramp-max-mix: 65%;
+  }
+}