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

package/src/theme.ts

@@ -0,0 +1,61 @@
+import { createContext, useContext } from "react";
+import type { Role } from "./raster.ts";
+
+/** The canvas's colors, as `#rrggbb`. `<Flow theme>` overrides any of them. */
+export type FlowTheme = {
+  text: string;
+  muted: string;
+  border: string;
+  selected: string;
+  /** A node proposed as the target of a connection, and the connection's line. */
+  connect: string;
+  group: string;
+  edge: string;
+  animated: string;
+  label: string;
+  labelBg: string;
+  marker: string;
+  background: string;
+  handle: string;
+  panelBg: string;
+};
+
+export const defaultTheme: FlowTheme = {
+  text: "#e6edf3",
+  muted: "#8b98a5",
+  border: "#4d5966",
+  selected: "#67d9bc",
+  connect: "#f2cc60",
+  group: "#3b4450",
+  edge: "#6e7c8a",
+  animated: "#79c0ff",
+  label: "#c9d1d9",
+  labelBg: "#1f262e",
+  marker: "#8b98a5",
+  background: "#2d353e",
+  handle: "#f2cc60",
+  panelBg: "#161b22",
+};
+
+export const ThemeContext = createContext<FlowTheme>(defaultTheme);
+export const useFlowTheme = () => useContext(ThemeContext);
+
+/** The color a grid cell of `role` is drawn in. */
+export function roleColor(theme: FlowTheme, role: Role): string {
+  switch (role) {
+    case "edge":
+      return theme.edge;
+    case "selected":
+      return theme.selected;
+    case "animated":
+      return theme.animated;
+    case "label":
+      return theme.label;
+    case "marker":
+      return theme.marker;
+    case "background":
+      return theme.background;
+    case "handle":
+      return theme.handle;
+  }
+}

package/src/types.ts

@@ -0,0 +1,130 @@
+import type { ReactNode } from "react";
+
+/**
+ * The graph's vocabulary, after React Flow's (`@xyflow/system` types): a node, an edge,
+ * the changes an interaction proposes, the viewport. Coordinates are terminal cells: `x`
+ * counts columns, `y` rows, and a row is about twice as tall as a column is wide.
+ */
+
+export type XY = { x: number; y: number };
+export type Rect = { x: number; y: number; width: number; height: number };
+
+/** Which side of a node a handle sits on. */
+export type Position = "left" | "right" | "top" | "bottom";
+
+/**
+ * Semantic zoom: the terminal cannot scale glyphs, so zooming out spaces nodes closer and
+ * draws less of each. `full` renders the node's component, `compact` its label on one
+ * row, `dot` a single cell.
+ */
+export type Detail = "full" | "compact" | "dot";
+
+/** A node as the application keeps it. `position` is relative to `parentId`'s, if any. */
+export type Node<Data extends Record<string, unknown> = Record<string, unknown>> = {
+  id: string;
+  position: XY;
+  data: Data;
+  /** A key of `nodeTypes`, or a built-in: `default`, `input`, `output`, `group`. */
+  type?: string;
+  selected?: boolean;
+  dragging?: boolean;
+  hidden?: boolean;
+  /** A group node this one sits in: its position is relative to the group's. */
+  parentId?: string;
+  /** Fixed size in cells (a group needs one); otherwise the rendered size is measured. */
+  width?: number;
+  height?: number;
+  /** Where edges leave (default `right`) and arrive (default `left`) without a `<Handle>`. */
+  sourcePosition?: Position;
+  targetPosition?: Position;
+  draggable?: boolean;
+  selectable?: boolean;
+  connectable?: boolean;
+  zIndex?: number;
+  /** The node's color where the canvas draws it itself: a dot when zoomed out, the minimap. */
+  color?: string;
+};
+
+export type MarkerType = "arrow" | "none";
+
+export type Edge<Data extends Record<string, unknown> = Record<string, unknown>> = {
+  id: string;
+  source: string;
+  target: string;
+  sourceHandle?: string | null;
+  targetHandle?: string | null;
+  /** A key of `edgeTypes`, or a built-in: `smoothstep` (default), `step`, `straight`, `bezier`. */
+  type?: string;
+  label?: string;
+  /** Dashes that run from source to target. */
+  animated?: boolean;
+  selected?: boolean;
+  hidden?: boolean;
+  /** Default `arrow`. */
+  markerEnd?: MarkerType;
+  markerStart?: MarkerType;
+  /** A color for the line, as `#rrggbb`. */
+  color?: string;
+  data?: Data;
+};
+
+export type Connection = {
+  source: string;
+  target: string;
+  sourceHandle: string | null;
+  targetHandle: string | null;
+};
+
+export type Viewport = { x: number; y: number; zoom: number };
+
+// The changes, as @xyflow/system's types/changes.ts names them.
+export type NodePositionChange = {
+  id: string;
+  type: "position";
+  position?: XY;
+  dragging?: boolean;
+};
+export type NodeDimensionsChange = {
+  id: string;
+  type: "dimensions";
+  dimensions: { width: number; height: number };
+};
+export type SelectionChange = { id: string; type: "select"; selected: boolean };
+export type RemoveChange = { id: string; type: "remove" };
+export type AddChange<T> = { type: "add"; item: T; index?: number };
+export type ReplaceChange<T> = { id: string; type: "replace"; item: T };
+
+export type NodeChange<N extends Node = Node> =
+  | NodePositionChange
+  | NodeDimensionsChange
+  | SelectionChange
+  | RemoveChange
+  | AddChange<N>
+  | ReplaceChange<N>;
+export type EdgeChange<E extends Edge = Edge> =
+  | SelectionChange
+  | RemoveChange
+  | AddChange<E>
+  | ReplaceChange<E>;
+
+export type HandleType = "source" | "target";
+/** A handle a node declared with `<Handle>`. */
+export type HandleSpec = { id: string | null; type: HandleType; position: Position };
+
+/** A node type: a function component of `NodeProps`. */
+export type NodeComponent<N extends Node = Node> = (props: NodeProps<N>) => ReactNode;
+
+/** What a node component receives. */
+export type NodeProps<N extends Node = Node> = {
+  id: string;
+  data: N["data"];
+  type: string;
+  selected: boolean;
+  dragging: boolean;
+  /** `full` or `compact`: at `dot`, the canvas draws the node itself. */
+  detail: Detail;
+  /** Keyboard connection under way and this node is the proposed target. */
+  connectTarget: boolean;
+  width?: number;
+  height?: number;
+};

