@kgdiff/viewer 0.5.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/controller.ts

@@ -1,482 +1,91 @@
 /**
- * The canvas side of the viewer: a `DiffSession` (state, commands, events; `session.ts`) plus
- * the one view that draws it (RFC 0001 §1: renderer, camera, framing, minimap), behind the
- * `SessionView` boundary. Phase 3 of the RFC moves this view out into a `StageView` of its own,
- * so one session can drive several canvases.
- *
- * - draws the session's view state into the renderer (and the minimap, throttled while
- *   replaying);
- * - frames what the session asks for in the free part of the canvas, clear of the chrome over
- *   it (`framing.ts`); the replay camera follows the playing hunk / chapter unless the user
- *   moved it in the last 2 s;
- * - fits a new diff once the canvas is laid out, and again on resize with `autoFit`;
- * - turns canvas hovers and clicks into session commands.
+ * The session of `<kgdiff-viewer>`: a `DiffSession` (state, commands, events; `session.ts`) with
+ * the one view of the default layout's canvas (`StageView`, `view.ts`: renderer, camera,
+ * framing, minimap) built in, so the layout and its tests address both as one object. A
+ * `<kgdiff-stage>` bound to the viewer adds a view of its own; `fit()` and `zoom()` reach all.
  */
-import type { Rect } from '@kgdiff/core';
-import {
-  type Camera,
-  type CameraState,
-  labelFootprint,
-  type Minimap,
-  type PickResult,
-  type Renderer,
-} from '@kgdiff/renderer';
-import {
-  createViewState,
-  type FocusState,
-  type FrameVisuals,
-  frameBounds,
-  type Layer,
-  type Scene,
-} from '@kgdiff/scene';
-import {
-  type ChromeLayout,
-  chromeInsets,
-  FRAME_PADDING,
-  freeView,
-  type Insets,
-  NO_INSETS,
-  zoomFit,
-} from './framing.js';
-import { renderBackend } from './renderer-port.js';
-import {
-  DiffSession,
-  padRect,
-  type SessionDeps,
-  type SessionHost,
-  type SessionView,
-} from './session.js';
+import type { Camera } from '@kgdiff/renderer';
+import type { ChromeLayout } from './framing.js';
+import { DiffSession, type SessionDeps, type SessionHost } from './session.js';
+import { StageView } from './view.js';
 
 export type { Preference, Status, Topic } from './session.js';
+export type { FitOptions } from './view.js';
+export {
+  coverage,
+  FIT_MAX_ZOOM,
+  FLY_MAX_ZOOM,
+  FOLLOW_COVERAGE,
+  OVERVIEW_COVERAGE,
+  USER_CAMERA_GRACE,
+} from './view.js';
 export type ControllerHost = SessionHost;
 export type ControllerDeps = SessionDeps;
 
