@elabs-ai/components-flow 4.0.0

package/src/helper-lines/use-helper-lines.ts

@@ -0,0 +1,109 @@
+"use client";
+
+import { useCallback, useState } from "react";
+import { useReactFlow, type Node, type NodeChange } from "@xyflow/react";
+import { getHelperLines, type HelperLineRect } from "./get-helper-lines";
+
+export interface UseHelperLinesOptions {
+  /** Alignment threshold in flow coordinates. Defaults to 5. */
+  threshold?: number;
+}
+
+export interface UseHelperLinesResult<NodeType extends Node = Node> {
+  /**
+   * Drop-in replacement for the consumer's `onNodesChange`: it snaps a dragged
+   * node onto any near-aligned edge/center, then forwards the (mutated) changes
+   * to the wrapped handler.
+   */
+  onNodesChange: (changes: NodeChange<NodeType>[]) => void;
+  /** Absolute flow-y of the active horizontal guide, or `undefined`. */
+  helperLineHorizontal: number | undefined;
+  /** Absolute flow-x of the active vertical guide, or `undefined`. */
+  helperLineVertical: number | undefined;
+}
+
+function nodeRect(node: Node): HelperLineRect {
+  return {
+    x: node.position.x,
+    y: node.position.y,
+    width: node.measured?.width ?? node.width ?? 0,
+    height: node.measured?.height ?? node.height ?? 0,
+  };
+}
+
+/**
+ * Decorate a consumer's `onNodesChange` with alignment guides + snapping.
+ *
+ * While a **single** node is dragged, the returned handler compares its
+ * left/center/right and top/middle/bottom against every other node; when a pair
+ * is within `threshold` flow px it (a) snaps the dragged node's position change
+ * onto the guide and (b) exposes the guide coordinates so `<HelperLines>` can
+ * draw them. Guides clear when the drag ends or nothing aligns.
+ *
+ * Must be called inside a React Flow context (a `<ReactFlowProvider>` or a
+ * component rendered under `<ReactFlow>`), since it reads the live node store.
+ *
+ * @example
+ *   const [nodes, , onNodesChange] = useNodesState(initialNodes);
+ *   const { onNodesChange: handle, helperLineHorizontal, helperLineVertical } =
+ *     useHelperLines(onNodesChange);
+ *   // <ReactFlow onNodesChange={handle}>
+ *   //   <HelperLines horizontal={helperLineHorizontal} vertical={helperLineVertical} />
+ */
+export function useHelperLines<NodeType extends Node = Node>(
+  onNodesChange?: (changes: NodeChange<NodeType>[]) => void,
+  options: UseHelperLinesOptions = {},
+): UseHelperLinesResult<NodeType> {
+  const { threshold = 5 } = options;
+  const { getNodes } = useReactFlow<NodeType>();
+  const [helperLineHorizontal, setHelperLineHorizontal] = useState<number>();
+  const [helperLineVertical, setHelperLineVertical] = useState<number>();
+
+  const handleNodesChange = useCallback(
+    (changes: NodeChange<NodeType>[]) => {
+      let horizontal: number | undefined;
+      let vertical: number | undefined;
+
+      const dragChanges = changes.filter(
+        (c): c is Extract<NodeChange<NodeType>, { type: "position" }> =>
+          c.type === "position" && c.dragging === true && c.position != null,
+      );
+
+      // Only guide/snap a single dragged node — multi-select drags are ambiguous.
+      if (dragChanges.length === 1) {
+        const change = dragChanges[0];
+        const nodes = getNodes();
+        const dragged = change ? nodes.find((n) => n.id === change.id) : undefined;
+
+        if (change && change.position && dragged) {
+          const draggedRect: HelperLineRect = {
+            x: change.position.x,
+            y: change.position.y,
+            width: dragged.measured?.width ?? dragged.width ?? 0,
+            height: dragged.measured?.height ?? dragged.height ?? 0,
+          };
+          const others = nodes.filter((n) => n.id !== change.id).map(nodeRect);
+          const {
+            snapX,
+            snapY,
+            vertical: v,
+            horizontal: h,
+          } = getHelperLines(draggedRect, others, threshold);
+
+          // Mutate the position change so the node lands exactly on the guide.
+          if (snapX !== undefined) change.position.x = snapX;
+          if (snapY !== undefined) change.position.y = snapY;
+          vertical = v;
+          horizontal = h;
+        }
+      }
+
+      setHelperLineHorizontal(horizontal);
+      setHelperLineVertical(vertical);
+      onNodesChange?.(changes);
+    },
+    [getNodes, onNodesChange, threshold],
+  );
+
+  return { onNodesChange: handleNodesChange, helperLineHorizontal, helperLineVertical };
+}

