@eocrm/design-system 0.0.0-stage → 0.6.18

package/src/components/TreeView/treeModel.ts

@@ -0,0 +1,224 @@
+import type { ReactNode } from 'react';
+
+/** One node of a TreeView. */
+export interface TreeViewNode {
+  /** Stable unique id. */
+  id: string;
+  /** Accessible name of the row and typeahead text; rendered when `content` is absent. */
+  label: string;
+  /** Whether the node can expand. Its children may not be loaded yet. */
+  hasChildren: boolean;
+  /** Rich, non-interactive row content. Visual only: the row is named by `label`. */
+  content?: ReactNode;
+}
+
+/** Children of a node: the loaded array, `undefined` while loading, `{ error: true }` when the load failed. */
+export type TreeViewChildren = TreeViewNode[] | undefined | { error: true };
+
+/** "N more not shown" row at the end of a level. */
+export interface TreeViewOverflow {
+  /** Visible text and accessible name, e.g. "12 more not shown". */
+  label: string;
+  /** Makes the row actionable (Enter / click). */
+  onLoadMore?: () => void;
+  /** A load-more fetch is in flight: the row shows the translated loading text and is inert. */
+  loading?: boolean;
+}
+
+/** Presentation of a TreeView. */
+export type TreeViewView = 'list' | 'chart';
+
+/** One rendered row: a node (with its nested children) or a loading / error / overflow status row. */
+export type TreeItem =
+  | {
+      kind: 'node';
+      key: string;
+      node: TreeViewNode;
+      level: number;
+      parentId: string | null;
+      setSize: number;
+      posInSet: number;
+      expanded: boolean;
+      children: TreeItem[];
+    }
+  | { kind: 'loading' | 'error'; key: string; level: number; parentId: string }
+  | {
+      kind: 'overflow';
+      key: string;
+      level: number;
+      parentId: string | null;
+      overflow: TreeViewOverflow;
+    };
+
+/** Everything `buildTree` needs to derive the visible rows. */
+export interface TreeModelInput {
+  roots: TreeViewNode[];
+  childrenOf: (id: string) => TreeViewChildren;
+  expandedIds: ReadonlySet<string>;
+  overflowOf?: (parentId: string | null) => TreeViewOverflow | null;
+}
+
+/** What a key press resolves to; the component performs it. */
+export type TreeAction =
+  | { type: 'focus'; key: string }
+  | { type: 'expand'; id: string }
+  | { type: 'collapse'; id: string }
+  | { type: 'activate'; key: string };
+
+/** Item key of the node with this id. */
+export const nodeKey = (id: string) => `node:${id}`;
+
+function level(
+  nodes: TreeViewNode[],
+  depth: number,
+  parentId: string | null,
+  input: TreeModelInput,
+): TreeItem[] {
+  const out: TreeItem[] = nodes.map((node, i) => {
+    const expanded = node.hasChildren && input.expandedIds.has(node.id);
+    let children: TreeItem[] = [];
+    if (expanded) {
+      const kids = input.childrenOf(node.id);
+      if (kids === undefined) {
+        children = [
+          { kind: 'loading', key: `loading:${node.id}`, level: depth + 1, parentId: node.id },
+        ];
+      } else if (!Array.isArray(kids)) {
+        children = [
+          { kind: 'error', key: `error:${node.id}`, level: depth + 1, parentId: node.id },
+        ];
+      } else {
+        children = level(kids, depth + 1, node.id, input);
+      }
+    }
+    return {
+      kind: 'node',
+      key: nodeKey(node.id),
+      node,
+      level: depth,
+      parentId,
+      setSize: nodes.length,
+      posInSet: i + 1,
+      expanded,
+      children,
+    };
+  });
+  const overflow = input.overflowOf?.(parentId) ?? null;
+  if (overflow) {
+    out.push({
+      kind: 'overflow',
+      key: `overflow:${parentId ?? ''}`,
+      level: depth,
+      parentId,
+      overflow,
+    });
+  }
+  return out;
+}
+
+/** Nested items in render order: nodes, plus loading / error / overflow status rows. */
+export function buildTree(input: TreeModelInput): TreeItem[] {
+  return level(input.roots, 1, null, input);
+}
+
+/** Visible items in document order. */
+export function flatten(items: TreeItem[]): TreeItem[] {
+  return items.flatMap((item) =>
+    item.kind === 'node' ? [item, ...flatten(item.children)] : [item],
+  );
+}
+
+function enter(flat: TreeItem[], i: number): TreeAction | null {
+  const item = flat[i];
+  if (item.kind !== 'node' || !item.node.hasChildren) return null;
+  if (!item.expanded) return { type: 'expand', id: item.node.id };
+  const next = flat[i + 1];
+  return next && next.parentId === item.node.id ? { type: 'focus', key: next.key } : null;
+}
+
+function leave(flat: TreeItem[], i: number): TreeAction | null {
+  const item = flat[i];
+  if (item.kind === 'node' && item.expanded) return { type: 'collapse', id: item.node.id };
+  return item.parentId === null ? null : { type: 'focus', key: nodeKey(item.parentId) };
+}
+
+function sibling(flat: TreeItem[], i: number, step: 1 | -1): TreeAction | null {
+  const item = flat[i];
+  for (let j = i + step; j >= 0 && j < flat.length; j += step) {
+    if (flat[j].level < item.level) return null;
+    if (flat[j].level === item.level) return { type: 'focus', key: flat[j].key };
+  }
+  return null;
+}
+
+/** Resolves a keyboard key on the item `currentKey` to an action, or null when the key does nothing. */
+export function keyAction(
+  flat: TreeItem[],
+  currentKey: string,
+  key: string,
+  view: TreeViewView,
+): TreeAction | null {
+  const i = flat.findIndex((item) => item.key === currentKey);
+  if (i < 0) return null;
+  const focus = (j: number): TreeAction | null =>
+    flat[j] ? { type: 'focus', key: flat[j].key } : null;
+  switch (key) {
+    case 'Home':
+      return focus(0);
+    case 'End':
+      return focus(flat.length - 1);
+    case 'Enter':
+    case ' ':
+      return { type: 'activate', key: currentKey };
+  }
+  if (view === 'list') {
+    switch (key) {
+      case 'ArrowDown':
+        return focus(i + 1);
+      case 'ArrowUp':
+        return i > 0 ? focus(i - 1) : null;
+      case 'ArrowRight':
+        return enter(flat, i);
+      case 'ArrowLeft':
+        return leave(flat, i);
+    }
+    return null;
+  }
+  switch (key) {
+    case 'ArrowDown':
+      return enter(flat, i);
+    case 'ArrowUp':
+      return leave(flat, i);
+    case 'ArrowRight':
+      return sibling(flat, i, 1);
+    case 'ArrowLeft':
+      return sibling(flat, i, -1);
+  }
+  return null;
+}
+
+/**
+ * Next node whose label starts with `buffer` (case-insensitive), searching after the current item for a
+ * single character and from the current item for a longer buffer, wrapping. Status rows are skipped.
+ */
+export function typeaheadMatch(
+  flat: TreeItem[],
+  currentKey: string,
+  buffer: string,
+): string | null {
+  const i = Math.max(
+    0,
+    flat.findIndex((item) => item.key === currentKey),
+  );
+  const needle = buffer.toLocaleLowerCase();
+  // A repeated single character ("ss") cycles through the matches for that character (APG).
+  const repeated = buffer.length > 1 && [...needle].every((c) => c === needle[0]);
+  const start = buffer.length > 1 && !repeated ? i : i + 1;
+  const prefix = repeated ? needle[0] : needle;
+  for (let k = 0; k < flat.length; k++) {
+    const item = flat[(start + k) % flat.length];
+    if (item.kind === 'node' && item.node.label.toLocaleLowerCase().startsWith(prefix))
+      return item.key;
+  }
+  return null;
+}

