@astryxdesign/lab 0.0.0-bootstrap.0 → 0.1.2-canary.04e71b2

package/src/Sankey/SankeyChart.tsx

@@ -0,0 +1,220 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file SankeyChart.tsx
+ * @output Root Sankey container — computes layout and provides context
+ * @position Parent component; all Sankey marks are children
+ *
+ * When columns × minColumnWidth exceeds the container, the chart
+ * scrolls horizontally rather than squishing columns together.
+ */
+
+import {
+  type ReactNode,
+  useMemo,
+  useRef,
+  useState,
+  useLayoutEffect,
+} from 'react';
+import {SankeyProvider} from './SankeyContext';
+import {computeLayout} from './layout';
+import type {SankeyNodeDatum, SankeyLinkDatum, SankeyColumn} from './types';
+
+export interface SankeyChartProps {
+  /** Node definitions */
+  nodes: SankeyNodeDatum[];
+  /** Link definitions */
+  links: SankeyLinkDatum[];
+  /**
+   * Column definitions. Accepts either:
+   * - Simple: `string[][]` — arrays of node IDs per column
+   * - Rich: `SankeyColumnDef[]` — objects with `ids`, optional `label`
+   * - Mixed: any combination
+   *
+   * If omitted, columns are auto-detected via topological sort.
+   */
+  columns?: SankeyColumn[];
+  /** Chart height in px (default: 320) */
+  height?: number;
+  /** Node bar width in px (default: 20) */
+  nodeWidth?: number;
+  /** Vertical gap between sibling nodes (default: 14) */
+  nodeGap?: number;
+  /**
+   * Override all node bar colors with a single CSS color.
+   * Both SankeyNode and SankeyLabel read this from context
+   * so labels adapt their text color for contrast.
+   */
+  nodeColor?: string;
+  /**
+   * Minimum width per column in px (default: 160).
+   * When total min width exceeds the container, horizontal scrolling activates.
+   */
+  minColumnWidth?: number;
+  /** Chart contents */
+  children: ReactNode;
+}
+
+/** Resolve column count from raw column input or auto-detect from graph */
+function resolveColumnCount(
+  columns: SankeyColumn[] | undefined,
+  nodes: SankeyNodeDatum[],
+  links: SankeyLinkDatum[],
+): number {
+  if (columns) {
+    return columns.length;
+  }
+  // Quick topological column count
+  const inDegree = new Map<string, number>();
+  const outEdges = new Map<string, string[]>();
+  nodes.forEach(n => {
+    inDegree.set(n.id, 0);
+    outEdges.set(n.id, []);
+  });
+  links.forEach(l => {
+    inDegree.set(l.target, (inDegree.get(l.target) || 0) + 1);
+    outEdges.get(l.source)?.push(l.target);
+  });
+  const colMap = new Map<string, number>();
+  const queue: string[] = [];
+  nodes.forEach(n => {
+    if (inDegree.get(n.id) === 0) {
+      queue.push(n.id);
+      colMap.set(n.id, 0);
+    }
+  });
+  while (queue.length) {
+    const id = queue.shift();
+    if (id == null) {
+      break;
+    }
+    const col = colMap.get(id) ?? 0;
+    for (const tgt of outEdges.get(id) || []) {
+      colMap.set(tgt, Math.max(colMap.get(tgt) || 0, col + 1));
+      inDegree.set(tgt, (inDegree.get(tgt) || 0) - 1);
+      if (inDegree.get(tgt) === 0) {
+        queue.push(tgt);
+      }
+    }
+  }
+  return Math.max(...Array.from(colMap.values()), 0) + 1;
+}
+
+/**
+ * Root component for Sankey/flow diagrams.
+ *
+ * Computes layout from nodes + links, exposes positions via context.
+ * Width is responsive but enforces minColumnWidth — scrolls when needed.
+ *
+ * @example
+ * ```tsx
+ * <SankeyChart
+ *   nodes={nodes}
+ *   links={links}
+ *   columns={[
+ *     {ids: ['a', 'b'], label: 'Source'},
+ *     {ids: ['c', 'd'], label: 'Target'},
+ *   ]}
+ * >
+ *   <SankeyGrid />
+ *   <SankeyLink />
+ *   <SankeyNode />
+ *   <SankeyLabel />
+ * </SankeyChart>
+ * ```
+ */
+export function SankeyChart({
+  nodes,
+  links,
+  columns,
+  height = 320,
+  nodeWidth = 20,
+  nodeGap = 14,
+  nodeColor,
+  minColumnWidth = 160,
+  children,
+}: SankeyChartProps) {
+  const containerRef = useRef<HTMLDivElement>(null);
+  const [containerWidth, setContainerWidth] = useState(0);
+
+  useLayoutEffect(() => {
+    const el = containerRef.current;
+    if (!el) {
+      return;
+    }
+    const ro = new ResizeObserver(entries => {
+      const w = entries[0]?.contentRect.width ?? 0;
+      setContainerWidth(w);
+    });
+    ro.observe(el);
+    return () => ro.disconnect();
+  }, []);
+
+  const colCount = useMemo(
+    () => resolveColumnCount(columns, nodes, links),
+    [columns, nodes, links],
+  );
+
+  const minWidth = colCount * minColumnWidth;
+  const chartWidth = Math.max(containerWidth, minWidth);
+  const needsScroll = containerWidth > 0 && chartWidth > containerWidth;
+
+  const layout = useMemo(() => {
+    if (containerWidth === 0) {
+      return null;
+    }
+    return computeLayout(nodes, links, {
+      width: chartWidth,
+      height,
+      nodeWidth,
+      nodeGap,
+      columns,
+    });
+  }, [
+    nodes,
+    links,
+    chartWidth,
+    height,
+    nodeWidth,
+    nodeGap,
+    columns,
+    containerWidth,
+  ]);
+
+  const ctx = useMemo(() => {
+    if (!layout) {
+      return null;
+    }
+    return {
+      nodes: layout.nodes,
+      links: layout.links,
+      columns: layout.columns,
+      width: chartWidth,
+      height,
+      valueScale: layout.valueScale,
+      maxValue: layout.maxValue,
+      nodeWidth,
+      nodeColor,
+    };
+  }, [layout, chartWidth, height, nodeWidth, nodeColor]);
+
+  return (
+    <div ref={containerRef} style={{width: '100%'}}>
+      {ctx && (
+        <div
+          style={
+            needsScroll ? {overflowX: 'auto', overflowY: 'hidden'} : undefined
+          }>
+          <svg
+            width={chartWidth}
+            height={height}
+            style={{overflow: 'visible', display: 'block'}}>
+            <SankeyProvider value={ctx}>{children}</SankeyProvider>
+          </svg>
+        </div>
+      )}
+    </div>
+  );
+}
+
+SankeyChart.displayName = 'SankeyChart';