package/src/index.ts

@@ -0,0 +1,37 @@
+/**
+ * @elabs-ai/components-flow — branded React Flow (@xyflow/react) building blocks.
+ *
+ * Import the React Flow stylesheet once at the app root:
+ *   import "@xyflow/react/dist/style.css";
+ */
+export * from "./canvas-shell";
+export * from "./flow-node";
+export * from "./flow-edge";
+export * from "./flow-smart-edge";
+export * from "./flow-floating-edge";
+export * from "./flow-placeholder-node";
+export * from "./flow-button-edge";
+export * from "./flow-layout";
+export * from "./helper-lines";
+export * from "./flow-mini-map";
+export * from "./inspector-panel";
+export * from "./legend";
+export * from "./zoom-controls";
+export * from "./flow-group-node";
+export * from "./use-flow-groups";
+
+// Convenience re-exports so consumers can build flows without a direct dep.
+export {
+  Background,
+  Controls,
+  MiniMap,
+  Panel,
+  Position,
+  ReactFlow,
+  ReactFlowProvider,
+  useReactFlow,
+  useNodesState,
+  useEdgesState,
+  addEdge,
+} from "@xyflow/react";
+export type { Node, Edge, Connection, NodeProps, EdgeProps } from "@xyflow/react";

package/src/inspector-panel/index.ts

@@ -0,0 +1 @@
+export { InspectorPanel, type InspectorPanelProps } from "./inspector-panel";

package/src/inspector-panel/inspector-panel.stories.tsx

