@jcsoftdev/ui 0.0.0-stage → 0.1.0

package/src/charts/tree-chart/tree-model.ts

@@ -0,0 +1,217 @@
+import { seriesColor } from "../core/palette.js";
+import type { TreeLayoutInput } from "../core/tree-layout.js";
+
+/** One person (or unit) of the tree. */
+export interface TreeChartDatum {
+  /** Stable key among siblings; defaults to `name`. */
+  id?: string;
+  name: string;
+  /** Second line of the default card, e.g. the role. */
+  subtitle?: string;
+  /** Short pill on the default card, e.g. a branch or a count. */
+  badge?: string;
+  /** Avatar image URL; initials are shown without it. */
+  image?: string;
+  /** CSS color of this node and its subtree; defaults to a palette slot per top-level branch. */
+  color?: string;
+  /** Start with this node's children hidden. */
+  collapsed?: boolean;
+  /** Children are fetched on first expand through the chart's `loadChildren`. */
+  lazy?: boolean;
+  /** Known number of children of a `lazy` node, shown on its toggle before they load. */
+  childCount?: number;
+  /** A synthetic node standing for several leaves (see `groupLeaves`). */
+  group?: boolean;
+  children?: readonly TreeChartDatum[];
+}
+
+export interface TreeChartNode {
+  /** Unique path id, e.g. `root/miraflores/kevin`. */
+  id: string;
+  name: string;
+  subtitle?: string;
+  badge?: string;
+  image?: string;
+  /** Resolved color (own, inherited or the branch palette slot). */
+  color: string;
+  /** 0 for the root. */
+  depth: number;
+  parent: TreeChartNode | null;
+  children: TreeChartNode[];
+  /** Rank among its siblings. */
+  index: number;
+  /** Children not loaded yet. */
+  lazy: boolean;
+  /** Stands for a group of leaves. */
+  group: boolean;
+  data: TreeChartDatum;
+}
+
+export interface TreeModel {
+  root: TreeChartNode;
+  /** Pre-order list of every node, hidden ones included. */
+  nodes: TreeChartNode[];
+  byId: Map<string, TreeChartNode>;
+}
+
+/**
+ * Builds the node model. `loaded` holds children fetched lazily, keyed by the
+ * node's path id; they take the place of an empty `children`.
+ */
+export function buildTreeModel(
+  data: TreeChartDatum,
+  loaded: ReadonlyMap<string, readonly TreeChartDatum[]> = new Map(),
+): TreeModel {
+  const nodes: TreeChartNode[] = [];
+  const visit = (
+    item: TreeChartDatum,
+    parent: TreeChartNode | null,
+    id: string,
+    index: number,
+  ): TreeChartNode => {
+    const depth = parent ? parent.depth + 1 : 0;
+    const node: TreeChartNode = {
+      id,
+      name: item.name,
+      subtitle: item.subtitle,
+      badge: item.badge,
+      image: item.image,
+      color:
+        item.color ??
+        (depth === 0 ? seriesColor(0) : depth === 1 ? seriesColor(index + 1) : parent?.color) ??
+        seriesColor(0),
+      depth,
+      parent,
+      children: [],
+      index,
+      lazy: false,
+      group: !!item.group,
+      data: item,
+    };
+    nodes.push(node);
+    const seen = new Map<string, number>();
+    const fetched = loaded.get(id);
+    const own = item.children?.length ? item.children : fetched;
+    node.lazy = !!item.lazy && !fetched && !item.children?.length;
+    node.children = (own ?? []).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);
+    });
+    return node;
+  };
+  const root = visit(data, null, data.id ?? "root", 0);
+  return { root, nodes, byId: new Map(nodes.map((node) => [node.id, node])) };
+}
+
+/** Ids collapsed at first: nodes flagged `collapsed`, and every node at `initialDepth`. */
+export function initialCollapsed(model: TreeModel, initialDepth: number): Set<string> {
+  const collapsed = new Set<string>();
+  for (const node of model.nodes) {
+    if (node.children.length === 0) continue;
+    if (node.data.collapsed || node.depth >= initialDepth) collapsed.add(node.id);
+  }
+  return collapsed;
+}
+
+/** The part of the tree that is visible, as layout input. */
+export function visibleTree(
+  root: TreeChartNode,
+  collapsed: ReadonlySet<string>,
+  size: (node: TreeChartNode) => { width: number; height: number },
+): TreeLayoutInput {
+  const visit = (node: TreeChartNode): TreeLayoutInput => ({
+    id: node.id,
+    ...size(node),
+    children: collapsed.has(node.id) ? [] : node.children.map(visit),
+  });
+  return visit(root);
+}
+
+/** Every node below `node`. */
+export function subtreeSize(node: TreeChartNode): number {
+  return node.children.reduce((sum, child) => sum + 1 + subtreeSize(child), 0);
+}
+
+/** "AR" for "Ana Rojas", "K" for "Kevin". */
+export function initials(name: string): string {
+  const words = name.trim().split(/\s+/).filter(Boolean);
+  const first = words[0]?.[0] ?? "";
+  const last = words.length > 1 ? (words[words.length - 1]?.[0] ?? "") : "";
+  return `${first}${last}`.toUpperCase();
+}
+
+/**
+ * Folds runs of leaf siblings into one group node, so a manager with twenty
+ * apprentices shows "20 apprentices" instead of twenty cards. A node is
+ * grouped when it has at least `min` leaf children; the group starts collapsed
+ * and expands to the original leaves. Nodes with other children keep them.
+ */
+export function groupLeaves(
+  data: TreeChartDatum,
+  min: number,
+  label: (count: number) => string = (count) => `${count}`,
+): TreeChartDatum {
+  const visit = (item: TreeChartDatum, key: string): TreeChartDatum => {
+    const children = item.children ?? [];
+    if (children.length === 0) return item;
+    const leaves = children.filter((child) => !child.children?.length && !child.lazy);
+    const next = children.map((child) =>
+      leaves.includes(child) ? child : visit(child, child.id ?? child.name),
+    );
+    if (leaves.length < min) return { ...item, children: next };
+    const group: TreeChartDatum = {
+      id: `${key}~leaves`,
+      name: label(leaves.length),
+      subtitle: leaves
+        .slice(0, 3)
+        .map((leaf) => leaf.name)
+        .join(", "),
+      group: true,
+      collapsed: true,
+      children: leaves,
+    };
+    const kept = next.filter((child) => !leaves.includes(child));
+    return { ...item, children: [...kept, group] };
+  };
+  return visit(data, data.id ?? data.name);
+}
+
+/** Lower-case text without accents, for forgiving searches. */
+export function foldText(text: string): string {
+  return text
+    .normalize("NFD")
+    .replace(/[\u0300-\u036f]/g, "")
+    .toLowerCase();
+}
+
+/**
+ * Nodes whose name, subtitle or badge contains every word of `query`, in
+ * pre-order (document order). An empty query matches nothing.
+ */
+export function searchTree(model: TreeModel, query: string): TreeChartNode[] {
+  const words = foldText(query).split(/\s+/).filter(Boolean);
+  if (words.length === 0) return [];
+  return model.nodes.filter((node) => {
+    const haystack = foldText([node.name, node.subtitle, node.badge].filter(Boolean).join(" "));
+    return words.every((word) => haystack.includes(word));
+  });
+}
+
+/** Ids of the ancestors of `node`, root first (the node itself excluded). */
+export function ancestorIds(node: TreeChartNode): string[] {
+  const ids: string[] = [];
+  for (let parent = node.parent; parent; parent = parent.parent) ids.unshift(parent.id);
+  return ids;
+}
+
+/** Edge color rule: `depth` colors by level, `branch` by top-level branch, `neutral` is the line token. */
+export type TreeEdgeColor = "neutral" | "depth" | "branch";
+
+/** Color of the edge that enters `node`. */
+export function edgeColorOf(node: TreeChartNode, mode: TreeEdgeColor): string {
+  if (mode === "branch") return node.color;
+  if (mode === "depth") return seriesColor(Math.max(0, node.depth - 1));
+  return "var(--line-strong)";
+}