package/src/components/VisuallyHidden/VisuallyHidden.module.scss

@@ -0,0 +1,7 @@
+@use '../../styles/mixins' as *;
+
+// The standard clip technique. Its position/margin are how the text leaves
+// the layout while staying in the accessibility tree — not component layout.
+.root {
+  @include visually-hidden;
+}

package/src/components/VisuallyHidden/VisuallyHidden.tsx

@@ -0,0 +1,29 @@
+import { forwardRef, type HTMLAttributes } from 'react';
+import clsx from 'clsx';
+import styles from './VisuallyHidden.module.scss';
+
+/** Element VisuallyHidden renders. `'span'` (default) for inline text, `'div'` for block content. */
+export type VisuallyHiddenAs = 'span' | 'div';
+
+export interface VisuallyHiddenProps extends HTMLAttributes<HTMLElement> {
+  /**
+   * Element to render. `'span'` for inline text (the common case — a link
+   * suffix, a labelling phrase). `'div'` when the hidden content is itself
+   * block-level (e.g. wraps other block elements).
+   * @default 'span'
+   */
+  as?: VisuallyHiddenAs;
+}
+
+/**
+ * Content removed from the visual layout but kept in the accessibility tree.
+ * @see docs/components/VisuallyHidden.md
+ */
+export const VisuallyHidden = forwardRef<HTMLElement, VisuallyHiddenProps>(function VisuallyHidden(
+  { as, className, ...props },
+  ref,
+) {
+  const Tag = as ?? 'span';
+  // {...props} last (Pattern A) — nothing here is semantic to protect.
+  return <Tag ref={ref as never} className={clsx(styles.root, className)} {...props} />;
+});