@@ -0,0 +1,161 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { useState } from "react";
+import { fn } from "storybook/test";
+import { InspectorPanel } from "./inspector-panel";
+
+const meta = {
+  title: "Flow/InspectorPanel",
+  component: InspectorPanel,
+  tags: ["autodocs"],
+  parameters: { layout: "centered" },
+  args: {
+    onClose: fn(),
+  },
+} satisfies Meta<typeof InspectorPanel>;
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+/** Default: a node is selected; inspector shows its properties. */
+export const Default: Story = {
+  args: {
+    title: "Inspector",
+    hasSelection: true,
+    selectionKey: "node-1",
+    children: (
+      <dl className="space-y-3">
+        <div>
+          <dt className="text-meta font-medium text-muted-foreground">Kind</dt>
+          <dd className="mt-0.5 text-body text-foreground">Source</dd>
+        </div>
+        <div>
+          <dt className="text-meta font-medium text-muted-foreground">Title</dt>
+          <dd className="mt-0.5 text-body text-foreground">Postgres</dd>
+        </div>
+        <div>
+          <dt className="text-meta font-medium text-muted-foreground">Subtitle</dt>
+          <dd className="mt-0.5 text-body text-foreground">orders table</dd>
+        </div>
+        <div>
+          <dt className="text-meta font-medium text-muted-foreground">Tone</dt>
+          <dd className="mt-0.5 text-body text-foreground">accent</dd>
+        </div>
+      </dl>
+    ),
+  },
+  decorators: [
+    (Story) => (
+      <div className="h-[400px] w-72">
+        <Story />
+      </div>
+    ),
+  ],
+};
+
+/** Empty state when nothing is selected. */
+export const NoSelection: Story = {
+  args: {
+    title: "Inspector",
+    hasSelection: false,
+    children: null,
+  },
+  decorators: [
+    (Story) => (
+      <div className="h-[400px] w-72">
+        <Story />
+      </div>
+    ),
+  ],
+};
+
+/** Custom empty message. */
+export const CustomEmptyMessage: Story = {
+  args: {
+    title: "Node details",
+    hasSelection: false,
+    emptyMessage: "Click a node or edge to inspect its properties.",
+    children: null,
+  },
+  decorators: [
+    (Story) => (
+      <div className="h-[400px] w-72">
+        <Story />
+      </div>
+    ),
+  ],
+};
+
+function CollapsibleDemo() {
+  const [open, setOpen] = useState(true);
+  return (
+    <div className="flex h-[400px] w-[480px] overflow-hidden rounded-lg border">
+      <div className="flex min-w-0 flex-1 flex-col items-start gap-2 p-4">
+        <button
+          type="button"
+          aria-expanded={open}
+          onClick={() => setOpen((o) => !o)}
+          className="rounded-md border border-input px-3 py-1.5 text-body hover:bg-accent focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
+        >
+          Toggle inspector
+        </button>
+        <p className="text-body text-muted-foreground">
+          The panel is always mounted — the width tweens via the shared useCollapsiblePanel base (no
+          conditional mount).
+        </p>
+      </div>
+      <InspectorPanel
+        title="Inspector"
+        hasSelection
+        selectionKey="node-1"
+        open={open}
+        onOpenChange={setOpen}
+        onClose={() => setOpen(false)}
+      >
+        <dl className="space-y-3">
+          <div>
+            <dt className="text-meta text-muted-foreground">Kind</dt>
+            <dd className="mt-0.5 text-body text-foreground">Source</dd>
+          </div>
+          <div>
+            <dt className="text-meta text-muted-foreground">Title</dt>
+            <dd className="mt-0.5 text-body text-foreground">Postgres</dd>
+          </div>
+        </dl>
+      </InspectorPanel>
+    </div>
+  );
+}
+
+/** Collapse (research 09 step 3): controlled open on the shared @elabs-ai/components-ui base. */
+export const Collapsible: Story = {
+  args: { children: null },
+  render: () => <CollapsibleDemo />,
+};
+
+/** Without a close button (no onClose). */
+export const NoClose: Story = {
+  args: {
+    title: "Properties",
+    hasSelection: true,
+    onClose: undefined,
+    selectionKey: "node-2",
+    children: (
+      <dl className="space-y-3">
+        <div>
+          <dt className="text-meta font-medium text-muted-foreground">Kind</dt>
+          <dd className="mt-0.5 text-body text-foreground">Transform</dd>
+        </div>
+        <div>
+          <dt className="text-meta font-medium text-muted-foreground">Title</dt>
+          <dd className="mt-0.5 text-body text-foreground">Clean &amp; join</dd>
+        </div>
+      </dl>
+    ),
+  },
+  decorators: [
+    (Story) => (
+      <div className="h-[400px] w-72">
+        <Story />
+      </div>
+    ),
+  ],
+};

package/src/inspector-panel/inspector-panel.test.tsx

