@kgdiff/viewer 0.4.0 → 0.6.0

package/src/elements/actions.ts

@@ -0,0 +1,94 @@
+/**
+ * `<kgdiff-actions>` (RFC 0001 §3), documented on its class. Importing this module defines it.
+ */
+import type { Region, ViewerContext } from '../bind.js';
+import { isOpen } from '../dom.js';
+import type { KgdiffBoundElement } from '../index.js';
+import type { UiContext } from '../ui/context.js';
+import { Actions } from '../ui/header.js';
+import { HelpDialog, Menu } from '../ui/popovers.js';
+import { BoundElement, define } from './bound.js';
+
+/**
+ * The appearance menu (theme, color palette, language: the root's `theme`, `palette` and `locale`)
+ * and the keyboard shortcuts dialog, which `?` opens too. Binds to a root (`for`, `htmlFor`,
+ * `rootElement`); bound to a `<kgdiff-viewer>` it has the sidebar toggle too (a composed root has
+ * no sidebar). Slotted into a viewer it replaces the actions over its canvas.
+ *
+ * @tagname kgdiff-actions
+ * @experimental In 0.6; stable from 0.7 (RFC 0001, decision 7).
+ */
+export class KgdiffActions extends BoundElement implements KgdiffBoundElement {
+  protected readonly name = 'actions';
+
+  protected build(ui: UiContext, ctx: ViewerContext, release: (fn: () => void) => void): Region {
+    let menu: Menu | null = null;
+    let help: HelpDialog | null = null;
+    let actions: Actions | null = null;
+    const toggle = (open?: boolean): void => {
+      if (!menu || !actions) return;
+      const next = open ?? !menu.open;
+      if (next) menu.show(actions.menuButton);
+      else menu.hide(false);
+      actions.setMenuState(next);
+    };
+    // The menu and the dialog are this element's: they open here, not in the root's layout.
+    const local: UiContext = { ...ui, toggleMenu: toggle, openHelp: () => help?.show() };
+    // The sidebar toggle where the root has a sidebar (a `<kgdiff-viewer>`); none in a
+    // composed root, where `\` does nothing.
+    const hasSidebar = ui.hasSidebar;
+    menu = new Menu(local);
+    help = new HelpDialog(local, hasSidebar ? [] : ['sidebar']);
+    actions = new Actions(local, hasSidebar !== undefined);
+    actions.attachMenu(menu.el);
+    const sidebar = (): void => {
+      const button = actions?.sidebarButton;
+      if (!button || !hasSidebar) return;
+      button.hidden = !hasSidebar();
+      actions?.setSidebarState(ui.sidebarOpen());
+    };
+    if (hasSidebar) {
+      // The viewer reports every change of its panels, the sidebar's folds included.
+      sidebar();
+      ctx.host.addEventListener('kgdiff-layout', sidebar);
+      release(() => ctx.host.removeEventListener('kgdiff-layout', sidebar));
+    }
+    this.shadow.append(actions.el, help.el);
+    const shown = actions;
+    const dialog = help;
+    const popover = menu;
+    // `?` opens this element's dialog (the root's `help` target).
+    ui.target(
+      'help',
+      () => dialog.show(),
+      () => isOpen(shown.el),
+    );
+    // The menu closes on Escape by itself: keep the button's state up with it.
+    popover.el.addEventListener('keydown', () =>
+      queueMicrotask(() => shown.setMenuState(popover.open)),
+    );
+    const outside = (e: PointerEvent): void => {
+      if (!popover.open) return;
+      const path = e.composedPath();
+      if (!path.includes(popover.el) && !path.includes(shown.menuButton)) toggle(false);
+    };
+    document.addEventListener('pointerdown', outside);
+    release(() => document.removeEventListener('pointerdown', outside));
+    return {
+      update: (topics) => {
+        shown.update(topics);
+        if (popover.open && (topics.has('locale') || topics.has('theme'))) popover.render();
+        if (dialog.open && topics.has('locale')) dialog.render();
+      },
+    };
+  }
+}
+
+define('kgdiff-actions', KgdiffActions);
+
+declare global {
+  interface HTMLElementTagNameMap {
+    /** @experimental In 0.6. */
+    'kgdiff-actions': KgdiffBoundElement;
+  }
+}

