@jcsoftdev/ui 0.0.0-stage → 0.1.0

package/dist/charts/core/tooltip.js

@@ -0,0 +1,83 @@
+"use client";
+import { jsx, jsxs } from "react/jsx-runtime";
+import { useRef, useState } from "react";
+import { cn } from "../../utils/cn.js";
+import { useIsomorphicLayoutEffect } from "./use-chart-size.js";
+const OFFSET = 14;
+const EDGE = 4;
+function ChartTooltip({
+  x,
+  y,
+  containerWidth,
+  title,
+  rows,
+  body,
+  side,
+  className
+}) {
+  const ref = useRef(null);
+  const [size, setSize] = useState(0);
+  useIsomorphicLayoutEffect(() => {
+    const next = ref.current?.offsetWidth ?? 0;
+    if (Math.abs(next - size) > 0.5) setSize(next);
+  });
+  const left = tooltipLeft(x, size, containerWidth, side);
+  return /* @__PURE__ */ jsxs(
+    "div",
+    {
+      ref,
+      "aria-hidden": "true",
+      className: cn(
+        "pointer-events-none absolute top-0 left-0 z-10 min-w-[120px] rounded-popover surface-overlay px-3 py-2.5 text-[12px] shadow-overlay",
+        "motion-safe:transition-transform motion-safe:duration-100 motion-safe:ease-out",
+        className
+      ),
+      style: {
+        maxWidth: Math.max(120, Math.min(260, containerWidth - EDGE * 2)),
+        transform: `translate3d(${Math.round(left)}px, ${Math.round(y)}px, 0) translateY(-50%)`
+      },
+      children: [
+        title ? /* @__PURE__ */ jsx("div", { className: "mb-1.5 font-bold text-[12px] text-ink", children: title }) : null,
+        body ? /* @__PURE__ */ jsx("div", { className: "text-ink-2 leading-snug", children: body }) : null,
+        /* @__PURE__ */ jsx("div", { className: "flex flex-col gap-1", children: rows.map((row) => /* @__PURE__ */ jsxs(
+          "div",
+          {
+            className: cn(
+              "flex items-center gap-2 text-ink-2",
+              row.emphasis && "mt-0.5 border-t-divider pt-1.5 text-ink"
+            ),
+            children: [
+              row.emphasis ? /* @__PURE__ */ jsx("span", { className: "w-2.5 shrink-0" }) : /* @__PURE__ */ jsx(
+                "span",
+                {
+                  className: cn(
+                    "size-2.5 shrink-0",
+                    row.shape === "line" || row.shape === "dashed" || row.shape === "dot" ? "rounded-pill" : "rounded-[3px]"
+                  ),
+                  style: { background: row.color }
+                }
+              ),
+              /* @__PURE__ */ jsx("span", { className: "min-w-0 flex-1 truncate", children: row.name }),
+              /* @__PURE__ */ jsx("span", { className: "font-bold text-ink tabular-nums", children: row.value }),
+              row.note ? /* @__PURE__ */ jsx("span", { className: "text-ink-3 tabular-nums", children: row.note }) : null
+            ]
+          },
+          row.id
+        )) })
+      ]
+    }
+  );
+}
+function tooltipLeft(x, width, containerWidth, side) {
+  const right = x + OFFSET;
+  const leftSide = x - OFFSET - width;
+  const preferLeft = side ? side === "left" : x > containerWidth * 0.6;
+  const fitsRight = right + width <= containerWidth - EDGE;
+  const fitsLeft = leftSide >= EDGE;
+  const chosen = preferLeft && fitsLeft ? leftSide : fitsRight ? right : fitsLeft ? leftSide : right;
+  return Math.max(EDGE, Math.min(chosen, containerWidth - width - EDGE));
+}
+export {
+  ChartTooltip,
+  tooltipLeft
+};

package/dist/charts/core/tree-fit.d.ts

