@multiplatform.one/node-graph 7.7.2

package/src/edges/Edges.stories.tsx

@@ -0,0 +1,271 @@
+/**
+ * NodeGraph/Edges — the four kinds side by side, plus a refused connection with
+ * its real message.
+ *
+ * The canvas mounts `ReactFlow` directly rather than `NodeGraphWeb`, which is
+ * task 1.11's. Nodes are React Flow's own default type for the same reason:
+ * this story is about the EDGES, and pulling in `GraphNode` (task 1.8) would
+ * make it fail for reasons that have nothing to do with them.
+ */
+
+import { YStack } from "tamagui";
+import "@xyflow/react/dist/style.css";
+// The package's own published stylesheet. Task 1.11's `NodeGraphWeb` imports it
+// for real consumers; a story that mounts `ReactFlow` directly imports it here.
+import "../../css/graph.css";
+import { SizableText, View } from "tamagui";
+// Relative, not `@multiplatform.one/node-graph/model`: the subpath resolves
+// into `dist/`, which a source-consumed workspace package never builds.
+import { createGraphSchema, defaultRules, resolvePorts, validateConnection } from "../model/index";
+import { legalTargets } from "../interaction/legalTargets";
+import { connectionPuckLabel } from "../react-flow/ConnectionPuck";
+import { NodeGraphWeb } from "../react-flow/NodeGraphWeb";
+import { demoGraphSchema } from "../react-flow/demoNodeBody";
+import { demoDocument } from "../react-flow/fixtures";
+import type { GraphDocument } from "../model/index";
+import { graphEdgeType, graphEdgeTypes } from "./GraphEdge";
+import { builtinEdgeKindNames, builtinEdgeKinds } from "./edgeKinds";
+import type { BuiltinEdgeData, BuiltinEdgeKind } from "./edgeKinds";
+import { edgeMarkerEnd } from "./edgeStyle";
+import { domOnlyStoryDecorator } from "../native/DomOnlyStory";
+import { Position, ReactFlow, ReactFlowProvider } from "../react-flow/xy";
+import type { Edge, Node } from "../react-flow/xy";
+
+export default {
+  title: "NodeGraph/Edges",
+  parameters: { status: { type: "beta" } },
+  /*
+    NATIVE STOPS HERE (task 6.8). These stories mount `ReactFlow` directly —
+    the edge kinds are the subject, so the lanes are built by hand rather than
+    through a document — and React Flow renders `div`s and `svg`s, which React
+    Native answers with `View config getter callback for component "div" must
+    be a function` and a dead tree.
+
+    The edges themselves render on device inside the canvas's WebView, which is
+    what `NodeGraph → NodeGraph` shows.
+  */
+  decorators: [
+    domOnlyStoryDecorator({
+      needs: "mounts React Flow directly to build one lane per edge kind",
+      readInstead: "NodeGraph → NodeGraph, where the same typed edges render in a real document",
+    }),
+  ],
+};
+
+const rowHeight = 110;
+
+/** One source/target pair per kind, stacked, so all four read at once. */
+function laneNodes(labels: readonly string[]): Node[] {
+  return labels.flatMap((label, row) => [
+    {
+      id: `s${row}`,
+      position: { x: 0, y: row * rowHeight },
+      data: { label },
+      sourcePosition: Position.Right,
+      targetPosition: Position.Left,
+    },
+    {
+      id: `t${row}`,
+      position: { x: 320, y: row * rowHeight },
+      data: { label: "target" },
+      sourcePosition: Position.Right,
+      targetPosition: Position.Left,
+    },
+  ]);
+}
+
+function laneEdge(kind: BuiltinEdgeKind, row: number, label?: string): Edge {
+  return {
+    id: `e${row}`,
+    type: graphEdgeType,
+    source: `s${row}`,
+    target: `t${row}`,
+    // The marker TYPE rides on the edge object: React Flow builds its marker
+    // defs from the edges array.
+    markerEnd: edgeMarkerEnd({ kind }),
+    data: { kind, label },
+  };
+}
+
+function Canvas({ nodes, edges }: { nodes: Node[]; edges: Edge[] }) {
+  return (
+    <View width="100%" height={rowHeight * Math.max(1, edges.length) + 60}>
+      <ReactFlowProvider>
+        <ReactFlow
+          nodes={nodes}
+          edges={edges}
+          edgeTypes={graphEdgeTypes}
+          fitView
+          proOptions={{ hideAttribution: true }}
+        />
+      </ReactFlowProvider>
+    </View>
+  );
+}
+
+export const main = {
+  name: "Main",
+  render: () => (
+    <Canvas
+      nodes={laneNodes(builtinEdgeKindNames)}
+      edges={builtinEdgeKindNames.map((kind, row) => laneEdge(kind, row))}
+    />
+  ),
+};
+
+export const labels = {
+  name: "Labels",
+  render: () => (
+    <Canvas
+      nodes={laneNodes(builtinEdgeKindNames)}
+      edges={builtinEdgeKindNames.map((kind, row) => laneEdge(kind, row, kind))}
+    />
+  ),
+};
+
+// ── Refused ────────────────────────────────────────────────────
+// The message is the model's, not the story's: `validateConnection` produces
+// the code and the wording, and this story only shows them. A refusal invented
+// here would drift from the one a user actually sees on a drop.
+
+type Nodes = {
+  readonly numberOut: Record<string, never>;
+  readonly textIn: Record<string, never>;
+};
+
+const refusalSchema = createGraphSchema<Nodes, BuiltinEdgeData>({
+  id: "edges-story-refusal",
+  nodes: {
+    numberOut: {
+      kind: "numberOut",
+      render: () => null,
+      defaultData: {},
+      measure: { width: 172, minHeight: 48 },
+      ports: [
+        { id: "out", side: "right", direction: "out", dataType: "number" },
+        // An input on the SAME node, so the self-loop case below really is a
+        // self loop. Without it `a.out -> a.out` reports `wrong-direction`,
+        // because refuseDirection runs first — correct, but not what a story
+        // captioned "onto itself" claims to be showing.
+        { id: "in", side: "left", direction: "in", dataType: "number" },
+      ],
+    },
+    textIn: {
+      kind: "textIn",
+      render: () => null,
+      defaultData: {},
+      measure: { width: 172, minHeight: 48 },
+      ports: [{ id: "in", side: "left", direction: "in", dataType: "string" }],
+    },
+  },
+  edges: builtinEdgeKinds,
+  rules: defaultRules,
+});
+
+const refusalDoc: GraphDocument<Nodes, BuiltinEdgeData> = {
+  version: 1,
+  nodes: [
+    { id: "a", kind: "numberOut", position: { x: 0, y: 0 }, data: {} },
+    { id: "b", kind: "textIn", position: { x: 320, y: 0 }, data: {} },
+  ],
+  edges: [],
+};
+
+const refusals = [
+  {
+    title: "number → string",
+    source: { node: "a", port: "out" },
+    target: { node: "b", port: "in" },
+  },
+  { title: "backwards", source: { node: "b", port: "in" }, target: { node: "a", port: "out" } },
+  { title: "onto itself", source: { node: "a", port: "out" }, target: { node: "a", port: "in" } },
+] as const;
+
+export const refused = {
+  name: "Refused",
+  render: () => (
+    <YStack gap="$3" padding="$4">
+      {refusals.map(({ title, source, target }) => {
+        const verdict = validateConnection({
+          document: refusalDoc,
+          schema: refusalSchema,
+          source,
+          target,
+        });
+        return (
+          <YStack key={title} gap="$1">
+            <SizableText fontWeight="600">{title}</SizableText>
+            <SizableText>
+              {verdict.ok ? "allowed" : `${verdict.code} — ${verdict.message}`}
+            </SizableText>
+          </YStack>
+        );
+      })}
+    </YStack>
+  ),
+};
+
+/**
+ * `Connecting` — legal-target magnetism and the puck that names what you are
+ * over (design §7.4, task 3.5).
+ *
+ * DRAG from a port. Two things to watch, and they are the whole task:
+ *
+ *  1. The puck at the top of the canvas names the candidate — but only while
+ *     the candidate is one `validateConnection` accepts. `connectionRadius` is
+ *     the 44 px hit diameter (task 3.4 H5), so React Flow's magnetism will snap
+ *     the drag onto a refused port quite happily; the puck refuses to promise
+ *     it and falls back to naming what you are dragging FROM.
+ *  2. The puck does not grow or shrink when you zoom. It renders as a sibling
+ *     of `.react-flow__viewport`, so the pan/zoom matrix never reaches it.
+ *
+ * The table underneath is the same `connectionPuckLabel` call, run over every
+ * port in the document at once, so what the puck will say is readable without
+ * holding a mouse button down.
+ */
+const connectDoc = demoDocument();
+const connectSchema = demoGraphSchema();
+
+function everyTarget(): { node: string; port: string }[] {
+  return connectDoc.nodes.flatMap((node) =>
+    resolvePorts(connectSchema, node).map((spec) => ({ node: node.id, port: spec.id })),
+  );
+}
+
+export const connecting = {
+  name: "Connecting",
+  render: () => {
+    const source = { node: "a", port: "rows" };
+    const legal = new Set(
+      legalTargets({ document: connectDoc, schema: connectSchema, source }).map(
+        (ref) => `${ref.node}:${ref.port}`,
+      ),
+    );
+    return (
+      <YStack gap="$5" padding="$4">
+        <View width="100%" height={420}>
+          <NodeGraphWeb schema={connectSchema} defaultDocument={connectDoc} />
+        </View>
+        <YStack gap="$2">
+          <SizableText fontWeight="600">
+            Dragging from a / rows — what the puck says over each port
+          </SizableText>
+          {everyTarget().map((target) => {
+            const key = `${target.node}:${target.port}`;
+            const label = connectionPuckLabel({
+              document: connectDoc,
+              schema: connectSchema,
+              source,
+              candidate: target,
+            });
+            return (
+              <SizableText key={key} opacity={legal.has(key) ? 1 : 0.55}>
+                {key} — {label?.legal ? "MAGNETIC" : "refused"} — {label?.text}
+              </SizableText>
+            );
+          })}
+        </YStack>
+      </YStack>
+    );
+  },
+};

