@prnt/dagr-explorer 0.1.3

package/src/dagr-explorer.tsx

@@ -0,0 +1,85 @@
+/**
+ * `DagrExplorer`: the explorer, preassembled.
+ *
+ * It is composed only from the public parts, with no private access, so
+ * anything it does a host can do by composing the parts itself. Its props are
+ * the root's, plus the parts' slots and options under the names below.
+ *
+ * `N` and `E` are inferred from `views` (or `nodes` and `edges`), and every
+ * slot is typed from them. That is the check hand-composed parts cannot
+ * give, because they talk through a context.
+ */
+
+import type { ReactElement } from 'react';
+import type { ExplorerBase } from './base.js';
+import { ExplorerDetails } from './explorer-details.js';
+import type { ExplorerDetailsProps } from './explorer-details.js';
+import { ExplorerSearch } from './explorer-search.js';
+import { ExplorerToolbar } from './explorer-toolbar.js';
+import { ExplorerTraceToggle } from './explorer-trace-toggle.js';
+import { ExplorerViewport } from './explorer-viewport.js';
+import type { ExplorerViewportProps } from './explorer-viewport.js';
+import { ExplorerViews } from './explorer-views.js';
+import type { ExplorerViewsProps } from './explorer-views.js';
+import { ExplorerRoot } from './root.js';
+import type { ExplorerRootProps } from './root.js';
+import type { ExplorerEdge, ExplorerNode } from './types.js';
+import type { ExplorerTiers } from './visible-set.js';
+
+interface DagrExplorerParts<N extends ExplorerNode, E extends ExplorerEdge> {
+  /** `ExplorerViewport`'s `renderNode`. */
+  readonly renderNode?: ExplorerViewportProps<N>['renderNode'];
+  /** `ExplorerViewport`'s `nodeAriaLabel`. */
+  readonly nodeAriaLabel?: ExplorerViewportProps<N>['nodeAriaLabel'];
+  readonly tiers?: ExplorerTiers | undefined;
+  readonly maxOverlayNodes?: number | undefined;
+  /** Experimental. See `ExplorerBase`. */
+  readonly base?: ExplorerBase | undefined;
+  /** `ExplorerDetails`'s children. */
+  readonly renderDetails?: ExplorerDetailsProps<N, E>['children'];
+  /** `ExplorerDetails`'s `renderConnection`. */
+  readonly renderConnection?: ExplorerDetailsProps<N, E>['renderConnection'];
+  /** `ExplorerViews`'s children. */
+  readonly renderViews?: ExplorerViewsProps<N, E>['children'];
+  /** Preassembled: compose the parts to add your own. */
+  readonly children?: never;
+}
+
+export type DagrExplorerProps<
+  N extends ExplorerNode = ExplorerNode,
+  E extends ExplorerEdge = ExplorerEdge,
+> = ExplorerRootProps<N, E> & DagrExplorerParts<N, E>;
+
+export function DagrExplorer<N extends ExplorerNode = ExplorerNode, E extends ExplorerEdge = ExplorerEdge>(
+  props: DagrExplorerProps<N, E>,
+): ReactElement {
+  const {
+    renderNode,
+    nodeAriaLabel,
+    tiers,
+    maxOverlayNodes,
+    base,
+    renderDetails,
+    renderConnection,
+    renderViews,
+    ...root
+  } = props;
+  return (
+    <ExplorerRoot<N, E> {...(root as ExplorerRootProps<N, E>)}>
+      <ExplorerViews<N, E>>{renderViews}</ExplorerViews>
+      <ExplorerSearch />
+      <ExplorerTraceToggle />
+      {/* The drawer in the viewport's stage overlays the graph, not the whole explorer or the hint. */}
+      <ExplorerViewport<N, E>
+        renderNode={renderNode}
+        nodeAriaLabel={nodeAriaLabel}
+        tiers={tiers}
+        maxOverlayNodes={maxOverlayNodes}
+        base={base}
+      >
+        <ExplorerDetails<N, E> renderConnection={renderConnection}>{renderDetails}</ExplorerDetails>
+      </ExplorerViewport>
+      <ExplorerToolbar />
+    </ExplorerRoot>
+  );
+}