package/src/components/VisuallyHidden/index.ts

@@ -0,0 +1,2 @@
+export { VisuallyHidden } from './VisuallyHidden';
+export type { VisuallyHiddenProps, VisuallyHiddenAs } from './VisuallyHidden';

package/src/components/WidgetPreview/WidgetPreview.module.scss

@@ -0,0 +1,11 @@
+@use './WidgetPreview.tokens';
+
+.root {
+  display: block;
+  width: 100%;
+  aspect-ratio: var(--widget-preview-aspect);
+  padding: var(--widget-preview-padding);
+  overflow: hidden;
+  background: var(--widget-preview-bg);
+  border-radius: var(--widget-preview-radius);
+}

package/src/components/WidgetPreview/WidgetPreview.tokens.scss

@@ -0,0 +1,26 @@
+:root {
+  // Decorative miniature of a widget kind (CatalogPicker previews).
+  --widget-preview-bg: var(--color-bg-subtle);
+  --widget-preview-radius: var(--radius-md);
+  --widget-preview-padding: var(--space-3);
+  --widget-preview-aspect: 16 / 10;
+
+  // Shape pieces on the preview box, and the accent "hero" pieces per kind.
+  // Decorative, but must read at gallery-card size (#626): the strongest
+  // non-text neutral as a fill, and a half-strength accent. The accent is
+  // translucent, so it sits correctly on an overridden --widget-preview-bg;
+  // these resolve at :root, so a scoped --color-* override does NOT reach
+  // them — override the --widget-preview-* tokens. Measured in contrast.test.ts.
+  --widget-preview-shape: var(--color-border-strong);
+  --widget-preview-accent: color-mix(in srgb, var(--color-accent) 50%, transparent);
+  --widget-preview-accent-strong: var(--color-accent);
+
+  // Shared by preview and loading shapes.
+  --widget-shape-gap: var(--space-2);
+  --widget-shape-line: var(--space-2);
+  --widget-shape-value: var(--space-6);
+  --widget-shape-avatar: var(--space-4);
+  --widget-shape-dot: var(--space-2);
+  --widget-shape-card: var(--space-5);
+  --widget-shape-line-stroke: var(--border-width-emphasis);
+}

package/src/components/WidgetPreview/WidgetPreview.tsx

