@luciole-sh/flow-graph 0.0.0-stage → 0.1.0

package/src/hooks.tsx

@@ -0,0 +1,121 @@
+import {
+  createContext,
+  useCallback,
+  useContext,
+  useState,
+  useSyncExternalStore,
+  type Dispatch,
+  type ReactNode,
+  type SetStateAction,
+} from "react";
+import { FlowStore } from "./store.ts";
+import type { Detail, Edge, EdgeChange, Node, NodeChange, Viewport, XY } from "./types.ts";
+import { applyEdgeChanges, applyNodeChanges } from "./vendor/xyflow/changes.ts";
+
+export const StoreContext = createContext<FlowStore | null>(null);
+/** The node a `<Handle>` belongs to. */
+export const NodeIdContext = createContext<string | null>(null);
+
+/**
+ * Shares one canvas's store with components outside `<Flow>` (a side panel that calls
+ * `fitView`, a toolbar): wrap both in it. Without it, `<Flow>` keeps its own.
+ */
+export function FlowProvider({
+  children,
+  defaultViewport,
+  fitView,
+}: {
+  children: ReactNode;
+  defaultViewport?: Viewport;
+  fitView?: boolean;
+}) {
+  const [store] = useState(() => new FlowStore({ viewport: defaultViewport, fitView }));
+  return <StoreContext.Provider value={store}>{children}</StoreContext.Provider>;
+}
+
+export function useStore(): FlowStore {
+  const store = useContext(StoreContext);
+  if (!store) throw new Error("useFlow and the canvas components need a <Flow> or <FlowProvider>");
+  return store;
+}
+
+/** Re-renders on every change of the store; returns it. */
+export function useStoreVersion(): FlowStore {
+  const store = useStore();
+  useSyncExternalStore(store.subscribe, store.getVersion);
+  return store;
+}
+
+/** `useState` for nodes, with the `onNodesChange` that applies the canvas's changes. */
+export function useNodesState<N extends Node = Node>(
+  initial: N[],
+): [N[], Dispatch<SetStateAction<N[]>>, (changes: NodeChange<N>[]) => void] {
+  const [nodes, setNodes] = useState(initial);
+  const onNodesChange = useCallback(
+    (changes: NodeChange<N>[]) => setNodes((current) => applyNodeChanges(changes, current)),
+    [],
+  );
+  return [nodes, setNodes, onNodesChange];
+}
+
+/** `useState` for edges, with the `onEdgesChange` that applies the canvas's changes. */
+export function useEdgesState<E extends Edge = Edge>(
+  initial: E[],
+): [E[], Dispatch<SetStateAction<E[]>>, (changes: EdgeChange<E>[]) => void] {
+  const [edges, setEdges] = useState(initial);
+  const onEdgesChange = useCallback(
+    (changes: EdgeChange<E>[]) => setEdges((current) => applyEdgeChanges(changes, current)),
+    [],
+  );
+  return [edges, setEdges, onEdgesChange];
+}
+
+export type FlowInstance = {
+  getNodes(): readonly Node[];
+  getNode(id: string): Node | undefined;
+  getEdges(): readonly Edge[];
+  getViewport(): Viewport;
+  setViewport(viewport: Viewport): void;
+  /** The closest zoom level at which every node is seen, centered. */
+  fitView(): void;
+  zoomIn(): void;
+  zoomOut(): void;
+  /** Centers the view on a point in flow coordinates. */
+  setCenter(point: XY, zoom?: number): void;
+  /** Pans just enough to show node `id`. */
+  reveal(id: string): void;
+  /** Proposes removing these nodes (with their edges) and edges. */
+  deleteElements(elements: { nodes?: readonly string[]; edges?: readonly string[] }): void;
+  /** Proposes selecting exactly these nodes and edges. */
+  select(elements: { nodes?: readonly string[]; edges?: readonly string[] }): void;
+  /** The canvas point at the center of the view, in flow coordinates. */
+  center(): XY;
+};
+
+/** The canvas's controls, for a component inside `<Flow>` or `<FlowProvider>`. */
+export function useFlow(): FlowInstance {
+  const store = useStore();
+  const [instance] = useState<FlowInstance>(() => ({
+    getNodes: () => store.nodes,
+    getNode: (id) => store.nodes.find((n) => n.id === id),
+    getEdges: () => store.edges,
+    getViewport: () => store.viewport,
+    setViewport: (viewport) => store.setViewport(viewport),
+    fitView: () => store.fitView(),
+    zoomIn: () => store.zoom(1),
+    zoomOut: () => store.zoom(-1),
+    setCenter: (point, zoom) => store.setCenter(point, zoom),
+    reveal: (id) => store.reveal(id),
+    deleteElements: (elements) => store.deleteElements(elements),
+    select: (elements) => store.select(elements),
+    center: () =>
+      store.toFlow({ x: Math.floor(store.size.width / 2), y: Math.floor(store.size.height / 2) }),
+  }));
+  return instance;
+}
+
+/** The viewport and the detail it draws nodes at, re-rendering when they change. */
+export function useViewport(): Viewport & { detail: Detail } {
+  const store = useStoreVersion();
+  return { ...store.viewport, detail: store.detail };
+}

