@prnt/dagr-explorer 0.1.3

package/src/explorer-viewport.tsx

@@ -0,0 +1,181 @@
+/**
+ * `ExplorerViewport`: the graph surface, wired to the root.
+ *
+ * It is the internal `ViewportSurface` with its props filled from the root:
+ * the active view and its layout, the selection, the dimming, and the
+ * activation callbacks (a click inspects, a double click flies to the node).
+ * The camera controls and the camera source go back up to the root, so
+ * `ExplorerApi`'s camera methods and the toolbar's readout reach them.
+ *
+ * **One per root, counted in an effect.** The viewport registers with its
+ * root in an effect with cleanup, and the second registration throws.
+ * Counting in render would misfire under StrictMode's double render, and
+ * when Suspense keeps an old tree alive beside a new one.
+ *
+ * **A view switch remounts the surface,** keyed by view id. That is the
+ * camera reset the spec asks of a switch: a new surface fits its layout on
+ * its first measure, with no flight from a camera framed on other content.
+ *
+ * **The surface renders only for what it shows.** It is memoized, and given
+ * only the state it draws (the view, the layout, the selection, the dimming)
+ * and the root's stable methods, so a keystroke that changes neither the
+ * dimming nor the selection does not render the graph.
+ *
+ * **A stage for overlays.** The surface sits in a positioned element with
+ * the part's children, such as `ExplorerDetails`, which position against it.
+ * The hint, the graph's description, comes after the stage, so an overlay
+ * never covers it.
+ */
+
+import { memo, useEffect, useId, useRef } from 'react';
+import type { CSSProperties, ReactElement, ReactNode } from 'react';
+import type { ExplorerBase, ExplorerCameraSource } from './base.js';
+import { useExplorerApiContext, useExplorerContext } from './context.js';
+import type { ExplorerApi, ExplorerInternals } from './context.js';
+import type { ExplorerLayout } from './layout.js';
+import type { ExplorerEdge, ExplorerGroup, ExplorerNode, ExplorerView } from './types.js';
+import { ViewportSurface } from './viewport-surface.js';
+import type { ExplorerTier, ExplorerTiers } from './visible-set.js';
+
+/** Only the node type: nothing here takes an edge. */
+export interface ExplorerViewportProps<N extends ExplorerNode = ExplorerNode> {
+  /**
+   * A node's content, for nodes large enough on screen to read. It sits
+   * inside the explorer's own node button, so it must not be interactive.
+   * Default: the label.
+   */
+  readonly renderNode?:
+    | ((node: N, context: { readonly tier: ExplorerTier; readonly selected: boolean; readonly dimmed: boolean }) => ReactNode)
+    | undefined;
+  /** A node's accessible name. Default: its label, then `labels.inGroup(group)` for each group. */
+  readonly nodeAriaLabel?:
+    | ((node: N, context: { readonly groups: readonly ExplorerGroup[] }) => string)
+    | undefined;
+  /** On-screen widths, in CSS pixels, at which a node becomes a summary and then rich. Default 56 and 200. */
+  readonly tiers?: ExplorerTiers | undefined;
+  /** The most node elements mounted at once, before pins. Default 200. */
+  readonly maxOverlayNodes?: number | undefined;
+  /** What draws the nodes that have no element. Default: the SVG base. Experimental. */
+  readonly base?: ExplorerBase | undefined;
+  readonly className?: string | undefined;
+  /**
+   * Sizing and decoration pass through: `{ height: 600 }` replaces
+   * `--dagr-explorer-height`. `position` and `overflow` stay the viewport's
+   * own, because the graph needs them.
+   */
+  readonly style?: CSSProperties | undefined;
+  /**
+   * Overlays positioned against the graph, such as `ExplorerDetails`. They
+   * share a positioned stage with the graph, and the hint comes after it.
+   */
+  readonly children?: ReactNode;
+}
+
+interface PaneProps<N extends ExplorerNode, E extends ExplorerEdge>
+  extends Omit<ExplorerViewportProps<N>, 'children'> {
+  readonly label: string;
+  readonly inGroup: (groupLabel: string) => string;
+  readonly view: ExplorerView<N, E>;
+  readonly layout: ExplorerLayout;
+  readonly selectedId: string | null;
+  readonly dimmed: ReadonlySet<string>;
+  readonly api: ExplorerApi;
+  readonly internals: ExplorerInternals;
+  readonly describedBy: string;
+}
+
+/**
+ * One surface for one view, attached to the root's camera hub while it lives.
+ * Memoized: every prop is stable unless what it draws changes.
+ */
+const ViewportPane = memo(function ViewportPane<N extends ExplorerNode, E extends ExplorerEdge>(
+  props: PaneProps<N, E>,
+): ReactElement {
+  const { api, internals, describedBy, ...rest } = props;
+  const sourceRef = useRef<ExplorerCameraSource | null>(null);
+
+  // The surface's own effects have run by now, so its source is in the ref.
+  useEffect(() => {
+    const source = sourceRef.current;
+    return source === null ? undefined : internals.camera.attach(source);
+  }, [internals]);
+
+  return (
+    <ViewportSurface<N, E>
+      {...rest}
+      onNodeActivate={(id, trigger) => api.inspect(id, trigger)}
+      onNodeZoom={(id) => api.focusNode(id)}
+      controlsRef={internals.controlsRef}
+      cameraSourceRef={sourceRef}
+      describedBy={describedBy}
+    />
+  );
+}) as <N extends ExplorerNode, E extends ExplorerEdge>(props: PaneProps<N, E>) => ReactElement;
+
+const STAGE: CSSProperties = { position: 'relative' };
+
+export function ExplorerViewport<N extends ExplorerNode = ExplorerNode, E extends ExplorerEdge = ExplorerEdge>(
+  props: ExplorerViewportProps<N>,
+): ReactElement {
+  const { children, ...rest } = props;
+  const { state, internals } = useExplorerContext('ExplorerViewport');
+  const api = useExplorerApiContext('ExplorerViewport');
+  const describedBy = useId();
+
+  useEffect(() => internals.registerViewport(), [internals]);
+
+  // The part's type parameters are a claim about the root's data. See context.ts.
+  const view = state.activeView as ExplorerView<N, E> | null;
+  const { layout, labels } = state;
+
+  const empty = view === null || layout === null || view.nodes.length === 0;
+
+  // One shape for both states, so the stage and its children survive a view
+  // that empties and fills again.
+  return (
+    <>
+      <div data-dagr-explorer="stage" style={STAGE}>
+        {empty ? (
+          <div
+            data-dagr-explorer="viewport"
+            data-empty="true"
+            role="region"
+            aria-label={state.label}
+            className={rest.className}
+            style={{
+              position: 'relative',
+              height: 'var(--dagr-explorer-height, 480px)',
+              display: 'flex',
+              alignItems: 'center',
+              justifyContent: 'center',
+              ...rest.style,
+            }}
+          >
+            {view === null ? labels.noViews : labels.emptyView}
+          </div>
+        ) : (
+          <ViewportPane<N, E>
+            key={view.id}
+            {...rest}
+            label={state.label}
+            inGroup={labels.inGroup}
+            view={view}
+            layout={layout}
+            selectedId={state.selectedId}
+            dimmed={state.dimmed}
+            api={api}
+            internals={internals}
+            describedBy={describedBy}
+          />
+        )}
+        {children}
+      </div>
+      {empty ? null : (
+        <p id={describedBy} data-dagr-explorer="hint">
+          <span>{labels.stats({ nodes: view.nodes.length, edges: view.edges.length })}</span>{' '}
+          <span>{labels.hint}</span>
+        </p>
+      )}
+    </>
+  );
+}