@@ -0,0 +1,82 @@
+import { cleanup, render, screen } from "@testing-library/react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { InspectorPanel } from "./inspector-panel";
+
+afterEach(cleanup);
+
+describe("InspectorPanel", () => {
+  it("renders the default title", () => {
+    render(<InspectorPanel>Details here</InspectorPanel>);
+    expect(screen.getByRole("heading", { name: "Inspector" })).toBeInTheDocument();
+  });
+
+  it("renders a custom title", () => {
+    render(<InspectorPanel title="Node Properties">Details</InspectorPanel>);
+    expect(screen.getByRole("heading", { name: "Node Properties" })).toBeInTheDocument();
+  });
+
+  it("renders children when hasSelection is true (default)", () => {
+    render(<InspectorPanel>Panel content</InspectorPanel>);
+    expect(screen.getByText("Panel content")).toBeInTheDocument();
+  });
+
+  it("renders the empty message when hasSelection is false", () => {
+    render(<InspectorPanel hasSelection={false}>Panel content</InspectorPanel>);
+    expect(screen.getByText("Select a node to see its details.")).toBeInTheDocument();
+    expect(screen.queryByText("Panel content")).not.toBeInTheDocument();
+  });
+
+  it("renders a custom empty message", () => {
+    render(
+      <InspectorPanel hasSelection={false} emptyMessage="No edge selected.">
+        Panel content
+      </InspectorPanel>,
+    );
+    expect(screen.getByText("No edge selected.")).toBeInTheDocument();
+  });
+
+  it("renders the close button when onClose is provided", () => {
+    const onClose = vi.fn();
+    render(<InspectorPanel onClose={onClose}>Details</InspectorPanel>);
+    expect(screen.getByRole("button", { name: "Close inspector" })).toBeInTheDocument();
+  });
+
+  it("omits the close button when onClose is not provided", () => {
+    render(<InspectorPanel>Details</InspectorPanel>);
+    expect(screen.queryByRole("button", { name: "Close inspector" })).not.toBeInTheDocument();
+  });
+
+  it("calls onClose when the close button is clicked", async () => {
+    const onClose = vi.fn();
+    const { getByRole } = render(<InspectorPanel onClose={onClose}>Details</InspectorPanel>);
+    getByRole("button", { name: "Close inspector" }).click();
+    expect(onClose).toHaveBeenCalledTimes(1);
+  });
+
+  it("applies custom className to the root element", () => {
+    const { container } = render(<InspectorPanel className="my-panel">Details</InspectorPanel>);
+    expect(container.firstChild).toHaveClass("my-panel");
+  });
+
+  it("converges on the shared collapse base: expanded by default, always mounted", () => {
+    const { container } = render(<InspectorPanel>Details</InspectorPanel>);
+    const root = container.firstChild as HTMLElement;
+    expect(root).toHaveAttribute("data-state", "expanded");
+    expect(root).toHaveAttribute("data-side", "right");
+    expect(root).not.toHaveAttribute("inert");
+  });
+
+  it("collapses via controlled open without unmounting (research 09 step 3)", () => {
+    const { container, rerender } = render(<InspectorPanel open>Details</InspectorPanel>);
+    const root = container.firstChild as HTMLElement;
+    expect(root).toHaveAttribute("data-state", "expanded");
+
+    rerender(<InspectorPanel open={false}>Details</InspectorPanel>);
+    expect(container.firstChild).toBe(root);
+    expect(root).toHaveAttribute("data-state", "collapsed");
+    // Collapsed panel is inert so its controls leave the tab order.
+    expect(root).toHaveAttribute("inert");
+    // Content stays mounted (the width tween needs a mounted node).
+    expect(screen.getByText("Details")).toBeInTheDocument();
+  });
+});

package/src/inspector-panel/inspector-panel.tsx