package/src/index.ts

@@ -0,0 +1,21 @@
+/**
+ * `@luciole-sh/flow-graph`: node graphs in the terminal, after React Flow. Use it in a Client
+ * Component (`"use client"`): pan, zoom, drag and selection stay on the Client.
+ */
+export { Flow, type FlowProps } from "./Flow.tsx";
+export { Background, Controls, MiniMap, Panel, type PanelPosition } from "./components.tsx";
+export { DefaultNode, GroupNode, Handle } from "./nodes.tsx";
+export {
+  FlowProvider,
+  useEdgesState,
+  useFlow,
+  useNodesState,
+  useViewport,
+  type FlowInstance,
+} from "./hooks.tsx";
+export { addEdge, applyEdgeChanges, applyNodeChanges, getEdgeId } from "./vendor/xyflow/changes.ts";
+export { composeFrame, hitTest, type EdgeRoute, type EdgeType, type Frame } from "./frame.ts";
+export { ZOOMS, detailFor, fitViewport, flowBounds } from "./geometry.ts";
+export { Grid, type BackgroundVariant, type EdgeStyle } from "./raster.ts";
+export { defaultTheme, type FlowTheme } from "./theme.ts";
+export type * from "./types.ts";

package/src/keymap.tsx

@@ -0,0 +1,45 @@
+import { useState, type ReactNode } from "react";
+import type { CliRenderer, KeyEvent, Renderable } from "@opentui/core";
+import type { Keymap } from "@opentui/keymap";
+import { createDefaultOpenTuiKeymap } from "@opentui/keymap/opentui";
+import { KeymapProvider, useKeymap } from "@opentui/keymap/react";
+import { useRenderer } from "@opentui/react";
+
+type OpenTuiKeymap = Keymap<Renderable, KeyEvent>;
+
+/**
+ * The keymap of the application's `<KeymapProvider>`, or null without one.
+ * `@opentui/keymap/react` exports no context, only `useKeymap`, which throws when there is
+ * no provider: the throw comes after its `useContext`, so hooks keep their order.
+ */
+function useOptionalKeymap(): OpenTuiKeymap | null {
+  try {
+    return useKeymap();
+  } catch {
+    return null;
+  }
+}
+
+// A keymap listens to its renderer for good (it has no dispose): one per renderer, shared
+// by every canvas that has no provider, however often they mount.
+const ownKeymaps = new WeakMap<CliRenderer, OpenTuiKeymap>();
+function keymapFor(renderer: CliRenderer): OpenTuiKeymap {
+  const known = ownKeymaps.get(renderer);
+  if (known) return known;
+  const keymap = createDefaultOpenTuiKeymap(renderer);
+  ownKeymaps.set(renderer, keymap);
+  return keymap;
+}
+
+/**
+ * The canvas's bindings go through `useBindings` in every case. Inside the application's
+ * `<KeymapProvider>` (luciole's Shell installs one), they join its layers: `<KeyHelp>`
+ * lists them, and the application's own layers can shadow them. Without one, the canvas
+ * provides a keymap of its own on the renderer.
+ */
+export function FlowKeymap({ children }: { children: ReactNode }) {
+  const outer = useOptionalKeymap();
+  const renderer = useRenderer();
+  const [own] = useState(() => (outer ? null : keymapFor(renderer)));
+  return own ? <KeymapProvider keymap={own}>{children}</KeymapProvider> : children;
+}

