@cueplusplus/ui 0.1.0

package/dist/flow/flow.css

@@ -0,0 +1,121 @@
+/*! @cueplusplus/ui — React Flow theme layer.
+ *
+ * Consumer app CSS, in this order:
+ *   @import "@xyflow/react/dist/style.css";
+ *   @import "@cueplusplus/ui/flow.css";
+ *
+ * Plain CSS, no Tailwind: this file only re-inks chrome the *library* paints,
+ * so it has to work in a lane-B app that never installed Tailwind at all.
+ *
+ * Two mechanisms, deliberately:
+ *
+ * 1. Custom properties. React Flow consults `--xy-<thing>` before its own
+ *    `--xy-<thing>-default` for every colour it paints, so declaring them on
+ *    `.react-flow` re-themes edges, handles, controls, the minimap and the
+ *    selection box without touching specificity at all — this block wins over
+ *    the library's defaults whichever stylesheet loads last. It is the same map
+ *    `useFlowTheme().style` publishes, and a test asserts the two agree.
+ * 2. Two extra rules for the things with no property hook — the controls
+ *    capsule's shape and the pulse's keyframes. Those are scoped
+ *    `.react-flow .react-flow__…`, one class more specific than the library's
+ *    own rule, so they also win regardless of import order.
+ *
+ * Nothing here is required: every component in `@cueplusplus/ui/flow` publishes
+ * the same map on its own root. Import this to theme a canvas built from raw
+ * `@xyflow/react` parts, or to keep the token map out of your React tree.
+ */
+
+.react-flow {
+  /* The pane itself. Left to the library this is a hard-coded #141414 in dark
+     mode, which is nobody's ground. */
+  --xy-background-color: var(--cue-bg);
+  --xy-background-pattern-color: var(--cue-surface-2);
+
+  /* Wires. `border-strong` rather than a fg rung: an edge nobody has said
+     anything about is structure, not content. */
+  --xy-edge-stroke: var(--cue-border-strong);
+  --xy-edge-stroke-width: 1.5;
+  --xy-edge-stroke-selected: var(--cue-fg);
+  --xy-connectionline-stroke: var(--cue-accent);
+  --xy-connectionline-stroke-width: 1.5;
+  --xy-edge-label-background-color: var(--cue-surface-2);
+  --xy-edge-label-color: var(--cue-fg);
+
+  /* Connection points, for a plain `Handle`. `NodeHandle` paints itself. */
+  --xy-handle-background-color: var(--cue-accent);
+  --xy-handle-border-color: var(--cue-bg);
+
+  /* The library's built-in node types. A `NodeCard` uses none of this. */
+  --xy-node-background-color: var(--cue-surface-1);
+  --xy-node-border: 1px solid var(--cue-border);
+  --xy-node-border-radius: var(--cue-radius-surface);
+  --xy-node-color: var(--cue-fg);
+  --xy-node-group-background-color: var(--cue-surface-2);
+  /* Rings rather than drops: this portfolio spends its one shadow on overlays. */
+  --xy-node-boxshadow-hover: 0 0 0 1px var(--cue-border-strong);
+  --xy-node-boxshadow-selected: 0 0 0 1px var(--cue-fg);
+
+  /* The zoom capsule, which is an overlay surface like any other. */
+  --xy-controls-button-background-color: var(--cue-surface-2);
+  --xy-controls-button-background-color-hover: var(--cue-surface-3);
+  --xy-controls-button-color: var(--cue-fg-muted);
+  --xy-controls-button-color-hover: var(--cue-accent);
+  --xy-controls-button-border-color: var(--cue-border);
+  --xy-controls-box-shadow: 0 8px 24px rgba(0, 0, 0, 0.4);
+
+  --xy-minimap-background-color: var(--cue-surface-1);
+  --xy-minimap-mask-background-color: color-mix(in oklch, var(--cue-bg) 70%, transparent);
+  --xy-minimap-mask-stroke-color: var(--cue-border);
+  --xy-minimap-node-background-color: var(--cue-surface-3);
+  --xy-minimap-node-stroke-color: var(--cue-border);
+
+  /* Lasso select and the node-resize grips. */
+  --xy-selection-background-color: var(--cue-accent-soft);
+  --xy-selection-border: 1px dashed var(--cue-accent);
+  --xy-resize-background-color: var(--cue-accent);
+
+  --xy-attribution-background-color: color-mix(in oklch, var(--cue-bg) 70%, transparent);
+}
+
+/* The capsule's shape: no `--xy-*` hook exists for it, so it is a rule.
+   `overflow: hidden` is what makes the first and last buttons take the
+   capsule's corners instead of squaring them off. */
+.react-flow .react-flow__controls {
+  border: 1px solid var(--cue-border-overlay);
+  border-radius: var(--cue-radius-overlay);
+  overflow: hidden;
+}
+
+/* The buttons are operable, so they keep a real focus ring. Inset, because the
+   capsule clips anything drawn outside it. */
+.react-flow .react-flow__controls-button:focus-visible {
+  outline: 2px solid var(--cue-focus);
+  outline-offset: -2px;
+}
+
+/* The attribution's own link colour is a hard-coded #999 in the library. */
+.react-flow .react-flow__attribution a {
+  color: var(--cue-fg-subtle);
+}
+
+/* The pulse on a live wire (`SignalEdge`). The dash pattern is inline on the
+   path; only the march lives here, because keyframes cannot be. The offset is a
+   whole number of dash periods (2 x (3 + 8)) — anything else visibly jumps as
+   the animation loops. */
+@keyframes cue-signal-dash {
+  to {
+    stroke-dashoffset: -22;
+  }
+}
+
+.cue-signal-flow {
+  animation: cue-signal-dash 700ms linear infinite;
+}
+
+/* Reduced motion keeps the highlight and stops the march: the pulse carries no
+   information the wire's own opacity does not. */
+@media (prefers-reduced-motion: reduce) {
+  .cue-signal-flow {
+    animation: none;
+  }
+}