package/src/vendor/xyflow/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2019-2025 webkid GmbH
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/src/vendor/xyflow/README.md

@@ -0,0 +1,20 @@
+# Code repris de xyflow
+
+Les fichiers de ce répertoire sont adaptés de [xyflow](https://github.com/xyflow/xyflow)
+(React Flow), sous licence MIT ; la notice d'origine est dans [LICENSE](LICENSE).
+
+Révision : `3d35b57317576b0916c0bfeaaedd573aaacc2839` (`@xyflow/system` 0.0.83,
+`@xyflow/react` 12.12.0).
+
+| Fichier         | Origine                                                                                                                                                                   | Adaptation                                                                                                                                       |
+| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `smoothstep.ts` | `packages/system/src/utils/edges/smoothstep-edge.ts` (`getPoints`)                                                                                                        | Les points du tracé orthogonal sont rendus tels quels (pas de chemin SVG ni de virages arrondis) : la grille les dessine en caractères de boîte. |
+| `bezier.ts`     | `packages/system/src/utils/edges/bezier-edge.ts` (`calculateControlOffset`, `getControlWithCurvature`, `getBezierEdgeCenter`), `utils/edges/general.ts` (`getEdgeCenter`) | Points de contrôle rendus en nombres, pas en chemin SVG ; `Position` en chaînes.                                                                 |
+| `changes.ts`    | `packages/react/src/utils/changes.ts` (`applyChanges`, `applyChange`), `packages/system/src/utils/edges/general.ts` (`addEdge`, `getEdgeId`, `connectionExists`)          | Typé sans `any` ; pas de `dimensions`/`resizing` sur les attributs (le terminal mesure, il ne redimensionne pas) ; `addEdge` sans `onError`.     |
+
+Pourquoi recopier plutôt que dépendre de `@xyflow/system` : le paquet s'importe sous Bun
+sans DOM, mais il tire d3 (`d3-drag`, `d3-zoom`, `d3-selection`, `d3-interpolate`,
+`d3-transition` et leurs types, 15 paquets) pour du code qui ne sert pas au terminal
+(`XYPanZoom`, `XYDrag`, `XYHandle`, `XYResizer`, mesure par `getBoundingClientRect`), et ses
+fonctions de tracé ne rendent que des chaînes SVG qu'il faudrait reparser. Ce qui sert tient
+en quelques fonctions pures, reprises ici.

package/src/vendor/xyflow/bezier.ts

@@ -0,0 +1,102 @@
+// Adapted from xyflow, packages/system/src/utils/edges/bezier-edge.ts and
+// utils/edges/general.ts (MIT, see LICENSE and README.md in this directory): the control
+// points and centers as numbers instead of an SVG path.
+import type { Position } from "../../types.ts";
+
+const HALF = 0.5;
+// cubic bezier t=0.5 mid point weights: (1-t)^3, 3t(1-t)^2, 3t^2(1-t), t^3
+const END_WEIGHT = 0.125;
+const CONTROL_WEIGHT = 0.375;
+const CURVATURE_SCALE = 25;
+
+// this is used for straight edges and simple smoothstep edges (LTR, RTL, BTT, TTB)
+export function getEdgeCenter({
+  sourceX,
+  sourceY,
+  targetX,
+  targetY,
+}: {
+  sourceX: number;
+  sourceY: number;
+  targetX: number;
+  targetY: number;
+}): [number, number, number, number] {
+  const xOffset = Math.abs(targetX - sourceX) / 2;
+  const centerX = targetX < sourceX ? targetX + xOffset : targetX - xOffset;
+
+  const yOffset = Math.abs(targetY - sourceY) / 2;
+  const centerY = targetY < sourceY ? targetY + yOffset : targetY - yOffset;
+
+  return [centerX, centerY, xOffset, yOffset];
+}
+
+export function getBezierEdgeCenter({
+  sourceX,
+  sourceY,
+  targetX,
+  targetY,
+  sourceControlX,
+  sourceControlY,
+  targetControlX,
+  targetControlY,
+}: {
+  sourceX: number;
+  sourceY: number;
+  targetX: number;
+  targetY: number;
+  sourceControlX: number;
+  sourceControlY: number;
+  targetControlX: number;
+  targetControlY: number;
+}): [number, number] {
+  /*
+   * cubic bezier t=0.5 mid point, not the actual mid point, but easy to calculate
+   * https://stackoverflow.com/questions/67516101/how-to-find-distance-mid-point-of-bezier-curve
+   */
+  const centerX =
+    sourceX * END_WEIGHT +
+    sourceControlX * CONTROL_WEIGHT +
+    targetControlX * CONTROL_WEIGHT +
+    targetX * END_WEIGHT;
+  const centerY =
+    sourceY * END_WEIGHT +
+    sourceControlY * CONTROL_WEIGHT +
+    targetControlY * CONTROL_WEIGHT +
+    targetY * END_WEIGHT;
+  return [centerX, centerY];
+}
+
+function calculateControlOffset(distance: number, curvature: number): number {
+  if (distance >= 0) {
+    return HALF * distance;
+  }
+
+  return curvature * CURVATURE_SCALE * Math.sqrt(-distance);
+}
+
+export function getControlWithCurvature({
+  pos,
+  x1,
+  y1,
+  x2,
+  y2,
+  c,
+}: {
+  pos: Position;
+  x1: number;
+  y1: number;
+  x2: number;
+  y2: number;
+  c: number;
+}): [number, number] {
+  switch (pos) {
+    case "left":
+      return [x1 - calculateControlOffset(x1 - x2, c), y1];
+    case "right":
+      return [x1 + calculateControlOffset(x2 - x1, c), y1];
+    case "top":
+      return [x1, y1 - calculateControlOffset(y1 - y2, c)];
+    case "bottom":
+      return [x1, y1 + calculateControlOffset(y2 - y1, c)];
+  }
+}

package/src/vendor/xyflow/changes.ts

@@ -0,0 +1,177 @@
+// Adapted from xyflow, packages/react/src/utils/changes.ts and
+// packages/system/src/utils/edges/general.ts (MIT, see LICENSE and README.md in this
+// directory): typed without `any`, and without the resizer's attributes.
+import type { Connection, Edge, EdgeChange, Node, NodeChange } from "../../types.ts";
+
+type Change<T> =
+  | { type: "add"; item: T; index?: number }
+  | { type: "replace"; id: string; item: T }
+  | { type: "remove"; id: string }
+  | { type: "select"; id: string; selected: boolean }
+  | { type: "position"; id: string; position?: Element["position"]; dragging?: boolean }
+  | { type: "dimensions"; id: string };
+type Element = { id: string; selected?: boolean; position?: unknown; dragging?: boolean };
+
+/*
+ * This function applies changes to nodes or edges that are triggered by the canvas.
+ * When you drag a node for example, the canvas sends a position change update.
+ * This function then applies the changes and returns the updated elements.
+ */
+function applyChanges<T extends Element>(
+  changes: readonly Change<T>[],
+  elements: readonly T[],
+): T[] {
+  const updatedElements: T[] = [];
+  /*
+   * By storing a map of changes for each element, we can a quick lookup as we
+   * iterate over the elements array!
+   */
+  const changesMap = new Map<string, Change<T>[]>();
+  const addItemChanges: { item: T; index?: number }[] = [];
+
+  for (const change of changes) {
+    if (change.type === "add") {
+      addItemChanges.push(change);
+      continue;
+    } else if (change.type === "remove" || change.type === "replace") {
+      /*
+       * For a 'remove' change we can safely ignore any other changes queued for
+       * the same element, it's going to be removed anyway!
+       */
+      changesMap.set(change.id, [change]);
+    } else {
+      const elementChanges = changesMap.get(change.id);
+
+      if (elementChanges) {
+        /*
+         * If we have some changes queued already, we can do a mutable update of
+         * that array and save ourselves some copying.
+         */
+        elementChanges.push(change);
+      } else {
+        changesMap.set(change.id, [change]);
+      }
+    }
+  }
+
+  for (const element of elements) {
+    const queued = changesMap.get(element.id);
+
+    /*
+     * When there are no changes for an element we can just push it unmodified,
+     * no need to copy it.
+     */
+    if (!queued) {
+      updatedElements.push(element);
+      continue;
+    }
+
+    const [first] = queued;
+    // If we have a 'remove' change queued, it'll be the only change in the array
+    if (first?.type === "remove") {
+      continue;
+    }
+
+    if (first?.type === "replace") {
+      updatedElements.push({ ...first.item });
+      continue;
+    }
+
+    /**
+     * For other types of changes, we want to start with a shallow copy of the
+     * object so React knows this element has changed. Sequential changes will
+     * each _mutate_ this object, so there's only ever one copy.
+     */
+    const updatedElement = { ...element };
+
+    for (const change of queued) {
+      applyChange(change, updatedElement);
+    }
+
+    updatedElements.push(updatedElement);
+  }
+
+  /*
+   * we need to wait for all changes to be applied before adding new items
+   * to be able to add them at the correct index
+   */
+  for (const change of addItemChanges) {
+    if (change.index !== undefined) {
+      updatedElements.splice(change.index, 0, { ...change.item });
+    } else {
+      updatedElements.push({ ...change.item });
+    }
+  }
+
+  return updatedElements;
+}
+
+// A connection spread into an edge is one once it has an id: this narrows it to `E`.
+function isElement<T>(item: unknown): item is T {
+  return typeof item === "object" && item !== null && "id" in item;
+}
+
+// Applies a single change to an element. This is a *mutable* update.
+function applyChange<T extends Element>(change: Change<T>, element: T): void {
+  switch (change.type) {
+    case "select": {
+      element.selected = change.selected;
+      break;
+    }
+
+    case "position": {
+      if (typeof change.position !== "undefined") {
+        element.position = change.position;
+      }
+
+      if (typeof change.dragging !== "undefined") {
+        element.dragging = change.dragging;
+      }
+
+      break;
+    }
+  }
+}
+
+/** Applies what the canvas proposes (drag, selection, removal…) to the application's nodes. */
+export function applyNodeChanges<N extends Node = Node>(
+  changes: readonly NodeChange<N>[],
+  nodes: readonly N[],
+): N[] {
+  return applyChanges(changes, nodes);
+}
+
+/** Applies what the canvas proposes to the application's edges. */
+export function applyEdgeChanges<E extends Edge = Edge>(
+  changes: readonly EdgeChange<E>[],
+  edges: readonly E[],
+): E[] {
+  return applyChanges(changes, edges);
+}
+
+export const getEdgeId = ({ source, sourceHandle, target, targetHandle }: Connection | Edge) =>
+  `xy-edge__${source}${sourceHandle || ""}-${target}${targetHandle || ""}`;
+
+const connectionExists = (edge: Edge, edges: readonly Edge[]) =>
+  edges.some(
+    (el) =>
+      el.source === edge.source &&
+      el.target === edge.target &&
+      (el.sourceHandle === edge.sourceHandle || (!el.sourceHandle && !edge.sourceHandle)) &&
+      (el.targetHandle === edge.targetHandle || (!el.targetHandle && !edge.targetHandle)),
+  );
+
+/** `edges` with a new edge for `connection`, unless the same connection exists already. */
+export function addEdge<E extends Edge = Edge>(
+  connection: (Connection & Partial<Omit<E, keyof Connection>>) | E,
+  edges: readonly E[],
+  getId: (connection: Connection | Edge) => string = getEdgeId,
+): E[] {
+  if (!connection.source || !connection.target) return [...edges];
+  const known = "id" in connection ? connection.id : undefined;
+  const edge: Edge = { ...connection, id: typeof known === "string" ? known : getId(connection) };
+  if (connectionExists(edge, edges)) return [...edges];
+  if (edge.sourceHandle === null) delete edge.sourceHandle;
+  if (edge.targetHandle === null) delete edge.targetHandle;
+  return isElement<E>(edge) ? [...edges, edge] : [...edges];
+}