@kgdiff/g6 0.0.0-stage → 0.1.0

package/src/options.ts

@@ -0,0 +1,215 @@
+/**
+ * The G6 options `createDiffGraph` generates: no G6 theme (so no theme state styles, palettes or
+ * default animations leak into kgdiff's encodings), a background plugin carrying the canvas
+ * color, kgdiff-node, private hover states, and update animations for the fields kgdiff changes.
+ */
+import type { EdgeData, GraphOptions, IEvent, NodeData } from '@antv/g6';
+import type { ChangeFamily, Theme } from '@kgdiff/scene';
+import {
+  BACKGROUND_PLUGIN_KEY,
+  EDGE_LABEL_SIZE,
+  HOVER_BEHAVIOR_KEY,
+  HOVER_EDGE_WIDTH,
+  HOVER_NODE_WIDTH,
+  HOVER_STATE,
+  NODE_TYPE,
+  TEXT_HALO_ALPHA,
+  Z,
+} from './constants.js';
+import { kgdiffData } from './map.js';
+
+type NodeStyle = NonNullable<NodeData['style']>;
+type EdgeStyle = NonNullable<EdgeData['style']>;
+
+const CHANGE_FAMILIES: ReadonlySet<string> = new Set<ChangeFamily>([
+  'added',
+  'removed',
+  'content',
+  'structure',
+  'identity',
+]);
+
+function num(v: unknown, fallback: number): number {
+  return typeof v === 'number' && Number.isFinite(v) ? v : fallback;
+}
+
+/**
+ * Hover on a node, as the resolver does it: a 2-wide stroke in the family's strong color
+ * (secondary text color for context), drawn on top, label revealed even below its LOD zoom.
+ */
+export function hoverNodeStyle(datum: NodeData, theme: Theme): NodeStyle {
+  const d = kgdiffData(datum.data);
+  if (d === null || d.kgdiff !== 'node') return {};
+  const style = datum.style ?? {};
+  const fam = d.family;
+  const opacity = Math.max(num(style.labelOpacity, 0), num(style.opacity, 1));
+  return {
+    lineWidth: HOVER_NODE_WIDTH,
+    stroke:
+      d.changed && CHANGE_FAMILIES.has(fam)
+        ? theme.family[fam as ChangeFamily].strong
+        : theme.text.secondary,
+    zIndex: Z.node + Z.span - 1,
+    label: typeof style.labelText === 'string' && style.labelText.length > 0,
+    labelOpacity: opacity,
+    labelStrokeOpacity: TEXT_HALO_ALPHA * opacity,
+  };
+}
+
+/** Hover on an edge: at least 2.5 wide, arrowhead, on top, its label shown. */
+export function hoverEdgeStyle(datum: EdgeData, theme: Theme): EdgeStyle {
+  const d = kgdiffData(datum.data);
+  if (d === null || (d.kgdiff !== 'edge' && d.kgdiff !== 'glyph')) return {};
+  const style = datum.style ?? {};
+  const own = typeof style.labelText === 'string' && style.labelText.length > 0;
+  const text = own ? (style.labelText as string) : d.label;
+  const opacity = Math.max(num(style.labelOpacity, 0), num(style.opacity, 1));
+  return {
+    lineWidth: Math.max(num(style.lineWidth, 1), HOVER_EDGE_WIDTH),
+    endArrow: datum.source !== datum.target,
+    zIndex: (d.kgdiff === 'glyph' ? Z.glyph : Z.edge) + Z.span - 1,
+    label: text.length > 0,
+    labelText: text,
+    labelFill: own ? (style.labelFill as string) : theme.neutral.label,
+    labelFontSize: own ? num(style.labelFontSize, EDGE_LABEL_SIZE) : EDGE_LABEL_SIZE,
+    labelOpacity: opacity,
+    labelStrokeOpacity: TEXT_HALO_ALPHA * opacity,
+  };
+}
+
+export interface GeneratedOptionsInput {
+  readonly container: HTMLElement | string;
+  readonly data: NonNullable<GraphOptions['data']>;
+  readonly theme: () => Theme;
+  readonly interactive: boolean;
+  /** Whether a pointer event may activate the hover state. */
+  readonly hoverable: (event: IEvent) => boolean;
+}
+
+/** Update animations: what interpolates when a frame replaces the previous one. */
+const NODE_ANIMATION = {
+  enter: 'fade',
+  exit: 'fade',
+  show: 'fade',
+  hide: 'fade',
+  update: [
+    {
+      fields: [
+        'x',
+        'y',
+        'size',
+        'fill',
+        'stroke',
+        'lineWidth',
+        'opacity',
+        'labelOpacity',
+        'ringOpacity',
+        'haloStrokeOpacity',
+        'sublabelOpacity',
+      ],
+    },
+  ],
+  translate: [{ fields: ['x', 'y'] }],
+};
+
+const EDGE_ANIMATION = {
+  enter: 'fade',
+  exit: 'fade',
+  show: 'fade',
+  hide: 'fade',
+  update: [
+    {
+      fields: [
+        'sourceNode',
+        'targetNode',
+        'stroke',
+        'lineWidth',
+        'opacity',
+        'labelOpacity',
+        'curveOffset',
+      ],
+    },
+  ],
+  translate: [{ fields: ['sourceNode', 'targetNode'] }],
+};
+
+export function generatedOptions(input: GeneratedOptionsInput): GraphOptions {
+  const theme = input.theme;
+  return {
+    container: input.container,
+    autoResize: true,
+    theme: false,
+    padding: 32,
+    data: input.data,
+    node: {
+      type: NODE_TYPE,
+      state: { [HOVER_STATE]: (datum: NodeData) => hoverNodeStyle(datum, theme()) },
+      animation: NODE_ANIMATION,
+    },
+    edge: {
+      state: { [HOVER_STATE]: (datum: EdgeData) => hoverEdgeStyle(datum, theme()) },
+      animation: EDGE_ANIMATION,
+    },
+    behaviors: input.interactive
+      ? [
+          'zoom-canvas',
+          'drag-canvas',
+          {
+            type: 'hover-activate',
+            key: HOVER_BEHAVIOR_KEY,
+            state: HOVER_STATE,
+            degree: 0,
+            enable: input.hoverable,
+          },
+        ]
+      : [],
+    plugins: [
+      { type: 'background', key: BACKGROUND_PLUGIN_KEY, background: theme().canvas.background },
+    ],
+  };
+}
+
+const CONCAT = new Set(['behaviors', 'plugins', 'transforms']);
+
+function isPlain(v: unknown): v is Record<string, unknown> {
+  return (
+    v !== null &&
+    typeof v === 'object' &&
+    !Array.isArray(v) &&
+    Object.getPrototypeOf(v) === Object.prototype
+  );
+}
+
+function deepMerge(
+  a: Record<string, unknown>,
+  b: Record<string, unknown>,
+): Record<string, unknown> {
+  const out: Record<string, unknown> = { ...a };
+  for (const [key, value] of Object.entries(b)) {
+    const base = out[key];
+    out[key] = isPlain(base) && isPlain(value) ? deepMerge(base, value) : value;
+  }
+  return out;
+}
+
+/**
+ * User options over generated ones: `behaviors`, `plugins` and `transforms` are appended to the
+ * generated lists; plain objects (`node`, `edge`, `node.state`…) merge recursively; everything
+ * else (arrays, functions, primitives) from `user` replaces the generated value.
+ */
+export function mergeG6Options(
+  generated: GraphOptions,
+  user: Readonly<Record<string, unknown>> | undefined,
+): GraphOptions {
+  if (user === undefined) return generated;
+  const out: Record<string, unknown> = { ...generated };
+  for (const [key, value] of Object.entries(user)) {
+    const base = out[key];
+    if (CONCAT.has(key) && Array.isArray(base) && Array.isArray(value))
+      out[key] = [...base, ...value];
+    else if (isPlain(base) && isPlain(value)) out[key] = deepMerge(base, value);
+    else out[key] = value;
+  }
+  // The merged object is GraphOptions plus whatever the caller added; G6 validates it.
+  return out as GraphOptions;
+}