package/dist/flow/handles.d.ts

@@ -0,0 +1,40 @@
+import * as React from "react";
+import { HandleProps } from "@xyflow/react";
+//#region src/flow/handles.d.ts
+/** What a connection point is carrying, or refusing to. */
+type FlowHandleTone = "accent" | "muted" | "ok" | "busy" | "warn" | "danger" | "info";
+/**
+ * Pin diameter in px at the 16px root.
+ *
+ * The library's own 6px is a hard target with a mouse and an impossible one with
+ * a trackpad; 9px is what dmxhub's bridge settled on after the same complaint.
+ */
+declare const FLOW_HANDLE_SIZE = 9;
+interface NodeHandleProps extends HandleProps {
+  /** What the connection carries. Defaults to `"accent"`. */
+  tone?: FlowHandleTone;
+  /** Diameter in px at the 16px root, emitted as `rem`. Defaults to `9`. */
+  size?: number;
+}
+/**
+ * A connection point on a node, drawn as a pin rather than a dot.
+ *
+ * Everything visual is **inline style, not a class**, and that is deliberate:
+ * `.react-flow__handle` sets `background-color`, `border` and `width`/`height`
+ * from the library's own unlayered stylesheet, while Tailwind's utilities live in
+ * a cascade layer — and any layered rule loses to an unlayered one of the same
+ * specificity, whatever order the files load in. An inline declaration is the
+ * only paint that reliably wins, which is also how the port did it.
+ *
+ * The pin is ringed in `--cue-bg` rather than in the card's own surface, so it
+ * reads as lifted off the edge it straddles no matter which surface rung the
+ * node is on.
+ *
+ * @example
+ * <NodeHandle type="source" position={Position.Right} id="u1" />
+ * @example
+ * <NodeHandle type="target" position={Position.Left} id="in" tone="muted" />
+ */
+declare const NodeHandle: React.ForwardRefExoticComponent<NodeHandleProps & React.RefAttributes<HTMLDivElement>>;
+//#endregion
+export { FLOW_HANDLE_SIZE, FlowHandleTone, NodeHandle, NodeHandleProps };

package/dist/flow/handles.js