package/src/Sankey/SankeyContext.ts

@@ -0,0 +1,23 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file SankeyContext.ts
+ * @output React context for sharing Sankey layout between components
+ * @position Consumed by SankeyChart (provider) and all child components (consumers)
+ */
+
+import {createContext, useContext} from 'react';
+import type {SankeyContext} from './types';
+
+const SankeyCtx = createContext<SankeyContext | null>(null);
+
+export const SankeyProvider = SankeyCtx.Provider;
+
+/** Access the sankey context. Throws if used outside <SankeyChart>. */
+export function useSankey(): SankeyContext {
+  const ctx = useContext(SankeyCtx);
+  if (!ctx) {
+    throw new Error('Sankey components must be used inside <SankeyChart>');
+  }
+  return ctx;
+}

package/src/Sankey/SankeyGrid.tsx

@@ -0,0 +1,69 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file SankeyGrid.tsx
+ * @output Dashed vertical lines at each column + optional column headers
+ * @position Visual layer — structural guide behind the flow ribbons
+ */
+
+import {useSankey} from './SankeyContext';
+
+export interface SankeyGridProps {
+  /** Dash pattern (default: "4 4") */
+  dashArray?: string;
+  /** Stroke color (default: theme border) */
+  color?: string;
+  /** Opacity (default: 0.3) */
+  opacity?: number;
+  /** Show column header labels if defined (default: true) */
+  showHeaders?: boolean;
+}
+
+/**
+ * Vertical grid lines at each column position, with optional column headers.
+ *
+ * Place before SankeyLink so grid renders behind ribbons.
+ */
+export function SankeyGrid({
+  dashArray = '4 4',
+  color,
+  opacity = 0.3,
+  showHeaders = true,
+}: SankeyGridProps) {
+  const {columns, height, nodeWidth} = useSankey();
+
+  return (
+    <g>
+      {columns.map((col, i) => (
+        <g key={i}>
+          <line
+            x1={col.x + nodeWidth / 2}
+            x2={col.x + nodeWidth / 2}
+            y1={0}
+            y2={height}
+            stroke={color || 'var(--color-border, #d0d0d8)'}
+            strokeOpacity={opacity}
+            strokeDasharray={dashArray}
+            strokeWidth={1}
+          />
+          {showHeaders && col.label && (
+            <text
+              x={col.x + nodeWidth / 2}
+              y={height - 2}
+              textAnchor="middle"
+              style={{
+                font: '500 10px/1 system-ui',
+                fill: 'var(--color-text-secondary, #6e6e80)',
+                textTransform: 'uppercase',
+                letterSpacing: '0.04em',
+              }}>
+              {col.label}
+            </text>
+          )}
+        </g>
+      ))}
+    </g>
+  );
+}
+
+SankeyGrid.displayName = 'SankeyGrid';