package/src/patch.ts

@@ -0,0 +1,133 @@
+/**
+ * Frame-to-frame patches. G6's `setData` re-reads and compares the whole graph and merges full
+ * styles into every changed element; sending G6 only what changed — new elements, removed ids,
+ * and for updated elements just the changed style keys — keeps its data layer proportional to
+ * the change. Pure.
+ */
+import type { EdgeData, ID, NodeData } from '@antv/g6';
+
+export type Datum = NodeData | EdgeData;
+
+export interface Patch {
+  readonly add: { nodes: NodeData[]; edges: EdgeData[] };
+  /** Partial data: `id` (edges also `source` / `target`), the changed style keys, changed `data`. */
+  readonly update: { nodes: NodeData[]; edges: EdgeData[] };
+  readonly remove: { nodes: ID[]; edges: ID[] };
+  /**
+   * Elements whose id switched between node and edge (only possible through id collisions):
+   * added after `remove`, since G6 rejects a duplicate id.
+   */
+  readonly readd: { nodes: NodeData[]; edges: EdgeData[] };
+  /** Number of elements added, updated, removed or re-added. */
+  readonly size: number;
+}
+
+/** Structural equality for style values (primitives, arrays, plain objects such as badges). */
+export function deepEqual(a: unknown, b: unknown): boolean {
+  if (a === b) return true;
+  if (typeof a !== 'object' || typeof b !== 'object' || a === null || b === null) return false;
+  if (Array.isArray(a) !== Array.isArray(b)) return false;
+  const ka = Object.keys(a);
+  const kb = Object.keys(b);
+  if (ka.length !== kb.length) return false;
+  const ra = a as Record<string, unknown>;
+  const rb = b as Record<string, unknown>;
+  return ka.every((k) => deepEqual(ra[k], rb[k]));
+}
+
+/** Keys of `next` whose values differ from `prev` (structurally), or null when none do. */
+function changedKeys(
+  prev: Record<string, unknown> | undefined,
+  next: Record<string, unknown> | undefined,
+): Record<string, unknown> | null {
+  if (next === undefined) return null;
+  let out: Record<string, unknown> | null = null;
+  for (const key of Object.keys(next)) {
+    const value = next[key];
+    const old = prev?.[key];
+    if (old === value || (typeof value === 'object' && deepEqual(old, value))) continue;
+    if (out === null) out = {};
+    out[key] = value;
+  }
+  return out;
+}
+
+function shallowEqual(
+  a: Record<string, unknown> | undefined,
+  b: Record<string, unknown> | undefined,
+): boolean {
+  if (a === b) return true;
+  if (a === undefined || b === undefined) return false;
+  const ka = Object.keys(a);
+  return ka.length === Object.keys(b).length && ka.every((k) => a[k] === b[k]);
+}
+
+/**
+ * The patch turning `prev` (by id) into `next`. Edge updates always carry `zIndex`: without a
+ * numeric one, G6's `updateData` recomputes an edge's zIndex from its endpoints. O(elements ×
+ * style keys).
+ */
+export function diffData(
+  prev: ReadonlyMap<ID, Datum>,
+  next: { readonly nodes: readonly NodeData[]; readonly edges: readonly EdgeData[] },
+): Patch {
+  const add: Patch['add'] = { nodes: [], edges: [] };
+  const update: Patch['update'] = { nodes: [], edges: [] };
+  const remove: Patch['remove'] = { nodes: [], edges: [] };
+  const readd: Patch['readd'] = { nodes: [], edges: [] };
+  const seen = new Set<ID>();
+  for (const node of next.nodes) {
+    const old = prev.get(node.id);
+    if (old === undefined || 'source' in old) {
+      if (old === undefined) add.nodes.push(node);
+      else readd.nodes.push(node);
+      continue;
+    }
+    seen.add(node.id);
+    const style = changedKeys(old.style, node.style);
+    const dataChanged = !shallowEqual(old.data, node.data);
+    const typeChanged = old.type !== node.type;
+    if (style === null && !dataChanged && !typeChanged) continue;
+    const patch: NodeData = { id: node.id };
+    if (style !== null) patch.style = style;
+    if (dataChanged) patch.data = node.data;
+    if (typeChanged) patch.type = node.type;
+    update.nodes.push(patch);
+  }
+  for (const edge of next.edges) {
+    const id = edge.id as ID;
+    const old = prev.get(id);
+    if (old === undefined || !('source' in old)) {
+      if (old === undefined) add.edges.push(edge);
+      else readd.edges.push(edge);
+      continue;
+    }
+    seen.add(id);
+    const style = changedKeys(old.style, edge.style);
+    const dataChanged = !shallowEqual(old.data, edge.data);
+    const typeChanged = old.type !== edge.type;
+    const endsChanged = old.source !== edge.source || old.target !== edge.target;
+    if (style === null && !dataChanged && !typeChanged && !endsChanged) continue;
+    const patch: EdgeData = { id, source: edge.source, target: edge.target };
+    patch.style = { ...style, zIndex: edge.style?.zIndex };
+    if (dataChanged) patch.data = edge.data;
+    if (typeChanged) patch.type = edge.type;
+    update.edges.push(patch);
+  }
+  for (const [id, old] of prev) {
+    // Kept elements were marked seen; added ones were not in `prev` at all.
+    if (seen.has(id)) continue;
+    if ('source' in old) remove.edges.push(id);
+    else remove.nodes.push(id);
+  }
+  const size =
+    add.nodes.length +
+    add.edges.length +
+    update.nodes.length +
+    update.edges.length +
+    remove.nodes.length +
+    remove.edges.length +
+    readd.nodes.length +
+    readd.edges.length;
+  return { add, update, remove, readd, size };
+}

