@kgdiff/viewer 0.4.0 → 0.6.0

package/src/bind.ts

@@ -0,0 +1,80 @@
+/**
+ * How regions and elements find the root whose session they show (RFC 0001 §2): the context
+ * the root provides (`kgdiff.viewer/1`), what it provides, and the binding helpers. Type-only
+ * imports of the session: an element's subpath does not pull the session in through here.
+ */
+import { createContext, requestContext } from './context.js';
+import type { Keymap } from './keyboard.js';
+import type { DiffSession, Topic } from './session.js';
+import type { FocusTarget, UiActions, UiContext } from './ui/context.js';
+
+/** Something the root renders: a region, or the layout itself. */
+export interface Region {
+  update(topics: ReadonlySet<Topic>): void;
+}
+
+/** What a root provides to the regions that bind to it. */
+export interface ViewerContext {
+  readonly controller: DiffSession;
+  readonly actions: UiActions;
+  /** The element the root's events are dispatched on and its tokens are set on. */
+  readonly host: HTMLElement;
+  /** Render `region` on every notification (in binding order); returns the detach. */
+  attach(region: Region): () => void;
+  target(name: FocusTarget, focus: () => void, available?: () => boolean): () => void;
+  focus(name: FocusTarget): boolean;
+  /** The keys bound over the default map (the root's `keymap`), or null for the default. */
+  readonly keymap: Keymap | null;
+  /** The keyboard map, for a key event that reached the root. */
+  handleKey(e: KeyboardEvent): void;
+  /** A key pressed in an element bound with `for` (outside the root): the root's rules apply. */
+  forwardKey(e: KeyboardEvent): void;
+  /** The root's token set as a sheet of `doc` (for elements outside the root's subtree). */
+  tokens(doc: Document): CSSStyleSheet;
+  /** The pointer entered or left the graph (holds a looping replay with `pause-on-hover`). */
+  hover(over: boolean): void;
+}
+
+export const viewerContext = createContext<ViewerContext>('kgdiff.viewer/1');
+
+/** Key events an element forwarded to its root: they belong to that root alone. */
+const forwarded = new WeakSet<Event>();
+
+/** Forward `e` to `ctx`'s root; no other root acts on it, whether it was handled or not. */
+export function forwardKey(ctx: ViewerContext, e: KeyboardEvent): void {
+  forwarded.add(e);
+  ctx.forwardKey(e);
+}
+
+/** Whether `e` was forwarded to a root by an element bound with `for`. */
+export function wasForwarded(e: Event): boolean {
+  return forwarded.has(e);
+}
+
+/** The UI context of a region placed in `root` (its shadow tree), bound to `ctx`. */
+export function uiContext(ctx: ViewerContext, root: ShadowRoot): UiContext {
+  return {
+    ...ctx.actions,
+    controller: ctx.controller,
+    root,
+    target: (name, focus, available) => ctx.target(name, focus, available),
+    focus: (name) => ctx.focus(name),
+    keymap: () => ctx.keymap,
+  };
+}
+
+/**
+ * Bind a region to the root nearest `anchor` (an element where the region is placed): `make`
+ * builds it once the root answers, and the root renders it from then on.
+ */
+export function bindRegion<R extends Region>(anchor: Element, make: (ui: UiContext) => R): R {
+  const bound: { region?: R } = {};
+  requestContext(anchor, viewerContext, (ctx) => {
+    if (bound.region) return;
+    bound.region = make(uiContext(ctx, anchor.getRootNode() as ShadowRoot));
+    ctx.attach(bound.region);
+  });
+  // The default layout binds its regions to the root it owns, which answers at once.
+  if (!bound.region) throw new Error('[kgdiff] a region found no root to bind to.');
+  return bound.region;
+}

package/src/context.ts