@@ -0,0 +1,61 @@
+"use client";
+import { toRem } from "../instruments/_rem.js";
+import * as React from "react";
+import { jsx } from "react/jsx-runtime";
+import { Handle } from "@xyflow/react";
+//#region src/flow/handles.tsx
+/**
+* Pin diameter in px at the 16px root.
+*
+* The library's own 6px is a hard target with a mouse and an impossible one with
+* a trackpad; 9px is what dmxhub's bridge settled on after the same complaint.
+*/
+const FLOW_HANDLE_SIZE = 9;
+const TONE_COLORS = {
+	accent: "var(--cue-accent)",
+	muted: "var(--cue-border-strong)",
+	ok: "var(--cue-ok)",
+	busy: "var(--cue-busy)",
+	warn: "var(--cue-warn)",
+	danger: "var(--cue-danger)",
+	info: "var(--cue-info)"
+};
+/**
+* A connection point on a node, drawn as a pin rather than a dot.
+*
+* Everything visual is **inline style, not a class**, and that is deliberate:
+* `.react-flow__handle` sets `background-color`, `border` and `width`/`height`
+* from the library's own unlayered stylesheet, while Tailwind's utilities live in
+* a cascade layer — and any layered rule loses to an unlayered one of the same
+* specificity, whatever order the files load in. An inline declaration is the
+* only paint that reliably wins, which is also how the port did it.
+*
+* The pin is ringed in `--cue-bg` rather than in the card's own surface, so it
+* reads as lifted off the edge it straddles no matter which surface rung the
+* node is on.
+*
+* @example
+* <NodeHandle type="source" position={Position.Right} id="u1" />
+* @example
+* <NodeHandle type="target" position={Position.Left} id="in" tone="muted" />
+*/
+const NodeHandle = React.forwardRef(function NodeHandle({ className, style, tone = "accent", size = 9, ...handleProps }, ref) {
+	return /* @__PURE__ */ jsx(Handle, {
+		ref,
+		"data-slot": "node-handle",
+		"data-tone": tone,
+		className,
+		style: {
+			width: toRem(size),
+			height: toRem(size),
+			minWidth: toRem(size),
+			minHeight: toRem(size),
+			backgroundColor: TONE_COLORS[tone],
+			borderColor: "var(--cue-bg)",
+			...style
+		},
+		...handleProps
+	});
+});
+//#endregion
+export { FLOW_HANDLE_SIZE, NodeHandle };

package/dist/flow/index.d.ts

@@ -0,0 +1,7 @@
+import { FLOW_NODE_FRAME_COLOR, FLOW_NODE_FRAME_FALLBACK, FLOW_NODE_FRAME_PROPERTY, FlowNodeState, FlowNodeTone, flowFrameColor } from "./_frame.js";
+import { FlowBackground, FlowBackgroundProps, FlowControls, FlowControlsProps } from "./controls.js";
+import { FLOW_HANDLE_SIZE, FlowHandleTone, NodeHandle, NodeHandleProps } from "./handles.js";
+import { NodeCard, NodeCardProps } from "./node-card.js";
+import { SIGNAL_EDGE_FLOW_CLASS, SIGNAL_EDGE_INTERACTION_WIDTH, SignalEdge, SignalEdgeData, SignalEdgeProps, SignalEdgeType, SignalTone } from "./signal-edge.js";
+import { FLOW_THEME_VARIABLES, FlowTheme, useFlowTheme } from "./use-flow-theme.js";
+export { FLOW_HANDLE_SIZE, FLOW_NODE_FRAME_COLOR, FLOW_NODE_FRAME_FALLBACK, FLOW_NODE_FRAME_PROPERTY, FLOW_THEME_VARIABLES, FlowBackground, type FlowBackgroundProps, FlowControls, type FlowControlsProps, type FlowHandleTone, type FlowNodeState, type FlowNodeTone, type FlowTheme, NodeCard, type NodeCardProps, NodeHandle, type NodeHandleProps, SIGNAL_EDGE_FLOW_CLASS, SIGNAL_EDGE_INTERACTION_WIDTH, SignalEdge, type SignalEdgeData, type SignalEdgeProps, type SignalEdgeType, type SignalTone, flowFrameColor, useFlowTheme };

package/dist/flow/index.js