package/src/edges/GraphEdge.tsx

@@ -0,0 +1,198 @@
+/**
+ * ONE registered React Flow edge type, switching on `edge.kind` internally.
+ *
+ * Design §4.4: the package registers exactly one `edgeType`. That keeps the
+ * edge component count at one and the `d`-string building in one place, which
+ * is where the merged single-path overview layer plugs in later — 1,968 `<svg>`
+ * down to 1 in the engine-split spike. Registering four types would make that a
+ * four-site change.
+ *
+ * `edge.kind` is the MODEL's kind and rides in `edge.data.kind`; React Flow's
+ * own `edge.type` is always `graphEdgeType`.
+ */
+
+import { usePresetContext, useResolvedKnobs } from "@multiplatform.one/theme";
+import { defaultKnobs } from "@multiplatform.one/theme";
+import type { Animation, BorderWidth } from "@multiplatform.one/theme";
+import { memo } from "react";
+import { SizableText, useTheme, View } from "tamagui";
+import {
+  BaseEdge,
+  EdgeLabelRenderer,
+  getBezierPath,
+  getSmoothStepPath,
+  getStraightPath,
+} from "../react-flow/xy";
+import type { EdgeProps } from "../react-flow/xy";
+import { resolveEdgeStyle, themeTokenName } from "./edgeStyle";
+import type { EdgePathKind, EdgeStyle } from "./edgeStyle";
+
+export const graphEdgeType = "mpGraphEdge";
+
+export interface GraphEdgeData {
+  /** The model's `edge.kind`. */
+  readonly kind?: string;
+  /** `EdgeKindSpec.appearance`, when the kind is not one of the four. */
+  readonly appearance?: string;
+  readonly label?: string;
+}
+
+interface PathGeometry {
+  readonly sourceX: number;
+  readonly sourceY: number;
+  readonly targetX: number;
+  readonly targetY: number;
+  readonly sourcePosition: EdgeProps["sourcePosition"];
+  readonly targetPosition: EdgeProps["targetPosition"];
+}
+
+/**
+ * `step` is `getSmoothStepPath` with a zero corner radius — React Flow has no
+ * separate step builder, and the design's table names four path SHAPES, not
+ * four functions.
+ */
+export function buildEdgePath(
+  path: EdgePathKind,
+  geometry: PathGeometry,
+): [d: string, labelX: number, labelY: number] {
+  const { sourceX, sourceY, targetX, targetY, sourcePosition, targetPosition } = geometry;
+  switch (path) {
+    case "bezier": {
+      const [d, labelX, labelY] = getBezierPath({
+        sourceX,
+        sourceY,
+        targetX,
+        targetY,
+        sourcePosition,
+        targetPosition,
+      });
+      return [d, labelX, labelY];
+    }
+    case "straight": {
+      const [d, labelX, labelY] = getStraightPath({ sourceX, sourceY, targetX, targetY });
+      return [d, labelX, labelY];
+    }
+    case "step":
+    case "smoothstep": {
+      const [d, labelX, labelY] = getSmoothStepPath({
+        sourceX,
+        sourceY,
+        targetX,
+        targetY,
+        sourcePosition,
+        targetPosition,
+        borderRadius: path === "step" ? 0 : undefined,
+      });
+      return [d, labelX, labelY];
+    }
+  }
+}
+
+/**
+ * The raw knob values an edge paints from.
+ *
+ * `useResolvedKnobs` returns `knobProps`, not the knob NAMES, and the edge
+ * needs the names because §11 remaps `borderWidth` rather than honouring the
+ * resolved value. So this reads the same Preset context `useResolvedKnobs`
+ * reads at its own step 1 — which means task 1.6's `KnobEnvelopeProvider`,
+ * which rebuilds that context inside the WebView, feeds this hook with no
+ * change here.
+ */
+export function useEdgeKnobs(): { borderWidth: BorderWidth; animation: Animation } {
+  const preset = usePresetContext();
+  const knobs = preset ? { ...preset.preset.knobs, ...preset.overrides } : defaultKnobs;
+  return { borderWidth: knobs.borderWidth, animation: knobs.animation };
+}
+
+/**
+ * A token is not a CSS value. `stroke: "$color9"` is an invalid declaration, so
+ * the browser drops it and falls through to React Flow's own
+ * `.react-flow__edge-path` rule — which resolves to nothing, because its
+ * `--xy-edge-stroke` is undefined until task 1.7's bridge writes it. The result
+ * is a canvas of invisible edges with visible arrowheads, which is what the
+ * story showed before this existed.
+ *
+ * So the token is resolved through the live Tamagui theme here. Task 1.7's
+ * `--mp-graph-edge-stroke` still wins when it lands, because it is the first
+ * arm of the `var()` fallback below.
+ */
+function useStrokeValue(stroke: string): string {
+  const theme = useTheme();
+  const entry = (theme as unknown as Record<string, { get?: () => unknown } | undefined>)[
+    themeTokenName(stroke)
+  ];
+  const value = entry?.get?.();
+  // `currentColor` rather than a hex fallback: a hex literal in this package is
+  // exactly what `edgeStyle.spec.ts` bans, and an edge that inherits the canvas
+  // ink is still visible.
+  return typeof value === "string" ? value : "currentColor";
+}
+
+export function GraphEdgeComponent(props: EdgeProps) {
+  const data = (props.data ?? {}) as GraphEdgeData;
+  const { borderWidth, animation } = useEdgeKnobs();
+  const style: EdgeStyle = resolveEdgeStyle({
+    kind: data.kind ?? "flow",
+    appearance: data.appearance,
+    borderWidth,
+    animation,
+  });
+  const strokeValue = useStrokeValue(style.stroke);
+  const [d, labelX, labelY] = buildEdgePath(style.path, props);
+  const label = data.label ?? (typeof props.label === "string" ? props.label : undefined);
+
+  return (
+    <>
+      <BaseEdge
+        id={props.id}
+        path={d}
+        // Already a resolved `url(#...)`: React Flow builds the marker defs
+        // from the edges array, so the TYPE is chosen by `edgeMarkerEnd` where
+        // the edge is built, not here.
+        markerEnd={props.markerEnd}
+        style={{
+          stroke: `var(--mp-graph-edge-stroke, ${strokeValue})`,
+          strokeWidth: style.strokeWidth,
+          strokeDasharray: style.strokeDasharray,
+          animation: style.animation,
+          ...props.style,
+        }}
+      />
+      {label ? <EdgeLabel label={label} x={labelX} y={labelY} /> : null}
+    </>
+  );
+}
+
+/**
+ * §11 radius: a chip inside the canvas frame steps down, so it remaps to
+ * `borderRadiusNested`. Whole `knobProps.*` fragments only, per AGENTS.md — a
+ * cherry-picked token is how a chip ends up half-themed.
+ *
+ * Padding is `panelPadding`, the only complete padding fragment the recipes
+ * expose (`public/theme/src/theme/recipes.ts`). §11 rules the chip's RADIUS and
+ * says nothing about its padding, so this is the nearest whole fragment rather
+ * than an invented one.
+ */
+function EdgeLabel({ label, x, y }: { label: string; x: number; y: number }) {
+  const { knobProps } = useResolvedKnobs({ component: "GraphEdge" });
+  return (
+    <EdgeLabelRenderer>
+      <View
+        className="mp-graph-edge-label"
+        position="absolute"
+        transform={`translate(-50%, -50%) translate(${x}px, ${y}px)`}
+        pointerEvents="none"
+        {...knobProps.surface}
+        {...knobProps.borderRadiusNested}
+        {...knobProps.panelPadding}
+      >
+        <SizableText {...knobProps.body}>{label}</SizableText>
+      </View>
+    </EdgeLabelRenderer>
+  );
+}
+
+export const GraphEdge = memo(GraphEdgeComponent);
+
+/** The whole registration. One entry, on purpose. */
+export const graphEdgeTypes = { [graphEdgeType]: GraphEdge } as const;

