@prnt/dagr-explorer 0.1.3

package/src/visible-set.ts

@@ -0,0 +1,225 @@
+/**
+ * Which nodes get a DOM element, which are left to the base layer, and which
+ * edges are in view: the explorer's virtualization, as one pure function.
+ *
+ * A node's tier comes from its width on screen in CSS pixels, with half-open
+ * gates, the rule `@prnt/dagr-render`'s rich nodes use. Below the `summary`
+ * gate it is a mark and has NO element: the base layer draws it.
+ *
+ * **The scan is linear on purpose.** Testing 10,000 boxes costs about half a
+ * millisecond per call (0.4 to 0.6 ms measured in `packages/explorer/bench`,
+ * the output lists included), well inside a 16 ms frame. The renderer's overlay scans the same way and names a spatial
+ * index as the fix if a measurement ever asks for one.
+ *
+ * Internal to the package. Only the tier types and `ExplorerVisibleSet` are
+ * exported from the entry, as types: a base layer is given a visible set.
+ */
+
+import type { ExplorerBox, ExplorerLayout } from './layout.js';
+import type { Vec2 } from '@prnt/dagr-render/core';
+import { visibleWorld } from './camera.js';
+import type { ExplorerCamera, ExplorerViewportSize } from './camera.js';
+
+export type ExplorerTier = 'summary' | 'rich';
+export interface ExplorerTiers {
+  readonly summary: number;
+  readonly rich: number;
+}
+export const DEFAULT_TIERS: ExplorerTiers = Object.freeze({ summary: 56, rich: 200 });
+export const DEFAULT_MAX_OVERLAY_NODES = 200;
+export const OVERSCAN = 0.25;
+
+export interface LayoutIndex {
+  readonly nodeIds: readonly string[];
+  readonly nodeBoxes: readonly ExplorerBox[];
+  readonly edgeIds: readonly string[];
+  /** `null` for an edge with no route, which is never in view. */
+  readonly edgeBounds: readonly (ExplorerBox | null)[];
+}
+
+export function indexLayout(layout: ExplorerLayout): LayoutIndex {
+  const edgeIds: string[] = [];
+  const edgeBounds: (ExplorerBox | null)[] = [];
+  for (const [id, points] of layout.routes) {
+    edgeIds.push(id);
+    if (points.length === 0) {
+      edgeBounds.push(null);
+      continue;
+    }
+    let minX = Infinity;
+    let minY = Infinity;
+    let maxX = -Infinity;
+    let maxY = -Infinity;
+    for (const p of points) {
+      minX = Math.min(minX, p.x);
+      minY = Math.min(minY, p.y);
+      maxX = Math.max(maxX, p.x);
+      maxY = Math.max(maxY, p.y);
+    }
+    edgeBounds.push({ x: minX, y: minY, width: maxX - minX, height: maxY - minY });
+  }
+  return {
+    nodeIds: [...layout.boxes.keys()],
+    nodeBoxes: [...layout.boxes.values()],
+    edgeIds,
+    edgeBounds,
+  };
+}
+
+export interface VisibleSetOptions {
+  readonly tiers?: ExplorerTiers | undefined;
+  readonly maxOverlayNodes?: number | undefined;
+  /** Node ids that are always overlay nodes, exempt from the cap. */
+  readonly pinned?: readonly string[] | undefined;
+}
+
+/**
+ * What is in view: the nodes with an element, the nodes and edges a base
+ * layer draws. Exported as a type, and experimental like the base-layer seam
+ * that is given it: it may change until a native base confirms it.
+ */
+export interface ExplorerVisibleSet {
+  /** Overlay nodes and their tier, in data order. */
+  readonly overlay: ReadonlyMap<string, ExplorerTier>;
+  /** Nodes in view that the base layer draws as marks, in data order. */
+  readonly baseNodes: readonly string[];
+  /** Edges whose route is in view, in data order. */
+  readonly edges: readonly string[];
+}
+
+/** Inclusive: boxes that only touch count, so a hairline route is not culled. */
+function intersects(a: ExplorerBox, b: ExplorerBox): boolean {
+  return (
+    a.x <= b.x + b.width &&
+    a.x + a.width >= b.x &&
+    a.y <= b.y + b.height &&
+    a.y + a.height >= b.y
+  );
+}
+
+export function computeVisibleSet(
+  index: LayoutIndex,
+  camera: ExplorerCamera,
+  viewport: ExplorerViewportSize,
+  options: VisibleSetOptions = {},
+): ExplorerVisibleSet {
+  const tiers = options.tiers ?? DEFAULT_TIERS;
+  const cap = options.maxOverlayNodes ?? DEFAULT_MAX_OVERLAY_NODES;
+  const pinned = new Set(options.pinned ?? []);
+  const world = visibleWorld(camera, viewport);
+  const view: ExplorerBox = {
+    x: world.x - world.width * OVERSCAN,
+    y: world.y - world.height * OVERSCAN,
+    width: world.width * (1 + OVERSCAN * 2),
+    height: world.height * (1 + OVERSCAN * 2),
+  };
+  const centerX = world.x + world.width / 2;
+  const centerY = world.y + world.height / 2;
+
+  const tierOf = new Map<number, ExplorerTier>();
+  const candidates: { readonly i: number; readonly distance: number }[] = [];
+  const inView: number[] = [];
+  index.nodeBoxes.forEach((box, i) => {
+    const id = index.nodeIds[i] as string;
+    const screenWidth = box.width * camera.scale;
+    const natural: ExplorerTier | null =
+      screenWidth >= tiers.rich ? 'rich' : screenWidth >= tiers.summary ? 'summary' : null;
+    if (pinned.has(id)) {
+      tierOf.set(i, natural ?? 'summary');
+      return;
+    }
+    if (!intersects(box, view)) return;
+    inView.push(i);
+    if (natural === null) return;
+    tierOf.set(i, natural);
+    const dx = box.x + box.width / 2 - centerX;
+    const dy = box.y + box.height / 2 - centerY;
+    candidates.push({ i, distance: dx * dx + dy * dy });
+  });
+
+  if (candidates.length > cap) {
+    candidates.sort(
+      (a, b) =>
+        a.distance - b.distance ||
+        ((index.nodeIds[a.i] as string) < (index.nodeIds[b.i] as string) ? -1 : 1),
+    );
+    for (const dropped of candidates.slice(Math.max(0, cap))) tierOf.delete(dropped.i);
+  }
+
+  const overlay = new Map<string, ExplorerTier>();
+  index.nodeIds.forEach((id, i) => {
+    const tier = tierOf.get(i);
+    if (tier !== undefined) overlay.set(id, tier);
+  });
+  const baseNodes = inView.filter((i) => !tierOf.has(i)).map((i) => index.nodeIds[i] as string);
+  const edges: string[] = [];
+  index.edgeBounds.forEach((bounds, i) => {
+    if (bounds !== null && intersects(bounds, view)) edges.push(index.edgeIds[i] as string);
+  });
+  return { overlay, baseNodes, edges };
+}
+
+/**
+ * Whether two sets hold the same nodes at the same tiers, and the same marks
+ * and edges in the same order. Overlay order is not compared:
+ * `computeVisibleSet` always emits the overlay in the index's data order, so
+ * two sets over one index cannot differ in order alone.
+ */
+export function sameVisibleSet(a: ExplorerVisibleSet, b: ExplorerVisibleSet): boolean {
+  if (a === b) return true;
+  if (
+    a.overlay.size !== b.overlay.size ||
+    a.baseNodes.length !== b.baseNodes.length ||
+    a.edges.length !== b.edges.length
+  ) {
+    return false;
+  }
+  for (const [id, tier] of a.overlay) {
+    if (b.overlay.get(id) !== tier) return false;
+  }
+  for (let i = 0; i < a.baseNodes.length; i += 1) {
+    if (a.baseNodes[i] !== b.baseNodes[i]) return false;
+  }
+  for (let i = 0; i < a.edges.length; i += 1) {
+    if (a.edges[i] !== b.edges[i]) return false;
+  }
+  return true;
+}
+
+export function nearestToCenter(
+  index: LayoutIndex,
+  camera: ExplorerCamera,
+  viewport: ExplorerViewportSize,
+): string | null {
+  const world = visibleWorld(camera, viewport);
+  const centerX = world.x + world.width / 2;
+  const centerY = world.y + world.height / 2;
+  let best: string | null = null;
+  let bestDistance = Infinity;
+  index.nodeBoxes.forEach((box, i) => {
+    const dx = box.x + box.width / 2 - centerX;
+    const dy = box.y + box.height / 2 - centerY;
+    const distance = dx * dx + dy * dy;
+    const id = index.nodeIds[i] as string;
+    if (distance < bestDistance || (distance === bestDistance && best !== null && id < best)) {
+      best = id;
+      bestDistance = distance;
+    }
+  });
+  return best;
+}
+
+export function nodeAtPoint(index: LayoutIndex, point: Vec2): string | null {
+  for (let i = index.nodeBoxes.length - 1; i >= 0; i -= 1) {
+    const box = index.nodeBoxes[i] as ExplorerBox;
+    if (
+      point.x >= box.x &&
+      point.x <= box.x + box.width &&
+      point.y >= box.y &&
+      point.y <= box.y + box.height
+    ) {
+      return index.nodeIds[i] as string;
+    }
+  }
+  return null;
+}