package/src/errors.ts

@@ -0,0 +1,85 @@
+/**
+ * Errors thrown by `@prnt/dagr-explorer` for data it cannot draw honestly.
+ *
+ * One class with a `code`, because a caller switches on the code and never on
+ * the class: the failures are all "this view is malformed", and they differ
+ * only in how. Codes are UPPER_SNAKE and the type is named for the package, as
+ * in every sibling.
+ *
+ * **The offender is a field, not only a phrase in the message.** A host that
+ * wants to highlight the bad node, or list the errors of one view, reads `id`
+ * and `viewId` and never parses prose. What `id` names depends on the code:
+ *
+ * - `INVALID_ID`: the empty id itself, so `id` is `''`. `viewId` is the view, or `undefined` when the empty id is a view's.
+ * - `DUPLICATE_VIEW_ID`: the view. `viewId` is `undefined`.
+ * - `INVALID_LAYOUT_OPTION`: the view. `viewId` is `undefined`.
+ * - `DUPLICATE_NODE_ID`, `INVALID_NODE_SIZE`: the node.
+ * - `DUPLICATE_EDGE_ID`, `MISSING_EDGE_ENDPOINT`: the edge.
+ * - `DUPLICATE_GROUP_ID`, `EMPTY_GROUP`, `MISSING_GROUP_MEMBER`,
+ *   `GROUP_ENCLOSES_NON_MEMBER`: the group.
+ *
+ * The message still names every id involved, including the second one a
+ * missing endpoint or an enclosed node adds, so a log line is enough to fix it.
+ *
+ * The prototype is restored explicitly, as every sibling package does, so
+ * `instanceof` stays correct when the output is downlevelled below ES2022.
+ */
+
+/** The `code` of every data error this package throws. */
+export type DagrExplorerErrorCode =
+  | 'INVALID_ID'
+  | 'DUPLICATE_VIEW_ID'
+  | 'DUPLICATE_NODE_ID'
+  | 'DUPLICATE_EDGE_ID'
+  | 'DUPLICATE_GROUP_ID'
+  | 'INVALID_NODE_SIZE'
+  | 'INVALID_LAYOUT_OPTION'
+  | 'MISSING_EDGE_ENDPOINT'
+  | 'MISSING_GROUP_MEMBER'
+  | 'EMPTY_GROUP'
+  | 'GROUP_ENCLOSES_NON_MEMBER';
+
+export class ExplorerDataError extends Error {
+  readonly code: DagrExplorerErrorCode;
+
+  /** The view, node, edge or group the error is about. See the table above. */
+  readonly id: string;
+
+  /** The view it was found in. `undefined` when the error is about a view. */
+  readonly viewId: string | undefined;
+
+  constructor(code: DagrExplorerErrorCode, message: string, id: string, viewId?: string) {
+    super(message);
+    this.name = 'ExplorerDataError';
+    this.code = code;
+    this.id = id;
+    this.viewId = viewId;
+    Object.setPrototypeOf(this, ExplorerDataError.prototype);
+  }
+}
+
+/**
+ * The `code` of every composition error: a part used where it cannot work.
+ *
+ * - `OUTSIDE_EXPLORER`: a part, or `useExplorer()`, rendered outside an
+ *   `ExplorerRoot`. The message names the part.
+ * - `SECOND_VIEWPORT`: a second `ExplorerViewport` in one root.
+ */
+export type ExplorerContextErrorCode = 'OUTSIDE_EXPLORER' | 'SECOND_VIEWPORT';
+
+/**
+ * A mistake in how the parts are put together, as opposed to the data. A
+ * separate class from {@link ExplorerDataError}, because a host that shows
+ * data errors to its users should never show these: they are the host's own
+ * bug, found the first time the page renders.
+ */
+export class ExplorerContextError extends Error {
+  readonly code: ExplorerContextErrorCode;
+
+  constructor(code: ExplorerContextErrorCode, message: string) {
+    super(message);
+    this.name = 'ExplorerContextError';
+    this.code = code;
+    Object.setPrototypeOf(this, ExplorerContextError.prototype);
+  }
+}