@@ -0,0 +1,7 @@
+import { FLOW_NODE_FRAME_COLOR, FLOW_NODE_FRAME_FALLBACK, FLOW_NODE_FRAME_PROPERTY, flowFrameColor } from "./_frame.js";
+import { SIGNAL_EDGE_FLOW_CLASS, SIGNAL_EDGE_INTERACTION_WIDTH, SignalEdge } from "./signal-edge.js";
+import { FLOW_THEME_VARIABLES, useFlowTheme } from "./use-flow-theme.js";
+import { FlowBackground, FlowControls } from "./controls.js";
+import { FLOW_HANDLE_SIZE, NodeHandle } from "./handles.js";
+import { NodeCard } from "./node-card.js";
+export { FLOW_HANDLE_SIZE, FLOW_NODE_FRAME_COLOR, FLOW_NODE_FRAME_FALLBACK, FLOW_NODE_FRAME_PROPERTY, FLOW_THEME_VARIABLES, FlowBackground, FlowControls, NodeCard, NodeHandle, SIGNAL_EDGE_FLOW_CLASS, SIGNAL_EDGE_INTERACTION_WIDTH, SignalEdge, flowFrameColor, useFlowTheme };

package/dist/flow/node-card.d.ts

@@ -0,0 +1,71 @@
+import { FlowNodeState, FlowNodeTone } from "./_frame.js";
+import * as React from "react";
+//#region src/flow/node-card.d.ts
+interface NodeCardProps extends React.ComponentPropsWithoutRef<"div"> {
+  /** Where the node sits in the signal path. Inks the frame at rest. */
+  tone?: FlowNodeTone;
+  /**
+   * What the node is doing right now. Outranks `tone`.
+   *
+   * Pass React Flow's own `selected` through:
+   * `state={selected ? "selected" : "idle"}`.
+   */
+  state?: FlowNodeState;
+  /** The summary band: a label, a toggle, a badge. Also the drag handle. */
+  header?: React.ReactNode;
+  /** Whether the body is shown. Defaults to `true`; `false` renders the band alone. */
+  expanded?: boolean;
+  /**
+   * Called with the requested state when the caret is clicked. Supplying it is
+   * what makes the caret appear — a card nobody can collapse should not offer to.
+   */
+  onExpandedChange?: (expanded: boolean) => void;
+  /** Accessible name for the caret. Defaults to `"Collapse"` / `"Expand"`. */
+  toggleLabel?: string;
+  /** The body: rows, bars, fields. Full-bleed — rows own their own padding. */
+  children?: React.ReactNode;
+}
+/**
+ * A node on a graph canvas, drawn in this system's language.
+ *
+ * Framed with an **outline, never a border**. React Flow is told a node's height
+ * up front — every layout that stacks nodes computes it — and a 1px border on
+ * each side makes the rendered box 2px taller than the number the layout used,
+ * which is how node stacks end up overlapping by a hairline that grows with the
+ * node count. An outline is painted outside the box model entirely and costs
+ * nothing, so the formula and the DOM agree. `-outline-offset-1` then pulls it
+ * back inside the corner radius.
+ *
+ * The frame's colour is the node's state (see `_frame.ts`): selected beats live
+ * beats identity. When neither `tone` nor `state` is given the card paints no
+ * colour of its own and inherits `--cue-node-frame` from the node wrapper, which
+ * is how `useFlowTheme().nodeStyles` colours a whole class of nodes at once.
+ *
+ * The header band is the drag handle — pass
+ * `dragHandle: '[data-slot="node-card-header"]'` on the node so a pointer inside
+ * the body edits instead of dragging.
+ *
+ * Nothing here imports `@xyflow/react`: a node card is a div, and the same card
+ * draws a static diagram on a marketing page with no graph engine shipped. It
+ * also never clips — handles straddle the rim, so an `overflow-hidden` in
+ * `className` would slice every connection point in half.
+ *
+ * @example
+ * function MergeNode({ selected }: NodeProps) {
+ *   const [open, setOpen] = React.useState(true);
+ *   return (
+ *     <NodeCard
+ *       tone="processing"
+ *       state={selected ? "selected" : "live"}
+ *       header={<span className="truncate">merge · universe 3</span>}
+ *       expanded={open}
+ *       onExpandedChange={setOpen}
+ *     >
+ *       <DmxBar data={frame} />
+ *     </NodeCard>
+ *   );
+ * }
+ */
+declare const NodeCard: React.ForwardRefExoticComponent<NodeCardProps & React.RefAttributes<HTMLDivElement>>;
+//#endregion
+export { NodeCard, NodeCardProps };

package/dist/flow/node-card.js