@@ -0,0 +1,129 @@
+import { type CSSProperties, type ReactNode } from "react";
+import { Reveal, useCollapsiblePanel } from "@elabs-ai/components-ui";
+import { cn } from "@elabs-ai/components-ui/lib/cn";
+
+const INSPECTOR_PANEL_WIDTH = "18rem";
+
+export interface InspectorPanelProps {
+  title?: ReactNode;
+  children: ReactNode;
+  onClose?: () => void;
+  /** Empty-state shown when nothing is selected. */
+  emptyMessage?: ReactNode;
+  /** When false, render the empty state instead of children. */
+  hasSelection?: boolean;
+  /**
+   * Stable identity of the current selection (e.g. the selected node's id).
+   * When it changes, the body replays a quick fade so it reads as "details for
+   * THIS node". Pass the selected entity's id (or any stable key derived from
+   * the selected data).
+   */
+  selectionKey?: string | number;
+  /**
+   * Collapse (research 09 step 3 — converged on the shared `@elabs-ai/components-ui`
+   * `useCollapsiblePanel` base; the panel stays single-view, drill-in is
+   * ContextPanel-only). Controlled `open` / uncontrolled `defaultOpen`.
+   */
+  open?: boolean;
+  defaultOpen?: boolean;
+  onOpenChange?: (open: boolean) => void;
+  /** Which edge the panel sits on (collapse slide direction). Default `"right"`. */
+  side?: "left" | "right";
+  /** Expanded width (any CSS length). Default `"18rem"` (the original `w-72`). */
+  width?: string;
+  className?: string;
+}
+
+/**
+ * Properties panel for the selected node/edge. Reusable beside a canvas (e.g.
+ * inside a <SplitPanel>) or as a React Flow <Panel>. Always mounted; collapses
+ * via the canonical `useCollapsiblePanel` width tween (CSS-gated, reduced-
+ * motion safe) when `open`/`defaultOpen` drive it.
+ */
+export function InspectorPanel({
+  title = "Inspector",
+  children,
+  onClose,
+  emptyMessage = "Select a node to see its details.",
+  hasSelection = true,
+  selectionKey,
+  open,
+  defaultOpen = true,
+  onOpenChange,
+  side = "right",
+  width = INSPECTOR_PANEL_WIDTH,
+  className,
+}: InspectorPanelProps) {
+  const panel = useCollapsiblePanel({
+    side,
+    open,
+    defaultOpen,
+    onOpenChange,
+    widthClassName: "w-(--inspector-panel-width)",
+    spacerCollapsedClassName: "group-data-[state=collapsed]:w-0",
+    containerSlideClassNames: {
+      left: "left-0 group-data-[state=collapsed]:left-[calc(var(--inspector-panel-width)*-1)]",
+      right: "right-0 group-data-[state=collapsed]:right-[calc(var(--inspector-panel-width)*-1)]",
+    },
+  });
+
+  return (
+    <div
+      className={cn("group relative h-full overflow-hidden", className)}
+      style={{ "--inspector-panel-width": width } as CSSProperties}
+      inert={panel.open ? undefined : true}
+      {...panel.attrs}
+    >
+      <div data-slot="inspector-panel-gap" className={panel.spacerClassName} />
+      <div
+        data-slot="inspector-panel-container"
+        // Bounded to the host (a SplitPanel / canvas edge), not the viewport:
+        // absolute within the relative group, full height (research 09 §B.2).
+        className={cn(panel.containerClassName, "absolute inset-y-0 flex h-full border-s")}
+      >
+        {/* Detail-tier surface: raised `card` — robust across themes (#193). */}
+        <div className="flex h-full w-full flex-col bg-card">
+          <div className="flex items-center justify-between border-b px-4 py-3">
+            <h3 className="text-body font-semibold text-foreground">{title}</h3>
+            {onClose ? (
+              <button
+                type="button"
+                aria-label="Close inspector"
+                onClick={onClose}
+                className="rounded-sm p-1 text-muted-foreground hover:text-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
+              >
+                <svg
+                  width="14"
+                  height="14"
+                  viewBox="0 0 24 24"
+                  fill="none"
+                  stroke="currentColor"
+                  strokeWidth="2"
+                  strokeLinecap="round"
+                  strokeLinejoin="round"
+                  aria-hidden="true"
+                >
+                  <path d="M18 6 6 18M6 6l12 12" />
+                </svg>
+              </button>
+            ) : null}
+          </div>
+          {hasSelection ? (
+            <Reveal
+              key={selectionKey}
+              appear="fade"
+              speed="fast"
+              className="flex-1 overflow-y-auto p-4 text-body"
+            >
+              {children}
+            </Reveal>
+          ) : (
+            <div className="flex-1 overflow-y-auto p-4 text-body">
+              <p className="text-muted-foreground">{emptyMessage}</p>
+            </div>
+          )}
+        </div>
+      </div>
+    </div>
+  );
+}

package/src/legend/index.ts

@@ -0,0 +1 @@
+export { Legend, type LegendProps, type LegendItem } from "./legend";

package/src/legend/legend.stories.tsx