package/src/edges/edgeKinds.ts

@@ -0,0 +1,51 @@
+/**
+ * The four built-in edge kinds, design §4.4.
+ *
+ * These are MODEL objects — `EdgeKindSpec`s a consumer drops into
+ * `createGraphSchema`. Their appearance lives in `edgeStyle.ts` and is reached
+ * by NAME, so the model half stays free of rendering and one registered React
+ * Flow edge type can switch on the kind internally.
+ */
+
+import type { EdgeKindSpec } from "../model/index";
+
+export type BuiltinEdgeKind = "flow" | "data" | "error" | "conditional";
+
+/**
+ * Declaration order is the order the table in design §4.4 reads, and the order
+ * the `Main` story lays them out.
+ */
+export const builtinEdgeKindNames: readonly BuiltinEdgeKind[] = [
+  "flow",
+  "data",
+  "error",
+  "conditional",
+];
+
+/**
+ * A type alias, not an interface. An interface has no implicit index signature,
+ * so `interface BuiltinEdgeData` does not satisfy `EdgeKindDefs` and
+ * `createGraphSchema` refuses it. That is a TypeScript rule about declaration
+ * merging rather than a modelling choice, and it bites every consumer the same
+ * way — so the kind maps in this package are written the shape a consumer must
+ * write too.
+ */
+export type BuiltinEdgeData = {
+  /** Control moving. */
+  readonly flow: Record<string, never>;
+  /** A value moving. */
+  readonly data: { readonly dataType?: string };
+  /** The failure branch. */
+  readonly error: { readonly reason?: string };
+  /** A branch not always taken. */
+  readonly conditional: { readonly when?: string };
+};
+
+export const builtinEdgeKinds: {
+  readonly [K in BuiltinEdgeKind]: EdgeKindSpec<BuiltinEdgeData[K]>;
+} = {
+  flow: { kind: "flow", defaultData: {}, appearance: "flow" },
+  data: { kind: "data", defaultData: {}, appearance: "data" },
+  error: { kind: "error", defaultData: {}, appearance: "error" },
+  conditional: { kind: "conditional", defaultData: {}, appearance: "conditional" },
+};