package/src/navigation.ts

@@ -0,0 +1,86 @@
+/**
+ * Moving the selection with the keyboard: in reading order (columns left to right, a
+ * column top to bottom, as a left-to-right flow reads), along the edges (downstream,
+ * upstream), among siblings, or to the nearest node on one side. Pure functions of the
+ * graph and the nodes' positions.
+ */
+import type { Edge, Node, Position, XY } from "./types.ts";
+
+type Located = { id: string; at: XY };
+
+const byColumn = (a: Located, b: Located) => a.at.x - b.at.x || a.at.y - b.at.y;
+const byRow = (a: Located, b: Located) => a.at.y - b.at.y || a.at.x - b.at.x;
+
+/** Selectable, visible nodes with their positions, in reading order. */
+export function readingOrder(nodes: readonly Node[], positions: ReadonlyMap<string, XY>) {
+  return nodes
+    .filter((n) => !n.hidden && n.selectable !== false && n.type !== "group")
+    .map((n) => ({ id: n.id, at: positions.get(n.id) ?? n.position }))
+    .sort(byColumn);
+}
+
+/** The next (`1`) or previous (`-1`) node after `current` in reading order, cycling. */
+export function cycle(order: readonly Located[], current: string | undefined, step: 1 | -1) {
+  if (order.length === 0) return undefined;
+  const index = order.findIndex((n) => n.id === current);
+  if (index < 0) return (step === 1 ? order[0] : order.at(-1))?.id;
+  return order[(index + step + order.length) % order.length]?.id;
+}
+
+/** The first node `current`'s edges lead to (`down`) or come from (`up`), top first. */
+export function follow(
+  edges: readonly Edge[],
+  order: readonly Located[],
+  current: string,
+  direction: "down" | "up",
+) {
+  const ids = new Set(
+    edges
+      .filter((e) => !e.hidden && (direction === "down" ? e.source : e.target) === current)
+      .map((e) => (direction === "down" ? e.target : e.source)),
+  );
+  return order.filter((n) => ids.has(n.id)).sort(byRow)[0]?.id;
+}
+
+/**
+ * The next (`1`) or previous (`-1`) sibling of `current`: another node an upstream node
+ * of `current` leads to, top to bottom, cycling.
+ */
+export function sibling(
+  edges: readonly Edge[],
+  order: readonly Located[],
+  current: string,
+  step: 1 | -1,
+) {
+  const parents = new Set(edges.filter((e) => e.target === current).map((e) => e.source));
+  const ids = new Set(edges.filter((e) => parents.has(e.source)).map((e) => e.target));
+  // A root's siblings are the other roots.
+  if (parents.size === 0) {
+    const targets = new Set(edges.map((e) => e.target));
+    for (const n of order) if (!targets.has(n.id)) ids.add(n.id);
+  }
+  const list = order.filter((n) => ids.has(n.id)).sort(byRow);
+  return list.length > 1 ? cycle(list, current, step) : undefined;
+}
+
+/**
+ * The nearest node on `side` of `current`: within a 45° cone first, by distance with rows
+ * counted twice (a row is about two columns tall).
+ */
+export function nearest(order: readonly Located[], current: string, side: Position) {
+  const from = order.find((n) => n.id === current);
+  if (!from) return undefined;
+  let best: { id: string; score: number } | undefined;
+  for (const n of order) {
+    if (n.id === current) continue;
+    const dx = n.at.x - from.at.x;
+    const dy = (n.at.y - from.at.y) * 2;
+    const forward = side === "right" ? dx : side === "left" ? -dx : side === "bottom" ? dy : -dy;
+    const across = side === "left" || side === "right" ? Math.abs(dy) : Math.abs(dx);
+    if (forward <= 0) continue;
+    // Outside the cone costs as much again as the distance across.
+    const score = forward + across * (across > forward ? 2 : 1);
+    if (!best || score < best.score) best = { id: n.id, score };
+  }
+  return best?.id;
+}