@@ -0,0 +1,56 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { Legend } from "./legend";
+
+const meta = {
+  title: "Flow/Legend",
+  component: Legend,
+  tags: ["autodocs"],
+  parameters: { layout: "centered" },
+} satisfies Meta<typeof Legend>;
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+/** Default legend with a title and token-based color references. */
+export const Default: Story = {
+  args: {
+    title: "Node types",
+    items: [
+      { label: "Source", color: "var(--primary)" },
+      { label: "Transform", color: "var(--muted-foreground)" },
+      { label: "Output", color: "var(--success)" },
+    ],
+  },
+};
+
+/** Legend without a title — items only. */
+export const NoTitle: Story = {
+  args: {
+    items: [
+      { label: "Source", color: "var(--primary)" },
+      { label: "Transform", color: "var(--muted-foreground)" },
+      { label: "Output", color: "var(--success)" },
+    ],
+  },
+};
+
+/** Richer set of items representing a full pipeline. */
+export const FullPipeline: Story = {
+  args: {
+    title: "Pipeline stages",
+    items: [
+      { label: "Source", color: "var(--primary)" },
+      { label: "Transform", color: "var(--muted-foreground)" },
+      { label: "Validate", color: "var(--warning)" },
+      { label: "Output", color: "var(--success)" },
+      { label: "Error", color: "var(--destructive)" },
+    ],
+  },
+};
+
+/** Single item. */
+export const SingleItem: Story = {
+  args: {
+    title: "Key",
+    items: [{ label: "Active node", color: "var(--primary)" }],
+  },
+};

package/src/legend/legend.test.tsx

@@ -0,0 +1,46 @@
+import { cleanup, render, screen } from "@testing-library/react";
+import { afterEach, describe, expect, it } from "vitest";
+import { Legend } from "./legend";
+
+afterEach(cleanup);
+
+describe("Legend", () => {
+  const items = [
+    { label: "Source", color: "var(--chart-1)" },
+    { label: "Target", color: "var(--chart-2)" },
+  ];
+
+  it("renders all item labels", () => {
+    render(<Legend items={items} />);
+    expect(screen.getByText("Source")).toBeInTheDocument();
+    expect(screen.getByText("Target")).toBeInTheDocument();
+  });
+
+  it("renders the title when provided", () => {
+    render(<Legend items={items} title="Legend Title" />);
+    expect(screen.getByText("Legend Title")).toBeInTheDocument();
+  });
+
+  it("omits the title when not provided", () => {
+    const { container } = render(<Legend items={items} />);
+    // No title text in the container beyond the items
+    expect(container.querySelector(".font-medium")).toBeNull();
+  });
+
+  it("renders a color swatch for each item", () => {
+    const { container } = render(<Legend items={items} />);
+    const swatches = container.querySelectorAll("span[aria-hidden='true']");
+    expect(swatches).toHaveLength(2);
+  });
+
+  it("applies custom className", () => {
+    const { container } = render(<Legend items={items} className="custom-class" />);
+    expect(container.firstChild).toHaveClass("custom-class");
+  });
+
+  it("renders an empty list when items is empty", () => {
+    render(<Legend items={[]} />);
+    const list = screen.queryByRole("list");
+    expect(list).toBeInTheDocument();
+  });
+});

package/src/legend/legend.tsx

@@ -0,0 +1,39 @@
+import { cn } from "@elabs-ai/components-ui/lib/cn";
+
+export interface LegendItem {
+  label: string;
+  /** Any CSS color or token reference, e.g. "var(--chart-1)". */
+  color: string;
+}
+
+export interface LegendProps {
+  items: LegendItem[];
+  title?: string;
+  className?: string;
+}
+
+/** Small legend mapping colors/types to labels for a canvas or chart. */
+export function Legend({ items, title, className }: LegendProps) {
+  return (
+    <div
+      className={cn(
+        "rounded-lg bg-surface-elevated/90 p-3 text-xs shadow-ring-sm backdrop-blur",
+        className,
+      )}
+    >
+      {title ? <div className="mb-1.5 font-medium text-foreground">{title}</div> : null}
+      <ul className="space-y-1">
+        {items.map((item) => (
+          <li key={item.label} className="flex items-center gap-2 text-muted-foreground">
+            <span
+              aria-hidden="true"
+              className="size-2.5 shrink-0 rounded-full"
+              style={{ backgroundColor: item.color }}
+            />
+            {item.label}
+          </li>
+        ))}
+      </ul>
+    </div>
+  );
+}