@@ -0,0 +1,36 @@
+import { forwardRef, type HTMLAttributes } from 'react';
+import clsx from 'clsx';
+import { WidgetShape } from './WidgetShape';
+import styles from './WidgetPreview.module.scss';
+
+/** Widget kind depicted by a WidgetPreview. */
+export type WidgetPreviewVariant = 'kpi' | 'list' | 'chart' | 'line' | 'pipeline' | 'activity';
+
+export interface WidgetPreviewProps extends HTMLAttributes<HTMLDivElement> {
+  /**
+   * Which widget kind the miniature depicts. Required.
+   * - `'kpi'` — label, a large value block (strong accent), an accented trend line.
+   * - `'list'` — rows of accented avatar + line; first avatar strong.
+   * - `'chart'` — a bar series (accented, one bar strong).
+   * - `'line'` — a line series over a light area (strong accent line).
+   * - `'pipeline'` — stage columns of cards; current stage header strong and its cards accented; next stage header accented.
+   * - `'activity'` — timeline rows with accented dots; first dot strong.
+   */
+  variant: WidgetPreviewVariant;
+}
+
+/**
+ * Decorative, data-free miniature of a dashboard widget kind (for CatalogPicker items).
+ * @see docs/components/WidgetPreview.md
+ */
+// {...rest} FIRST so aria-hidden always wins (Pattern B): the surrounding card names the item.
+export const WidgetPreview = forwardRef<HTMLDivElement, WidgetPreviewProps>(function WidgetPreview(
+  { variant, className, ...rest },
+  ref,
+) {
+  return (
+    <div {...rest} ref={ref} aria-hidden="true" className={clsx(styles.root, className)}>
+      <WidgetShape kind={variant} mode="preview" />
+    </div>
+  );
+});

package/src/components/WidgetPreview/WidgetShape.module.scss

@@ -0,0 +1,140 @@
+@use './WidgetPreview.tokens';
+
+.root {
+  display: flex;
+  flex-direction: column;
+  width: 100%;
+  height: 100%;
+  min-height: 0;
+  overflow: hidden;
+}
+
+// Skeleton's own --skeleton-bg is the muted surface; previews sit ON a muted
+// box, so preview shapes take the darker shape colour instead.
+.root[data-mode='preview'] .piece {
+  --skeleton-bg: var(--widget-preview-shape);
+}
+
+.piece {
+  display: block;
+}
+
+.root[data-mode='preview'] .hero {
+  --skeleton-bg: var(--widget-preview-accent);
+}
+
+.root[data-mode='preview'] .heroStrong {
+  --skeleton-bg: var(--widget-preview-accent-strong);
+}
+
+.kpi {
+  display: flex;
+  flex-direction: column;
+  justify-content: center;
+  gap: var(--widget-shape-gap);
+  height: 100%;
+}
+
+.kpiLabel {
+  width: 40%;
+  height: var(--widget-shape-line);
+}
+
+.kpiValue {
+  width: 60%;
+  height: var(--widget-shape-value);
+}
+
+.kpiTrend {
+  width: 30%;
+  height: var(--widget-shape-line);
+}
+
+.rows {
+  display: flex;
+  flex-direction: column;
+  gap: var(--widget-shape-gap);
+}
+
+.row {
+  display: flex;
+  align-items: center;
+  gap: var(--widget-shape-gap);
+}
+
+.avatar {
+  flex: none;
+  width: var(--widget-shape-avatar);
+  height: var(--widget-shape-avatar);
+}
+
+.dot {
+  flex: none;
+  width: var(--widget-shape-dot);
+  height: var(--widget-shape-dot);
+}
+
+.line {
+  flex: 1;
+  height: var(--widget-shape-line);
+}
+
+.lineShort {
+  flex: 0 1 60%;
+}
+
+.chart {
+  display: flex;
+  align-items: flex-end;
+  gap: var(--widget-shape-gap);
+  height: 100%;
+}
+
+.barSlot {
+  display: flex;
+  flex: 1;
+  align-items: flex-end;
+  height: 100%;
+}
+
+.bar {
+  width: 100%;
+}
+
+.pipeline {
+  display: flex;
+  gap: var(--widget-shape-gap);
+  height: 100%;
+}
+
+.column {
+  display: flex;
+  flex: 1;
+  flex-direction: column;
+  gap: var(--widget-shape-gap);
+}
+
+.stage {
+  height: var(--widget-shape-line);
+}
+
+.dealCard {
+  height: var(--widget-shape-card);
+}
+
+.lineChart {
+  display: block;
+  width: 100%;
+  height: 100%;
+}
+
+.lineArea {
+  fill: var(--widget-preview-accent);
+}
+
+.linePath {
+  fill: none;
+  stroke: var(--widget-preview-accent-strong);
+  stroke-width: var(--widget-shape-line-stroke);
+  stroke-linejoin: round;
+}