package/src/Sankey/SankeyLabel.tsx

@@ -0,0 +1,234 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file SankeyLabel.tsx
+ * @output Renders node labels — rotated on bar or beside it based on fit
+ * @position Visual layer — adapts placement for readability at every scale
+ *
+ * Two strategies based on available space:
+ * - Tall nodes: rotated -90° text directly on the bar (no background)
+ * - Short nodes: horizontal label beside the bar with surface pill
+ *
+ * Last-column labels anchor to the left to avoid clipping at the chart edge.
+ * Text on bars uses --color-on-dark/--color-on-light from MediaTheme.
+ */
+
+import {useSankey} from './SankeyContext';
+import type {SankeyNodeLayout} from './types';
+
+export interface SankeyLabelProps {
+  /** Show percentage below the node (default: true) */
+  showPercent?: boolean;
+  /** Format function for the value (default: compact notation) */
+  formatValue?: (value: number) => string;
+}
+
+function defaultFormat(value: number): string {
+  if (value >= 10000) {
+    return Math.round(value / 1000) + 'k';
+  }
+  if (value >= 1000) {
+    return (value / 1000).toFixed(1) + 'k';
+  }
+  return value.toLocaleString();
+}
+
+/**
+ * On-surface text color. When a CSS color override is active, parse its
+ * perceived lightness. For oklch tuples, use the L channel directly.
+ */
+function onSurfaceColor(
+  color: [number, number, number],
+  cssOverride?: string,
+): string {
+  if (cssOverride) {
+    // Quick heuristic: if the override looks dark, use on-dark
+    // Check for common dark patterns (#1, #0, rgb(0-80,...), black, etc.)
+    const c = cssOverride.toLowerCase().trim();
+    const isDark =
+      c === 'black' ||
+      /^#[0-3]/.test(c) ||
+      /^#.[0-3]/.test(c) ||
+      /^rgb\(\s*[0-7]\d?\s*,/.test(c);
+    return isDark
+      ? 'var(--color-on-dark, #fff)'
+      : 'var(--color-on-light, #000)';
+  }
+  return color[0] < 0.6
+    ? 'var(--color-on-dark, #fff)'
+    : 'var(--color-on-light, #000)';
+}
+
+export function SankeyLabel({
+  showPercent = true,
+  formatValue = defaultFormat,
+}: SankeyLabelProps) {
+  const {nodes, columns, maxValue, height, nodeWidth, nodeColor} = useSankey();
+  const lastColumn = columns.length - 1;
+
+  return (
+    <g>
+      {nodes.map(node => {
+        const pct = (node.value / maxValue) * 100;
+        const pctStr = pct >= 10 ? Math.round(pct) + '%' : pct.toFixed(1) + '%';
+        const formatted = formatValue(node.value);
+        const text = `${node.label} = ${formatted}`;
+
+        const textWidth = text.length * 6.5;
+        const fitsRotated = node.height >= textWidth + 8;
+
+        if (fitsRotated) {
+          return (
+            <RotatedLabel
+              key={node.id}
+              node={node}
+              nodeWidth={nodeWidth}
+              nodeColor={nodeColor}
+              text={text}
+              pctStr={pctStr}
+              showPercent={showPercent}
+              height={height}
+            />
+          );
+        }
+
+        return (
+          <BesideLabel
+            key={node.id}
+            node={node}
+            nodeWidth={nodeWidth}
+            text={text}
+            pctStr={pctStr}
+            showPercent={showPercent}
+            height={height}
+            isLastColumn={node.column === lastColumn}
+          />
+        );
+      })}
+    </g>
+  );
+}
+
+/** Tall bars: rotated text directly on the bar, no background */
+function RotatedLabel({
+  node,
+  nodeWidth,
+  nodeColor,
+  text,
+  pctStr,
+  showPercent,
+  height,
+}: {
+  node: SankeyNodeLayout;
+  nodeWidth: number;
+  nodeColor?: string;
+  text: string;
+  pctStr: string;
+  showPercent: boolean;
+  height: number;
+}) {
+  const cx = node.x + nodeWidth / 2;
+  const cy = node.y + node.height / 2;
+
+  return (
+    <g>
+      <g transform={`translate(${cx}, ${cy}) rotate(-90)`}>
+        <text
+          x={0}
+          y={0}
+          textAnchor="middle"
+          dominantBaseline="central"
+          style={{
+            font: '600 10px/1 system-ui',
+            fill: onSurfaceColor(node.color, nodeColor),
+            letterSpacing: '-0.01em',
+          }}>
+          {text}
+        </text>
+      </g>
+      {showPercent && node.column > 0 && (
+        <text
+          x={cx}
+          y={Math.min(height - 2, node.y + node.height + 12)}
+          textAnchor="middle"
+          style={{
+            font: '500 9px/1 system-ui',
+            fill: 'var(--color-text-tertiary, #8e8ea0)',
+          }}>
+          {pctStr}
+        </text>
+      )}
+    </g>
+  );
+}
+
+/**
+ * Short bars: label beside the node with surface pill.
+ * Last column labels go to the left to avoid clipping.
+ */
+function BesideLabel({
+  node,
+  nodeWidth,
+  text,
+  pctStr,
+  showPercent,
+  height,
+  isLastColumn,
+}: {
+  node: SankeyNodeLayout;
+  nodeWidth: number;
+  text: string;
+  pctStr: string;
+  showPercent: boolean;
+  height: number;
+  isLastColumn: boolean;
+}) {
+  const cx = node.x + nodeWidth / 2;
+  const cy = node.y + node.height / 2;
+  const pillW = text.length * 6 + 10;
+  const pillH = 16;
+
+  const labelX = isLastColumn ? node.x - 6 : node.x + nodeWidth + 6;
+  const pillX = isLastColumn ? labelX - pillW + 4 : labelX - 4;
+  const textAnchor = isLastColumn ? 'end' : 'start';
+
+  return (
+    <g>
+      <rect
+        x={pillX}
+        y={cy - pillH / 2}
+        width={pillW}
+        height={pillH}
+        rx={3}
+        fill="var(--color-background-surface, #fff)"
+        fillOpacity={0.9}
+      />
+      <text
+        x={labelX}
+        y={cy}
+        textAnchor={textAnchor}
+        dominantBaseline="central"
+        style={{
+          font: '600 10px/1 system-ui',
+          fill: 'var(--color-text-primary, #1c1c1e)',
+          letterSpacing: '-0.01em',
+        }}>
+        {text}
+      </text>
+      {showPercent && node.column > 0 && (
+        <text
+          x={cx}
+          y={Math.min(height - 2, node.y + node.height + 12)}
+          textAnchor="middle"
+          style={{
+            font: '500 9px/1 system-ui',
+            fill: 'var(--color-text-tertiary, #8e8ea0)',
+          }}>
+          {pctStr}
+        </text>
+      )}
+    </g>
+  );
+}
+
+SankeyLabel.displayName = 'SankeyLabel';

package/src/Sankey/SankeyLink.tsx

@@ -0,0 +1,167 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file SankeyLink.tsx
+ * @output Renders flow ribbons with configurable color modes
+ * @position Visual layer — the colorful flowing areas between nodes
+ *
+ * Color modes: flat CSS string, 'source', 'target', 'gradient',
+ * or {gradient: bias} for leaned transitions.
+ */
+
+import {useSankey} from './SankeyContext';
+import type {SankeyLinkLayout} from './types';
+
+/**
+ * Link color mode:
+ * - `'gradient'` — even transition from source to target color
+ * - `'source'` — each link uses its source node's color
+ * - `'target'` — each link uses its target node's color
+ * - `{gradient: number}` — biased gradient (0–1). 0.2 = source-leaned, 0.8 = target-leaned
+ * - `string` — any CSS color for flat uniform fill
+ */
+export type SankeyLinkColor =
+  | 'gradient'
+  | 'source'
+  | 'target'
+  | {gradient: number}
+  | (string & {});
+
+export interface SankeyLinkProps {
+  /** Link coloring mode (default: 'gradient') */
+  color?: SankeyLinkColor;
+  /** Opacity of the link fills (default: 0.7) */
+  opacity?: number;
+  /** Bezier tension — 0 is straight, 1 is maximum curve (default: 0.5) */
+  tension?: number;
+}
+
+function oklch(c: [number, number, number], alpha: number): string {
+  return `oklch(${c[0]} ${c[1]} ${c[2]} / ${alpha})`;
+}
+
+type ResolvedMode =
+  | {type: 'flat'; value: string}
+  | {type: 'source'}
+  | {type: 'target'}
+  | {type: 'gradient'; bias: number};
+
+function resolveColor(color: SankeyLinkColor): ResolvedMode {
+  if (typeof color === 'object' && 'gradient' in color) {
+    return {type: 'gradient', bias: color.gradient};
+  }
+  if (color === 'gradient') {
+    return {type: 'gradient', bias: 0.5};
+  }
+  if (color === 'source') {
+    return {type: 'source'};
+  }
+  if (color === 'target') {
+    return {type: 'target'};
+  }
+  return {type: 'flat', value: color};
+}
+
+/**
+ * Renders all link ribbons in the Sankey chart.
+ *
+ * Place before SankeyNode so nodes render on top.
+ */
+export function SankeyLink({
+  color = 'gradient',
+  opacity = 0.7,
+  tension = 0.5,
+}: SankeyLinkProps) {
+  const {links} = useSankey();
+  const mode = resolveColor(color);
+
+  return (
+    <g>
+      {mode.type === 'gradient' && (
+        <defs>
+          {links.map((link, i) => (
+            <GradientDef
+              key={i}
+              index={i}
+              link={link}
+              opacity={opacity}
+              bias={mode.bias}
+            />
+          ))}
+        </defs>
+      )}
+      {links.map((link, i) => {
+        const sx = link.source.x + link.source.width;
+        const tx = link.target.x;
+        const sy = link.sourceY;
+        const ty = link.targetY;
+        const lh = link.height;
+        const dx = (tx - sx) * tension;
+
+        const d = [
+          `M${sx},${sy}`,
+          `C${sx + dx},${sy} ${tx - dx},${ty} ${tx},${ty}`,
+          `L${tx},${ty + lh}`,
+          `C${tx - dx},${ty + lh} ${sx + dx},${sy + lh} ${sx},${sy + lh}`,
+          'Z',
+        ].join(' ');
+
+        let fill: string;
+        let pathOpacity: number | undefined;
+        if (mode.type === 'flat') {
+          fill = mode.value;
+          pathOpacity = opacity;
+        } else if (mode.type === 'source') {
+          fill = oklch(link.source.color, opacity);
+        } else if (mode.type === 'target') {
+          fill = oklch(link.target.color, opacity);
+        } else {
+          fill = `url(#astryx-sankey-grad-${i})`;
+        }
+
+        return <path key={i} d={d} fill={fill} opacity={pathOpacity} />;
+      })}
+    </g>
+  );
+}
+
+/** Gradient definition with bias-adjusted stops */
+function GradientDef({
+  index,
+  link,
+  opacity,
+  bias,
+}: {
+  index: number;
+  link: SankeyLinkLayout;
+  opacity: number;
+  bias: number;
+}) {
+  const sx = link.source.x + link.source.width;
+  const tx = link.target.x;
+  const s1 = Math.max(0, bias - 0.15);
+  const s2 = Math.min(1, bias + 0.15);
+
+  return (
+    <linearGradient
+      id={`astryx-sankey-grad-${index}`}
+      x1={sx}
+      x2={tx}
+      y1={0}
+      y2={0}
+      gradientUnits="userSpaceOnUse">
+      <stop offset="0%" stopColor={oklch(link.source.color, opacity)} />
+      <stop
+        offset={`${s1 * 100}%`}
+        stopColor={oklch(link.source.color, opacity * 0.9)}
+      />
+      <stop
+        offset={`${s2 * 100}%`}
+        stopColor={oklch(link.target.color, opacity * 0.9)}
+      />
+      <stop offset="100%" stopColor={oklch(link.target.color, opacity)} />
+    </linearGradient>
+  );
+}
+
+SankeyLink.displayName = 'SankeyLink';