-export interface FitOptions {
-  readonly animate?: boolean;
-  /** Room around the content, px (default `FRAME_PADDING`); kept for later automatic fits. */
-  readonly padding?: number;
-}
+export class ViewerController extends DiffSession {
+  /** The default layout's canvas. */
+  readonly view: StageView;
 
-/** Camera follow is suppressed this long after the user moved the camera (ms). */
-export const USER_CAMERA_GRACE = 2000;
-/** The camera follows when less than this share of the target bounds is in view. */
-export const FOLLOW_COVERAGE = 0.7;
-/** Flights to a change never zoom in further, so its neighbourhood stays readable. */
-export const FLY_MAX_ZOOM = 1.8;
-/** Fitting everything never zooms in further (the renderer's default). */
-export const FIT_MAX_ZOOM = 2.5;
-/** Minimap marks are re-rasterized at most this often while replaying (ms). */
-const MINIMAP_INTERVAL = 200;
-/** Everything counts as in view (the minimap hides) from this share of the content bounds on. */
-export const OVERVIEW_COVERAGE = 0.98;
+  constructor(host: SessionHost, deps: SessionDeps) {
+    super(host, deps);
+    this.view = new StageView(this);
+    this.addView(this.view);
+  }
 
-interface Frames {
-  main: FrameVisuals | null;
-  before: FrameVisuals | null;
-  after: FrameVisuals | null;
-}
+  /** Keep the canvas fitted (`StageView.autoFit`). */
+  get autoFit(): boolean {
+    return this.view.autoFit;
+  }
 
-/** Share of `bounds` inside `view`, in [0, 1]. */
-export function coverage(bounds: Rect, view: Rect): number {
-  const w = Math.min(bounds.x + bounds.width, view.x + view.width) - Math.max(bounds.x, view.x);
-  const h = Math.min(bounds.y + bounds.height, view.y + view.height) - Math.max(bounds.y, view.y);
-  const area = bounds.width * bounds.height;
-  if (!(area > 0)) {
-    const inside =
-      bounds.x >= view.x &&
-      bounds.x <= view.x + view.width &&
-      bounds.y >= view.y &&
-      bounds.y <= view.y + view.height;
-    return inside ? 1 : 0;
+  set autoFit(value: boolean) {
+    this.view.autoFit = value;
   }
-  return w > 0 && h > 0 ? (w * h) / area : 0;
-}
 
-export class ViewerController extends DiffSession implements SessionView {
-  /**
-   * Keep the view fitted (embeds without controls): fit again when the canvas is resized unless
-   * the user moved the camera since, and at the start of every loop.
-   */
-  autoFit = false;
-  /** Canvas clicks select (and double clicks fly); off for embeds without controls. */
-  selectOnClick = true;
-  /** The whole content is in view (the minimap has nothing to add). */
-  overview = true;
+  /** Canvas clicks select (`StageView.selectOnClick`). */
+  get selectOnClick(): boolean {
+    return this.view.selectOnClick;
+  }
 
-  #labelsInside = false;
-  #renderer: Renderer | null = null;
-  #minimap: Minimap | null = null;
-  readonly #unbind: (() => void)[] = [];
-  readonly #frames: Frames = { main: null, before: null, after: null };
-  #minimapDirty = true;
-  #lastMinimap = Number.NEGATIVE_INFINITY;
-  #lastUserCamera = Number.NEGATIVE_INFINITY;
-  #boundsCache: {
-    readonly scene: Scene;
-    readonly focus: FocusState | null;
-    readonly rect: Rect | null;
-  } | null = null;
-  #chrome: (() => ChromeLayout) | null = null;
-  /** Camera kept across detach / attach (element moved in the DOM). */
-  #savedCamera: CameraState | null = null;
-  /** A new diff is installed but has not been fitted to a laid-out canvas yet. */
-  #needsFit = false;
-  /** The user panned or zoomed since the last fit. */
-  #userMoved = false;
-  #fitPadding = FRAME_PADDING;
-  readonly #now: () => number;
+  set selectOnClick(value: boolean) {
+    this.view.selectOnClick = value;
+  }
 
-  constructor(host: SessionHost, deps: SessionDeps) {
-    super(host, deps);
-    this.#now = deps.now;
-    this.addView(this);
+  /** The whole content is in the canvas's view (the minimap has nothing to add). */
+  get overview(): boolean {
+    return this.view.overview;
   }
 
-  // ─── Renderer ─────────────────────────────────────────────────────────────
+  get camera(): Camera | null {
+    return this.view.camera;
+  }
 
   attach(stage: HTMLElement, minimapHost: HTMLElement | null): void {
-    if (this.#renderer) return;
-    const backend = renderBackend();
-    const renderer = backend.createRenderer(stage, {
-      theme: this.theme,
-      labelsInside: this.#labelsInside,
-    });
-    this.#renderer = renderer;
-    // Re-attached (element moved): keep the view; this also stops the renderer's auto-fit.
-    if (this.#savedCamera) renderer.camera.set(this.#savedCamera);
-    if (minimapHost) this.#minimap = backend.createMinimap(minimapHost, renderer);
-    this.#unbind.push(
-      renderer.on('hover', (pick) => this.#onHover(pick)),
-      renderer.on('click', ({ pick }) => this.#onCanvasClick(pick)),
-      renderer.on('dblclick', ({ pick }) => this.#onCanvasDblClick(pick)),
-      renderer.on('camera', ({ source }) => {
-        if (source === 'user') this.noteUserCamera();
-        this.#updateOverview();
-      }),
-    );
-    this.#minimapDirty = true;
-    this.invalidate();
+    this.view.attach(stage, minimapHost);
   }
 
   detach(): void {
-    // A pending initial fit still runs after re-attach (`layoutChanged`), overriding this.
-    if (this.#renderer && this.status === 'ready') this.#savedCamera = this.#renderer.camera.get();
+    this.view.detach();
     this.sleep();
-    for (const fn of this.#unbind.splice(0)) fn();
-    this.#minimap?.destroy();
-    this.#minimap = null;
-    this.#renderer?.destroy();
-    this.#renderer = null;
   }
 
   override destroy(): void {
     super.destroy();
-    this.detach();
-  }
-
-  get camera(): Camera | null {
-    return this.#renderer?.camera ?? null;
+    this.view.detach();
   }
 
-  /**
-   * Where floating chrome covers the canvas (measured by the element at fit / flight time).
-   * Every fit and flight frames its target in the free part of the canvas (`framing.ts`).
-   */
   setChrome(provider: (() => ChromeLayout) | null): void {
-    this.#chrome = provider;
+    this.view.setChrome(provider);
   }
 
-  /**
-   * Keep labels whole inside the canvas (embeds without camera controls): a label pushed from
-   * its spot by a neighbour moves inside or is left out, never cut at the edge.
-   */
   setLabelsInside(inside: boolean): void {
-    this.#labelsInside = inside;
-    this.#renderer?.setLabelsInside(inside);
+    this.view.setLabelsInside(inside);
   }
 
-  /**
-   * The canvas was laid out or resized: run the initial fit a new diff is waiting for, or (with
-   * `autoFit`) fit again unless the user moved the camera since the last fit.
-   */
   layoutChanged(): void {
-    this.#updateOverview();
-    if (this.status !== 'ready') return;
-    if (!this.#needsFit) {
-      if (this.autoFit && !this.#userMoved) void this.fit({ animate: false });
-      return;
-    }
-    // A selection made before the first layout (deep link, `kgdiff-ready` handler) wins.
-    const target = this.selectionBounds();
-    if (target) {
-      if (!this.#frameInsets(target, FLY_MAX_ZOOM)) return;
-      this.#needsFit = false;
-      this.#flyTo(target, { animate: false });
-      return;
-    }
-    const fit = this.#fitTarget();
-    const camera = this.#renderer?.camera;
-    if (!fit || !camera) return;
-    void this.#fitTo(camera, fit, { animate: false });
+    this.view.layoutChanged();
   }
 
-  /** The user panned / zoomed: suspend replay camera follow for `USER_CAMERA_GRACE`. */
   noteUserCamera(): void {
-    this.#lastUserCamera = this.#now();
-    this.#userMoved = true;
+    this.view.noteUserCamera();
   }
-
-  // ─── SessionView ──────────────────────────────────────────────────────────
-
-  /** Resolve the current view and hand it to the renderer (and the minimap). */
-  draw(now = this.#now()): void {
-    const resolver = this.resolver;
-    const renderer = this.#renderer;
-    if (!resolver || !renderer || this.status !== 'ready') return;
-    const f = this.#frames;
-    let mapFrame: FrameVisuals;
-    if (this.mode === 'swipe') {
-      f.before = resolver.resolve(this.viewState('before'), f.before ?? undefined);
-      f.after = resolver.resolve(this.viewState('after'), f.after ?? undefined);
-      renderer.setFrame({ split: this.split, before: f.before, after: f.after });
-      mapFrame = f.after;
-    } else {
-      const layer: Layer = this.mode === 'replay' ? 'replay' : 'union';
-      f.main = resolver.resolve(this.viewState(layer), f.main ?? undefined);
-      renderer.setFrame(f.main);
-      mapFrame = f.main;
-    }
-    const replaying = this.mode === 'replay' && (this.clock?.playing ?? false);
-    if (
-      this.#minimap &&
-      (this.#minimapDirty || (replaying && now - this.#lastMinimap >= MINIMAP_INTERVAL))
-    ) {
-      this.#minimap.update(mapFrame);
-      this.#minimapDirty = false;
-      this.#lastMinimap = now;
-    }
-  }
-
-  sceneChanged(): void {
-    const f = this.#frames;
-    f.main = f.before = f.after = null;
-    this.#renderer?.setTheme(this.scene?.theme ?? this.theme);
-    this.#minimapDirty = true;
-  }
-
-  installed(): void {
-    // Fitted after the UI has shown its chrome (the session's notification is delivered
-    // first) and once the canvas has a size (see `layoutChanged`).
-    this.#needsFit = true;
-    this.#savedCamera = null;
-    queueMicrotask(() => this.layoutChanged());
-  }
-
-  drawnChanged(): void {
-    this.#updateOverview();
-    this.#minimapDirty = true;
-  }
-
-  show(bounds: Rect): void {
-    this.#flyTo(bounds);
-  }
-
-  /** Follow `bounds` (replay): fly unless the user steered recently or it is mostly visible. */
-  follow(bounds: Rect): void {
-    if (this.#now() - this.#lastUserCamera < USER_CAMERA_GRACE) return;
-    const free = this.#freeWorld(bounds);
-    if (!free || coverage(bounds, free) >= FOLLOW_COVERAGE) return;
-    this.#flyTo(bounds);
-  }
-
-  looped(): void {
-    if (this.autoFit) void this.fit();
-  }
-
-  viewport(): Rect | null {
-    return this.#renderer?.camera.viewport() ?? null;
-  }
-
-  // ─── Camera ───────────────────────────────────────────────────────────────
-
-  /** Insets keeping `bounds` clear of the chrome over the canvas, or null before layout. */
-  #frameInsets(bounds: Rect, maxZoom: number): Insets | null {
-    const layout = this.#chrome?.();
-    if (!layout || !(layout.width > 0) || !(layout.height > 0)) return null;
-    return chromeInsets(bounds, layout, FRAME_PADDING, maxZoom);
-  }
-
-  #flyTo(bounds: Rect, options: { readonly animate?: boolean } = {}): void {
-    const camera = this.#renderer?.camera;
-    if (!camera) return;
-    const padding = this.#frameInsets(bounds, FLY_MAX_ZOOM);
-    void camera.flyTo(bounds, {
-      ...options,
-      maxZoom: FLY_MAX_ZOOM,
-      ...(padding ? { padding } : {}),
-    });
-  }
-
-  /** The world region visible outside the chrome, as framed for `bounds`. */
-  #freeWorld(bounds: Rect): Rect | null {
-    const camera = this.#renderer?.camera;
-    if (!camera) return null;
-    const insets = this.#frameInsets(bounds, FLY_MAX_ZOOM) ?? NO_INSETS;
-    return freeView(camera.viewport(), camera.get().k, insets);
-  }
-
-  /**
-   * Fit everything visible (the focus in changes-only mode), labels included, into the free part
-   * of the canvas. Before the canvas is laid out it falls back to the renderer's own fit.
-   */
-  fit(options: FitOptions = {}): Promise<void> {
-    const camera = this.#renderer?.camera;
-    if (!camera) return Promise.resolve();
-    const { padding, ...transition } = options;
-    if (padding !== undefined) {
-      this.#fitPadding = Number.isFinite(padding) && padding >= 0 ? padding : FRAME_PADDING;
-    }
-    const fit = this.#fitTarget();
-    if (!fit) return camera.fit(undefined, transition);
-    return this.#fitTo(camera, fit, transition);
-  }
-
-  #fitTo(
-    camera: Camera,
-    fit: { readonly bounds: Rect; readonly insets: Insets },
-    transition: { readonly animate?: boolean },
-  ): Promise<void> {
-    this.#needsFit = false;
-    this.#userMoved = false;
-    return camera.fit(fit.bounds, { ...transition, padding: fit.insets, maxZoom: FIT_MAX_ZOOM });
-  }
-
-  /**
-   * Bounds and insets that show everything visible (the changes-only focus) with every label
-   * in its spot below its node, clear of the chrome, or null before layout. Measured in the
-   * union layer, which holds every state a replay or swipe passes through. Insets depend on
-   * what is framed, which depends on the zoom they allow: they are settled once more.
-   */
-  #fitTarget(): { bounds: Rect; insets: Insets } | null {
-    const layout = this.#chrome?.();
-    const resolver = this.resolver;
-    if (!layout || !resolver || !(layout.width > 0) || !(layout.height > 0)) return null;
-    const frame = resolver.resolve(
-      createViewState({
-        layer: 'union',
-        focus: this.focus,
-        families: this.families,
-        reducedMotion: this.reducedMotion,
-      }),
-    );
-    const footprint = labelFootprint(frame, this.theme);
-    const extent = (k: number): Rect | null => footprint.at(k);
-    const discs = extent(Number.POSITIVE_INFINITY);
-    if (!discs) return null;
-    const { width, height } = layout;
-    const padding = this.#fitPadding;
-    let insets = chromeInsets(discs, layout, padding, FIT_MAX_ZOOM);
-    let fit = zoomFit(extent, width, height, insets, FIT_MAX_ZOOM);
-    if (!fit) return null;
-    const settled = chromeInsets(fit.content, layout, padding, FIT_MAX_ZOOM);
-    if (!sameInsets(settled, insets)) {
-      insets = settled;
-      fit = zoomFit(extent, width, height, insets, FIT_MAX_ZOOM) ?? fit;
-    }
-    return { bounds: fit.bounds, insets };
-  }
-
-  /** Bounds of what is drawn: the scene, or the visible part of the `changes` scope's focus. */
-  #contentBounds(): Rect | null {
-    const scene = this.scene;
-    if (!scene) return null;
-    const focus = this.focus;
-    const cached = this.#boundsCache;
-    if (cached && cached.scene === scene && cached.focus === focus) return cached.rect;
-    const rect = focus ? focusBounds(scene, focus) : frameBounds(scene);
-    this.#boundsCache = { scene, focus, rect };
-    return rect;
-  }
-
-  /** Whether everything drawn is in view; the minimap hides while it is. */
-  #updateOverview(): void {
-    const bounds = this.#contentBounds();
-    const view = this.#renderer?.camera.viewport();
-    const next = !bounds || !view || coverage(bounds, view) >= OVERVIEW_COVERAGE;
-    if (next === this.overview) return;
-    this.overview = next;
-    this.notify('overview');
-  }
-
-  zoom(direction: 1 | -1): void {
-    this.noteUserCamera();
-    this.#renderer?.camera.zoomBy(direction > 0 ? 1.4 : 1 / 1.4);
-  }
-
-  // ─── Canvas events ────────────────────────────────────────────────────────
-
-  #onHover(pick: PickResult | null): void {
-    this.setHover(
-      pick?.type === 'node' ? pick.index : -1,
-      pick?.type === 'edge' ? pick.index : -1,
-      pick?.type === 'collapsed' ? pick.index : -1,
-    );
-  }
-
-  #onCanvasClick(pick: PickResult | null): void {
-    if (!this.selectOnClick) return;
-    if (!pick) {
-      this.clearSelection();
-      return;
-    }
-    switch (pick.type) {
-      case 'node':
-        this.selectNode(pick.index, { fly: false });
-        break;
-      case 'edge': {
-        const e = this.scene?.edges[pick.index];
-        if (e && e.hunk >= 0) this.selectHunk(e.hunk, { fly: false });
-        this.pinnedEdge = pick.index;
-        this.invalidate();
-        break;
-      }
-      case 'collapsed':
-        this.expandGroup(pick.index);
-        break;
-      default:
-        break;
-    }
-  }
-
-  #onCanvasDblClick(pick: PickResult | null): void {
-    if (!this.selectOnClick || pick?.type !== 'node') return;
-    const n = this.scene?.nodes[pick.index];
-    if (!n) return;
-    if (n.hunk >= 0) this.flyToHunk(n.hunk);
-    else this.flyToNode(pick.index);
-  }
-}
-
-function sameInsets(a: Insets, b: Insets): boolean {
-  return a.top === b.top && a.right === b.right && a.bottom === b.bottom && a.left === b.left;
-}
-
-/** Bounds of the visible part of `focus`, with room for labels and the collapsed pills. */
-function focusBounds(scene: Scene, focus: FocusState): Rect {
-  let x0 = Number.POSITIVE_INFINITY;
-  let y0 = Number.POSITIVE_INFINITY;
-  let x1 = Number.NEGATIVE_INFINITY;
-  let y1 = Number.NEGATIVE_INFINITY;
-  const add = (x: number, y: number, rx: number, top: number, bottom: number): void => {
-    x0 = Math.min(x0, x - rx);
-    x1 = Math.max(x1, x + rx);
-    y0 = Math.min(y0, y - top);
-    y1 = Math.max(y1, y + bottom);
-  };
-  // Labels sit centered below their node: leave room for a typical one.
-  for (const n of scene.nodes)
-    if (focus.nodes[n.index] === 1) add(n.x, n.y, n.r + 48, n.r, n.r + 24);
-  for (const g of focus.collapsed) add(g.x, g.y, 48, 12, 12);
-  if (!(x0 <= x1)) return frameBounds(scene);
-  return padRect({ x: x0, y: y0, width: x1 - x0, height: y1 - y0 }, 160, 1.12);
 }

package/src/dom.ts

@@ -129,3 +129,33 @@ export function relabel(el: Element, label: string): void {
   attr(el, 'aria-label', label);
   attr(el, 'title', label);
 }
+
+/**
+ * Whether `el` is shown and can take focus: connected, and neither it nor an ancestor (across
+ * shadow roots) is `hidden` or `inert`.
+ */
+export function isOpen(el: Element): boolean {
+  if (!el.isConnected) return false;
+  for (let n: Element | null = el; n; ) {
+    if ((n as HTMLElement).hidden || (n as HTMLElement).inert) return false;
+    n = n.parentElement ?? (n.getRootNode() as Partial<ShadowRoot>).host ?? null;
+  }
+  return true;
+}
+
+/**
+ * Before `from` (a region) folds or hides: if focus is inside it, move focus to `to()`, or let
+ * go of it when there is nowhere to go (focus never stays inside an inert region).
+ */
+export function moveFocusOut(
+  root: DocumentOrShadowRoot,
+  from: Element,
+  to: () => HTMLElement | null | undefined,
+): void {
+  // A focused element inside a nested shadow root shows as its host here.
+  const here = root.activeElement as HTMLElement | null;
+  if (!here || !from.contains(here)) return;
+  const next = to();
+  if (next && !from.contains(next)) next.focus({ preventScroll: true });
+  else here.blur();
+}