package/src/elements/bound.ts

@@ -0,0 +1,247 @@
+/**
+ * What the elements bound to a root share (RFC 0001 §2–§6): finding the root, in every
+ * topology, and living with it.
+ *
+ * - **Binding.** The nearest `<kgdiff-root>` (or `<kgdiff-viewer>`) around the element, across
+ *   shadow roots, or the one named by `for="<id>"` anywhere on the page. A root that is defined
+ *   or connected later is found then (the context protocol replays the request; `for` waits
+ *   for a root of that id to announce itself). Changing `for` binds again.
+ * - **Rendering.** The element builds its region in its own shadow root once bound, and the root
+ *   renders it on every notification from then on.
+ * - **Outside the root's subtree** (`for`): the element adopts the root's token set (inside,
+ *   tokens are inherited, page overrides on the root included) and forwards its key presses to
+ *   the root, which owns the keyboard map.
+ */
+import { forwardKey, type Region, uiContext, type ViewerContext, viewerContext } from '../bind.js';
+import { type Context, type ContextProviderEvent, requestContext } from '../context.js';
+import type { KgdiffBoundElement, KgdiffRootElement } from '../index.js';
+import { type ElementName, elementSheet, stylesheet } from '../styles.js';
+import { ALL_TOPICS } from '../topics.js';
+import type { UiContext } from '../ui/context.js';
+
+/** Whether `el` is inside `host`'s subtree, across shadow roots. */
+function inside(el: Element, host: Element): boolean {
+  for (let n: Node | null = el; n; ) {
+    if (n === host) return true;
+    n = n.parentNode ?? ((n as Partial<ShadowRoot>).host as Node | undefined) ?? null;
+  }
+  return false;
+}
+
+/** The element of `id` as `el` sees it: in its own tree first, then in the document. */
+function byId(el: Element, id: string): Element | null {
+  const tree = el.getRootNode() as { getElementById?: (id: string) => Element | null };
+  return tree.getElementById?.(id) ?? el.ownerDocument.getElementById(id);
+}
+
+/**
+ * Find the provider of `context` for `consumer`: the nearest one around it when `id` is empty,
+ * else the element of that id as `consumer` sees it (its own tree first, then the document),
+ * now, once that element provides `context` (the protocol replays the request), or once a
+ * provider of that id announces itself. `answer` gets the first value only, and none after the
+ * returned function cancels (a rebinding or a disconnection).
+ */
+export function bindContext<T>(
+  consumer: Element,
+  context: Context<T>,
+  id: string | null,
+  answer: (value: T) => void,
+): () => void {
+  let live = true;
+  const once = (value: T): void => {
+    if (!live) return;
+    live = false;
+    answer(value);
+  };
+  if (!id) {
+    requestContext(consumer, context, once);
+    return () => {
+      live = false;
+    };
+  }
+  const named = byId(consumer, id);
+  if (named) {
+    requestContext(consumer, context, once, named);
+    return () => {
+      live = false;
+    };
+  }
+  // No element of that id yet: wait for a provider of that id to announce itself.
+  const onProvider = (e: Event): void => {
+    const host = e.composedPath()[0];
+    if ((e as ContextProviderEvent<unknown>).context?.key !== context.key) return;
+    if (!(host instanceof Element) || host.id !== id) return;
+    document.removeEventListener('context-provider', onProvider);
+    requestContext(consumer, context, once, host);
+  };
+  document.addEventListener('context-provider', onProvider);
+  return () => {
+    live = false;
+    document.removeEventListener('context-provider', onProvider);
+  };
+}
+
+/** Define `name` once (another copy of the library may have defined it first). */
+export function define(name: string, ctor: CustomElementConstructor): void {
+  if (typeof customElements !== 'undefined' && customElements.get(name) === undefined) {
+    customElements.define(name, ctor);
+  }
+}
+
+/**
+ * Show `build`'s region in `host`'s shadow root, bound to the root `ctx`: the shared sheet, the
+ * host rules and, outside the root's subtree, its token set (kept up with theme changes); the
+ * session's language; the root's notifications; and, outside its subtree, the keys pressed in
+ * `host`, forwarded to the root (which owns the keyboard map). `release` collects the undo.
+ */
+export function mount(
+  host: HTMLElement,
+  shadow: ShadowRoot,
+  name: ElementName,
+  ctx: ViewerContext,
+  build: (ui: UiContext) => Region,
+  release: (fn: () => void) => void,
+): void {
+  const outside = !inside(host, ctx.host);
+  const adopt = (): void => {
+    const doc = host.ownerDocument;
+    shadow.adoptedStyleSheets = [
+      stylesheet(doc),
+      elementSheet(doc, name),
+      ...(outside ? [ctx.tokens(doc)] : []),
+    ];
+  };
+  const lang = (): void => {
+    for (const el of shadow.children) el.setAttribute('lang', ctx.controller.locale);
+  };
+  const ui: UiContext = {
+    ...uiContext(ctx, shadow),
+    // Focus targets go when the element does.
+    target: (target, focus, available) => {
+      const off = ctx.target(target, focus, available);
+      release(off);
+      return off;
+    },
+  };
+  adopt();
+  const region = build(ui);
+  release(
+    ctx.attach({
+      update: (topics) => {
+        if (outside && topics.has('theme')) adopt();
+        if (topics.has('locale') || topics.has('status')) lang();
+        region.update(topics);
+      },
+    }),
+  );
+  if (outside) {
+    // The root owns the keyboard map; keys pressed here would not reach it (and a root this
+    // element sits in must leave them alone).
+    const forward = (e: KeyboardEvent): void => forwardKey(ctx, e);
+    host.addEventListener('keydown', forward);
+    release(() => host.removeEventListener('keydown', forward));
+  }
+  lang();
+  try {
+    region.update(ALL_TOPICS);
+  } catch (error) {
+    console.error('[kgdiff] render failed:', error);
+  }
+}
+
+/** @experimental The base of the bound elements (`KgdiffBoundElement`), in 0.6. */
+export abstract class BoundElement extends HTMLElement implements KgdiffBoundElement {
+  static get observedAttributes(): readonly string[] {
+    return ['for'];
+  }
+
+  protected readonly shadow: ShadowRoot;
+  #ctx: ViewerContext | null = null;
+  readonly #release: (() => 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, bound to `ui`; `release` collects what to undo. */
+  protected abstract build(
+    ui: UiContext,
+    ctx: ViewerContext,
+    release: (fn: () => void) => void,
+  ): Region;
+
+  /** The root this element is bound to, or null while it waits for one. */
+  protected get context(): ViewerContext | null {
+    return this.#ctx;
+  }
+
+  /** Properties a page may set before the element is defined (they shadow the accessors). */
+  protected upgradedProperties(): readonly string[] {
+    return ['htmlFor'];
+  }
+
+  /**
+   * Reflects `for`, as on `<label>` and `<output>`: the id of the root to show; '' (no
+   * attribute) for the nearest one.
+   */
+  get htmlFor(): string {
+    return this.getAttribute('for') ?? '';
+  }
+
+  set htmlFor(value: string) {
+    const id = String(value);
+    if (id === '') this.removeAttribute('for');
+    else this.setAttribute('for', id);
+  }
+
+  /** The root this element shows, or null while it waits for one. */
+  get rootElement(): KgdiffRootElement | null {
+    return (this.#ctx?.host as KgdiffRootElement | undefined) ?? null;
+  }
+
+  connectedCallback(): void {
+    for (const prop of this.upgradedProperties()) {
+      if (!Object.hasOwn(this, prop)) continue;
+      const value = (this as unknown as Record<string, unknown>)[prop];
+      delete (this as unknown as Record<string, unknown>)[prop];
+      (this as unknown as Record<string, unknown>)[prop] = value;
+    }
+    this.#bind();
+  }
+
+  disconnectedCallback(): void {
+    this.#unbind();
+  }
+
+  attributeChangedCallback(name: string, old: string | null, value: string | null): void {
+    if (name === 'for' && old !== value && this.isConnected) {
+      this.#unbind();
+      this.#bind();
+    }
+  }
+
+  #bind(): void {
+    const cancel = bindContext(this, viewerContext, this.getAttribute('for'), (ctx) =>
+      this.#attach(ctx),
+    );
+    this.#release.push(cancel);
+  }
+
+  #attach(ctx: ViewerContext): void {
+    this.#ctx = ctx;
+    const release = (fn: () => void): void => {
+      this.#release.push(fn);
+    };
+    mount(this, this.shadow, this.name, ctx, (ui) => this.build(ui, ctx, release), release);
+  }
+
+  #unbind(): void {
+    this.#ctx = null;
+    for (const fn of this.#release.splice(0)) fn();
+    this.shadow.replaceChildren();
+  }
+}

