@kgdiff/viewer 0.2.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/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));
@@ -595,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/ui/stage.ts

@@ -1,8 +1,9 @@
 /**
  * The canvas area and its floating chrome: replay caption and transport, swipe divider,
- * changes-only context stepper, legend, zoom controls + minimap, hover tooltip and the
- * loading / identical / error / empty states. Overlays never cover the current hunk: the
- * element reserves their space through the renderer's safe area.
+ * changes-only context stepper, legend (a card, or one line of dots for chrome-less embeds),
+ * zoom controls + minimap, hover tooltip and the loading / identical / error / empty states.
+ * Overlays never cover the current hunk: the element reserves their space through the
+ * renderer's safe area.
  */
 import { KgdiffError, type Rect } from '@kgdiff/core';
 import type { ChangeFamily, Family } from '@kgdiff/scene';
@@ -24,6 +25,9 @@ import { sceneHunkGlyph, type UiContext } from './context.js';
 
 const TICK_W = 1000;
 
+/** How the legend shows: the card, one line of dots, or not at all. */
+export type LegendStyle = 'full' | 'mini' | 'none';
+
 /** Legend swatch: the node cue of each family (docs/visual-language.md §Meaning families). */
 function swatch(family: Family): SVGSVGElement {
   const v = (name: string) => `var(--kg-${name})`;
@@ -84,6 +88,7 @@ export class Stage {
   readonly #legend: HTMLElement;
   readonly #legendHead: HTMLButtonElement;
   readonly #legendBody: HTMLElement;
+  readonly #miniLegend: HTMLElement;
   readonly #zoomIn: HTMLButtonElement;
   readonly #zoomOut: HTMLButtonElement;
   readonly #fitButton: HTMLButtonElement;
@@ -236,6 +241,7 @@ export class Stage {
       this.#legendHead,
       this.#legendBody,
     );
+    this.#miniLegend = h('div', { class: 'mini-legend float bottom-left', role: 'list' });
 
     // Zoom + minimap
     this.#zoomIn = iconButton('plus', '', () => c.zoom(1));
@@ -264,6 +270,7 @@ export class Stage {
       this.#caption,
       this.#stepper,
       this.#legend,
+      this.#miniLegend,
       this.#mapCluster,
       this.#finished,
       this.#transport,
@@ -297,6 +304,7 @@ export class Stage {
     const obstacles: Rect[] = [];
     const parts = [
       this.#legend,
+      this.#miniLegend,
       this.#mapCluster,
       this.#transport,
       this.#finished,
@@ -326,12 +334,19 @@ export class Stage {
     attr(this.#legendHead, 'aria-expanded', String(open));
   }
 
+  /** Legend style, and whether clicks select (the tooltip only hints at clicking then). */
+  setChrome(legend: LegendStyle, selectable: boolean): void {
+    this.el.dataset.legend = legend;
+    this.el.dataset.selectable = String(selectable);
+  }
+
   update(topics: ReadonlySet<Topic>): void {
     const c = this.#ctx.controller;
     const tr = this.#ctx.tr();
     const all = topics.has('status') || topics.has('data') || topics.has('locale');
     if (all) {
       this.#renderLabels(tr);
+      this.#renderMiniLegend(tr);
       this.#renderState(tr);
       this.#renderTicks();
       this.#renderCanvasLabel(tr);
@@ -381,6 +396,32 @@ export class Stage {
     );
   }
 
+  /** One line: the families this diff has, then the unchanged context. */
+  #renderMiniLegend(tr: Translator): void {
+    const scene = this.#ctx.controller.scene;
+    const present = new Set<Family>(scene?.hunks.map((x) => x.family));
+    if (scene?.nodes.some((n) => n.status === 'unchanged')) present.add('neutral');
+    attr(this.#miniLegend, 'aria-label', tr.t('legend.title'));
+    replace(
+      this.#miniLegend,
+      [...FAMILIES, 'neutral' as const]
+        .filter((f) => present.has(f))
+        .map((f) =>
+          h(
+            'span',
+            {
+              class: 'mini-item',
+              role: 'listitem',
+              'data-family': f,
+              title: tr.t(`familyHint.${f}`),
+            },
+            h('span', { class: 'dot', 'aria-hidden': 'true' }),
+            tr.t(`family.${f}`),
+          ),
+        ),
+    );
+  }
+
   #renderCanvasLabel(tr: Translator): void {
     const stats = this.#ctx.controller.diff?.stats;
     const canvas = this.canvasHost.querySelector('canvas');