@@ -0,0 +1,102 @@
+"use client";
+import { cn } from "../lib/cn.js";
+import { FLOW_NODE_FRAME_COLOR, FLOW_NODE_FRAME_PROPERTY, flowFrameColor } from "./_frame.js";
+import * as React from "react";
+import { jsx, jsxs } from "react/jsx-runtime";
+//#region src/flow/node-card.tsx
+/**
+* React Flow's two opt-outs, on every control a card owns.
+*
+* Without `nodrag` a click on the chevron drags the node out from under the
+* pointer; without `nopan` a drag that starts inside the card pans the whole
+* viewport. They are class names because that is the only interface the library
+* offers for it.
+*/
+const NO_CANVAS_GESTURE = "nodrag nopan";
+/**
+* A node on a graph canvas, drawn in this system's language.
+*
+* Framed with an **outline, never a border**. React Flow is told a node's height
+* up front — every layout that stacks nodes computes it — and a 1px border on
+* each side makes the rendered box 2px taller than the number the layout used,
+* which is how node stacks end up overlapping by a hairline that grows with the
+* node count. An outline is painted outside the box model entirely and costs
+* nothing, so the formula and the DOM agree. `-outline-offset-1` then pulls it
+* back inside the corner radius.
+*
+* The frame's colour is the node's state (see `_frame.ts`): selected beats live
+* beats identity. When neither `tone` nor `state` is given the card paints no
+* colour of its own and inherits `--cue-node-frame` from the node wrapper, which
+* is how `useFlowTheme().nodeStyles` colours a whole class of nodes at once.
+*
+* The header band is the drag handle — pass
+* `dragHandle: '[data-slot="node-card-header"]'` on the node so a pointer inside
+* the body edits instead of dragging.
+*
+* Nothing here imports `@xyflow/react`: a node card is a div, and the same card
+* draws a static diagram on a marketing page with no graph engine shipped. It
+* also never clips — handles straddle the rim, so an `overflow-hidden` in
+* `className` would slice every connection point in half.
+*
+* @example
+* function MergeNode({ selected }: NodeProps) {
+*   const [open, setOpen] = React.useState(true);
+*   return (
+*     <NodeCard
+*       tone="processing"
+*       state={selected ? "selected" : "live"}
+*       header={<span className="truncate">merge · universe 3</span>}
+*       expanded={open}
+*       onExpandedChange={setOpen}
+*     >
+*       <DmxBar data={frame} />
+*     </NodeCard>
+*   );
+* }
+*/
+const NodeCard = React.forwardRef(function NodeCard({ className, style, tone, state, header, expanded = true, onExpandedChange, toggleLabel, children, ...elementProps }, ref) {
+	const bodyId = React.useId();
+	const frame = flowFrameColor(tone, state);
+	const hasBody = expanded && children !== void 0 && children !== null;
+	return /* @__PURE__ */ jsxs("div", {
+		ref,
+		"data-slot": "node-card",
+		"data-tone": tone,
+		"data-state": state,
+		className: cn("relative flex min-w-0 flex-col rounded-(--radius-surface) bg-surface-1 font-mono text-(length:--cue-text-label) text-fg outline-1 outline-solid -outline-offset-1", state === "disabled" && "opacity-50", className),
+		style: {
+			outlineColor: FLOW_NODE_FRAME_COLOR,
+			...frame === void 0 ? null : { [FLOW_NODE_FRAME_PROPERTY]: frame },
+			...style
+		},
+		...elementProps,
+		children: [header === void 0 ? null : /* @__PURE__ */ jsxs("div", {
+			"data-slot": "node-card-header",
+			className: cn("flex h-control-sm min-w-0 shrink-0 items-center gap-(--cue-space-2) px-(--cue-space-3) font-medium", hasBody && "shadow-[inset_0_-1px_0_var(--cue-border)]"),
+			children: [/* @__PURE__ */ jsx("span", {
+				"data-slot": "node-card-title",
+				className: "min-w-0 flex-1 truncate",
+				children: header
+			}), onExpandedChange === void 0 ? null : /* @__PURE__ */ jsx("button", {
+				type: "button",
+				"data-slot": "node-card-toggle",
+				"aria-expanded": expanded,
+				"aria-controls": hasBody ? bodyId : void 0,
+				"aria-label": toggleLabel ?? (expanded ? "Collapse" : "Expand"),
+				className: cn(NO_CANVAS_GESTURE, "shrink-0 cursor-pointer border-0 bg-transparent p-0 text-(length:--cue-text-micro) leading-none text-fg-subtle outline-none select-none hover:text-fg-muted focus-visible:outline-2 focus-visible:outline-solid focus-visible:outline-offset-2 focus-visible:outline-accent"),
+				onClick: () => onExpandedChange(!expanded),
+				children: /* @__PURE__ */ jsx("span", {
+					"aria-hidden": "true",
+					children: expanded ? "▾" : "▸"
+				})
+			})]
+		}), hasBody ? /* @__PURE__ */ jsx("div", {
+			id: bodyId,
+			"data-slot": "node-card-body",
+			className: "flex min-w-0 flex-col",
+			children
+		}) : null]
+	});
+});
+//#endregion
+export { NodeCard };