package/src/explorer-details.tsx

@@ -0,0 +1,156 @@
+/**
+ * `ExplorerDetails`: the drawer that shows the inspected node.
+ *
+ * It renders nothing while closed. Open, it is an overlay at every width,
+ * positioned against the nearest positioned ancestor (the viewport's stage
+ * when it is `ExplorerViewport`'s child, else the root or a host's own
+ * wrapper), so opening it never resizes the graph.
+ *
+ * The body is a keyboard scroll stop and scrolls to the top when the
+ * inspected node changes. Its content is the slot's, or by default the
+ * node's label and its connections as buttons, each inspecting the node at
+ * the other end. Those buttons keep the drawer's original opener, so
+ * `Escape` after following three edges still returns where the reader began.
+ *
+ * Closing restores focus, and the root does it, because every way the drawer
+ * closes (this part's `Escape` and close button, the api, the selected node
+ * leaving the data) ends in the same place. See `ExplorerRoot`.
+ */
+
+import { useEffect, useId, useMemo, useRef } from 'react';
+import type { CSSProperties, KeyboardEvent, ReactElement, ReactNode } from 'react';
+import { useExplorerContext } from './context.js';
+import type { ExplorerEdge, ExplorerNode } from './types.js';
+
+/** An edge touching the inspected node, and the node at its other end. */
+export interface ExplorerConnection<N extends ExplorerNode = ExplorerNode, E extends ExplorerEdge = ExplorerEdge> {
+  readonly edge: E;
+  /** The other end. For a self loop, the node itself. */
+  readonly node: N;
+}
+
+/** What the drawer's slot receives. */
+export interface ExplorerDetailsContext<N extends ExplorerNode = ExplorerNode, E extends ExplorerEdge = ExplorerEdge> {
+  readonly node: N;
+  /** Every edge touching `node`, in data order. */
+  readonly connections: readonly ExplorerConnection<N, E>[];
+  /** Inspects another node, keeping the drawer's opener. */
+  readonly inspect: (id: string) => void;
+}
+
+export interface ExplorerDetailsProps<N extends ExplorerNode = ExplorerNode, E extends ExplorerEdge = ExplorerEdge> {
+  /** The drawer's content. Default: the label and the connection list. */
+  readonly children?: ((context: ExplorerDetailsContext<N, E>) => ReactNode) | undefined;
+  /** One connection's content in the default list. Default: the other node's label. */
+  readonly renderConnection?: ((edge: E, otherNode: N) => ReactNode) | undefined;
+  readonly className?: string | undefined;
+  readonly style?: CSSProperties | undefined;
+}
+
+export function ExplorerDetails<N extends ExplorerNode = ExplorerNode, E extends ExplorerEdge = ExplorerEdge>(
+  props: ExplorerDetailsProps<N, E>,
+): ReactElement | null {
+  const { children, renderConnection, className, style } = props;
+  const { state } = useExplorerContext('ExplorerDetails');
+  const { labels, activeView, detailsOpen } = state;
+  // The part's type parameters are a claim about the root's data. See context.ts.
+  const node = detailsOpen ? (state.selectedNode as N | null) : null;
+  const nodeId = node?.id ?? null;
+  const titleId = useId();
+  const connectionsId = useId();
+  const bodyRef = useRef<HTMLDivElement>(null);
+
+  useEffect(() => {
+    if (nodeId !== null && bodyRef.current !== null) bodyRef.current.scrollTop = 0;
+  }, [nodeId]);
+
+  const connections = useMemo(() => {
+    if (nodeId === null || activeView === null) return [];
+    const byId = new Map(activeView.nodes.map((each) => [each.id, each as N]));
+    const list: ExplorerConnection<N, E>[] = [];
+    for (const edge of activeView.edges as readonly E[]) {
+      if (edge.source !== nodeId && edge.target !== nodeId) continue;
+      const other = byId.get(edge.source === nodeId ? edge.target : edge.source);
+      if (other !== undefined) list.push({ edge, node: other });
+    }
+    return list;
+  }, [nodeId, activeView]);
+
+  if (node === null) return null;
+
+  // No trigger, and the drawer is open: the root keeps the opener it has.
+  const inspect = (id: string): void => state.inspect(id);
+
+  const onKeyDown = (event: KeyboardEvent<HTMLElement>): void => {
+    if (event.key !== 'Escape') return;
+    event.preventDefault();
+    state.closeDetails();
+  };
+
+  return (
+    <aside
+      data-dagr-explorer="details"
+      aria-labelledby={titleId}
+      className={className}
+      onKeyDown={onKeyDown}
+      style={{
+        position: 'absolute',
+        top: 0,
+        right: 0,
+        bottom: 0,
+        width: 'min(360px, 100%)',
+        display: 'flex',
+        flexDirection: 'column',
+        zIndex: 1,
+        // The stylesheet's fallback, so the drawer looks the same with or without it.
+        background: 'var(--dagr-explorer-bg, #ffffff)',
+        ...style,
+      }}
+    >
+      <div
+        data-dagr-explorer="details-header"
+        style={{ display: 'flex', alignItems: 'center', justifyContent: 'space-between', flex: 'none' }}
+      >
+        <span id={titleId}>{labels.drawerTitle}</span>
+        <button type="button" data-dagr-explorer="details-close" onClick={() => state.closeDetails()}>
+          {labels.close}
+        </button>
+      </div>
+      <div
+        ref={bodyRef}
+        data-dagr-explorer="details-body"
+        tabIndex={0}
+        // A keyboard scroll stop is announced, so it needs a name: the drawer's title.
+        role="region"
+        aria-labelledby={titleId}
+        style={{ overflow: 'auto', flex: '1 1 auto', minHeight: 0 }}
+      >
+        {children !== undefined ? (
+          children({ node, connections, inspect })
+        ) : (
+          <>
+            <p data-dagr-explorer="details-label">{node.label}</p>
+            {connections.length === 0 ? null : (
+              <>
+                <p id={connectionsId}>{labels.connections}</p>
+                <ul
+                  data-dagr-explorer="connections"
+                  aria-labelledby={connectionsId}
+                  style={{ listStyle: 'none', margin: 0, padding: 0 }}
+                >
+                  {connections.map(({ edge, node: other }) => (
+                    <li key={edge.id}>
+                      <button type="button" data-node-id={other.id} onClick={() => inspect(other.id)}>
+                        {renderConnection === undefined ? other.label : renderConnection(edge, other)}
+                      </button>
+                    </li>
+                  ))}
+                </ul>
+              </>
+            )}
+          </>
+        )}
+      </div>
+    </aside>
+  );
+}