package/src/elements/change-detail.ts

@@ -0,0 +1,34 @@
+/**
+ * `<kgdiff-change-detail>` (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 { Detail } from '../ui/detail.js';
+import { BoundElement, define } from './bound.js';
+
+/**
+ * The selected change, or the selected node: what changed first, then the unchanged rest; prev /
+ * next and the reviewed toggle. A labelled region.
+ *
+ * @tagname kgdiff-change-detail
+ * @experimental In 0.6; stable from 0.7 (RFC 0001, decision 7).
+ */
+export class KgdiffChangeDetail extends BoundElement implements KgdiffBoundElement {
+  protected readonly name = 'change-detail';
+
+  protected build(ui: UiContext): Region {
+    const detail = new Detail(ui);
+    this.shadow.append(detail.el);
+    return detail;
+  }
+}
+
+define('kgdiff-change-detail', KgdiffChangeDetail);
+
+declare global {
+  interface HTMLElementTagNameMap {
+    /** @experimental In 0.6. */
+    'kgdiff-change-detail': KgdiffBoundElement;
+  }
+}

package/src/elements/change-list.ts

@@ -0,0 +1,51 @@
+/**
+ * `<kgdiff-change-list>` (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 { ChangeList } from '../ui/change-list.js';
+import type { UiContext } from '../ui/context.js';
+import { BoundElement, define } from './bound.js';
+
+/**
+ * The "Changes" title with the count and review progress, and the changes grouped by phase (a
+ * virtualized listbox; `j` / `k` / `x`, Enter, Home / End). A labelled region. While a search is
+ * active (the session's query is not blank) its rows step aside. Registers itself as the root's
+ * `list` focus target (choosing a search result moves focus here).
+ *
+ * @tagname kgdiff-change-list
+ * @experimental In 0.6; stable from 0.7 (RFC 0001, decision 7).
+ */
+export class KgdiffChangeList extends BoundElement implements KgdiffBoundElement {
+  protected readonly name = 'change-list';
+
+  protected build(ui: UiContext, _ctx: unknown, release: (fn: () => void) => void): Region {
+    const list = new ChangeList(ui);
+    const rows = h('div', { class: 'list-wrap' }, list.sticky, list.list, list.phases);
+    this.shadow.append(
+      h(
+        'section',
+        { class: 'change-list', 'aria-labelledby': 'kg-changes-title' },
+        h('div', { class: 'sb-head' }, list.head),
+        rows,
+      ),
+    );
+    if (typeof ResizeObserver === 'function') {
+      // The list draws the rows in view: it needs its height.
+      const ro = new ResizeObserver(() => list.renderWindow());
+      ro.observe(rows);
+      release(() => ro.disconnect());
+    }
+    return list;
+  }
+}
+
+define('kgdiff-change-list', KgdiffChangeList);
+
+declare global {
+  interface HTMLElementTagNameMap {
+    /** @experimental In 0.6. */
+    'kgdiff-change-list': KgdiffBoundElement;
+  }
+}