package/src/explorer-views.tsx

@@ -0,0 +1,61 @@
+/**
+ * `ExplorerViews`: the view switcher. It renders nothing for a single view,
+ * slot or not, because there is nothing to switch to.
+ *
+ * The default is a group of buttons, the active one `aria-pressed`. Buttons
+ * rather than tabs: tabs promise arrow-key movement and a tab panel, and the
+ * panel here is the whole explorer.
+ */
+
+import type { CSSProperties, ReactElement, ReactNode } from 'react';
+import { useExplorerContext } from './context.js';
+import type { ExplorerEdge, ExplorerNode, ExplorerView } from './types.js';
+
+/** What the switcher's slot receives. */
+export interface ExplorerViewsContext<N extends ExplorerNode = ExplorerNode, E extends ExplorerEdge = ExplorerEdge> {
+  readonly views: readonly ExplorerView<N, E>[];
+  readonly activeView: ExplorerView<N, E>;
+  readonly selectView: (id: string) => void;
+}
+
+export interface ExplorerViewsProps<N extends ExplorerNode = ExplorerNode, E extends ExplorerEdge = ExplorerEdge> {
+  /** The switcher's content. Default: a button per view. */
+  readonly children?: ((context: ExplorerViewsContext<N, E>) => ReactNode) | undefined;
+  readonly className?: string | undefined;
+  readonly style?: CSSProperties | undefined;
+}
+
+export function ExplorerViews<N extends ExplorerNode = ExplorerNode, E extends ExplorerEdge = ExplorerEdge>(
+  props: ExplorerViewsProps<N, E>,
+): ReactElement | null {
+  const { children, className, style } = props;
+  const { state } = useExplorerContext('ExplorerViews');
+  // The part's type parameters are a claim about the root's data. See context.ts.
+  const views = state.views as unknown as readonly ExplorerView<N, E>[];
+  const activeView = state.activeView as ExplorerView<N, E> | null;
+  if (views.length < 2 || activeView === null) return null;
+
+  if (children !== undefined) {
+    return (
+      <div data-dagr-explorer="views" className={className} style={style}>
+        {children({ views, activeView, selectView: state.selectView })}
+      </div>
+    );
+  }
+
+  return (
+    <div data-dagr-explorer="views" role="group" aria-label={state.labels.views} className={className} style={style}>
+      {views.map((view) => (
+        <button
+          key={view.id}
+          type="button"
+          data-view-id={view.id}
+          aria-pressed={view.id === activeView.id}
+          onClick={() => state.selectView(view.id)}
+        >
+          {view.label}
+        </button>
+      ))}
+    </div>
+  );
+}