package/src/explorer-search.tsx

@@ -0,0 +1,140 @@
+/**
+ * `ExplorerSearch`: a labeled field, a live match count, and the matches as
+ * a list of buttons.
+ *
+ * Search is the complete way to every node. A virtualized node has no
+ * element, so the graph alone cannot reach it by keyboard or screen reader,
+ * and search can: every match is counted, and `Enter` reaches the first.
+ *
+ * **The list is capped,** at `maxResults` (default 50), in data order, with
+ * a plain line from `labels.moreMatches` for the rest, so a short query on a
+ * large graph does not mount thousands of buttons. A longer query narrows
+ * it. The list is memoized on the matches, which the root keeps by identity
+ * while the same nodes match.
+ *
+ * `Enter` inspects the first match and flies the camera to it, and choosing
+ * a result does the same for that result. The list stays mounted while a
+ * node is inspected, so its scroll position survives.
+ *
+ * `Escape` in the field closes the drawer if it is open, and only then
+ * clears the query, so a reader who opened a result from here can close it
+ * without losing the list.
+ */
+
+import { useEffect, useId, useMemo, useRef } from 'react';
+import type { CSSProperties, KeyboardEvent, ReactElement } from 'react';
+import { useExplorerContext } from './context.js';
+
+/** How many results the list shows before it says how many more there are. */
+const DEFAULT_MAX_RESULTS = 50;
+
+export interface ExplorerSearchProps {
+  /** The most results listed, in data order. Default 50. The count and `Enter` cover every match. */
+  readonly maxResults?: number | undefined;
+  readonly className?: string | undefined;
+  readonly style?: CSSProperties | undefined;
+}
+
+export function ExplorerSearch(props: ExplorerSearchProps): ReactElement {
+  const { state, internals } = useExplorerContext('ExplorerSearch');
+  const { labels, query, matches, detailsOpen, selectedId, inspect, focusNode } = state;
+  const { maxResults } = props;
+  const cap =
+    maxResults !== undefined && Number.isFinite(maxResults) && maxResults >= 0
+      ? Math.floor(maxResults)
+      : DEFAULT_MAX_RESULTS;
+  const inputId = useId();
+  const countId = useId();
+  const inputRef = useRef<HTMLInputElement>(null);
+
+  // The field is where focus goes when the drawer closes and its opener is gone.
+  useEffect(() => {
+    const field = inputRef.current;
+    internals.searchInputRef.current = field;
+    return () => {
+      if (internals.searchInputRef.current === field) internals.searchInputRef.current = null;
+    };
+  }, [internals]);
+
+  const blank = query.trim() === '';
+
+  // `inspect` and `focusNode` are the root's stable methods.
+  const pick = (id: string, trigger: HTMLElement): void => {
+    inspect(id, trigger);
+    focusNode(id);
+  };
+
+  const onKeyDown = (event: KeyboardEvent<HTMLInputElement>): void => {
+    if (event.key === 'Enter') {
+      const first = matches[0];
+      if (first === undefined) return;
+      event.preventDefault();
+      pick(first.id, event.currentTarget);
+    } else if (event.key === 'Escape') {
+      if (detailsOpen) state.closeDetails();
+      else if (query !== '') state.setQuery('');
+      else return;
+      // A search field clears itself on Escape in some browsers, which would
+      // skip the drawer's turn.
+      event.preventDefault();
+    }
+  };
+
+  const { searchResults, moreMatches } = labels;
+  const list = useMemo(() => {
+    if (matches.length === 0) return null;
+    const shown = cap < matches.length ? matches.slice(0, cap) : matches;
+    const more = matches.length - shown.length;
+    return (
+      <>
+        {shown.length === 0 ? null : (
+          <ul
+            data-dagr-explorer="search-results"
+            aria-label={searchResults}
+            style={{ listStyle: 'none', margin: 0, padding: 0, overflow: 'auto' }}
+          >
+            {shown.map((node) => (
+              <li key={node.id}>
+                <button
+                  type="button"
+                  data-node-id={node.id}
+                  data-selected={node.id === selectedId ? 'true' : undefined}
+                  aria-current={node.id === selectedId ? 'true' : undefined}
+                  onClick={(event) => {
+                    inspect(node.id, event.currentTarget);
+                    focusNode(node.id);
+                  }}
+                >
+                  {node.label}
+                </button>
+              </li>
+            ))}
+          </ul>
+        )}
+        {more === 0 ? null : <p data-dagr-explorer="search-more">{moreMatches(more)}</p>}
+      </>
+    );
+  }, [matches, cap, selectedId, searchResults, moreMatches, inspect, focusNode]);
+
+  return (
+    <div data-dagr-explorer="search" role="search" className={props.className} style={props.style}>
+      <label htmlFor={inputId}>{labels.search}</label>
+      <input
+        ref={inputRef}
+        id={inputId}
+        type="search"
+        value={query}
+        placeholder={labels.searchPlaceholder}
+        autoComplete="off"
+        spellCheck={false}
+        aria-describedby={countId}
+        onChange={(event) => state.setQuery(event.currentTarget.value)}
+        onKeyDown={onKeyDown}
+      />
+      <p id={countId} data-dagr-explorer="search-count" aria-live="polite">
+        {blank ? '' : labels.matches(matches.length)}
+      </p>
+      {list}
+    </div>
+  );
+}