package/dist/flow/signal-edge.d.ts

@@ -0,0 +1,60 @@
+import * as React from "react";
+import { Edge, EdgeProps } from "@xyflow/react";
+//#region src/flow/signal-edge.d.ts
+/** What a wire is carrying. `muted` is a link that exists but is switched off. */
+type SignalTone = "accent" | "ok" | "busy" | "warn" | "danger" | "info";
+/**
+ * The class the animated overlay carries.
+ *
+ * `flow.css` owns its `@keyframes` and its reduced-motion switch; the dash
+ * pattern itself is inline, so an app that never imported the stylesheet still
+ * gets a legible dashed highlight instead of a mystery second line.
+ */
+declare const SIGNAL_EDGE_FLOW_CLASS = "cue-signal-flow";
+/**
+ * Width of the invisible path the pointer actually hits, in px.
+ *
+ * A 1.6px wire is a nearly impossible click target and an outright impossible
+ * touch target. The library's own default is 20; 16 is the port's, and it is
+ * wide enough without swallowing the gap between two parallel wires.
+ */
+declare const SIGNAL_EDGE_INTERACTION_WIDTH = 16;
+interface SignalEdgeData extends Record<string, unknown> {
+  /** Signal is actually moving right now: full opacity plus the animated dash. */
+  live?: boolean;
+  /** The link exists but is switched off: grey, thin and dim. */
+  muted?: boolean;
+  /** What the wire carries. Defaults to `"accent"`. */
+  tone?: SignalTone;
+}
+/** The edge shape this component reads. Use it to type your `edges` array. */
+type SignalEdgeType = Edge<SignalEdgeData, "signal">;
+/** Props React Flow hands the edge — both endpoints already in viewport space. */
+type SignalEdgeProps = EdgeProps<SignalEdgeType>;
+/**
+ * A wire between two nodes, drawn as three paths.
+ *
+ * 1. **The wire.** A bezier in the tone's colour, thin and half-lit at rest.
+ * 2. **The hit path.** Sixteen invisible pixels of it, because nobody can click
+ *    1.6px. `BaseEdge` draws this one, and the edge label, for free.
+ * 3. **The pulse.** Only while `data.live` — a pale dashed overlay of the same
+ *    colour, marching along the wire. This is the only animation in the group,
+ *    it carries no information the opacity does not, and `flow.css` stops it
+ *    dead under `prefers-reduced-motion`.
+ *
+ * State is read from props rather than from a store on purpose: an edge that
+ * subscribed to "is this route live" would re-render on every frame of a 40Hz
+ * telemetry feed, times the number of edges. The host decides when the answer
+ * changed; this component only draws it. It also means the component is a pure
+ * function of its props — no hooks, no context, no canvas needed to test it.
+ *
+ * Selection outranks everything, including the pulse: two loud treatments on one
+ * wire read as neither.
+ *
+ * @example
+ * const edges = [{ id: "r1", source: "s1", target: "m1", type: "signal", data: { live: true } }];
+ * <ReactFlow edges={edges} edgeTypes={theme.edgeTypes} />
+ */
+declare function SignalEdge({ id, sourceX, sourceY, sourcePosition, targetX, targetY, targetPosition, selected, data, style, markerStart, markerEnd, interactionWidth, label, labelStyle, labelShowBg, labelBgStyle, labelBgPadding, labelBgBorderRadius }: SignalEdgeProps): React.JSX.Element;
+//#endregion
+export { SIGNAL_EDGE_FLOW_CLASS, SIGNAL_EDGE_INTERACTION_WIDTH, SignalEdge, SignalEdgeData, SignalEdgeProps, SignalEdgeType, SignalTone };