@@ -0,0 +1,29 @@
+import type { TreeDirection, TreeLayout } from "./tree-layout.js";
+import type { PanZoomView } from "./use-pan-zoom.js";
+/** `contain` shows the whole tree, `readable` keeps cards legible and puts the root in view. */
+export type TreeFitMode = "contain" | "readable";
+export interface TreeFitOptions {
+    /** Pixels reserved at the top (the zoom toolbar). */
+    inset?: number;
+    padding?: number;
+    /** `auto` falls back to `readable` when `contain` would scale below `minReadable`. */
+    mode?: TreeFitMode | "auto";
+    /** Smallest scale at which a fitted tree still counts as legible. */
+    minReadable?: number;
+    /** Scale range of the `readable` view. */
+    readableMin?: number;
+    readableMax?: number;
+    minZoom?: number;
+    /** Centre the root in the `readable` view (radial layouts), instead of pinning it to an edge. */
+    centerRoot?: boolean;
+}
+/**
+ * Initial view of a laid out tree in a `width` x `height` viewport. `contain` scales the whole
+ * tree to fit (never past 1). `readable` ignores the width: it fits by height within
+ * `[readableMin, readableMax]` and puts the root at its edge (centred across, never above the `inset` band), so the
+ * rest is a pan away. `auto` picks `contain` unless it would drop below `minReadable`.
+ */
+export declare function treeFitView(layout: Pick<TreeLayout, "nodes" | "width" | "height">, width: number, height: number, direction: TreeDirection, { inset, padding, mode, minReadable, readableMin, readableMax, minZoom, centerRoot, }?: TreeFitOptions): {
+    view: PanZoomView;
+    mode: TreeFitMode;
+};

package/dist/charts/core/tree-fit.js

@@ -0,0 +1,53 @@
+function clamp(value, min, max) {
+  return Math.min(max, Math.max(min, value));
+}
+function treeFitView(layout, width, height, direction, {
+  inset = 0,
+  padding = 16,
+  mode = "auto",
+  minReadable = 0.6,
+  readableMin = 0.85,
+  readableMax = 1,
+  minZoom = 0.05,
+  centerRoot = false
+} = {}) {
+  const areaHeight = Math.max(1, height - inset);
+  const containK = Math.max(
+    minZoom,
+    Math.min(
+      (width - padding * 2) / Math.max(1, layout.width),
+      (areaHeight - padding * 2) / Math.max(1, layout.height),
+      1
+    )
+  );
+  const root = layout.nodes[0];
+  if (!root || mode === "contain" || mode === "auto" && containK >= minReadable) {
+    return {
+      mode: "contain",
+      view: {
+        k: containK,
+        x: (width - layout.width * containK) / 2,
+        y: inset + (areaHeight - layout.height * containK) / 2
+      }
+    };
+  }
+  const k = clamp(
+    (areaHeight - padding * 2) / Math.max(1, layout.height),
+    readableMin,
+    readableMax
+  );
+  let x = width / 2 - root.x * k;
+  let y = inset + areaHeight / 2 - root.y * k;
+  if (centerRoot) {
+  } else if (direction === "top") y = inset + padding - (root.y - root.height / 2) * k;
+  else if (direction === "bottom") y = height - padding - (root.y + root.height / 2) * k;
+  else {
+    x = direction === "left" ? padding - (root.x - root.width / 2) * k : width - padding - (root.x + root.width / 2) * k;
+    const top = Math.min(...layout.nodes.map((node) => node.y - node.height / 2));
+    y = Math.max(y, inset + padding - top * k);
+  }
+  return { mode: "readable", view: { k, x, y } };
+}
+export {
+  treeFitView
+};

