@kgdiff/viewer 0.5.0 → 0.6.0

package/src/elements/root.ts

@@ -0,0 +1,86 @@
+/**
+ * `<kgdiff-root>` (RFC 0001 §3), documented on its class. Importing this module defines it.
+ */
+import type { KgdiffRootElement } from '../index.js';
+import { ROOT_ATTRIBUTES, RootElement } from '../root-element.js';
+import { DiffSession, type SessionDeps, type SessionHost } from '../session.js';
+import { elementSheet } from '../styles.js';
+import type { UiActions } from '../ui/context.js';
+import { define } from './bound.js';
+
+/**
+ * A root without visuals. It owns the session and provides it to the elements inside it
+ * (`<kgdiff-stage>`, `<kgdiff-change-list>`, …) or naming it with `for`, and owns what they share:
+ * the keyboard map, the live region announcing navigation, the events and the theme tokens. It has
+ * the attributes, properties, methods and events of `<kgdiff-viewer>` except the layout's
+ * (`panels`, `sidebar`, `header`, `chrome`, `legend`, `persist`): the page lays the elements out,
+ * and nothing is remembered.
+ *
+ * It renders as `display: contents`, so its children are laid out by the page as if it were not
+ * there.
+ *
+ * @tagname kgdiff-root
+ * @experimental In 0.6; stable from 0.7 (RFC 0001, decision 7).
+ */
+export class KgdiffRoot extends RootElement implements KgdiffRootElement {
+  static get observedAttributes(): readonly string[] {
+    return ROOT_ATTRIBUTES;
+  }
+
+  #built = false;
+
+  constructor() {
+    super();
+    this.root.attach({
+      update: (topics) => {
+        this.reflectSession(topics);
+        if (topics.has('locale') || topics.has('status')) {
+          this.root.live.setAttribute('lang', this.controller.locale);
+        }
+      },
+    });
+  }
+
+  protected sheets(doc: Document): readonly CSSStyleSheet[] {
+    return [elementSheet(doc, 'root')];
+  }
+
+  /** A session without a canvas of its own: each `<kgdiff-stage>` brings its view. */
+  protected createSession(host: SessionHost, deps: SessionDeps): DiffSession {
+    return new DiffSession(host, deps);
+  }
+
+  /** No layout of its own: `\` does nothing, `?` and `/` go to the elements registered last. */
+  protected actions(): UiActions {
+    return {
+      ...this.baseActions(),
+      toggleSidebar: () => undefined,
+      sidebarOpen: () => false,
+      toggleMenu: () => undefined,
+      // `?` opens the dialog of a `<kgdiff-actions>` bound to this root, if there is one.
+      openHelp: () => {
+        this.root.focus('help');
+      },
+      focusSearch: () => {
+        this.root.focus('search');
+      },
+    };
+  }
+
+  protected connected(): void {
+    if (this.#built) return;
+    this.#built = true;
+    this.shadow.append(document.createElement('slot'), this.root.live);
+  }
+
+  protected disconnected(): void {}
+}
+
+define('kgdiff-root', KgdiffRoot);
+
+declare global {
+  interface HTMLElementTagNameMap {
+    /** @experimental In 0.6. */
+    'kgdiff-root': KgdiffRootElement;
+  }
+}

package/src/elements/search.ts

@@ -0,0 +1,38 @@
+/**
+ * `<kgdiff-search>` (RFC 0001 §3), documented on its class. Importing this module defines it.
+ */
+import type { Region } from '../bind.js';
+import type { KgdiffBoundElement } from '../index.js';
+import type { UiContext } from '../ui/context.js';
+import { Search } from '../ui/search.js';
+import { BoundElement, define } from './bound.js';
+
+/**
+ * Node search, a combobox and the results list it owns (its `aria-controls` and
+ * `aria-activedescendant` stay inside the element). The results open below the box while the query
+ * is not blank; ↑ / ↓ move through them, Enter chooses one (its node and change are selected, and
+ * focus moves to the change list), Esc clears. The query lives in the session, so a change list
+ * bound to the same root steps aside meanwhile. Registers itself as the root's `search` focus
+ * target: `/` focuses the one registered last that is shown.
+ *
+ * @tagname kgdiff-search
+ * @experimental In 0.6; stable from 0.7 (RFC 0001, decision 7).
+ */
+export class KgdiffSearch extends BoundElement implements KgdiffBoundElement {
+  protected readonly name = 'search';
+
+  protected build(ui: UiContext): Region {
+    const search = new Search(ui);
+    this.shadow.append(search.box, search.results);
+    return search;
+  }
+}
+
+define('kgdiff-search', KgdiffSearch);
+
+declare global {
+  interface HTMLElementTagNameMap {
+    /** @experimental In 0.6. */
+    'kgdiff-search': KgdiffBoundElement;
+  }
+}

package/src/elements/stage-context.ts

@@ -0,0 +1,34 @@
+/**
+ * The view-level context a `<kgdiff-stage>` provides to its descendants (`kgdiff.stage/1`), in a
+ * module of its own: the chrome that acts on a view finds its stage through it without pulling
+ * the stage (and the renderer) into its subpath.
+ */
+import type { ViewerContext } from '../bind.js';
+import { createContext } from '../context.js';
+import type { KgdiffStageElement, KgdiffViewerElement } from '../index.js';
+import type { StageView } from '../view.js';
+
+/**
+ * What a stage provides to its descendants (the view-level context).
+ *
+ * @experimental Like the stage, in 0.6.
+ */
+export interface StageContext {
+  /** Keep `element` clear of fits and flights; returns the function that stops it. */
+  registerObstacle(element: Element): () => void;
+}
+
+/** @internal What the chrome that acts on a view (`<kgdiff-zoom>`, `<kgdiff-minimap>`) gets. */
+export interface StageViewContext extends StageContext {
+  /** The stage element, or the viewer (its built-in stage). */
+  readonly stage: KgdiffStageElement | KgdiffViewerElement;
+  /** The root the stage is bound to now, or null while it waits for one. */
+  readonly root: ViewerContext | null;
+  /** The stage's view now, or null while the stage waits for its root. */
+  readonly view: StageView | null;
+  /** Call `listener` with the view now and whenever it changes; returns the stop. */
+  watchView(listener: (view: StageView | null) => void): () => void;
+}
+
+/** @experimental The stage context's key (`Symbol.for('kgdiff.stage/1')`). */
+export const stageContext = createContext<StageContext>('kgdiff.stage/1');

package/src/elements/stage.ts

@@ -0,0 +1,285 @@
+/**
+ * `<kgdiff-stage>` (RFC 0001 §3), documented on its class. Importing this module defines it.
+ */
+import type { Region, ViewerContext } from '../bind.js';
+import { provideContext } from '../context.js';
+import type {
+  KgdiffStageElement,
+  PanelState,
+  StagePanels,
+  StageRegion,
+  StageVersion,
+} from '../index.js';
+import { DEFAULT_PANELS, formatPanels, toPanels } from '../panels.js';
+import type { UiContext } from '../ui/context.js';
+import { Stage } from '../ui/stage.js';
+import { StageView } from '../view.js';
+import { BoundElement, define } from './bound.js';
+import { type StageViewContext, stageContext } from './stage-context.js';
+
+export type { StageContext } from './stage-context.js';
+export { stageContext } from './stage-context.js';
+
+/**
+ * The regions of the built-in chrome a stage has.
+ *
+ * @experimental Like the stage, in 0.6.
+ */
+export const STAGE_REGIONS: readonly StageRegion[] = [
+  'dock',
+  'transport',
+  'legend',
+  'zoom',
+  'minimap',
+];
+
+type MutableStagePanels = { -readonly [R in StageRegion]?: PanelState };
+
+const VERSIONS: readonly StageVersion[] = ['before', 'after'];
+
+/** A version from an attribute or a property; anything else follows the mode, with a warning. */
+function toVersion(value: unknown): StageVersion | null {
+  if (value === null || value === undefined || value === '') return null;
+  if (VERSIONS.includes(value as StageVersion)) return value as StageVersion;
+  console.warn(`[kgdiff] <kgdiff-stage> ignoring version ${JSON.stringify(value)} (before, after)`);
+  return null;
+}
+
+/** Panels from an attribute or a property, keeping the stage's regions (warning about the rest). */
+function stagePanels(value: unknown): StagePanels {
+  const { panels, invalid } = toPanels(value);
+  const out: MutableStagePanels = {};
+  for (const [region, state] of Object.entries(panels)) {
+    if (STAGE_REGIONS.includes(region as StageRegion)) out[region as StageRegion] = state;
+    else invalid.push(`${region}:${state}`);
+  }
+  if (invalid.length > 0) {
+    console.warn(`[kgdiff] <kgdiff-stage> ignoring invalid panels: ${invalid.join(' ')}`);
+  }
+  return out;
+}
+
+/**
+ * The canvas of the root it is bound to: the graph, the hover tooltip, the swipe divider, the
+ * replay caption and the canvas chrome (view dock, replay transport, legend, zoom buttons and
+ * minimap). Each stage is a view of its own: a root draws every stage bound to it, each with its
+ * own camera, sharing the selection, the hover, the filters and the search; `version` pins one
+ * to a version.
+ *
+ * Five named slots take the page's content over the canvas. The stage positions it (12–16 px
+ * from the edges, stacked further from the corner than the chrome there), and every slotted
+ * element is an obstacle: fits and flights frame the graph in the free part of the canvas. A
+ * chrome element slotted in replaces the built-in region of its kind; `panels` keeps applying
+ * to the rest. Content positioned some other way registers itself with `registerObstacle`, on
+ * the element or on the stage context (`kgdiff.stage/1`) it provides to its descendants.
+ *
+ * @tagname kgdiff-stage
+ * @slot top-start - The page's content in the top left corner, below the version chip.
+ * @slot top-end - The page's content in the top right corner.
+ * @slot bottom-start - The page's content in the bottom left corner, above the legend.
+ * @slot bottom-center - The page's content above the view dock and the transport.
+ * @slot bottom-end - The page's content in the bottom right corner, above the zoom buttons and the minimap.
+ * @experimental In 0.6; stable from 0.7 (RFC 0001, decision 7).
+ */
+export class KgdiffStage extends BoundElement implements KgdiffStageElement {
+  static override get observedAttributes(): readonly string[] {
+    return ['for', 'panels', 'version'];
+  }
+
+  protected readonly name = 'stage';
+  #stage: Stage | null = null;
+  /** The page's `panels`, and what the user changed since (the legend's head). */
+  #declared: StagePanels = {};
+  readonly #runtime: MutableStagePanels = {};
+  #reflecting = false;
+  #version: StageVersion | null = null;
+  #view: StageView | null = null;
+  readonly #viewListeners = new Set<(view: StageView | null) => void>();
+  /** Registered obstacles, kept across rebinding (the stage is rebuilt then). */
+  readonly #obstacles = new Map<Element, () => void>();
+
+  get panels(): StagePanels {
+    return { ...this.#declared };
+  }
+
+  set panels(value: StagePanels | string | null) {
+    const panels = stagePanels(value);
+    this.#reflecting = true;
+    try {
+      const text = formatPanels(panels);
+      if (text) this.setAttribute('panels', text);
+      else this.removeAttribute('panels');
+    } finally {
+      this.#reflecting = false;
+    }
+    this.#declare(panels);
+  }
+
+  /**
+   * The version this stage draws whatever the mode, reflected to the `version` attribute:
+   * `before` or `after` (side by side with another stage of the same root), or null to follow
+   * the root's mode (overlay, swipe, replay).
+   */
+  get version(): StageVersion | null {
+    return this.#version;
+  }
+
+  set version(value: StageVersion | null) {
+    const v = toVersion(value);
+    this.#reflecting = true;
+    try {
+      if (v) this.setAttribute('version', v);
+      else this.removeAttribute('version');
+    } finally {
+      this.#reflecting = false;
+    }
+    this.#setVersion(v);
+  }
+
+  override attributeChangedCallback(name: string, old: string | null, value: string | null): void {
+    if (this.#reflecting) return;
+    if (name === 'panels') this.#declare(stagePanels(value ?? ''));
+    else if (name === 'version') this.#setVersion(toVersion(value));
+    else super.attributeChangedCallback(name, old, value);
+  }
+
+  protected override upgradedProperties(): readonly string[] {
+    return [...super.upgradedProperties(), 'panels', 'version'];
+  }
+
+  /** @internal This stage's view (its camera), for the dev harness and tests. */
+  get view(): StageView | null {
+    return this.#view;
+  }
+
+  #setVersion(version: StageVersion | null): void {
+    if (version === this.#version) return;
+    this.#version = version;
+    if (this.#view) this.#view.version = version;
+    this.#stage?.setVersion(version);
+  }
+
+  #setView(view: StageView | null): void {
+    this.#view = view;
+    for (const listener of this.#viewListeners) listener(view);
+  }
+
+  /** A region the page declares another state for gives way; the same again changes nothing. */
+  #declare(panels: StagePanels): void {
+    for (const r of STAGE_REGIONS) if (panels[r] !== this.#declared[r]) delete this.#runtime[r];
+    this.#declared = panels;
+    this.#applyPanels();
+  }
+
+  #applyPanels(): void {
+    const states = { ...DEFAULT_PANELS, ...this.#declared, ...this.#runtime };
+    this.#stage?.setPanels(states);
+  }
+
+  registerObstacle(element: Element): () => void {
+    if (!this.#obstacles.has(element)) {
+      this.#obstacles.set(element, this.#stage?.registerObstacle(element) ?? (() => undefined));
+    }
+    return () => {
+      this.#obstacles.get(element)?.();
+      this.#obstacles.delete(element);
+    };
+  }
+
+  protected build(ui: UiContext, ctx: ViewerContext, release: (fn: () => void) => void): Region {
+    release(
+      provideContext(this, stageContext, (): StageViewContext => {
+        const stage = this;
+        return {
+          stage,
+          get root() {
+            return stage.context;
+          },
+          registerObstacle: (el) => stage.registerObstacle(el),
+          get view() {
+            return stage.#view;
+          },
+          watchView: (listener) => {
+            stage.#viewListeners.add(listener);
+            listener(stage.#view);
+            return () => {
+              stage.#viewListeners.delete(listener);
+            };
+          },
+        };
+      }),
+    );
+    // The user opening or folding the legend holds until the page declares the legend again.
+    const stage = new Stage(
+      {
+        ...ui,
+        setPanel: (region, state) => {
+          if (STAGE_REGIONS.includes(region as StageRegion)) {
+            this.#runtime[region as StageRegion] = state;
+          }
+        },
+      },
+      true,
+    );
+    this.#stage = stage;
+    this.#applyPanels();
+    for (const el of this.#obstacles.keys()) this.#obstacles.set(el, stage.registerObstacle(el));
+    release(() => {
+      this.#stage = null;
+    });
+    stage.setChrome('full', true);
+    // One of the page's regions, not its main landmark.
+    stage.asRegion();
+    this.shadow.append(stage.el);
+    // Content slotted before the stage was built.
+    stage.slotted();
+    // This stage's own view of the shared session: canvas, camera, framing, minimap.
+    const view = new StageView(ctx.controller);
+    view.version = this.#version;
+    stage.view = view;
+    stage.setVersion(this.#version);
+    release(ctx.controller.addView(view));
+    // The stage adds its own minimap to the view (unless a slotted one replaces it).
+    view.attach(stage.canvasHost, null);
+    view.setChrome(() => stage.chromeLayout());
+    this.#setView(view);
+    release(() => {
+      this.#setView(null);
+      view.setChrome(null);
+      view.detach();
+    });
+    // The graph takes keyboard focus (shortcuts apply where focus is), also on click.
+    const canvas = stage.canvasHost.querySelector('canvas');
+    if (canvas) {
+      canvas.tabIndex = 0;
+      const focusCanvas = (): void => canvas.focus({ preventScroll: true });
+      canvas.addEventListener('pointerdown', focusCanvas);
+      release(() => canvas.removeEventListener('pointerdown', focusCanvas));
+    }
+    const hover = (over: boolean) => (e: PointerEvent) => {
+      if (e.pointerType !== 'touch') ctx.hover(over);
+    };
+    stage.el.addEventListener('pointerenter', hover(true));
+    stage.el.addEventListener('pointerleave', hover(false));
+    release(() => ctx.hover(false));
+    if (typeof ResizeObserver === 'function') {
+      const ro = new ResizeObserver(() => {
+        stage.layout();
+        view.layoutChanged();
+      });
+      ro.observe(stage.el);
+      release(() => ro.disconnect());
+    }
+    document.fonts?.ready?.then(() => this.#stage?.layout()).catch(() => undefined);
+    return stage;
+  }
+}
+
+define('kgdiff-stage', KgdiffStage);
+
+declare global {
+  interface HTMLElementTagNameMap {
+    /** @experimental In 0.6. */
+    'kgdiff-stage': KgdiffStageElement;
+  }
+}

package/src/elements/title.ts

@@ -0,0 +1,34 @@
+/**
+ * `<kgdiff-title>` (RFC 0001 §3), documented on its class. Importing this module defines it.
+ */
+import type { Region } from '../bind.js';
+import type { KgdiffBoundElement } from '../index.js';
+import type { UiContext } from '../ui/context.js';
+import { Title } from '../ui/header.js';
+import { BoundElement, define } from './bound.js';
+
+/**
+ * The kgdiff mark and the root's compared names and versions. Binds to a root (`for`, `htmlFor`,
+ * `rootElement`). Slotted into a `<kgdiff-viewer>` it replaces the title over its canvas.
+ *
+ * @tagname kgdiff-title
+ * @experimental In 0.6; stable from 0.7 (RFC 0001, decision 7).
+ */
+export class KgdiffTitle extends BoundElement implements KgdiffBoundElement {
+  protected readonly name = 'title';
+
+  protected build(ui: UiContext): Region {
+    const title = new Title(ui);
+    this.shadow.append(title.el);
+    return title;
+  }
+}
+
+define('kgdiff-title', KgdiffTitle);
+
+declare global {
+  interface HTMLElementTagNameMap {
+    /** @experimental In 0.6. */
+    'kgdiff-title': KgdiffBoundElement;
+  }
+}

package/src/elements/transport.ts

@@ -0,0 +1,39 @@
+/**
+ * `<kgdiff-transport>` (RFC 0001 §3), documented on its class. Importing this module defines it.
+ */
+import type { Region } from '../bind.js';
+import { h } from '../dom.js';
+import type { KgdiffBoundElement } from '../index.js';
+import type { UiContext } from '../ui/context.js';
+import { Transport } from '../ui/transport.js';
+import { BoundElement, define } from './bound.js';
+
+/**
+ * The replay transport of the root's diff. Previous, play / pause, next, the scrubber with one tick
+ * per change, the position and the speed; at the end, "Replay finished · Restart" above it. Shown
+ * in replay mode only. Binds to a root (`for`, `htmlFor`, `rootElement`). Slotted into a
+ * `<kgdiff-stage>` (`slot="bottom-center"`, say) it replaces the stage's built-in transport; placed
+ * anywhere else it is not kept clear of fits and flights unless registered. Importing this module
+ * defines it.
+ *
+ * @tagname kgdiff-transport
+ * @experimental In 0.6; stable from 0.7 (RFC 0001, decision 7).
+ */
+export class KgdiffTransport extends BoundElement implements KgdiffBoundElement {
+  protected readonly name = 'transport';
+
+  protected build(ui: UiContext): Region {
+    const transport = new Transport(ui);
+    this.shadow.append(h('div', { class: 'stack' }, transport.finished, transport.el));
+    return transport;
+  }
+}
+
+define('kgdiff-transport', KgdiffTransport);
+
+declare global {
+  interface HTMLElementTagNameMap {
+    /** @experimental In 0.6. */
+    'kgdiff-transport': KgdiffBoundElement;
+  }
+}

package/src/elements/view-bound.ts

@@ -0,0 +1,118 @@
+/**
+ * What the chrome that acts on one view shares (`<kgdiff-zoom>`, `<kgdiff-minimap>`; RFC 0001
+ * §3): it binds to a stage, not to a root. The nearest `<kgdiff-stage>` around it (across
+ * shadow roots, through the stage context `kgdiff.stage/1`), or the one its `stage="<id>"`
+ * names anywhere on the page (a `<kgdiff-viewer>` is the stage of what it holds, and can be
+ * named too); a stage defined or bound later is found then. It shows what the
+ * stage's root says (language, tokens), acts on the stage's view, and follows the stage when it
+ * binds again (a new view).
+ */
+import type { Region } from '../bind.js';
+import type { KgdiffRootElement, KgdiffStageElement, KgdiffViewerElement } from '../index.js';
+import type { ElementName } from '../styles.js';
+import type { UiContext } from '../ui/context.js';
+import type { StageView } from '../view.js';
+import { bindContext, mount } from './bound.js';
+import { type StageViewContext, stageContext } from './stage-context.js';
+
+/** @experimental The base of the chrome elements that act on a stage's view, in 0.6. */
+export abstract class ViewBoundElement extends HTMLElement {
+  static get observedAttributes(): readonly string[] {
+    return ['stage'];
+  }
+
+  protected readonly shadow: ShadowRoot;
+  #stage: StageViewContext | null = null;
+  /** Undone when the element unbinds from its stage. */
+  readonly #release: (() => void)[] = [];
+  /** Undone when the stage's view or root changes (the region is built again). */
+  readonly #regionRelease: (() => void)[] = [];
+
+  constructor() {
+    super();
+    this.shadow = this.attachShadow({ mode: 'open' });
+  }
+
+  /** The element's name after `kgdiff-` (its host rules). */
+  protected abstract readonly name: ElementName;
+
+  /** Build the region in the shadow root, for `view`; `release` collects what to undo. */
+  protected abstract build(
+    ui: UiContext,
+    view: StageView,
+    release: (fn: () => void) => void,
+  ): Region;
+
+  /**
+   * Reflects the `stage` attribute: the id of the stage to act on; '' (no attribute) for the
+   * nearest one around the element. Changing it binds again.
+   */
+  get stage(): string {
+    return this.getAttribute('stage') ?? '';
+  }
+
+  set stage(value: string) {
+    const id = String(value);
+    if (id === '') this.removeAttribute('stage');
+    else this.setAttribute('stage', id);
+  }
+
+  /** The stage this element acts on, or null while it waits for one. */
+  get stageElement(): KgdiffStageElement | KgdiffViewerElement | null {
+    return this.#stage?.stage ?? null;
+  }
+
+  /** The root whose session the stage shows, or null while either waits. */
+  get rootElement(): KgdiffRootElement | null {
+    return (this.#stage?.root?.host as KgdiffRootElement | undefined) ?? null;
+  }
+
+  connectedCallback(): void {
+    // Set before the element was defined: it shadows the accessor.
+    if (Object.hasOwn(this, 'stage')) {
+      const value = (this as unknown as Record<string, unknown>).stage;
+      delete (this as unknown as Record<string, unknown>).stage;
+      this.stage = String(value);
+    }
+    this.#bind();
+  }
+
+  disconnectedCallback(): void {
+    this.#unbind();
+  }
+
+  attributeChangedCallback(name: string, old: string | null, value: string | null): void {
+    if (name === 'stage' && old !== value && this.isConnected) {
+      this.#unbind();
+      this.#bind();
+    }
+  }
+
+  #bind(): void {
+    const cancel = bindContext(this, stageContext, this.getAttribute('stage'), (ctx) => {
+      const stage = ctx as StageViewContext;
+      this.#stage = stage;
+      this.#release.push(stage.watchView((view) => this.#build(view)));
+    });
+    this.#release.push(cancel);
+  }
+
+  /** The stage has a view (again), or lost it: show the region for it. */
+  #build(view: StageView | null): void {
+    for (const fn of this.#regionRelease.splice(0)) fn();
+    this.shadow.replaceChildren();
+    const root = this.#stage?.root;
+    if (!view || !root) return;
+    const release = (fn: () => void): void => {
+      this.#regionRelease.push(fn);
+    };
+    mount(this, this.shadow, this.name, root, (ui) => this.build(ui, view, release), release);
+  }
+
+  #unbind(): void {
+    this.#stage = null;
+    for (const fn of this.#regionRelease.splice(0)) fn();
+    for (const fn of this.#release.splice(0)) fn();
+    this.shadow.replaceChildren();
+  }
+}

package/src/elements/view-dock.ts

@@ -0,0 +1,43 @@
+/**
+ * `<kgdiff-view-dock>` (RFC 0001 §3), documented on its class. Importing this module defines it.
+ */
+import type { Region } from '../bind.js';
+import type { KgdiffBoundElement } from '../index.js';
+import type { UiContext } from '../ui/context.js';
+import { Dock } from '../ui/dock.js';
+import { BoundElement, define } from './bound.js';
+
+/**
+ * How the root's diff is viewed. The mode (overlay, swipe, replay; keys `1`–`3`) and "Changes only"
+ * (key `4`) with its context hops and the nearest "+N" expansion. Binds to a root like the other
+ * elements (`for`, `htmlFor`, `rootElement`). Slotted into a `<kgdiff-stage>` it replaces the
+ * stage's built-in dock; placed anywhere else it is not kept clear of fits and flights unless
+ * registered (`stage.registerObstacle`).
+ *
+ * @tagname kgdiff-view-dock
+ * @experimental In 0.6; stable from 0.7 (RFC 0001, decision 7).
+ */
+export class KgdiffViewDock extends BoundElement implements KgdiffBoundElement {
+  protected readonly name = 'view-dock';
+
+  protected build(ui: UiContext, _ctx: unknown, release: (fn: () => void) => void): Region {
+    const dock = new Dock(ui);
+    this.shadow.append(dock.el);
+    if (typeof ResizeObserver === 'function') {
+      // Narrow docks drop their labels.
+      const ro = new ResizeObserver(() => dock.layout());
+      ro.observe(this);
+      release(() => ro.disconnect());
+    }
+    return dock;
+  }
+}
+
+define('kgdiff-view-dock', KgdiffViewDock);
+
+declare global {
+  interface HTMLElementTagNameMap {
+    /** @experimental In 0.6. */
+    'kgdiff-view-dock': KgdiffBoundElement;
+  }
+}