package/dist/flow/signal-edge.js

@@ -0,0 +1,108 @@
+import "react";
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+import { BaseEdge, getBezierPath } from "@xyflow/react";
+//#region src/flow/signal-edge.tsx
+const TONE_COLORS = {
+	accent: "var(--cue-accent)",
+	ok: "var(--cue-ok)",
+	busy: "var(--cue-busy)",
+	warn: "var(--cue-warn)",
+	danger: "var(--cue-danger)",
+	info: "var(--cue-info)"
+};
+/** A wire nobody has switched on. */
+const MUTED_COLOR = "var(--cue-fg-subtle)";
+/** Selection is the loudest thing on the canvas, and it is never a hue. */
+const SELECTED_COLOR = "var(--cue-fg)";
+/**
+* The class the animated overlay carries.
+*
+* `flow.css` owns its `@keyframes` and its reduced-motion switch; the dash
+* pattern itself is inline, so an app that never imported the stylesheet still
+* gets a legible dashed highlight instead of a mystery second line.
+*/
+const SIGNAL_EDGE_FLOW_CLASS = "cue-signal-flow";
+/**
+* Width of the invisible path the pointer actually hits, in px.
+*
+* A 1.6px wire is a nearly impossible click target and an outright impossible
+* touch target. The library's own default is 20; 16 is the port's, and it is
+* wide enough without swallowing the gap between two parallel wires.
+*/
+const SIGNAL_EDGE_INTERACTION_WIDTH = 16;
+/** The dash and gap of the flowing overlay, in px. */
+const FLOW_DASH = "3 8";
+/** A pale mix of the wire's own colour: the same signal, not a second one. */
+function flowHighlight(stroke) {
+	return `color-mix(in oklch, ${stroke} 55%, var(--cue-fg))`;
+}
+/**
+* A wire between two nodes, drawn as three paths.
+*
+* 1. **The wire.** A bezier in the tone's colour, thin and half-lit at rest.
+* 2. **The hit path.** Sixteen invisible pixels of it, because nobody can click
+*    1.6px. `BaseEdge` draws this one, and the edge label, for free.
+* 3. **The pulse.** Only while `data.live` — a pale dashed overlay of the same
+*    colour, marching along the wire. This is the only animation in the group,
+*    it carries no information the opacity does not, and `flow.css` stops it
+*    dead under `prefers-reduced-motion`.
+*
+* State is read from props rather than from a store on purpose: an edge that
+* subscribed to "is this route live" would re-render on every frame of a 40Hz
+* telemetry feed, times the number of edges. The host decides when the answer
+* changed; this component only draws it. It also means the component is a pure
+* function of its props — no hooks, no context, no canvas needed to test it.
+*
+* Selection outranks everything, including the pulse: two loud treatments on one
+* wire read as neither.
+*
+* @example
+* const edges = [{ id: "r1", source: "s1", target: "m1", type: "signal", data: { live: true } }];
+* <ReactFlow edges={edges} edgeTypes={theme.edgeTypes} />
+*/
+function SignalEdge({ id, sourceX, sourceY, sourcePosition, targetX, targetY, targetPosition, selected, data, style, markerStart, markerEnd, interactionWidth = 16, label, labelStyle, labelShowBg, labelBgStyle, labelBgPadding, labelBgBorderRadius }) {
+	const [path, labelX, labelY] = getBezierPath({
+		sourceX,
+		sourceY,
+		sourcePosition,
+		targetX,
+		targetY,
+		targetPosition
+	});
+	const muted = data?.muted === true;
+	const live = data?.live === true && !muted && selected !== true;
+	const stroke = selected === true ? SELECTED_COLOR : muted ? MUTED_COLOR : TONE_COLORS[data?.tone ?? "accent"];
+	return /* @__PURE__ */ jsxs(Fragment, { children: [/* @__PURE__ */ jsx(BaseEdge, {
+		id,
+		path,
+		markerStart,
+		markerEnd,
+		interactionWidth,
+		label,
+		labelX,
+		labelY,
+		labelStyle,
+		labelShowBg,
+		labelBgStyle,
+		labelBgPadding,
+		labelBgBorderRadius,
+		style: {
+			stroke,
+			strokeWidth: selected === true ? 2.4 : muted ? 1 : 1.6,
+			opacity: selected === true || live ? 1 : muted ? .4 : .6,
+			...style
+		}
+	}), live ? /* @__PURE__ */ jsx("path", {
+		d: path,
+		fill: "none",
+		pointerEvents: "none",
+		className: SIGNAL_EDGE_FLOW_CLASS,
+		style: {
+			stroke: flowHighlight(stroke),
+			strokeWidth: 1.9,
+			strokeDasharray: FLOW_DASH
+		}
+	}) : null] });
+}
+//#endregion
+export { SIGNAL_EDGE_FLOW_CLASS, SIGNAL_EDGE_INTERACTION_WIDTH, SignalEdge };