package/src/index.ts

@@ -0,0 +1,76 @@
+/**
+ * `@prnt/dagr-explorer`: an interactive graph explorer.
+ *
+ * Two ways in, from one implementation: `DagrExplorer`, preassembled, and
+ * the named parts it is built from (`ExplorerRoot`, `ExplorerViewport`,
+ * `ExplorerSearch` and the rest) with `useExplorer()`, for a host that owns
+ * the layout. Beside them, the headless core: the data model, validation,
+ * layout into world coordinates, and search, none of which touches the DOM.
+ *
+ * The optional stylesheet is its own entry, `@prnt/dagr-explorer/styles.css`.
+ * Nothing here imports it.
+ *
+ * From `@prnt/dagr-render` this package imports only the `core` entry, which
+ * never loads three.js. `test/imports.test.ts` holds that.
+ */
+
+export { DagrExplorer } from './dagr-explorer.js';
+export type { DagrExplorerProps } from './dagr-explorer.js';
+export { ExplorerRoot } from './root.js';
+export type { ExplorerRootProps } from './root.js';
+export { ExplorerViews } from './explorer-views.js';
+export type { ExplorerViewsContext, ExplorerViewsProps } from './explorer-views.js';
+export { ExplorerSearch } from './explorer-search.js';
+export type { ExplorerSearchProps } from './explorer-search.js';
+export { ExplorerViewport } from './explorer-viewport.js';
+export type { ExplorerViewportProps } from './explorer-viewport.js';
+export { ExplorerDetails } from './explorer-details.js';
+export type {
+  ExplorerConnection,
+  ExplorerDetailsContext,
+  ExplorerDetailsProps,
+} from './explorer-details.js';
+export { ExplorerToolbar } from './explorer-toolbar.js';
+export type { ExplorerToolbarProps } from './explorer-toolbar.js';
+export { ExplorerTraceToggle } from './explorer-trace-toggle.js';
+export type { ExplorerTraceToggleProps } from './explorer-trace-toggle.js';
+export { useExplorer, useExplorerApi } from './use-explorer.js';
+export type { ExplorerApi, ExplorerState } from './context.js';
+export { DEFAULT_EXPLORER_LABELS } from './labels.js';
+export type { ExplorerLabels } from './labels.js';
+// The base-layer seam is experimental until a native base confirms it.
+export type {
+  ExplorerBase,
+  ExplorerBaseProps,
+  ExplorerCameraSource,
+  ExplorerEmphasis,
+} from './base.js';
+// The camera and the visible set as types only, because the public api
+// already hands them out: `ExplorerCameraSource.get()` returns a camera, and
+// a base layer is given a visible set (experimental, like the seam above). The
+// camera arithmetic and the visible set computation stay internal.
+export type { ExplorerCamera } from './camera.js';
+export type { ExplorerTier, ExplorerTiers, ExplorerVisibleSet } from './visible-set.js';
+
+export { ExplorerContextError, ExplorerDataError } from './errors.js';
+export type { DagrExplorerErrorCode, ExplorerContextErrorCode } from './errors.js';
+// `layoutKey` and the fixed spacing constants stay internal on purpose. A
+// public constant cannot change value, or become an option, without a break.
+export { DEFAULT_NODE_SEP, DEFAULT_RANK_SEP, layoutView } from './layout.js';
+export type {
+  ExplorerBox,
+  ExplorerLayout,
+  LayoutViewOptions,
+} from './layout.js';
+export { defaultSearchText, searchNodes } from './search.js';
+export { DEFAULT_NODE_SIZE, resolveNodeSize } from './size.js';
+export { validateView, validateViews } from './validate.js';
+export type {
+  ExplorerEdge,
+  ExplorerGroup,
+  ExplorerLayoutOptions,
+  ExplorerNode,
+  ExplorerView,
+  Size,
+} from './types.js';
+export type { Vec2 } from '@prnt/dagr-render/core';