package/src/components/WidgetPreview/WidgetShape.tsx

@@ -0,0 +1,159 @@
+import { Fragment } from 'react';
+import clsx from 'clsx';
+import { Skeleton } from '../Skeleton';
+import styles from './WidgetShape.module.scss';
+
+/** Internal: which widget silhouette to draw. `lines` = generic text lines (standard widget loading). */
+export type WidgetShapeKind = 'kpi' | 'list' | 'chart' | 'line' | 'pipeline' | 'activity' | 'lines';
+/** Internal: `preview` = static + accent hero (WidgetPreview); `loading` = pulsing, neutral, fills its box. */
+export type WidgetShapeMode = 'preview' | 'loading';
+
+// Loading mode repeats rows to fill a tall cell; the root clips the overflow.
+const LOADING_ROWS = 12;
+// 3 avatar rows fit the 16:10 box down to ~160px wide; dots are smaller so activity fits 4.
+const PREVIEW_ROWS: Partial<Record<WidgetShapeKind, number>> = { list: 3 };
+const PREVIEW_ROWS_DEFAULT = 4;
+const BAR_HEIGHTS = ['40%', '65%', '50%', '85%', '70%', '55%'];
+const PIPELINE_CARDS = [3, 2, 1];
+
+/**
+ * Internal widget silhouette shared by WidgetPreview (preview) and DashboardWidget (loading).
+ * Built only from Skeleton pieces; sizes are relative so it scales with its box.
+ */
+export function WidgetShape({ kind, mode }: { kind: WidgetShapeKind; mode: WidgetShapeMode }) {
+  const preview = mode === 'preview';
+  const animation = preview ? 'none' : 'pulse';
+  // `hero` marks the accent piece(s) — preview mode only, so a loading
+  // skeleton never looks like real data.
+  const hero = (on: boolean) => (preview && on ? { 'data-hero': '' } : {});
+  const piece = (
+    cls: string,
+    on = false,
+    variant: 'text' | 'circular' | 'rectangular' = 'rectangular',
+    strong = false,
+  ) => (
+    <Skeleton
+      variant={variant}
+      animation={animation}
+      className={clsx(
+        styles.piece,
+        cls,
+        preview && on && styles.hero,
+        preview && on && strong && styles.heroStrong,
+      )}
+      {...hero(on)}
+    />
+  );
+  const rows = preview ? (PREVIEW_ROWS[kind] ?? PREVIEW_ROWS_DEFAULT) : LOADING_ROWS;
+
+  let body;
+  switch (kind) {
+    case 'kpi':
+      body = (
+        <div className={styles.kpi}>
+          {piece(styles.kpiLabel)}
+          {piece(styles.kpiValue, true, 'rectangular', true)}
+          {piece(styles.kpiTrend, true)}
+        </div>
+      );
+      break;
+    case 'list':
+    case 'activity':
+      body = (
+        <div className={styles.rows}>
+          {Array.from({ length: rows }, (_, i) => (
+            <div key={i} className={styles.row}>
+              {piece(kind === 'list' ? styles.avatar : styles.dot, true, 'circular', i === 0)}
+              {piece(clsx(styles.line, i % 3 === 2 && styles.lineShort))}
+            </div>
+          ))}
+        </div>
+      );
+      break;
+    case 'chart':
+      body = (
+        <div className={styles.chart}>
+          {BAR_HEIGHTS.map((h, i) => (
+            <div key={i} className={styles.barSlot}>
+              {/* height is data-free decoration, set inline so the bars differ */}
+              <Skeleton
+                variant="rectangular"
+                animation={animation}
+                className={clsx(
+                  styles.piece,
+                  styles.bar,
+                  preview && styles.hero,
+                  preview && i === 3 && styles.heroStrong,
+                )}
+                style={{ height: h }}
+                {...hero(true)}
+              />
+            </div>
+          ))}
+        </div>
+      );
+      break;
+    case 'line':
+      // Data-free polyline in a 100×60 viewBox, stretched to the box; preview only
+      // (DashboardWidget never asks for a 'line' loading shape).
+      body = (
+        <svg
+          className={styles.lineChart}
+          viewBox="0 0 100 60"
+          preserveAspectRatio="none"
+          {...hero(true)}
+        >
+          <path
+            className={styles.lineArea}
+            d="M0,48 L20,36 L40,42 L60,20 L80,28 L100,10 L100,60 L0,60 Z"
+          />
+          <path
+            className={styles.linePath}
+            d="M0,48 L20,36 L40,42 L60,20 L80,28 L100,10"
+            vectorEffect="non-scaling-stroke"
+          />
+        </svg>
+      );
+      break;
+    case 'pipeline':
+      body = (
+        <div className={styles.pipeline}>
+          {PIPELINE_CARDS.map((n, col) => (
+            <div key={col} className={styles.column}>
+              <Skeleton
+                variant="rectangular"
+                animation={animation}
+                className={clsx(
+                  styles.piece,
+                  styles.stage,
+                  preview && col < 2 && styles.hero,
+                  preview && col === 0 && styles.heroStrong,
+                )}
+                {...hero(col < 2)}
+              />
+              {Array.from({ length: n }, (_, i) => (
+                <Fragment key={i}>{piece(styles.dealCard, col === 0)}</Fragment>
+              ))}
+            </div>
+          ))}
+        </div>
+      );
+      break;
+    default: // 'lines'
+      body = (
+        <div className={styles.rows}>
+          {Array.from({ length: rows }, (_, i) => (
+            <div key={i} className={styles.row}>
+              {piece(clsx(styles.line, i % 3 === 2 && styles.lineShort), false, 'text')}
+            </div>
+          ))}
+        </div>
+      );
+  }
+
+  return (
+    <div className={styles.root} data-widget-shape={kind} data-mode={mode} aria-hidden="true">
+      {body}
+    </div>
+  );
+}

