@jcsoftdev/ui 0.0.0-stage → 0.1.1

package/src/charts/core/hierarchy-chart.tsx

@@ -0,0 +1,236 @@
+"use client";
+
+import { ChartBreadcrumb } from "./breadcrumb.js";
+import { ChartDataTable } from "./data-table.js";
+import type { ValueFormatter } from "./format.js";
+import { descendants, type HierarchyNode } from "./hierarchy.js";
+import { ChartLegend } from "./legend.js";
+import { seriesColor } from "./palette.js";
+import type { TooltipRow } from "./tooltip.js";
+import { type ChartLabels, DEFAULT_LABELS } from "./types.js";
+
+/** Visible strings of the hierarchy charts (treemap, sunburst, icicle). */
+export interface HierarchyLabels extends ChartLabels {
+  /** Accessible name of the drill-down path. */
+  breadcrumb: string;
+  /** Tooltip row: share of the focused node. */
+  share: string;
+  /** Hint shown in the tooltip of a node that can be opened. */
+  drillHint: string;
+}
+
+export const DEFAULT_HIERARCHY_LABELS: HierarchyLabels = {
+  ...DEFAULT_LABELS,
+  explore: "Chart segments. Use the arrow keys to move, Enter to open, Escape to go back.",
+  category: "Segment",
+  breadcrumb: "Drill-down path",
+  share: "Share",
+  drillHint: "Click to open",
+};
+
+export function resolveHierarchyLabels(labels?: Partial<HierarchyLabels>): HierarchyLabels {
+  return labels ? { ...DEFAULT_HIERARCHY_LABELS, ...labels } : DEFAULT_HIERARCHY_LABELS;
+}
+
+/**
+ * Base color of a node: its own `color`, otherwise the palette slot of the
+ * branch it belongs to below `focus`, so the open level always shows several hues.
+ */
+export function branchColor(node: HierarchyNode, focus: HierarchyNode): string {
+  if (node.color) return node.color;
+  let branch: HierarchyNode = node;
+  while (branch.parent && branch.parent.id !== focus.id) branch = branch.parent;
+  return seriesColor(branch.parent ? branch.index : 0);
+}
+
+/** "Miraflores › Kevin" relative to `from` (excluded). */
+export function nodePath(node: HierarchyNode, from?: HierarchyNode): string {
+  const names: string[] = [];
+  for (
+    let current: HierarchyNode | null = node;
+    current && current !== from;
+    current = current.parent
+  ) {
+    names.unshift(current.name);
+  }
+  return names.join(" › ");
+}
+
+/**
+ * Strength (0-100) of the branch hue for a partition cell (sunburst ring or
+ * icicle band): strong next to the open node, lighter further out, with a small
+ * spread between siblings so neighbours stay distinguishable.
+ */
+export function levelStrength(node: HierarchyNode, focus: HierarchyNode): number {
+  const level = Math.max(1, node.depth - focus.depth);
+  const siblings = node.parent?.children.length ?? 1;
+  const spread = siblings > 1 ? node.index / (siblings - 1) : 0;
+  return Math.max(26, 86 - (level - 1) * 24 - spread * 10);
+}
+
+/**
+ * Label that fits in `maxWidth`: the full text, a shortened one with an
+ * ellipsis, or `null` when not even four characters fit.
+ */
+export function fitLabel(text: string, maxWidth: number, fontSize = 12): string | null {
+  const charWidth = fontSize * 0.58;
+  if (text.length * charWidth <= maxWidth) return text;
+  const chars = Math.floor(maxWidth / charWidth) - 1;
+  return chars >= 4 ? `${text.slice(0, chars).trimEnd()}…` : null;
+}
+
+export function shareOf(node: HierarchyNode, of: HierarchyNode): number {
+  return of.value > 0 ? node.value / of.value : 0;
+}
+
+function percent(value: number): string {
+  return `${(value * 100).toFixed(value < 0.1 ? 1 : 0)}%`;
+}
+
+/** Spoken summary of a node for the live region and `aria-valuetext`. */
+export function describeNode(
+  node: HierarchyNode,
+  focus: HierarchyNode,
+  format: ValueFormatter,
+): string {
+  return `${nodePath(node, focus)}: ${format(node.value)} (${percent(shareOf(node, focus))})`;
+}
+
+export function nodeTooltipRows(
+  node: HierarchyNode,
+  focus: HierarchyNode,
+  format: ValueFormatter,
+  labels: HierarchyLabels,
+  color: string,
+): TooltipRow[] {
+  const rows: TooltipRow[] = [
+    { id: "value", name: node.name, value: format(node.value), color },
+    {
+      id: "share",
+      name: `${labels.share} · ${focus.name}`,
+      value: percent(shareOf(node, focus)),
+      color: "transparent",
+    },
+  ];
+  if (node.children.length > 0) {
+    rows.push({
+      id: "hint",
+      name: labels.drillHint,
+      value: `${node.children.length}`,
+      color: "transparent",
+      emphasis: true,
+    });
+  }
+  return rows;
+}
+
+/**
+ * Class for the `ChartFrame` of a hierarchy chart: makes it a size container
+ * (`@container/chart`) so the header and legend below can react to its width.
+ */
+export const HIERARCHY_FRAME_CLASS = "@container/chart";
+
+export interface HierarchyHeaderProps {
+  path: readonly HierarchyNode[];
+  onSelect: (id: string) => void;
+  labels: HierarchyLabels;
+}
+
+/**
+ * Drill-down path, pass it as the frame `legend`. Always first in the frame,
+ * even when the legend moves above the drawing.
+ */
+export function HierarchyHeader({ path, onSelect, labels }: HierarchyHeaderProps) {
+  return (
+    <ChartBreadcrumb
+      className="-order-2"
+      items={path.map((node) => ({ id: node.id, name: node.name }))}
+      onSelect={onSelect}
+      label={labels.breadcrumb}
+    />
+  );
+}
+
+export interface HierarchyLegendProps {
+  focus: HierarchyNode;
+  /** Most items listed. */
+  limit?: number;
+}
+
+/**
+ * Read-only legend of the open level's branches, pass it as the frame
+ * `footer`: below the drawing in narrow containers, above it from `@md`.
+ */
+export function HierarchyLegend({ focus, limit = 8 }: HierarchyLegendProps) {
+  if (focus.children.length === 0) return null;
+  return (
+    <ChartLegend
+      className="@md/chart:-order-1"
+      items={focus.children.slice(0, limit).map((child) => ({
+        id: child.id,
+        name: child.name,
+        color: branchColor(child, focus),
+      }))}
+    />
+  );
+}
+
+export interface HierarchyTableProps {
+  root: HierarchyNode;
+  caption: string;
+  format: ValueFormatter;
+  labels: HierarchyLabels;
+}
+
+/** Hidden table: every node below the root with its value and share of the total. */
+export function HierarchyTable({ root, caption, format, labels }: HierarchyTableProps) {
+  const nodes = descendants(root).slice(1);
+  return (
+    <ChartDataTable
+      caption={caption}
+      categoryHeader={labels.category}
+      categories={nodes.map((node) => nodePath(node, root))}
+      columns={[
+        { id: "value", name: root.name, values: nodes.map((node) => format(node.value)) },
+        {
+          id: "share",
+          name: labels.share,
+          values: nodes.map((node) => percent(shareOf(node, root))),
+        },
+      ]}
+    />
+  );
+}
+
+/**
+ * Keyboard handling shared by the hierarchy charts: arrows move between the
+ * children of the focused node, Enter opens the active one, Escape goes up.
+ * Returns the next active index, or `undefined` when the key is not handled.
+ */
+export function hierarchyKey(
+  key: string,
+  active: number | null,
+  count: number,
+): "drill" | "up" | number | undefined {
+  if (count === 0) return key === "Escape" ? "up" : undefined;
+  const current = active ?? -1;
+  switch (key) {
+    case "ArrowRight":
+    case "ArrowDown":
+      return Math.min(count - 1, current + 1);
+    case "ArrowLeft":
+    case "ArrowUp":
+      return Math.max(0, current - 1);
+    case "Home":
+      return 0;
+    case "End":
+      return count - 1;
+    case "Enter":
+    case " ":
+      return "drill";
+    case "Escape":
+      return "up";
+    default:
+      return undefined;
+  }
+}