package/dist/flow/use-flow-theme.d.ts

@@ -0,0 +1,69 @@
+import { ResolvedMode } from "../system/theme-provider.js";
+import { FlowNodeTone } from "./_frame.js";
+import { SignalEdge } from "./signal-edge.js";
+import * as React from "react";
+//#region src/flow/use-flow-theme.d.ts
+/**
+ * React Flow paints its own chrome — edges, handles, controls, the minimap, the
+ * selection box — from a documented set of `--xy-*` custom properties, each one
+ * consulted before the library's built-in default. Mapping that set onto this
+ * system's tokens is the whole theme: no wrapper components, no props threaded
+ * through a graph, and a theme, mode or density switch that costs nothing
+ * because every value is a *reference*, re-resolved by the browser.
+ *
+ * The map is published two ways, and they are checked against each other
+ * (`test/flow/flow-css.test.ts`):
+ *
+ * - as this object, to spread on the canvas: `<ReactFlow style={theme.style}>`;
+ * - as the `.react-flow` block of `flow.css`, for apps that would rather import
+ *   a stylesheet than thread a prop.
+ *
+ * Either is enough. Both is harmless.
+ */
+declare const FLOW_THEME_VARIABLES: Readonly<Record<string, string>>;
+interface FlowTheme {
+  /**
+   * The resolved mode, for `<ReactFlow colorMode>`.
+   *
+   * Only a fallback: with {@link FlowTheme.style} spread (or `flow.css`
+   * imported) every value the library would pick from its own light/dark
+   * defaults has already been overridden. It costs one prop to be right anyway
+   * for the one that has not.
+   */
+  colorMode: ResolvedMode;
+  /** The `--xy-*` token map. Spread on `<ReactFlow style>`. */
+  style: Readonly<Record<string, string>>;
+  /** `{ signal: SignalEdge }`, stable across renders. */
+  edgeTypes: Readonly<Record<"signal", typeof SignalEdge>>;
+  /** `{ type: "signal", interactionWidth }`, stable across renders. */
+  defaultEdgeOptions: Readonly<{
+    type: "signal";
+    interactionWidth: number;
+  }>;
+  /** Frame colour per node kind, for a node's own `style`. */
+  nodeStyles: Readonly<Record<FlowNodeTone, React.CSSProperties>>;
+}
+/**
+ * Everything a `<ReactFlow>` needs to look like it belongs to this system.
+ *
+ * @example
+ * const theme = useFlowTheme();
+ * <ReactFlow
+ *   nodes={nodes}
+ *   edges={edges}
+ *   nodeTypes={nodeTypes}
+ *   edgeTypes={theme.edgeTypes}
+ *   defaultEdgeOptions={theme.defaultEdgeOptions}
+ *   colorMode={theme.colorMode}
+ *   style={theme.style}
+ * >
+ *   <FlowBackground />
+ *   <FlowControls />
+ * </ReactFlow>
+ * @example
+ * // Colour a whole class of nodes at once — the cards inherit the frame.
+ * const nodes = inputs.map((input) => ({ ...input, style: theme.nodeStyles.input }));
+ */
+declare function useFlowTheme(): FlowTheme;
+//#endregion
+export { FLOW_THEME_VARIABLES, FlowTheme, useFlowTheme };