package/src/components/WidgetPreview/index.ts

@@ -0,0 +1,2 @@
+export { WidgetPreview } from './WidgetPreview';
+export type { WidgetPreviewProps, WidgetPreviewVariant } from './WidgetPreview';

package/src/components/_internal/Trend.tsx

@@ -0,0 +1,27 @@
+import { Minus, TrendingDown, TrendingUp } from 'lucide-react';
+import { VisuallyHidden } from '../VisuallyHidden';
+import { useTranslation } from '../../i18n/useTranslation';
+import type { DashboardWidgetTrend } from '../DashboardWidget/DashboardWidget';
+
+const DEFAULT_SENTIMENT = { up: 'positive', down: 'negative', flat: 'neutral' } as const;
+const TREND_ICON = { up: TrendingUp, down: TrendingDown, flat: Minus } as const;
+const TREND_WORD = { up: 'trendUp', down: 'trendDown', flat: 'trendFlat' } as const;
+
+/**
+ * Internal: KPI trend line shared by DashboardWidget (kpi) and StatTile. Markup only;
+ * the caller's `className` sets size and colours (style `[data-sentiment]` per component).
+ */
+export function Trend({ trend, className }: { trend: DashboardWidgetTrend; className?: string }) {
+  const t = useTranslation();
+  const Icon = TREND_ICON[trend.direction];
+  return (
+    <div
+      className={className}
+      data-sentiment={trend.sentiment ?? DEFAULT_SENTIMENT[trend.direction]}
+    >
+      <Icon size={16} aria-hidden="true" />
+      <VisuallyHidden>{t(`dashboardWidget.${TREND_WORD[trend.direction]}`)} </VisuallyHidden>
+      <span>{trend.label}</span>
+    </div>
+  );
+}