package/src/charts/core/hierarchy.ts

@@ -0,0 +1,380 @@
+/**
+ * Hierarchy model and layouts for treemap, sunburst and icicle charts.
+ * Pure functions: no React, no DOM, so they are unit tested directly.
+ */
+
+/** Input tree. Leaves carry `value`; a parent's value is the sum of its children. */
+export interface HierarchyDatum {
+  /** Stable key among siblings; defaults to `name`. */
+  id?: string;
+  name: string;
+  value?: number;
+  /** CSS color for this branch, e.g. `var(--chart-cat-2)`. */
+  color?: string;
+  children?: readonly HierarchyDatum[];
+}
+
+export interface HierarchyNode {
+  /** Unique path id, e.g. `root/miraflores/kevin`. */
+  id: string;
+  name: string;
+  /** Leaf value, or the sum of the children. */
+  value: number;
+  /** 0 for the root. */
+  depth: number;
+  parent: HierarchyNode | null;
+  /** Positive-value children, largest first when sorted. */
+  children: HierarchyNode[];
+  /** Position of the top-level branch (depth 1) this node belongs to; -1 for the root. */
+  branch: number;
+  /** Rank among its siblings, 0 = first. */
+  index: number;
+  /** Own color, or the closest ancestor's. */
+  color?: string;
+  data: HierarchyDatum;
+}
+
+export interface BuildHierarchyOptions {
+  /** Largest first (default). `false` keeps the data order. */
+  sort?: boolean;
+}
+
+function positive(value: number | undefined): number {
+  return typeof value === "number" && Number.isFinite(value) && value > 0 ? value : 0;
+}
+
+/**
+ * Turns nested data into linked nodes with summed values. Zero, negative and
+ * non-finite branches are dropped, since they have no area to draw.
+ */
+export function buildHierarchy(
+  datum: HierarchyDatum,
+  { sort = true }: BuildHierarchyOptions = {},
+): HierarchyNode {
+  function visit(
+    item: HierarchyDatum,
+    parent: HierarchyNode | null,
+    id: string,
+    index: number,
+  ): HierarchyNode {
+    const node: HierarchyNode = {
+      id,
+      name: item.name,
+      value: 0,
+      depth: parent ? parent.depth + 1 : 0,
+      parent,
+      children: [],
+      branch: parent ? (parent.depth === 0 ? index : parent.branch) : -1,
+      index,
+      color: item.color ?? parent?.color,
+      data: item,
+    };
+    if (item.children && item.children.length > 0) {
+      const seen = new Map<string, number>();
+      const children = item.children.map((child, position) => {
+        const key = child.id ?? child.name;
+        const count = seen.get(key) ?? 0;
+        seen.set(key, count + 1);
+        return visit(child, node, `${id}/${count ? `${key}~${count}` : key}`, position);
+      });
+      const kept = children.filter((child) => child.value > 0);
+      if (sort) kept.sort((a, b) => b.value - a.value);
+      kept.forEach((child, rank) => {
+        child.index = rank;
+        if (node.depth === 0) reassignBranch(child, rank);
+      });
+      node.children = kept;
+      node.value = kept.reduce((sum, child) => sum + child.value, 0);
+    } else {
+      node.value = positive(item.value);
+    }
+    return node;
+  }
+  return visit(datum, null, datum.id ?? "root", 0);
+}
+
+function reassignBranch(node: HierarchyNode, branch: number): void {
+  node.branch = branch;
+  for (const child of node.children) reassignBranch(child, branch);
+}
+
+/** Root first, `node` last. */
+export function ancestors(node: HierarchyNode): HierarchyNode[] {
+  const path: HierarchyNode[] = [];
+  for (let current: HierarchyNode | null = node; current; current = current.parent) {
+    path.unshift(current);
+  }
+  return path;
+}
+
+/** Pre-order list: `node`, then its subtree. */
+export function descendants(node: HierarchyNode): HierarchyNode[] {
+  const out: HierarchyNode[] = [];
+  const stack = [node];
+  while (stack.length > 0) {
+    const current = stack.pop() as HierarchyNode;
+    out.push(current);
+    for (let i = current.children.length - 1; i >= 0; i--) {
+      stack.push(current.children[i] as HierarchyNode);
+    }
+  }
+  return out;
+}
+
+export function findNode(root: HierarchyNode, id: string): HierarchyNode | null {
+  return descendants(root).find((node) => node.id === id) ?? null;
+}
+
+/** Number of levels below `node` (0 for a leaf). */
+export function heightOf(node: HierarchyNode): number {
+  let height = 0;
+  for (const child of node.children) height = Math.max(height, heightOf(child) + 1);
+  return height;
+}
+
+export interface Rect {
+  x0: number;
+  y0: number;
+  x1: number;
+  y1: number;
+}
+
+/** Width / height ratio, always >= 1. Infinite for degenerate rectangles. */
+export function aspectRatio(rect: Rect): number {
+  const width = rect.x1 - rect.x0;
+  const height = rect.y1 - rect.y0;
+  if (width <= 0 || height <= 0) return Number.POSITIVE_INFINITY;
+  return Math.max(width / height, height / width);
+}
+
+/** Worst aspect ratio of a row with `sum` area along a side of length `side`. */
+function worstRatio(sum: number, min: number, max: number, side: number): number {
+  const side2 = side * side;
+  const sum2 = sum * sum;
+  return Math.max((side2 * max) / sum2, sum2 / (side2 * min));
+}
+
+/**
+ * Squarified treemap: splits `rect` into one rectangle per value, areas
+ * proportional to the values, keeping them as close to squares as possible.
+ * Rows are laid along the shorter side and grow while the worst aspect ratio
+ * of the row improves. Pass values largest first for the best result; the
+ * output keeps the input order. Zero values get an empty rectangle.
+ */
+export function squarify(values: readonly number[], rect: Rect): Rect[] {
+  const out: Rect[] = values.map(() => ({ x0: rect.x0, y0: rect.y0, x1: rect.x0, y1: rect.y0 }));
+  let { x0, y0 } = rect;
+  const { x1, y1 } = rect;
+  const order = values.map((_, index) => index).filter((index) => positive(values[index]) > 0);
+  let remaining = order.reduce((sum, index) => sum + (values[index] as number), 0);
+  let cursor = 0;
+
+  while (cursor < order.length) {
+    const width = x1 - x0;
+    const height = y1 - y0;
+    if (width <= 0 || height <= 0 || remaining <= 0) break;
+    const scale = (width * height) / remaining;
+    const side = Math.min(width, height);
+
+    let end = cursor;
+    let sum = 0;
+    let min = Number.POSITIVE_INFINITY;
+    let max = 0;
+    let worst = Number.POSITIVE_INFINITY;
+    while (end < order.length) {
+      const area = (values[order[end] as number] as number) * scale;
+      const nextSum = sum + area;
+      const nextMin = Math.min(min, area);
+      const nextMax = Math.max(max, area);
+      const nextWorst = worstRatio(nextSum, nextMin, nextMax, side);
+      if (end > cursor && nextWorst > worst) break;
+      sum = nextSum;
+      min = nextMin;
+      max = nextMax;
+      worst = nextWorst;
+      end++;
+    }
+
+    const last = end === order.length;
+    const thickness = last ? (width >= height ? width : height) : sum / side;
+    let offset = 0;
+    for (let k = cursor; k < end; k++) {
+      const index = order[k] as number;
+      const length =
+        k === end - 1 ? side - offset : ((values[index] as number) * scale) / thickness;
+      out[index] =
+        width >= height
+          ? { x0, y0: y0 + offset, x1: x0 + thickness, y1: y0 + offset + length }
+          : { x0: x0 + offset, y0, x1: x0 + offset + length, y1: y0 + thickness };
+      offset += length;
+    }
+    if (width >= height) x0 += thickness;
+    else y0 += thickness;
+    remaining -= sum / scale;
+    cursor = end;
+  }
+  return out;
+}
+
+export interface TreemapCell extends Rect {
+  node: HierarchyNode;
+  /** Depth below the laid-out root, 1 for its children. */
+  level: number;
+  /** Drawn as a group: header band on top, children inside. */
+  group: boolean;
+}
+
+export interface TreemapOptions {
+  /** Levels to draw below the root. */
+  maxDepth?: number;
+  /** Gap between siblings, in pixels. */
+  gap?: number;
+  /** Inset of a group's children from its border. */
+  padding?: number;
+  /** Header band height of a group (its name). */
+  headerHeight?: number;
+  /** A group smaller than this (either side) is drawn as a single cell. */
+  minGroupSize?: number;
+}
+
+function inset(rect: Rect, amount: number): Rect {
+  const dx = Math.min(amount, (rect.x1 - rect.x0) / 2);
+  const dy = Math.min(amount, (rect.y1 - rect.y0) / 2);
+  return { x0: rect.x0 + dx, y0: rect.y0 + dy, x1: rect.x1 - dx, y1: rect.y1 - dy };
+}
+
+/**
+ * Nested squarified layout of `root`'s subtree inside `rect`. Cells are
+ * returned parents before children, so painting in order nests correctly.
+ */
+export function treemapLayout(
+  root: HierarchyNode,
+  rect: Rect,
+  { maxDepth = 2, gap = 2, padding = 4, headerHeight = 22, minGroupSize = 64 }: TreemapOptions = {},
+): TreemapCell[] {
+  const cells: TreemapCell[] = [];
+  function place(node: HierarchyNode, area: Rect, level: number): void {
+    const rects = squarify(
+      node.children.map((child) => child.value),
+      area,
+    );
+    node.children.forEach((child, index) => {
+      const cellRect = inset(rects[index] as Rect, gap / 2);
+      const width = cellRect.x1 - cellRect.x0;
+      const height = cellRect.y1 - cellRect.y0;
+      if (width <= 0 || height <= 0) return;
+      const group =
+        child.children.length > 0 &&
+        level < maxDepth &&
+        width >= minGroupSize &&
+        height >= minGroupSize;
+      cells.push({ ...cellRect, node: child, level, group });
+      if (group) {
+        place(
+          child,
+          {
+            x0: cellRect.x0 + padding,
+            y0: cellRect.y0 + headerHeight,
+            x1: cellRect.x1 - padding,
+            y1: cellRect.y1 - padding,
+          },
+          level + 1,
+        );
+      }
+    });
+  }
+  place(root, rect, 1);
+  return cells;
+}
+
+export interface PartitionSpan {
+  /** Start and end of the node along the partitioned axis, 0-1 of the root. */
+  x0: number;
+  x1: number;
+}
+
+/**
+ * Adjacency partition: every node gets a slice of its parent's span
+ * proportional to its value. The root spans [0, 1]. Depth is the other axis
+ * (rings in a sunburst, bands in an icicle).
+ */
+export function partitionLayout(root: HierarchyNode): Map<string, PartitionSpan> {
+  const spans = new Map<string, PartitionSpan>();
+  function visit(node: HierarchyNode, x0: number, x1: number): void {
+    spans.set(node.id, { x0, x1 });
+    let start = x0;
+    const total = node.value || 1;
+    node.children.forEach((child, index) => {
+      const end =
+        index === node.children.length - 1 ? x1 : start + ((x1 - x0) * child.value) / total;
+      visit(child, start, end);
+      start = end;
+    });
+  }
+  visit(root, 0, 1);
+  return spans;
+}
+
+/** The focused window of a partition: which span fills the view and at which depth it sits. */
+export interface PartitionView {
+  x0: number;
+  x1: number;
+  depth: number;
+}
+
+/** Position of a span inside a view: x in 0-1 of the view (may fall outside), level relative to it. */
+export function projectSpan(
+  span: PartitionSpan,
+  depth: number,
+  view: PartitionView,
+): { x0: number; x1: number; level: number } {
+  const width = view.x1 - view.x0 || 1;
+  return {
+    x0: (span.x0 - view.x0) / width,
+    x1: (span.x1 - view.x0) / width,
+    level: depth - view.depth,
+  };
+}
+
+export function interpolateView(from: PartitionView, to: PartitionView, t: number): PartitionView {
+  return {
+    x0: from.x0 + (to.x0 - from.x0) * t,
+    x1: from.x1 + (to.x1 - from.x1) * t,
+    depth: from.depth + (to.depth - from.depth) * t,
+  };
+}
+
+const TAU = Math.PI * 2;
+
+/**
+ * Annular sector ("donut slice") path. Angles in radians, 0 at twelve
+ * o'clock, clockwise. `padAngle` trims both ends; a full turn draws a ring.
+ */
+export function sectorPath(
+  cx: number,
+  cy: number,
+  innerRadius: number,
+  outerRadius: number,
+  startAngle: number,
+  endAngle: number,
+  padAngle = 0,
+): string {
+  const r0 = Math.max(0, innerRadius);
+  const r1 = Math.max(r0, outerRadius);
+  const span = endAngle - startAngle;
+  if (r1 <= 0 || span <= 0) return "";
+  const point = (r: number, a: number) =>
+    `${(cx + r * Math.sin(a)).toFixed(2)},${(cy - r * Math.cos(a)).toFixed(2)}`;
+  if (span >= TAU - 1e-6) {
+    const outer = `M${point(r1, 0)}A${r1},${r1} 0 1 1 ${point(r1, Math.PI)}A${r1},${r1} 0 1 1 ${point(r1, 0)}Z`;
+    if (r0 <= 0) return outer;
+    return `${outer}M${point(r0, 0)}A${r0},${r0} 0 1 0 ${point(r0, Math.PI)}A${r0},${r0} 0 1 0 ${point(r0, 0)}Z`;
+  }
+  const pad = Math.min(padAngle, span * 0.4) / 2;
+  const a0 = startAngle + pad;
+  const a1 = endAngle - pad;
+  const large = a1 - a0 > Math.PI ? 1 : 0;
+  const outer = `M${point(r1, a0)}A${r1},${r1} 0 ${large} 1 ${point(r1, a1)}`;
+  if (r0 <= 0) return `${outer}L${point(0, 0)}Z`;
+  return `${outer}L${point(r0, a1)}A${r0},${r0} 0 ${large} 0 ${point(r0, a0)}Z`;
+}