package/src/nodes.tsx

@@ -0,0 +1,86 @@
+import { useContext, useEffect, useId } from "react";
+import { labelOf } from "./geometry.ts";
+import { NodeIdContext, useStore } from "./hooks.tsx";
+import { useFlowTheme } from "./theme.ts";
+import type { HandleType, NodeComponent, NodeProps, Position } from "./types.ts";
+
+/**
+ * Declares where a node's edges attach: a node component renders one per handle. It
+ * draws nothing itself: the canvas marks handles on the node's border when useful (the
+ * selected node's sources, every target while connecting). Handles sharing a side are
+ * spread along it, in the order they are rendered.
+ */
+export function Handle({
+  type,
+  position,
+  id = null,
+}: {
+  type: HandleType;
+  position: Position;
+  id?: string | null;
+}) {
+  const nodeId = useContext(NodeIdContext);
+  const store = useStore();
+  const key = useId();
+  useEffect(() => {
+    if (!nodeId) return;
+    store.addHandle(nodeId, key, { id, type, position });
+    return () => store.removeHandle(nodeId, key);
+  }, [store, nodeId, key, id, type, position]);
+  return null;
+}
+
+/** A label in a rounded box, one row tall; its label only when compact. */
+export function DefaultNode({ data, id, selected, detail, connectTarget, type }: NodeProps) {
+  const theme = useFlowTheme();
+  const label = labelOf({ id, data, position: { x: 0, y: 0 } });
+  const color = selected ? theme.selected : connectTarget ? theme.connect : theme.border;
+  if (detail === "compact")
+    return (
+      <text
+        selectable={false}
+        wrapMode="none"
+        fg={selected || connectTarget ? color : theme.text}
+        bg={theme.panelBg}
+      >
+        {` ${label} `}
+      </text>
+    );
+  // An input starts the flow and an output ends it: their border says so.
+  return (
+    <box
+      border
+      borderStyle={type === "input" ? "double" : type === "output" ? "heavy" : "rounded"}
+      borderColor={color}
+      paddingX={1}
+      backgroundColor={theme.panelBg}
+    >
+      <text selectable={false} fg={theme.text} wrapMode="none">
+        {label}
+      </text>
+    </box>
+  );
+}
+
+/** A frame other nodes sit in (`parentId`), sized by the node's `width` and `height`. */
+export function GroupNode({ data, id, selected, detail, width, height }: NodeProps) {
+  const theme = useFlowTheme();
+  const label = labelOf({ id, data, position: { x: 0, y: 0 } });
+  return (
+    <box
+      width={width}
+      height={height}
+      border
+      borderStyle="single"
+      borderColor={selected ? theme.selected : theme.group}
+      title={detail === "full" ? ` ${label} ` : undefined}
+    />
+  );
+}
+
+export const builtinNodeTypes: Record<string, NodeComponent> = {
+  default: DefaultNode,
+  input: DefaultNode,
+  output: DefaultNode,
+  group: GroupNode,
+};