package/styles.css

@@ -0,0 +1,253 @@
+/*
+ * @prnt/dagr-explorer/styles.css: the explorer's optional default look.
+ *
+ * The parts work without it: everything they need to function is inline.
+ * This file is the look on top, written only against the parts'
+ * `data-dagr-explorer` hooks and their state hooks (`data-tier`,
+ * `data-selected`, `data-dimmed`, `data-dragging`, `data-active`).
+ *
+ * Theme it with these variables, set anywhere above the explorer. Each has
+ * a fallback here for a light page, and none is defined by this file, so a
+ * value a host sets on `:root` is the one used:
+ *
+ *   --dagr-explorer-accent      selection and pressed controls
+ *   --dagr-explorer-fg          text
+ *   --dagr-explorer-fg-muted    secondary text, marks and edges
+ *   --dagr-explorer-border      borders
+ *   --dagr-explorer-bg          surfaces: nodes, controls, the drawer
+ *   --dagr-explorer-bg-subtle   the graph's background, hover
+ *   --dagr-explorer-focus       focus rings
+ *   --dagr-explorer-font-mono   the zoom readout
+ *
+ * `--dagr-explorer-height` sets the graph's height (default 480px).
+ *
+ * Every selector is wrapped in `:where()`, so it has no specificity and any
+ * rule of the host's wins without a fight. The exceptions are the `:hover`,
+ * `:focus` and `:focus-visible` rules: the pseudo-class sits outside the
+ * `:where()`, so each of those weighs as one class. A host rule overrides
+ * them with a class and a later position in the cascade, or with more
+ * specificity.
+ */
+
+:where([data-dagr-explorer='root']) {
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+  color: var(--dagr-explorer-fg, #1d2430);
+  font-family: system-ui, -apple-system, 'Segoe UI', Roboto, sans-serif;
+  font-size: 14px;
+  line-height: 1.4;
+}
+
+/* Controls */
+
+:where([data-dagr-explorer='views'] button, [data-dagr-explorer='trace'], [data-dagr-explorer='toolbar'] button, [data-dagr-explorer='details'] button) {
+  font: inherit;
+  color: inherit;
+  background: var(--dagr-explorer-bg, #ffffff);
+  border: 1px solid var(--dagr-explorer-border, #d3d9e3);
+  border-radius: 6px;
+  padding: 4px 10px;
+  cursor: pointer;
+}
+
+:where([data-dagr-explorer='views'] button, [data-dagr-explorer='trace'], [data-dagr-explorer='toolbar'] button, [data-dagr-explorer='details'] button, [data-dagr-explorer='search'] button):hover {
+  background: var(--dagr-explorer-bg-subtle, #f3f5f8);
+}
+
+:where([data-dagr-explorer='root'] button, [data-dagr-explorer='root'] input, [data-dagr-explorer='details-body']):focus-visible {
+  outline: 2px solid var(--dagr-explorer-focus, #2f6fdf);
+  outline-offset: 2px;
+}
+
+:where([data-dagr-explorer='views'] button[aria-pressed='true'], [data-dagr-explorer='trace'][data-active='true']) {
+  border-color: var(--dagr-explorer-accent, #2f6fdf);
+  color: var(--dagr-explorer-accent, #2f6fdf);
+}
+
+:where([data-dagr-explorer='toolbar'] button:disabled) {
+  opacity: 0.5;
+  cursor: default;
+}
+
+:where([data-dagr-explorer='views'], [data-dagr-explorer='toolbar']) {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: 4px;
+}
+
+:where([data-dagr-explorer='zoom-level']) {
+  min-width: 5ch;
+  text-align: center;
+  font-family: var(--dagr-explorer-font-mono, ui-monospace, SFMono-Regular, Menlo, monospace);
+  font-size: 12px;
+  color: var(--dagr-explorer-fg-muted, #5c6778);
+}
+
+:where([data-dagr-explorer='trace']) {
+  align-self: flex-start;
+}
+
+/* Search */
+
+:where([data-dagr-explorer='search']) {
+  display: flex;
+  flex-direction: column;
+  gap: 4px;
+}
+
+:where([data-dagr-explorer='search'] label) {
+  font-weight: 600;
+}
+
+:where([data-dagr-explorer='search'] input) {
+  font: inherit;
+  color: inherit;
+  background: var(--dagr-explorer-bg, #ffffff);
+  border: 1px solid var(--dagr-explorer-border, #d3d9e3);
+  border-radius: 6px;
+  padding: 6px 10px;
+}
+
+:where([data-dagr-explorer='search-count']) {
+  margin: 0;
+  min-height: 1.4em;
+  font-size: 12px;
+  color: var(--dagr-explorer-fg-muted, #5c6778);
+}
+
+:where([data-dagr-explorer='search-results']) {
+  max-height: 12em;
+  border: 1px solid var(--dagr-explorer-border, #d3d9e3);
+  border-radius: 6px;
+}
+
+:where([data-dagr-explorer='search-results'] button) {
+  display: block;
+  width: 100%;
+  font: inherit;
+  color: inherit;
+  text-align: left;
+  background: transparent;
+  border: 0;
+  padding: 4px 10px;
+  cursor: pointer;
+}
+
+:where([data-dagr-explorer='search-results'] button[data-selected='true']) {
+  color: var(--dagr-explorer-accent, #2f6fdf);
+  font-weight: 600;
+}
+
+/* Graph */
+
+:where([data-dagr-explorer='viewport']) {
+  background: var(--dagr-explorer-bg-subtle, #f3f5f8);
+  border: 1px solid var(--dagr-explorer-border, #d3d9e3);
+  border-radius: 8px;
+  cursor: grab;
+  color: var(--dagr-explorer-fg-muted, #5c6778);
+}
+
+:where([data-dagr-explorer='viewport'][data-dragging='true']) {
+  cursor: grabbing;
+}
+
+/* Graph focus is what turns wheel zoom on, so it always shows. */
+:where([data-dagr-explorer='viewport']):focus {
+  outline: 2px solid var(--dagr-explorer-focus, #2f6fdf);
+  outline-offset: 2px;
+}
+
+:where([data-dagr-explorer='plane'] svg [data-dimmed='true']) {
+  opacity: 0.25;
+}
+
+:where([data-dagr-explorer='node']) {
+  box-sizing: border-box;
+  overflow: hidden;
+  padding: 8px 10px;
+  font: inherit;
+  font-size: 13px;
+  text-align: left;
+  color: var(--dagr-explorer-fg, #1d2430);
+  background: var(--dagr-explorer-bg, #ffffff);
+  border: 1px solid var(--dagr-explorer-border, #d3d9e3);
+  border-radius: 6px;
+  cursor: pointer;
+}
+
+/* A summary is small on screen: its text is counter-scaled to stay legible, up to a point. */
+:where([data-dagr-explorer='node'][data-tier='summary']) {
+  font-size: calc(12px * min(var(--dagr-explorer-inv-zoom, 1), 2.5));
+  white-space: nowrap;
+  text-overflow: ellipsis;
+}
+
+:where([data-dagr-explorer='node'][data-selected='true']) {
+  border-color: var(--dagr-explorer-accent, #2f6fdf);
+  box-shadow: 0 0 0 2px var(--dagr-explorer-accent, #2f6fdf);
+}
+
+:where([data-dagr-explorer='node']):focus-visible {
+  outline: 2px solid var(--dagr-explorer-focus, #2f6fdf);
+  outline-offset: 2px;
+}
+
+:where([data-dagr-explorer='node'][data-dimmed='true']) {
+  opacity: 0.3;
+}
+
+:where([data-dagr-explorer='hint']) {
+  margin: 0;
+  font-size: 12px;
+  color: var(--dagr-explorer-fg-muted, #5c6778);
+}
+
+/* Drawer */
+
+:where([data-dagr-explorer='details']) {
+  box-sizing: border-box;
+  background: var(--dagr-explorer-bg, #ffffff);
+  border-left: 1px solid var(--dagr-explorer-border, #d3d9e3);
+  border-radius: 0 8px 8px 0;
+  box-shadow: -8px 0 24px rgb(20 30 50 / 0.12);
+}
+
+:where([data-dagr-explorer='details-header']) {
+  padding: 8px 12px;
+  border-bottom: 1px solid var(--dagr-explorer-border, #d3d9e3);
+  font-size: 12px;
+  font-weight: 600;
+  text-transform: uppercase;
+  letter-spacing: 0.04em;
+  color: var(--dagr-explorer-fg-muted, #5c6778);
+}
+
+:where([data-dagr-explorer='details-header'] button) {
+  text-transform: none;
+  letter-spacing: normal;
+}
+
+:where([data-dagr-explorer='details-body']) {
+  padding: 12px;
+}
+
+:where([data-dagr-explorer='details-label']) {
+  margin: 0 0 12px;
+  font-size: 16px;
+  font-weight: 600;
+  color: var(--dagr-explorer-fg, #1d2430);
+}
+
+:where([data-dagr-explorer='connections']) {
+  display: flex;
+  flex-direction: column;
+  gap: 4px;
+}
+
+:where([data-dagr-explorer='connections'] button) {
+  width: 100%;
+  text-align: left;
+}