package/src/charts/core/index.ts

@@ -0,0 +1,54 @@
+export * from "./a11y.js";
+export * from "./axes.js";
+export * from "./breadcrumb.js";
+export * from "./cartesian/axis-stack.js";
+export * from "./cartesian/brush.js";
+export * from "./cartesian/cartesian-chart.js";
+export * from "./cartesian/category-group-axis.js";
+export * from "./cartesian/category-groups.js";
+export * from "./cartesian/ink-layer.js";
+export * from "./cartesian/layout.js";
+export * from "./cartesian/sync.js";
+export * from "./cartesian/types.js";
+export * from "./category-axis.js";
+export * from "./category-explorer.js";
+export * from "./chart-frame.js";
+export * from "./chart-states.js";
+export * from "./chord.js";
+export * from "./color-scale.js";
+export * from "./data-table.js";
+export * from "./distribution/index.js";
+export * from "./downsample.js";
+export * from "./export.js";
+export * from "./export-menu.js";
+export * from "./format.js";
+export * from "./gantt.js";
+export * from "./hierarchy.js";
+export * from "./hierarchy-chart.js";
+export * from "./indicators.js";
+export * from "./ink.js";
+export * from "./legend.js";
+export * from "./motion.js";
+export * from "./palette.js";
+export * from "./path.js";
+export * from "./pattern-defs.js";
+export * from "./patterns.js";
+export * from "./plot-overlay.js";
+export * from "./polar.js";
+export * from "./sankey.js";
+export * from "./scales/index.js";
+export * from "./shape-morph.js";
+export * from "./stack.js";
+export * from "./time-range.js";
+export * from "./tooltip.js";
+export * from "./tree-layout.js";
+export * from "./tree-radial.js";
+export * from "./types.js";
+export * from "./unit-glyph.js";
+export * from "./unit-icons.js";
+export * from "./units.js";
+export * from "./use-chart-size.js";
+export * from "./use-drill.js";
+export * from "./use-index-navigation.js";
+export * from "./use-pan-zoom.js";
+export * from "./use-series-state.js";