package/src/replay.ts

@@ -0,0 +1,59 @@
+/**
+ * Replay plan: the timeline times at which the controller resolves a frame and hands it to G6,
+ * which animates linearly from one sample to the next. Pure.
+ */
+import type { Timeline } from '@kgdiff/scene';
+import { REPLAY_SAMPLES } from './constants.js';
+
+export interface ReplayStep {
+  /** Timeline time to resolve (ms at 1×). */
+  readonly t: number;
+  /** Time since the previous step (ms at 1×); the first step counts from 0. */
+  readonly dt: number;
+  /** On the first step of a unit (window, or chapter in chapter mode): its hunks, for the camera. */
+  readonly focus: readonly number[] | null;
+}
+
+interface Unit {
+  readonly start: number;
+  readonly end: number;
+  readonly hunks: readonly number[];
+}
+
+/**
+ * Sample every unit of `timeline` at `samples` (fractions of its duration). Units are the
+ * hunk windows, or the chapters in chapter mode (whose windows overlap and play together).
+ * Steps are sorted by time; samples closer than 1e-6 ms are merged. O(U log U).
+ */
+export function planReplay(
+  timeline: Timeline,
+  samples: readonly number[] = REPLAY_SAMPLES,
+): ReplayStep[] {
+  const units: Unit[] =
+    timeline.mode === 'chapters'
+      ? timeline.chapters.map((c) => ({ start: c.start, end: c.end, hunks: c.hunks }))
+      : timeline.windows.map((w) => ({ start: w.start, end: w.end, hunks: [w.hunk] }));
+  const raw: { t: number; focus: readonly number[] | null; order: number }[] = [];
+  units.forEach((u, k) => {
+    if (!Number.isFinite(u.start) || !Number.isFinite(u.end)) return;
+    const length = Math.max(0, u.end - u.start);
+    samples.forEach((f, s) => {
+      raw.push({ t: u.start + f * length, focus: s === 0 ? u.hunks : null, order: k });
+    });
+  });
+  raw.sort((a, b) => a.t - b.t || a.order - b.order);
+  const steps: ReplayStep[] = [];
+  let prev = 0;
+  for (const r of raw) {
+    const last = steps[steps.length - 1];
+    if (last !== undefined && r.t - last.t < 1e-6) {
+      if (r.focus !== null && last.focus === null) {
+        steps[steps.length - 1] = { ...last, focus: r.focus };
+      }
+      continue;
+    }
+    steps.push({ t: r.t, dt: Math.max(0, r.t - prev), focus: r.focus });
+    prev = r.t;
+  }
+  return steps;
+}