package/dist/charts/core/tree-layout.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Tidy tree layout for org charts and other node-link hierarchies.
+ * Pure functions: no React, no DOM, unit tested in `test/charts-graph.test.mjs`.
+ *
+ * The layout works in a local frame where `breadth` runs across siblings and
+ * `depth` runs from the root to the leaves, then maps that frame onto one of
+ * four directions. Subtrees are packed with contours (Reingold–Tilford): each
+ * subtree keeps, per level, the extent it occupies across the breadth axis,
+ * and the next sibling is pushed just far enough that no level overlaps.
+ * Siblings are packed once from the left and once from the right and the two
+ * placements are averaged, so small subtrees between large ones are spread
+ * evenly (the symmetry Walker's algorithm achieves) and every gap still holds.
+ */
+/** Where the root sits: `top` grows downwards, `left` grows to the right. */
+export type TreeDirection = "top" | "bottom" | "left" | "right";
+/** Input of the layout: a node box and the children that are visible. */
+export interface TreeLayoutInput {
+    id: string;
+    /** Box size on screen, in pixels. */
+    width: number;
+    height: number;
+    children?: readonly TreeLayoutInput[];
+}
+export interface TreeLayoutOptions {
+    direction?: TreeDirection;
+    /** Minimum gap between neighbouring boxes on the same level. */
+    siblingGap?: number;
+    /** Gap between levels (from the far side of a level to the near side of the next). */
+    levelGap?: number;
+}
+export interface TreeLayoutNode {
+    id: string;
+    parentId: string | null;
+    depth: number;
+    /** Centre of the box, in pixels; the bounds start at 0, 0. */
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    /** Radial layouts: angle in radians, 0 at twelve o'clock, clockwise. */
+    angle?: number;
+}
+export interface TreeLayout {
+    /** Pre-order: parents before their children, siblings in input order. */
+    nodes: TreeLayoutNode[];
+    /** Size of the whole drawing. */
+    width: number;
+    height: number;
+    /** Radial layouts: the root's centre, where the rings are centred. */
+    center?: {
+        x: number;
+        y: number;
+    };
+}
+/**
+ * Tidy layout of a tree: parents centred over their children, no two boxes
+ * on the same level closer than `siblingGap`, levels `levelGap` apart. Boxes
+ * of one level share the same depth band (the tallest box of the level).
+ */
+export declare function treeLayout(root: TreeLayoutInput, options?: TreeLayoutOptions): TreeLayout;
+/** Edge drawing style between a parent and a child. */
+export type TreeEdgeStyle = "curved" | "step" | "straight";
+type Box = Pick<TreeLayoutNode, "x" | "y" | "width" | "height">;
+/**
+ * SVG path from a parent box to a child box. `curved` is a cubic S-curve,
+ * `step` an orthogonal elbow with rounded corners (`radius`), `straight` a line.
+ */
+export declare function treeEdgePath(parent: Box, child: Box, direction: TreeDirection, style?: TreeEdgeStyle, radius?: number): string;
+/** Ids from the root down to `id` (inclusive), following `parentId`. */
+export declare function treePathToRoot(nodes: readonly Pick<TreeLayoutNode, "id" | "parentId">[], id: string): string[];
+/** What an arrow key means in a given direction. */
+export type TreeMove = "parent" | "child" | "previous" | "next";
+/**
+ * Maps an arrow key to a tree move relative to the drawing: in a top-down
+ * chart Down goes to the first child and Right to the next sibling; in a
+ * left-to-right chart Right goes to the child and Down to the next sibling.
+ */
+export declare function treeKeyMove(key: string, direction: TreeDirection): TreeMove | null;
+/**
+ * Node reached from `id` by `move` among the laid-out (visible) nodes.
+ * Siblings stop at the ends; `child` goes to the middle child, which sits
+ * right under the parent. Returns `id` itself when there is nowhere to go.
+ */
+export declare function treeNeighbor(nodes: readonly Pick<TreeLayoutNode, "id" | "parentId">[], id: string, move: TreeMove): string;
+export {};

package/dist/charts/core/tree-layout.js

@@ -0,0 +1,237 @@
+function isVertical(direction) {
+  return direction === "top" || direction === "bottom";
+}
+function place(input, depth, vertical) {
+  return {
+    input,
+    depth,
+    breadth: vertical ? input.width : input.height,
+    along: vertical ? input.height : input.width,
+    offset: 0,
+    children: (input.children ?? []).map((child) => place(child, depth + 1, vertical)),
+    contour: []
+  };
+}
+function clearRight(placed, next, gap) {
+  let offset = Number.NEGATIVE_INFINITY;
+  const levels = Math.min(placed.length, next.length);
+  for (let level = 0; level < levels; level++) {
+    offset = Math.max(
+      offset,
+      placed[level][1] - next[level][0] + gap
+    );
+  }
+  return offset;
+}
+function clearLeft(placed, next, gap) {
+  let offset = Number.POSITIVE_INFINITY;
+  const levels = Math.min(placed.length, next.length);
+  for (let level = 0; level < levels; level++) {
+    offset = Math.min(
+      offset,
+      placed[level][0] - next[level][1] - gap
+    );
+  }
+  return offset;
+}
+function mergeContour(into, contour, offset) {
+  contour.forEach(([min, max], level) => {
+    const current = into[level];
+    if (current) {
+      current[0] = Math.min(current[0], min + offset);
+      current[1] = Math.max(current[1], max + offset);
+    } else {
+      into[level] = [min + offset, max + offset];
+    }
+  });
+}
+function pack(children, gap, reverse) {
+  const offsets = new Array(children.length).fill(0);
+  const order = children.map((_, index) => index);
+  if (reverse) order.reverse();
+  const placed = [];
+  order.forEach((index, position) => {
+    const child = children[index];
+    const offset = position === 0 ? 0 : reverse ? clearLeft(placed, child.contour, gap) : clearRight(placed, child.contour, gap);
+    offsets[index] = offset;
+    mergeContour(placed, child.contour, offset);
+  });
+  return offsets;
+}
+function arrange(node, gap) {
+  for (const child of node.children) arrange(child, gap);
+  const half = node.breadth / 2;
+  node.contour = [[-half, half]];
+  if (node.children.length === 0) return;
+  const fromLeft = pack(node.children, gap, false);
+  const fromRight = pack(node.children, gap, true);
+  const shiftLeft = fromLeft[0];
+  const shiftRight = fromRight[0];
+  const offsets = fromLeft.map(
+    (value, index) => (value - shiftLeft + (fromRight[index] - shiftRight)) / 2
+  );
+  const first = offsets[0];
+  const last = offsets[offsets.length - 1];
+  const centre = (first + last) / 2;
+  const below = [];
+  node.children.forEach((child, index) => {
+    child.offset = offsets[index] - centre;
+    mergeContour(below, child.contour, child.offset);
+  });
+  node.contour.push(...below);
+}
+function treeLayout(root, options = {}) {
+  const { direction = "top", siblingGap = 20, levelGap = 48 } = options;
+  const vertical = isVertical(direction);
+  const tree = place(root, 0, vertical);
+  arrange(tree, siblingGap);
+  const all = [];
+  const levelSize = [];
+  const visit = (node, centre, parentId) => {
+    all.push({ node, centre, parentId });
+    levelSize[node.depth] = Math.max(levelSize[node.depth] ?? 0, node.along);
+    for (const child of node.children) visit(child, centre + child.offset, node.input.id);
+  };
+  visit(tree, 0, null);
+  const levelStart = [0];
+  for (let level = 1; level < levelSize.length; level++) {
+    levelStart[level] = levelStart[level - 1] + levelSize[level - 1] + levelGap;
+  }
+  const nodes = all.map(({ node, centre, parentId }) => {
+    const band = levelSize[node.depth];
+    const along = levelStart[node.depth] + band / 2;
+    const flip = direction === "bottom" || direction === "right" ? -1 : 1;
+    return {
+      id: node.input.id,
+      parentId,
+      depth: node.depth,
+      x: vertical ? centre : along * flip,
+      y: vertical ? along * flip : centre,
+      width: node.input.width,
+      height: node.input.height
+    };
+  });
+  let minX = Number.POSITIVE_INFINITY;
+  let minY = Number.POSITIVE_INFINITY;
+  let maxX = Number.NEGATIVE_INFINITY;
+  let maxY = Number.NEGATIVE_INFINITY;
+  for (const node of nodes) {
+    minX = Math.min(minX, node.x - node.width / 2);
+    maxX = Math.max(maxX, node.x + node.width / 2);
+    minY = Math.min(minY, node.y - node.height / 2);
+    maxY = Math.max(maxY, node.y + node.height / 2);
+  }
+  for (const node of nodes) {
+    node.x -= minX;
+    node.y -= minY;
+  }
+  return { nodes, width: maxX - minX, height: maxY - minY };
+}
+function anchor(box, direction, far) {
+  const sign = far ? 1 : -1;
+  switch (direction) {
+    case "top":
+      return [box.x, box.y + sign * box.height / 2];
+    case "bottom":
+      return [box.x, box.y - sign * box.height / 2];
+    case "left":
+      return [box.x + sign * box.width / 2, box.y];
+    default:
+      return [box.x - sign * box.width / 2, box.y];
+  }
+}
+function treeEdgePath(parent, child, direction, style = "curved", radius = 8) {
+  const [x0, y0] = anchor(parent, direction, true);
+  const [x1, y1] = anchor(child, direction, false);
+  const r = (n) => Math.round(n * 100) / 100;
+  if (style === "straight") return `M${r(x0)},${r(y0)}L${r(x1)},${r(y1)}`;
+  const vertical = isVertical(direction);
+  if (style === "curved") {
+    if (vertical) {
+      const mid3 = (y0 + y1) / 2;
+      return `M${r(x0)},${r(y0)}C${r(x0)},${r(mid3)} ${r(x1)},${r(mid3)} ${r(x1)},${r(y1)}`;
+    }
+    const mid2 = (x0 + x1) / 2;
+    return `M${r(x0)},${r(y0)}C${r(mid2)},${r(y0)} ${r(mid2)},${r(y1)} ${r(x1)},${r(y1)}`;
+  }
+  if (vertical) {
+    const mid2 = (y0 + y1) / 2;
+    const across2 = x1 - x0;
+    const turn2 = Math.min(radius, Math.abs(across2) / 2, Math.abs(mid2 - y0));
+    if (turn2 < 0.5) return `M${r(x0)},${r(y0)}V${r(mid2)}H${r(x1)}V${r(y1)}`;
+    const sx2 = Math.sign(across2);
+    const sy2 = Math.sign(y1 - y0);
+    return [
+      `M${r(x0)},${r(y0)}`,
+      `V${r(mid2 - sy2 * turn2)}`,
+      `Q${r(x0)},${r(mid2)} ${r(x0 + sx2 * turn2)},${r(mid2)}`,
+      `H${r(x1 - sx2 * turn2)}`,
+      `Q${r(x1)},${r(mid2)} ${r(x1)},${r(mid2 + sy2 * turn2)}`,
+      `V${r(y1)}`
+    ].join("");
+  }
+  const mid = (x0 + x1) / 2;
+  const across = y1 - y0;
+  const turn = Math.min(radius, Math.abs(across) / 2, Math.abs(mid - x0));
+  if (turn < 0.5) return `M${r(x0)},${r(y0)}H${r(mid)}V${r(y1)}H${r(x1)}`;
+  const sy = Math.sign(across);
+  const sx = Math.sign(x1 - x0);
+  return [
+    `M${r(x0)},${r(y0)}`,
+    `H${r(mid - sx * turn)}`,
+    `Q${r(mid)},${r(y0)} ${r(mid)},${r(y0 + sy * turn)}`,
+    `V${r(y1 - sy * turn)}`,
+    `Q${r(mid)},${r(y1)} ${r(mid + sx * turn)},${r(y1)}`,
+    `H${r(x1)}`
+  ].join("");
+}
+function treePathToRoot(nodes, id) {
+  const byId = new Map(nodes.map((node) => [node.id, node]));
+  const path = [];
+  for (let current = byId.get(id); current; ) {
+    path.unshift(current.id);
+    current = current.parentId != null ? byId.get(current.parentId) : void 0;
+  }
+  return path;
+}
+function treeKeyMove(key, direction) {
+  const towardsChild = {
+    top: "ArrowDown",
+    bottom: "ArrowUp",
+    left: "ArrowRight",
+    right: "ArrowLeft"
+  };
+  const towardsParent = {
+    top: "ArrowUp",
+    bottom: "ArrowDown",
+    left: "ArrowLeft",
+    right: "ArrowRight"
+  };
+  if (key === towardsChild[direction]) return "child";
+  if (key === towardsParent[direction]) return "parent";
+  const vertical = isVertical(direction);
+  if (key === (vertical ? "ArrowRight" : "ArrowDown")) return "next";
+  if (key === (vertical ? "ArrowLeft" : "ArrowUp")) return "previous";
+  return null;
+}
+function treeNeighbor(nodes, id, move) {
+  const current = nodes.find((node) => node.id === id);
+  if (!current) return id;
+  if (move === "parent") return current.parentId ?? id;
+  if (move === "child") {
+    const children = nodes.filter((node) => node.parentId === id);
+    return children[Math.floor((children.length - 1) / 2)]?.id ?? id;
+  }
+  if (current.parentId == null) return id;
+  const siblings = nodes.filter((node) => node.parentId === current.parentId);
+  const index = siblings.findIndex((node) => node.id === id);
+  const next = siblings[index + (move === "next" ? 1 : -1)];
+  return next?.id ?? id;
+}
+export {
+  treeEdgePath,
+  treeKeyMove,
+  treeLayout,
+  treeNeighbor,
+  treePathToRoot
+};

package/dist/charts/core/tree-radial.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Alternative tree layouts: radial (depth = distance from the centre) and
+ * dendrogram (every leaf on the last level). Pure functions that return the
+ * same `TreeLayout` as `treeLayout`, so the chart draws them with the same
+ * boxes, transitions and edge paths.
+ */
+import type { TreeDirection, TreeEdgeStyle, TreeLayout, TreeLayoutInput, TreeLayoutOptions } from "./tree-layout.js";
+export interface RadialLayoutOptions {
+    /** Minimum distance between rings (centre to centre). */
+    levelGap?: number;
+    /** Minimum gap between neighbouring boxes on one ring. */
+    siblingGap?: number;
+    /** Angle where the first leaf starts, radians, 0 at twelve o'clock clockwise. */
+    startAngle?: number;
+    /** Angular span in radians; a full circle by default. */
+    sweep?: number;
+}
+/**
+ * Radial tidy tree: the root sits in the centre, each level on its own ring,
+ * leaves share the angle evenly and every parent points at the middle of its
+ * leaves. Rings are pushed outwards until the boxes of a ring fit side by side.
+ */
+export declare function radialTreeLayout(root: TreeLayoutInput, { levelGap, siblingGap, startAngle, sweep }?: RadialLayoutOptions): TreeLayout;
+/**
+ * Dendrogram (cluster layout): like the tidy tree, but every leaf is drawn on
+ * the last level, so the leaves line up and the branches read as a hierarchy
+ * of groupings. Internal nodes are centred over their first and last child.
+ */
+export declare function dendrogramLayout(root: TreeLayoutInput, { direction, siblingGap, levelGap }?: TreeLayoutOptions): TreeLayout;
+/** Angle (0 at twelve o'clock, clockwise) and distance of a point around `center`. */
+export declare function toPolar(point: {
+    x: number;
+    y: number;
+}, center: {
+    x: number;
+    y: number;
+}): {
+    angle: number;
+    radius: number;
+};
+/**
+ * Edge between two points of a radial layout. `curved` bends smoothly from the
+ * parent's ring to the child's, `step` leaves radially, runs along the middle
+ * ring and enters radially, `straight` is a line.
+ */
+export declare function radialEdgePath(parent: {
+    x: number;
+    y: number;
+}, child: {
+    x: number;
+    y: number;
+}, center: {
+    x: number;
+    y: number;
+}, style?: TreeEdgeStyle): string;
+/** Layout kinds the tree chart can draw. */
+export type TreeLayoutKind = "tidy" | "radial" | "dendrogram";
+/** Re-exported so callers can type a direction next to a layout kind. */
+export type { TreeDirection };