package/src/explorer-toolbar.tsx

@@ -0,0 +1,77 @@
+/**
+ * `ExplorerToolbar`: zoom out, the zoom readout, zoom in, fit, and zoom to
+ * the selected node.
+ *
+ * **The readout follows the camera without a render.** It subscribes to the
+ * root's camera source and writes its own text when the whole percent
+ * changes, so a zoom that runs for twenty frames re-renders nothing. React
+ * renders the element with no children, so it never overwrites that text.
+ * It is not a live region: announcing every frame of a zoom is noise.
+ */
+
+import { useEffect, useRef } from 'react';
+import type { CSSProperties, ReactElement } from 'react';
+import type { ExplorerCamera } from './camera.js';
+import { useExplorerContext } from './context.js';
+
+/** The same steps as the `+` and `-` keys. */
+const ZOOM_IN = 1.25;
+const ZOOM_OUT = 0.8;
+
+export interface ExplorerToolbarProps {
+  readonly className?: string | undefined;
+  readonly style?: CSSProperties | undefined;
+}
+
+export function ExplorerToolbar(props: ExplorerToolbarProps): ReactElement {
+  const { state } = useExplorerContext('ExplorerToolbar');
+  const { labels, selectedNode, camera } = state;
+  const readoutRef = useRef<HTMLSpanElement>(null);
+  const { zoomLevel } = labels;
+
+  useEffect(() => {
+    const readout = readoutRef.current;
+    if (readout === null) return undefined;
+    let shown: number | null = null;
+    const write = (now: ExplorerCamera | null): void => {
+      if (now === null) return;
+      const percent = Math.round(now.scale * 100);
+      if (percent === shown) return;
+      shown = percent;
+      readout.textContent = zoomLevel(percent);
+    };
+    write(camera.get());
+    return camera.subscribe(write);
+  }, [camera, zoomLevel]);
+
+  return (
+    <div
+      data-dagr-explorer="toolbar"
+      role="group"
+      aria-label={labels.zoomControls}
+      className={props.className}
+      style={props.style}
+    >
+      <button type="button" data-action="zoom-out" onClick={() => state.zoomBy(ZOOM_OUT)}>
+        {labels.zoomOut}
+      </button>
+      <span ref={readoutRef} data-dagr-explorer="zoom-level" />
+      <button type="button" data-action="zoom-in" onClick={() => state.zoomBy(ZOOM_IN)}>
+        {labels.zoomIn}
+      </button>
+      <button type="button" data-action="fit" onClick={() => state.fit()}>
+        {labels.fit}
+      </button>
+      <button
+        type="button"
+        data-action="zoom-to-selected"
+        disabled={selectedNode === null}
+        onClick={() => {
+          if (selectedNode !== null) state.focusNode(selectedNode.id);
+        }}
+      >
+        {selectedNode === null ? labels.zoomToSelected : labels.zoomTo(selectedNode.label)}
+      </button>
+    </div>
+  );
+}

package/src/explorer-trace-toggle.tsx

@@ -0,0 +1,34 @@
+/**
+ * `ExplorerTraceToggle`: trace on and off. With trace on and a node
+ * selected, every node not adjacent to it is dimmed.
+ *
+ * The text names what a press does (`labels.traceOn` while off), so the
+ * button is not also `aria-pressed`: a toggle whose name flips and that
+ * reports a pressed state reads its state twice. `data-active` is the
+ * styling hook.
+ */
+
+import type { CSSProperties, ReactElement } from 'react';
+import { useExplorerContext } from './context.js';
+
+export interface ExplorerTraceToggleProps {
+  readonly className?: string | undefined;
+  readonly style?: CSSProperties | undefined;
+}
+
+export function ExplorerTraceToggle(props: ExplorerTraceToggleProps): ReactElement {
+  const { state } = useExplorerContext('ExplorerTraceToggle');
+  const { trace, labels } = state;
+  return (
+    <button
+      type="button"
+      data-dagr-explorer="trace"
+      data-active={trace ? 'true' : undefined}
+      className={props.className}
+      style={props.style}
+      onClick={() => state.setTrace(!trace)}
+    >
+      {trace ? labels.traceOff : labels.traceOn}
+    </button>
+  );
+}