package/src/charts/tree-chart/use-tree-transition.ts

@@ -0,0 +1,116 @@
+"use client";
+
+import { useEffect, useRef, useState } from "react";
+import { easeOutCubic, useReducedMotion } from "../core/motion.js";
+import type { TreeLayout, TreeLayoutNode } from "../core/tree-layout.js";
+
+/** A laid-out node as drawn in the current frame. */
+export interface TreePose extends TreeLayoutNode {
+  opacity: number;
+}
+
+interface Track {
+  node: TreeLayoutNode;
+  from: { x: number; y: number; opacity: number };
+  to: { x: number; y: number; opacity: number };
+}
+
+function settled(layout: TreeLayout): TreePose[] {
+  return layout.nodes.map((node) => ({ ...node, opacity: 1 }));
+}
+
+/**
+ * Moves the drawn nodes from the previous layout to the next one with
+ * `requestAnimationFrame`: nodes that stay glide to their new place, nodes that
+ * appear grow out of their closest visible ancestor, and nodes that disappear
+ * fold back into it. Jumps straight to the new layout when disabled, under
+ * `prefers-reduced-motion`, or on the server.
+ */
+export function useTreeTransition(
+  layout: TreeLayout,
+  parentOf: (id: string) => string | null,
+  { disabled = false, duration = 360 }: { disabled?: boolean; duration?: number } = {},
+): TreePose[] {
+  const reduced = useReducedMotion();
+  const [poses, setPoses] = useState<TreePose[]>(() => settled(layout));
+  const current = useRef(poses);
+  const parents = useRef(parentOf);
+  parents.current = parentOf;
+
+  useEffect(() => {
+    const final = settled(layout);
+    const previous = current.current;
+    const show = (next: TreePose[]) => {
+      current.current = next;
+      setPoses(next);
+    };
+    if (disabled || reduced || typeof requestAnimationFrame !== "function") {
+      show(final);
+      return;
+    }
+    const from = new Map(previous.map((pose) => [pose.id, pose]));
+    const target = new Map(layout.nodes.map((node) => [node.id, node]));
+    const nearest = <T>(id: string, among: Map<string, T>): T | undefined => {
+      for (let parent = parents.current(id); parent; parent = parents.current(parent)) {
+        const hit = among.get(parent);
+        if (hit) return hit;
+      }
+      return undefined;
+    };
+
+    const tracks: Track[] = layout.nodes.map((node) => {
+      const before = from.get(node.id);
+      const origin = before ?? nearest(node.id, from);
+      return {
+        node,
+        from: origin
+          ? { x: origin.x, y: origin.y, opacity: before ? before.opacity : 0 }
+          : { x: node.x, y: node.y, opacity: 0 },
+        to: { x: node.x, y: node.y, opacity: 1 },
+      };
+    });
+    for (const pose of previous) {
+      if (target.has(pose.id)) continue;
+      const into = nearest(pose.id, target);
+      tracks.push({
+        node: pose,
+        from: { x: pose.x, y: pose.y, opacity: pose.opacity },
+        to: { x: into?.x ?? pose.x, y: into?.y ?? pose.y, opacity: 0 },
+      });
+    }
+    const moved = tracks.some(
+      (track) =>
+        track.from.x !== track.to.x ||
+        track.from.y !== track.to.y ||
+        track.from.opacity !== track.to.opacity,
+    );
+    if (!moved) {
+      show(final);
+      return;
+    }
+
+    let frame = 0;
+    const start = performance.now();
+    const step = (now: number) => {
+      const t = Math.min(1, (now - start) / duration);
+      if (t >= 1) {
+        show(final);
+        return;
+      }
+      const e = easeOutCubic(t);
+      show(
+        tracks.map(({ node, from: a, to: b }) => ({
+          ...node,
+          x: a.x + (b.x - a.x) * e,
+          y: a.y + (b.y - a.y) * e,
+          opacity: a.opacity + (b.opacity - a.opacity) * e,
+        })),
+      );
+      frame = requestAnimationFrame(step);
+    };
+    frame = requestAnimationFrame(step);
+    return () => cancelAnimationFrame(frame);
+  }, [layout, disabled, reduced, duration]);
+
+  return poses;
+}

package/src/charts/treemap-chart/index.ts

@@ -0,0 +1 @@
+export * from "./treemap-chart.js";