@@ -0,0 +1,106 @@
+/**
+ * The Web Components community context protocol
+ * (https://github.com/webcomponents-cg/community-protocols/blob/main/proposals/context.md),
+ * without dependencies: how the viewer's regions find the root whose session they show
+ * (RFC 0001 §2).
+ *
+ * A consumer dispatches a `context-request` event (bubbling, composed: it crosses shadow roots
+ * on its way up); the nearest provider of that context answers through the callback and stops
+ * the event. Requests nobody answered reach `document`, where they wait; a provider that
+ * connects later announces itself with `context-provider` and the waiting requests are sent
+ * again, so definition and connection order do not matter. A consumer outside the provider's
+ * subtree sends its request through an element inside it (`via`: the root named by `for`).
+ */
+
+export interface Context<T> {
+  /**
+   * `Symbol.for(name)`: equal across copies of the library on one page (an IIFE report bundle
+   * next to an ESM build), so a component of one copy finds the root of another. The name is
+   * versioned when the provided value changes incompatibly.
+   */
+  readonly key: symbol;
+  /** Carries the value type only. */
+  readonly __value?: T;
+}
+
+export const createContext = <T>(name: string): Context<T> => ({ key: Symbol.for(name) });
+
+export class ContextRequestEvent<T> extends Event {
+  constructor(
+    readonly context: Context<T>,
+    /** The consumer, which may differ from the element the event is dispatched on (`via`). */
+    readonly consumer: Element,
+    readonly callback: (value: T) => void,
+  ) {
+    super('context-request', { bubbles: true, composed: true });
+  }
+}
+
+export class ContextProviderEvent<T> extends Event {
+  constructor(readonly context: Context<T>) {
+    super('context-provider', { bubbles: true, composed: true });
+  }
+}
+
+interface Waiting {
+  readonly context: Context<unknown>;
+  readonly consumer: Element;
+  readonly via: EventTarget;
+  readonly callback: (value: unknown) => void;
+}
+
+const waiting = new Set<Waiting>();
+let collecting = false;
+
+/** Keep the requests nobody answered, and send them again when a provider connects. */
+function collect(): void {
+  if (collecting || typeof document === 'undefined') return;
+  collecting = true;
+  document.addEventListener('context-request', (e) => {
+    // Consumers that left the document since they asked are forgotten, closures and all.
+    for (const w of waiting) if (!w.consumer.isConnected) waiting.delete(w);
+    const r = e as ContextRequestEvent<unknown>;
+    waiting.add({
+      context: r.context,
+      consumer: r.consumer,
+      via: e.composedPath()[0] ?? r.consumer,
+      callback: r.callback,
+    });
+  });
+  document.addEventListener('context-provider', (e) => {
+    const key = (e as ContextProviderEvent<unknown>).context.key;
+    for (const w of [...waiting]) {
+      if (w.context.key !== key) continue;
+      waiting.delete(w);
+      // Unanswered again: it waits again on its way through `document`.
+      if (w.consumer.isConnected) {
+        w.via.dispatchEvent(new ContextRequestEvent(w.context, w.consumer, w.callback));
+      }
+    }
+  });
+}
+
+/** Ask for `context` for `consumer`, through `via` (an element of the provider's subtree). */
+export function requestContext<T>(
+  consumer: Element,
+  context: Context<T>,
+  callback: (value: T) => void,
+  via: Element | null = null,
+): void {
+  collect();
+  (via ?? consumer).dispatchEvent(new ContextRequestEvent(context, consumer, callback));
+}
+
+/** Answer requests for `context` reaching `host`; returns the function that stops answering. */
+export function provideContext<T>(host: Element, context: Context<T>, value: () => T): () => void {
+  collect();
+  const answer = (e: Event): void => {
+    const r = e as ContextRequestEvent<T>;
+    if (r.context?.key !== context.key) return;
+    e.stopPropagation();
+    r.callback(value());
+  };
+  host.addEventListener('context-request', answer);
+  host.dispatchEvent(new ContextProviderEvent(context));
+  return () => host.removeEventListener('context-request', answer);
+}