package/src/isomorphic-layout-effect.ts

@@ -0,0 +1,7 @@
+import { useEffect, useLayoutEffect } from 'react';
+
+/**
+ * A layout effect in the browser and a plain one on a server, where React 18
+ * warns that a layout effect does nothing.
+ */
+export const useIsomorphicLayoutEffect = typeof document === 'undefined' ? useEffect : useLayoutEffect;

package/src/labels.ts

@@ -0,0 +1,109 @@
+/**
+ * Every string the parts show or announce, in one object.
+ *
+ * No part writes copy of its own: a host that translates, or names things in
+ * its own voice, passes `labels` to `ExplorerRoot` and replaces any subset.
+ * Counts and names arrive through formatters, so a language with other plural
+ * rules, or another word order, is a function and not a template.
+ *
+ * The defaults are neutral English and name no host framework.
+ */
+export interface ExplorerLabels {
+  /** The search field's label. */
+  readonly search: string;
+  readonly searchPlaceholder: string;
+  /** The accessible name of the search result list. */
+  readonly searchResults: string;
+  /** The live match count, shown while the query is not blank. */
+  readonly matches: (count: number) => string;
+  /** The line under a capped result list: how many matches it does not show. */
+  readonly moreMatches: (count: number) => string;
+  /** The graph's node and edge counts, part of its accessible description. */
+  readonly stats: (counts: { readonly nodes: number; readonly edges: number }) => string;
+  /** How to use the graph, the rest of its accessible description. */
+  readonly hint: string;
+  /** The accessible name of the view switcher. */
+  readonly views: string;
+  /** One group a node is in, as part of the node's default accessible name. */
+  readonly inGroup: (groupLabel: string) => string;
+  /** The trace toggle while trace is off, so pressing it turns trace on. */
+  readonly traceOn: string;
+  /** The trace toggle while trace is on. */
+  readonly traceOff: string;
+  /** The accessible name of the zoom toolbar. */
+  readonly zoomControls: string;
+  readonly zoomIn: string;
+  readonly zoomOut: string;
+  /** The zoom readout, from the zoom as a whole percent. */
+  readonly zoomLevel: (percent: number) => string;
+  readonly fit: string;
+  /** The zoom-to-selected button, with a node selected. */
+  readonly zoomTo: (label: string) => string;
+  /** The zoom-to-selected button, disabled, with nothing selected. */
+  readonly zoomToSelected: string;
+  /** Shown in place of the graph for a view with no nodes. */
+  readonly emptyView: string;
+  /** Shown in place of the graph when there are no views. */
+  readonly noViews: string;
+  /** The drawer's title and accessible name. */
+  readonly drawerTitle: string;
+  /** The drawer's close button. */
+  readonly close: string;
+  /** The heading of the drawer's default connection list. */
+  readonly connections: string;
+}
+
+const plural = (count: number, one: string, many: string): string =>
+  `${String(count)} ${count === 1 ? one : many}`;
+
+export const DEFAULT_EXPLORER_LABELS: ExplorerLabels = Object.freeze({
+  search: 'Search nodes',
+  searchPlaceholder: 'Name or id',
+  searchResults: 'Search results',
+  matches: (count: number) => (count === 0 ? 'No matches' : plural(count, 'match', 'matches')),
+  moreMatches: (count: number) => plural(count, 'more match', 'more matches'),
+  stats: ({ nodes, edges }: { readonly nodes: number; readonly edges: number }) =>
+    `${plural(nodes, 'node', 'nodes')}, ${plural(edges, 'edge', 'edges')}.`,
+  hint: 'Search reaches every node. In the graph, the arrow keys move between nodes and Shift with an arrow pans. Click the graph to zoom with the wheel, drag to pan, and press Escape to leave it.',
+  views: 'Views',
+  inGroup: (groupLabel: string) => `in ${groupLabel}`,
+  traceOn: 'Trace connections',
+  traceOff: 'Stop tracing',
+  zoomControls: 'Zoom',
+  zoomIn: 'Zoom in',
+  zoomOut: 'Zoom out',
+  zoomLevel: (percent: number) => `${String(percent)}%`,
+  fit: 'Fit',
+  zoomTo: (label: string) => `Zoom to ${label}`,
+  zoomToSelected: 'Zoom to selection',
+  emptyView: 'This view has no nodes.',
+  noViews: 'Nothing to show.',
+  drawerTitle: 'Details',
+  close: 'Close',
+  connections: 'Connections',
+});
+
+/**
+ * The defaults with the caller's overrides on top. A key the caller set to
+ * `undefined`, which a JavaScript caller can do, keeps its default rather
+ * than rendering nothing.
+ */
+export function resolveLabels(overrides: Partial<ExplorerLabels> | undefined): ExplorerLabels {
+  if (overrides === undefined) return DEFAULT_EXPLORER_LABELS;
+  const defined = Object.fromEntries(
+    Object.entries(overrides).filter(([, value]) => value !== undefined),
+  ) as Partial<ExplorerLabels>;
+  return { ...DEFAULT_EXPLORER_LABELS, ...defined };
+}
+
+/** Whether two label objects hold the same value under every key, by `Object.is`. */
+export function sameLabels(a: ExplorerLabels, b: ExplorerLabels): boolean {
+  if (a === b) return true;
+  const keys = new Set([...Object.keys(a), ...Object.keys(b)]);
+  for (const key of keys) {
+    if (!Object.is((a as unknown as Record<string, unknown>)[key], (b as unknown as Record<string, unknown>)[key])) {
+      return false;
+    }
+  }
+  return true;
+}