@kgdiff/viewer 0.1.0 → 0.3.0

package/src/framing.ts

@@ -3,7 +3,8 @@
  * float over the canvas; a fit or flight must keep its target clear of them without wasting the
  * rest of the canvas. Each obstacle can be avoided through one side (an inset); all assignments
  * are tried (4ⁿ, n ≤ ~6 visible chips) and the one that shows `bounds` largest wins, ties going
- * to the free region closest to the canvas center. Pure; all sizes in canvas px.
+ * to the free region closest to the canvas center. `zoomFit` fits content whose world extent
+ * depends on the zoom (labels). Pure; all sizes in canvas px.
  */
 import type { Rect } from '@kgdiff/core';
 
@@ -139,6 +140,69 @@ export function frameTarget(
   return { x: cx - (sx - width / 2) / k, y: cy - (sy - height / 2) / k, k };
 }
 
+/** Lowest zoom a fit considers (the renderer's default `minZoom`). */
+const MIN_FIT_ZOOM = 0.05;
+/** Bisection steps for the zoom of a label-aware fit (a fraction of a percent). */
+const FIT_STEPS = 16;
+
+/** A fit whose content depends on the zoom it reaches. */
+export interface ZoomFit {
+  /** The zoom the fit lands on. */
+  readonly k: number;
+  /** What it shows (world units). */
+  readonly content: Rect;
+  /** Bounds for the camera: `content` centred in a rect that a fit lands on at exactly `k`. */
+  readonly bounds: Rect;
+}
+
+/**
+ * Fit content whose world extent depends on the zoom, `extent(k)`: labels keep their pixel size
+ * (and change sides as they make room for each other), so the further out the camera, the more
+ * world they cover. Finds the largest zoom up to `maxK` at which the content fits the canvas
+ * minus `insets` at that very zoom, by bisection (what fits only grows on screen as the camera
+ * zooms in), and lands exactly there, since the labels could move at another zoom. When not
+ * even the smallest zoom has room, `extent(Infinity)` (the discs alone) is fitted plainly.
+ */
+export function zoomFit(
+  extent: (k: number) => Rect | null,
+  width: number,
+  height: number,
+  insets: Insets,
+  maxK: number,
+): ZoomFit | null {
+  const fits = (k: number): boolean => {
+    const b = extent(k);
+    return b !== null && fitZoom(b, width, height, insets) >= k;
+  };
+  let k = maxK;
+  if (!fits(k)) {
+    let lo = Math.min(MIN_FIT_ZOOM, maxK);
+    if (!fits(lo)) {
+      const discs = extent(Number.POSITIVE_INFINITY);
+      if (!discs) return null;
+      return { k: fitZoom(discs, width, height, insets), content: discs, bounds: discs };
+    }
+    let hi = k;
+    for (let i = 0; i < FIT_STEPS; i++) {
+      const mid = Math.sqrt(lo * hi);
+      if (fits(mid)) lo = mid;
+      else hi = mid;
+    }
+    k = lo;
+  }
+  const content = extent(k);
+  if (!content) return null;
+  const w = (width - insets.left - insets.right) / k;
+  const h = (height - insets.top - insets.bottom) / k;
+  const bounds = {
+    x: content.x + content.width / 2 - w / 2,
+    y: content.y + content.height / 2 - h / 2,
+    width: w,
+    height: h,
+  };
+  return { k, content, bounds };
+}
+
 /** The part of `view` (world units) not covered by `insets` at zoom `k`. */
 export function freeView(view: Rect, k: number, insets: Insets): Rect {
   return {

package/src/i18n.ts

@@ -85,6 +85,8 @@ const en = {
   'detail.emptyHint': 'Use j / k to step through changes.',
   'detail.prev': 'Previous change',
   'detail.next': 'Next change',
+  'detail.changes': 'Changes',
+  'detail.changedTo': 'changed to',
   'detail.identity': 'Overview',
   'detail.id': 'Id',
   'detail.types': 'Types',
@@ -93,7 +95,6 @@ const en = {
   'detail.before': 'Before',
   'detail.after': 'After',
   'detail.attributes': 'Attributes',
-  'detail.key': 'Key',
   'detail.aliases': 'Synonyms',
   'detail.hierarchy': 'Hierarchy',
   'detail.relations': 'Relations',
@@ -123,8 +124,6 @@ const en = {
   'detail.undeprecated': 'No longer deprecated',
   'detail.replacedBy': 'Replaced by',
   'detail.replaces': 'Replaces',
-  'detail.emptyValue': 'empty',
-  'detail.none': 'none',
   'detail.unchangedNode': 'Unchanged node',
   'detail.implicit': 'Created for a dangling relation',
   'detail.collapsed': 'duplicate, collapsed',
@@ -275,6 +274,8 @@ const zhCN: Messages = {
   'detail.emptyHint': '按 j / k 逐项浏览变更。',
   'detail.prev': '上一项变更',
   'detail.next': '下一项变更',
+  'detail.changes': '变更内容',
+  'detail.changedTo': '改为',
   'detail.identity': '基本信息',
   'detail.id': 'ID',
   'detail.types': '类型',
@@ -283,7 +284,6 @@ const zhCN: Messages = {
   'detail.before': '变更前',
   'detail.after': '变更后',
   'detail.attributes': '属性',
-  'detail.key': '键',
   'detail.aliases': '别名',
   'detail.hierarchy': '层级',
   'detail.relations': '关系',
@@ -313,8 +313,6 @@ const zhCN: Messages = {
   'detail.undeprecated': '取消弃用',
   'detail.replacedBy': '替代为',
   'detail.replaces': '替代了',
-  'detail.emptyValue': '空',
-  'detail.none': '无',
   'detail.unchangedNode': '未变节点',
   'detail.implicit': '因悬空关系自动创建',
   'detail.collapsed': '重复关系，已合并',

package/src/index.ts

@@ -27,6 +27,10 @@ import { viewerTags } from './registry.js';
 
 export type ViewerMode = 'overlay' | 'swipe' | 'replay' | 'changes';
 export type ThemePreference = 'auto' | 'light' | 'dark';
+/** `none`: the graph alone, for small embeds (see `KgdiffViewerElement.chrome`). */
+export type ViewerChrome = 'full' | 'none';
+/** The legend card, one line of dots, no legend, or `auto` (the card, one line without chrome). */
+export type ViewerLegend = 'auto' | 'full' | 'mini' | 'none';
 
 /** A precomputed diff + layout: what the CLI embeds in HTML reports. Deterministic. */
 export interface ReportPayload {
@@ -83,6 +87,18 @@ export interface KgdiffViewerEventMap {
     readonly progress: ReviewState;
   }>;
   'kgdiff-error': CustomEvent<{ readonly error: Error }>;
+  /**
+   * Playback reached the end of the replay (not fired for seeking or stepping there). `loop`:
+   * it starts again after `loopDelay` ms; set `loop = false` or call `pause()` to stop it.
+   */
+  'kgdiff-replay-end': CustomEvent<{ readonly loop: boolean }>;
+}
+
+export interface FitOptions {
+  /** Default true (false with reduced motion). */
+  readonly animate?: boolean;
+  /** Room kept around the graph and its labels, px. Default 24; later automatic fits keep it. */
+  readonly padding?: number;
 }
 
 /**
@@ -96,6 +112,9 @@ export interface KgdiffViewerEventMap {
  *
  * `header="compact"` leaves the brand and the compared names out of the header, for hosts that
  * show their own (such as the playground).
+ *
+ * A small looping replay for another page: `mode="replay" chrome="none" loop` (with a height of
+ * your choosing, such as 320px).
  */
 export interface KgdiffViewerElement extends HTMLElement {
   /** Reflected to the `mode` attribute. Default `overlay` (`changes` for large graphs). */
@@ -106,6 +125,32 @@ export interface KgdiffViewerElement extends HTMLElement {
   palette: PaletteName;
   /** Reflected to the `locale` attribute. Default from `navigator.language`. */
   locale: Locale;
+  /**
+   * Reflected to the `chrome` attribute. `none` shows the graph alone: no header, change list,
+   * step caption, playback bar, zoom buttons, minimap or legend card; the hover tooltip and a
+   * one-line legend stay. Clicks and keyboard shortcuts do nothing, the minimum height drops
+   * from 420px to 120px, and the view stays fitted: when the canvas is resized (unless the user
+   * panned or zoomed since) and at the start of every loop. Labels are never cut at the edge:
+   * one pushed from its spot by a neighbour moves inside or is left out. Default `full`.
+   */
+  chrome: ViewerChrome;
+  /**
+   * Reflected to the `legend` attribute: `full` (the card), `mini` (one line: the families this
+   * diff has, then unchanged), `none`. Default `auto`: `full`, or `mini` with `chrome="none"`.
+   */
+  legend: ViewerLegend;
+  /**
+   * Reflected to the boolean `loop` attribute. In `replay` mode the replay plays by itself and
+   * starts again `loopDelay` ms after it ends. `pause()` stops it until `play()`. Default false.
+   */
+  loop: boolean;
+  /** Reflected to `loop-delay`: ms between the end of a looping replay and its restart. Default 1200. */
+  loopDelay: number;
+  /**
+   * With `loop`, the replay pauses while the pointer is over the graph and continues when it
+   * leaves (a mouse or pen; not touch). Reflected as `pause-on-hover="false"` when off. Default true.
+   */
+  pauseOnHover: boolean;
   /** Set a precomputed report (no diff / layout work in the browser). */
   payload: ReportPayload | null;
   /** Parse (if needed), diff, lay out and show two graphs. Rejects with a KgdiffError on bad input. */
@@ -116,7 +161,8 @@ export interface KgdiffViewerElement extends HTMLElement {
   prev(): void;
   play(): void;
   pause(): void;
-  fit(): Promise<void>;
+  /** Fit the whole graph, labels included, into view. */
+  fit(options?: FitOptions): Promise<void>;
   /** The full delta of the current diff. */
   exportDelta(): Delta;
   reviewState(): ReviewState;

package/src/prefs.ts

@@ -6,11 +6,22 @@
 import type { Locale } from '@kgdiff/core';
 import type { PaletteName } from '@kgdiff/scene';
 import { normalizeLocale } from './i18n.js';
-import type { ReportPayload, ThemePreference, ViewerMode } from './index.js';
+import type {
+  ReportPayload,
+  ThemePreference,
+  ViewerChrome,
+  ViewerLegend,
+  ViewerMode,
+} from './index.js';
 
 const MODES: readonly ViewerMode[] = ['overlay', 'swipe', 'replay', 'changes'];
 const THEMES: readonly ThemePreference[] = ['auto', 'light', 'dark'];
 const PALETTES: readonly PaletteName[] = ['default', 'colorblind'];
+const CHROMES: readonly ViewerChrome[] = ['full', 'none'];
+const LEGENDS: readonly ViewerLegend[] = ['auto', 'full', 'mini', 'none'];
+
+/** Pause between the end of a looping replay and its next start, ms. */
+export const DEFAULT_LOOP_DELAY = 1200;
 
 export const THEME_PREFERENCES = THEMES;
 
@@ -30,6 +41,20 @@ export function toLocale(value: unknown): Locale | null {
   return typeof value === 'string' ? normalizeLocale(value) : null;
 }
 
+export function toChrome(value: unknown): ViewerChrome | null {
+  return CHROMES.includes(value as ViewerChrome) ? (value as ViewerChrome) : null;
+}
+
+export function toLegend(value: unknown): ViewerLegend | null {
+  return LEGENDS.includes(value as ViewerLegend) ? (value as ViewerLegend) : null;
+}
+
+/** A delay in ms (number or numeric string), at least 0. */
+export function toDelay(value: unknown): number | null {
+  const n = typeof value === 'string' && value.trim() !== '' ? Number(value) : value;
+  return typeof n === 'number' && Number.isFinite(n) && n >= 0 ? n : null;
+}
+
 type View = NonNullable<ReportPayload['view']>;
 
 /** Keep only the valid fields of a report's `view` (warning about the rest). */

package/src/styles.ts

@@ -90,6 +90,8 @@ export const STYLES = /* css */ `
   -webkit-font-smoothing: antialiased;
 }
 :host([hidden]) { display: none; }
+/* chrome="none" shows the graph alone: small embeds (a 320 px strip) are fine. */
+:host([chrome="none"]) { min-height: 120px; }
 *, *::before, *::after { box-sizing: border-box; }
 [hidden] { display: none !important; }
 button, input { font: inherit; color: inherit; letter-spacing: inherit; }
@@ -237,6 +239,15 @@ ${familyRules}
 .legend-row { display: grid; grid-template-columns: 22px auto; align-items: center; column-gap: 8px; height: 26px; padding: 0 10px 0 4px; border-radius: 6px; cursor: default; }
 .legend-row .name { font-size: 12px; font-weight: 550; color: var(--kg-text); }
 .swatch { width: 22px; height: 22px; display: block; }
+.mini-legend { display: none; }
+.stage-wrap[data-legend="mini"] .mini-legend {
+  display: flex; flex-wrap: wrap; align-items: center; gap: 2px 12px; bottom: 8px; left: 12px; max-width: calc(100% - 24px);
+  font-size: 11px; line-height: 16px; color: var(--kg-text-2);
+}
+.mini-item { display: inline-flex; align-items: center; gap: 5px; white-space: nowrap; }
+.mini-item .dot { width: 8px; height: 8px; border-radius: 50%; flex: none; background: var(--fam-base); }
+.mini-item[data-family="removed"] .dot { background: none; box-shadow: inset 0 0 0 1.5px var(--fam-base); }
+.stage-wrap[data-legend="mini"] .legend, .stage-wrap[data-legend="none"] .legend { display: none; }
 
 .caption {
   position: absolute; top: 12px; left: 50%; transform: translateX(-50%); max-width: min(560px, calc(100% - 200px));
@@ -515,22 +526,20 @@ ${familyRules}
 .vchip.add { color: var(--kg-added-text); background: var(--kg-added-soft); box-shadow: none; }
 .vchip.del { color: var(--kg-removed-text); background: var(--kg-removed-soft); box-shadow: none; text-decoration: line-through; text-decoration-thickness: 1px; }
 .vchip .sign { font-weight: 700; text-decoration: none; display: inline-block; }
-.namediff { display: grid; gap: 4px; font-size: 13.5px; }
-.namediff .line { display: grid; grid-template-columns: 16px minmax(0, 1fr); gap: 6px; align-items: baseline; overflow-wrap: anywhere; }
-.namediff .sign { font: 600 12px/1 var(--kg-mono); text-align: center; }
-.namediff .old { color: var(--kg-text-2); }
-.namediff .old .sign { color: var(--kg-removed-text); }
-.namediff .new .sign { color: var(--kg-added-text); }
+.pair { display: flex; flex-wrap: wrap; align-items: baseline; gap: 0 6px; }
+.pair .b, .line.old { color: var(--kg-text-2); }
+.pair .arr { color: var(--kg-text-3); }
+.line { display: grid; grid-template-columns: 10px minmax(0, 1fr); gap: 6px; align-items: baseline; }
+.line .sign { font: 600 12px/1 var(--kg-mono); text-align: center; }
+.line.old .sign { color: var(--kg-removed-text); }
+.line.new .sign { color: var(--kg-added-text); }
 del.hl { text-decoration: line-through; text-decoration-color: var(--kg-removed); background: var(--kg-removed-soft); color: var(--kg-removed-text); border-radius: 3px; padding: 0 1px; }
 ins.hl { text-decoration: none; background: var(--kg-added-soft); color: var(--kg-added-text); border-radius: 3px; padding: 0 1px; }
-.attrs { width: 100%; border-collapse: separate; border-spacing: 0; font-size: 12px; table-layout: fixed; }
-.attrs th { text-align: left; font-weight: 550; font-size: 11px; color: var(--kg-text-3); padding: 0 8px 6px 0; }
-.attrs td { vertical-align: top; padding: 6px 8px 6px 0; border-top: 1px solid var(--kg-border); overflow-wrap: anywhere; }
-.attrs td.k { color: var(--kg-text-2); font-family: var(--kg-mono); font-size: 11.5px; }
-.attrs td.b { color: var(--kg-text-2); }
-.attrs tr.changed td.k { color: var(--kg-text); }
-.attrs tr.unchanged td { color: var(--kg-text-3); }
-.attrs .empty { color: var(--kg-text-3); font-style: italic; }
+.attrs { width: 100%; border-collapse: separate; border-spacing: 0; font-size: 12.5px; table-layout: fixed; }
+.attrs td { vertical-align: baseline; padding: 6px 8px 6px 0; border-top: 1px solid var(--kg-border); overflow-wrap: anywhere; }
+.attrs tr:first-child td { border-top: 0; padding-top: 0; }
+.attrs td > * + * { margin-top: 4px; }
+.attrs td.k { color: var(--kg-text-2); }
 .attrs col.k { width: 28%; }
 .val { white-space: pre-wrap; }
 .val.clamped { display: -webkit-box; -webkit-line-clamp: 4; -webkit-box-orient: vertical; overflow: hidden; }
@@ -566,9 +575,6 @@ ins.hl { text-decoration: none; background: var(--kg-added-soft); color: var(--k
 .bar-row .fill { height: 100%; border-radius: 3px; background: var(--kg-identity); }
 .bar-row .v { text-align: right; color: var(--kg-text-2); font-variant-numeric: tabular-nums; }
 .note-line { font-size: 12px; color: var(--kg-text-3); margin-top: 6px; }
-.hier { display: grid; grid-template-columns: 56px minmax(0, 1fr); gap: 6px 12px; font-size: 12.5px; align-items: baseline; }
-.hier dt { color: var(--kg-text-3); }
-.hier dd { margin: 0; display: flex; flex-wrap: wrap; gap: 4px; }
 
 /* ── Popovers ────────────────────────────────────────────────────────────── */
 .menu {
@@ -600,6 +606,12 @@ ins.hl { text-decoration: none; background: var(--kg-added-soft); color: var(--k
 .key-row { display: flex; align-items: center; justify-content: space-between; gap: 12px; min-height: 34px; border-bottom: 1px solid var(--kg-border); font-size: 12.5px; color: var(--kg-text-2); }
 .key-row .ks { display: inline-flex; align-items: center; gap: 3px; flex: none; color: var(--kg-text-3); font-size: 11px; }
 
+/* ── chrome="none": the graph, its hover tooltip and the legend line only ──── */
+.root[data-chrome="none"] .header, .root[data-chrome="none"] .sidebar, .root[data-chrome="none"] .caption,
+.root[data-chrome="none"] .transport, .root[data-chrome="none"] .finished, .root[data-chrome="none"] .stepper,
+.root[data-chrome="none"] .map-cluster, .root[data-chrome="none"] .side-chip { display: none !important; }
+.stage-wrap[data-selectable="false"] .tooltip .t-hint { display: none; }
+
 /* ── Compact (< 760 px): bottom sheet ────────────────────────────────────── */
 .root[data-compact="true"] .body { flex-direction: column; }
 .root[data-compact="true"] .sidebar {

package/src/text-diff.ts

@@ -1,6 +1,6 @@
 /**
- * Myers O((N+M)·D) sequence diff for the detail panel: character-level name diffs and
- * word-level attribute diffs. Small, deterministic, no dependencies.
+ * Myers O((N+M)·D) sequence diff for the detail panel: character-level name diffs, word-level
+ * attribute diffs and set changes read as edits. Small, deterministic, no dependencies.
  */
 
 export type DiffOp = 'equal' | 'insert' | 'delete';
@@ -206,3 +206,58 @@ export function sideOf(segs: readonly DiffSegment[], side: 'before' | 'after'):
   for (const seg of segs) if (seg.op !== skip) s += seg.text;
   return s;
 }
+
+/** A set change read as edits: removed → added pairs, and the items left over. */
+export interface PairedItems {
+  readonly pairs: readonly (readonly [removed: string, added: string])[];
+  readonly removed: readonly string[];
+  readonly added: readonly string[];
+}
+
+/** Below this share of common characters a removal and an addition stay apart. */
+const PAIR_MIN = 0.5;
+/** Above this many removal × addition candidates, only a lone pair is paired. */
+const PAIR_MAX_CANDIDATES = 400;
+
+/** 2 · common code points / total code points. */
+function closeness(a: readonly string[], b: readonly string[]): number {
+  let common = 0;
+  for (const s of diffSequences(a, b)) if (s.op === 'equal') common += s.items.length;
+  return (2 * common) / (a.length + b.length);
+}
+
+/**
+ * Read a set change (synonyms, types, parents, list values) as edits: a lone removal and a lone
+ * addition pair up (`老赖 → 失信人`); otherwise removals and additions sharing at least half
+ * their characters pair up, closest first. Pairs keep the order of `removed`.
+ */
+export function pairItems(removed: readonly string[], added: readonly string[]): PairedItems {
+  const found: [score: number, i: number, j: number][] = [];
+  if (removed.length === 1 && added.length === 1) found.push([1, 0, 0]);
+  else if (removed.length * added.length <= PAIR_MAX_CANDIDATES) {
+    const as = added.map((x) => Array.from(x));
+    removed.forEach((r, i) => {
+      const rs = Array.from(r);
+      as.forEach((a, j) => {
+        const score = closeness(rs, a);
+        if (score >= PAIR_MIN) found.push([score, i, j]);
+      });
+    });
+    found.sort((x, y) => y[0] - x[0] || x[1] - y[1] || x[2] - y[2]);
+  }
+  const usedR = new Set<number>();
+  const usedA = new Set<number>();
+  const pairs: [number, number][] = [];
+  for (const [, i, j] of found) {
+    if (usedR.has(i) || usedA.has(j)) continue;
+    usedR.add(i);
+    usedA.add(j);
+    pairs.push([i, j]);
+  }
+  pairs.sort((x, y) => x[0] - y[0]);
+  return {
+    pairs: pairs.map(([i, j]) => [removed[i] as string, added[j] as string] as const),
+    removed: removed.filter((_, i) => !usedR.has(i)),
+    added: added.filter((_, j) => !usedA.has(j)),
+  };
+}