package/src/elements/filters.ts

@@ -0,0 +1,34 @@
+/**
+ * `<kgdiff-filters>` (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 { Filters } from '../ui/filters.js';
+import { BoundElement, define } from './bound.js';
+
+/**
+ * One chip per kind of change the diff has, with its count and the legend's swatch, toggling the
+ * session's family filter, and "Show all" while a filter is on.
+ *
+ * @tagname kgdiff-filters
+ * @experimental In 0.6; stable from 0.7 (RFC 0001, decision 7).
+ */
+export class KgdiffFilters extends BoundElement implements KgdiffBoundElement {
+  protected readonly name = 'filters';
+
+  protected build(ui: UiContext): Region {
+    const filters = new Filters(ui);
+    this.shadow.append(filters.el);
+    return filters;
+  }
+}
+
+define('kgdiff-filters', KgdiffFilters);
+
+declare global {
+  interface HTMLElementTagNameMap {
+    /** @experimental In 0.6. */
+    'kgdiff-filters': KgdiffBoundElement;
+  }
+}

package/src/elements/legend.ts

@@ -0,0 +1,103 @@
+/**
+ * `<kgdiff-legend>` (RFC 0001 §3), documented on its class. Importing this module defines it.
+ */
+import type { Region } from '../bind.js';
+import type { KgdiffLegendElement, LegendVariant } from '../index.js';
+import type { UiContext } from '../ui/context.js';
+import { Legend } from '../ui/legend.js';
+import { BoundElement, define } from './bound.js';
+
+const VARIANTS: readonly LegendVariant[] = ['full', 'mini'];
+
+/**
+ * What the colors mean. `variant="full"` (the default): a card of every family's swatch and name,
+ * folded to its head until opened; `open` reflects whether it is (the user's toggle included, as on
+ * `<details>`). `variant="mini"`: one line of dots for the families the root's diff has, then the
+ * unchanged context. Binds to a root (`for`, `htmlFor`, `rootElement`). Slotted into a
+ * `<kgdiff-stage>` it replaces the stage's built-in legend; placed anywhere else it is not kept
+ * clear of fits and flights unless registered.
+ *
+ * @tagname kgdiff-legend
+ * @experimental In 0.6; stable from 0.7 (RFC 0001, decision 7).
+ */
+export class KgdiffLegend extends BoundElement implements KgdiffLegendElement {
+  static override get observedAttributes(): readonly string[] {
+    return ['for', 'variant', 'open'];
+  }
+
+  protected readonly name = 'legend';
+  #legend: Legend | null = null;
+  #reflecting = false;
+
+  /** `full` (the card) or `mini` (one line), reflected to `variant`; another value reads `full`. */
+  get variant(): LegendVariant {
+    const v = this.getAttribute('variant') as LegendVariant | null;
+    return v !== null && VARIANTS.includes(v) ? v : 'full';
+  }
+
+  set variant(value: LegendVariant) {
+    if (VARIANTS.includes(value) && value !== 'full') this.setAttribute('variant', value);
+    else this.removeAttribute('variant');
+  }
+
+  /** Whether the card is open, reflected to the boolean `open` attribute (the user's toggle too). */
+  get open(): boolean {
+    return this.hasAttribute('open');
+  }
+
+  set open(value: boolean) {
+    this.toggleAttribute('open', Boolean(value));
+  }
+
+  override attributeChangedCallback(name: string, old: string | null, value: string | null): void {
+    if (name === 'for') super.attributeChangedCallback(name, old, value);
+    else if (name === 'open' && !this.#reflecting) this.#legend?.setOpen(this.open);
+    else if (name === 'variant') this.#place();
+  }
+
+  protected override upgradedProperties(): readonly string[] {
+    return [...super.upgradedProperties(), 'variant', 'open'];
+  }
+
+  protected build(ui: UiContext): Region {
+    const legend = new Legend(ui, (open) => {
+      // The user's toggle, reflected as <details> does.
+      this.#reflecting = true;
+      try {
+        this.toggleAttribute('open', open);
+      } finally {
+        this.#reflecting = false;
+      }
+    });
+    this.#legend = legend;
+    legend.setOpen(this.open);
+    this.#place();
+    return {
+      update: (topics) => {
+        if (this.#legend === legend) legend.update(topics);
+      },
+    };
+  }
+
+  /** Show the variant asked for. */
+  #place(): void {
+    const legend = this.#legend;
+    if (!legend || !this.isConnected) return;
+    const shown = this.variant === 'mini' ? legend.mini : legend.card;
+    if (this.shadow.firstElementChild !== shown) this.shadow.replaceChildren(shown);
+  }
+
+  override disconnectedCallback(): void {
+    super.disconnectedCallback();
+    this.#legend = null;
+  }
+}
+
+define('kgdiff-legend', KgdiffLegend);
+
+declare global {
+  interface HTMLElementTagNameMap {
+    /** @experimental In 0.6. */
+    'kgdiff-legend': KgdiffLegendElement;
+  }
+}

package/src/elements/minimap.ts

@@ -0,0 +1,75 @@
+/**
+ * `<kgdiff-minimap>` (RFC 0001 §3), documented on its class. Importing this module defines it.
+ */
+import type { Region } from '../bind.js';
+import { attr, h } from '../dom.js';
+import type { KgdiffMinimapElement } from '../index.js';
+import type { UiContext } from '../ui/context.js';
+import type { StageView } from '../view.js';
+import { define } from './bound.js';
+import { ViewBoundElement } from './view-bound.js';
+
+/**
+ * An overview of one stage's view, with the part in view outlined. While the whole graph is in view
+ * it has nothing to add: it is in the custom state `overview` then (`:state(overview)`, and the
+ * read-only `overview` property). A minimap the page places stays shown
+ * (`kgdiff-minimap:state(overview) { visibility: hidden }` hides it without moving the layout); one
+ * slotted into a stage replaces the stage's own and hides as it did. Binds to the nearest
+ * `<kgdiff-stage>` around it, or to the one `stage="<id>"` names (`stage`, `stageElement`,
+ * `rootElement`). Slotted into a stage it replaces the stage's built-in minimap; placed anywhere
+ * else it is not kept clear of fits and flights unless registered.
+ *
+ * @tagname kgdiff-minimap
+ * @cssstate overview - While the whole graph is in view. A minimap the page places stays
+ *   shown; `kgdiff-minimap:state(overview) { visibility: hidden }` hides it in place.
+ *   Slotted into a stage it hides then, as the stage's own does.
+ * @experimental In 0.6; stable from 0.7 (RFC 0001, decision 7).
+ */
+export class KgdiffMinimap extends ViewBoundElement implements KgdiffMinimapElement {
+  protected readonly name = 'minimap';
+
+  /** The custom states (`:state(overview)`); null where `ElementInternals` is missing. */
+  readonly #internals: ElementInternals | null =
+    typeof this.attachInternals === 'function' ? this.attachInternals() : null;
+  #overview = false;
+
+  /** Whether the whole graph is in view: the custom state `overview` (`:state(overview)`). */
+  get overview(): boolean {
+    return this.#overview;
+  }
+
+  #setOverview(overview: boolean): void {
+    if (overview === this.#overview) return;
+    this.#overview = overview;
+    const states = this.#internals?.states;
+    if (!states) return;
+    if (overview) states.add('overview');
+    else states.delete('overview');
+  }
+
+  protected build(ui: UiContext, view: StageView, release: (fn: () => void) => void): Region {
+    const host = h('div', { class: 'minimap-host' });
+    this.shadow.append(host);
+    release(view.addMinimap(host));
+    release(() => this.#setOverview(false));
+    return {
+      update: (topics) => {
+        if (topics.has('status') || topics.has('data') || topics.has('locale')) {
+          const label = ui.tr().t('minimap.label');
+          attr(host, 'aria-label', label);
+          attr(host, 'title', label);
+        }
+        this.#setOverview(view.overview);
+      },
+    };
+  }
+}
+
+define('kgdiff-minimap', KgdiffMinimap);
+
+declare global {
+  interface HTMLElementTagNameMap {
+    /** @experimental In 0.6. */
+    'kgdiff-minimap': KgdiffMinimapElement;
+  }
+}