@exellix/diagrams-toolkit 0.2.0

package/README.md

@@ -0,0 +1,95 @@
+# @exellix/diagrams-toolkit
+
+Reusable React UI primitives for graph and diagram authoring: library tables, tabs, inspector shell, JSON panels, and an interactive **GraphCanvas** (pan/zoom, drag, SVG edges).
+
+## Install
+
+```bash
+npm install @exellix/diagrams-toolkit react react-dom lucide-react
+```
+
+Peer dependencies: `react`, `react-dom` (^18 or ^19).
+
+## Tailwind CSS (required)
+
+Components use Tailwind utility classes. Configure your app to scan the package source.
+
+**Tailwind v4** (`src/index.css`):
+
+```css
+@import "tailwindcss";
+@source "../node_modules/@exellix/diagrams-toolkit/src";
+```
+
+**Tailwind v3** (`tailwind.config.js`):
+
+```js
+content: ['src/**/*.{js,jsx}', 'node_modules/@exellix/diagrams-toolkit/src/**/*.{js,jsx}'],
+```
+
+Optional base font helper:
+
+```js
+import '@exellix/diagrams-toolkit/styles.css';
+```
+
+## GraphCanvas example
+
+```jsx
+import { useState } from 'react';
+import { GraphCanvas } from '@exellix/diagrams-toolkit';
+
+export function Demo() {
+  const [nodes, setNodes] = useState([
+    { id: 'a', label: 'Task A', x: 80, y: 80 },
+    { id: 'b', label: 'Task B', x: 400, y: 160 },
+  ]);
+  const [selectedItem, setSelectedItem] = useState(null);
+
+  return (
+    <div className="h-[480px] flex flex-col">
+      <GraphCanvas
+        nodes={nodes}
+        edges={[{ from: 'a', to: 'b' }]}
+        onNodesChange={setNodes}
+        selectedItem={selectedItem}
+        onSelectItem={setSelectedItem}
+        renderNode={(node, { selected, onPointerDown }) => (
+          <button
+            type="button"
+            onPointerDown={onPointerDown}
+            className={`absolute p-3 rounded-lg border ${selected ? 'border-indigo-500' : 'border-slate-200'}`}
+            style={{ left: node.x, top: node.y }}
+          >
+            {node.label}
+          </button>
+        )}
+      />
+    </div>
+  );
+}
+```
+
+## Exports
+
+| Export | Purpose |
+|--------|---------|
+| `GraphCanvas` | Full topology canvas (pan, zoom, drag, edges) |
+| `GraphCanvasZoomControl` | Zoom slider + fit view |
+| `DefaultGraphEdge` | Simple SVG edge renderer |
+| `layoutGraphNodesFromTopology` | Auto-layout + in/out edge counts |
+| `computeEdgeBezierPath` | Edge geometry helper |
+| `FlowCanvas` | Legacy simple flow view (deprecated; use `GraphCanvas`) |
+| `ViewTabStrip`, `ResourceDataTable`, `InspectorShell`, … | Shell UI primitives |
+
+## Monorepo demo
+
+From the workspace root:
+
+```bash
+npm run demo:toolkit
+```
+
+## Publish
+
+This package ships raw ESM from `src/` (same pattern as other `@exellix/*` libs in the monorepo).

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@exellix/diagrams-toolkit",
+  "version": "0.2.0",
+  "description": "Reusable React UI primitives for graph and diagram authoring (tabs, tables, flow canvas, JSON panels).",
+  "type": "module",
+  "engines": {
+    "node": ">=20.19.0 || >=22.12.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+ssh://git@github.com/exellix/graphs-studio.git",
+    "directory": "packages/diagrams-toolkit"
+  },
+  "main": "./src/index.js",
+  "exports": {
+    ".": "./src/index.js",
+    "./styles.css": "./src/styles.css"
+  },
+  "files": [
+    "src"
+  ],
+  "peerDependencies": {
+    "react": "^18.0.0 || ^19.0.0",
+    "react-dom": "^18.0.0 || ^19.0.0"
+  },
+  "dependencies": {
+    "lucide-react": "^1.21.0"
+  },
+  "devDependencies": {
+    "react": "^19.2.7",
+    "react-dom": "^19.2.7"
+  },
+  "scripts": {
+    "demo": "npm run dev -w diagrams-toolkit-demo",
+    "prepublishOnly": "node --test tests/diagrams-toolkit.test.mjs"
+  }
+}

package/src/ConceptSummaryStrip.jsx

@@ -0,0 +1,75 @@
+import React from 'react';
+import { ChevronDown, ChevronRight } from 'lucide-react';
+import { StatusBadge } from './StatusBadge.jsx';
+
+/**
+ * @param {{
+ *   title?: string,
+ *   typeLabel?: string,
+ *   intentLabel?: string,
+ *   objective?: string,
+ *   status?: string,
+ *   collapsed?: boolean,
+ *   onToggleCollapsed?: () => void,
+ *   onOpenConcept?: () => void,
+ *   className?: string,
+ * }} props
+ */
+export function ConceptSummaryStrip({
+  title,
+  typeLabel,
+  intentLabel,
+  objective,
+  status = 'draft',
+  collapsed = false,
+  onToggleCollapsed,
+  onOpenConcept,
+  className = '',
+}) {
+  const chipText = typeLabel
+    ? `${typeLabel}${intentLabel ? ` · ${intentLabel}` : ''}`
+    : objective?.slice(0, 60) || title || 'Concept';
+
+  return (
+    <div
+      className={`shrink-0 border-b border-slate-200 bg-white px-3 py-2 flex items-center gap-2 ${className}`}
+    >
+      {onToggleCollapsed ? (
+        <button
+          type="button"
+          onClick={onToggleCollapsed}
+          className="p-1 rounded hover:bg-slate-100 text-slate-500"
+          aria-expanded={!collapsed}
+        >
+          {collapsed ? <ChevronRight size={16} /> : <ChevronDown size={16} />}
+        </button>
+      ) : null}
+      <StatusBadge status={status} />
+      {collapsed ? (
+        <button
+          type="button"
+          onClick={onOpenConcept}
+          className="text-sm text-slate-700 truncate hover:text-indigo-700"
+        >
+          {chipText}
+        </button>
+      ) : (
+        <div className="flex-1 min-w-0 text-sm text-slate-700">
+          {title ? <span className="font-medium">{title}</span> : null}
+          {objective ? (
+            <p className="text-xs text-slate-500 truncate mt-0.5">{objective}</p>
+          ) : null}
+        </div>
+      )}
+      {onOpenConcept ? (
+        <button
+          type="button"
+          onClick={onOpenConcept}
+          className="text-xs font-medium text-indigo-600 hover:text-indigo-800 shrink-0"
+        >
+          Open concept
+        </button>
+      ) : null}
+    </div>
+  );
+}

package/src/DefaultGraphEdge.jsx

@@ -0,0 +1,57 @@
+import React from 'react';
+import { computeEdgeBezierPath } from './lib/computeEdgeBezierPath.js';
+
+/**
+ * Simple topology edge with optional label.
+ *
+ * @param {{
+ *   edge: { from: string, to: string, label?: string },
+ *   sourceNode: { x: number, y: number },
+ *   targetNode: { x: number, y: number },
+ *   selected?: boolean,
+ *   filteredOut?: boolean,
+ *   onClick?: (edge: object) => void,
+ *   nodeWidth?: number,
+ *   anchorY?: number,
+ * }} props
+ */
+export function DefaultGraphEdge({
+  edge,
+  sourceNode,
+  targetNode,
+  selected = false,
+  filteredOut = false,
+  onClick,
+  nodeWidth,
+  anchorY,
+}) {
+  if (!sourceNode || !targetNode) return null;
+
+  const { path, midX, midY } = computeEdgeBezierPath(sourceNode, targetNode, { nodeWidth, anchorY });
+  const stroke = selected ? '#4f46e5' : '#cbd5e1';
+  const marker = selected ? 'selected' : 'normal';
+
+  return (
+    <g
+      className={`cursor-pointer pointer-events-auto edge-element ${filteredOut ? 'opacity-20' : ''}`}
+      onClick={(e) => {
+        e.stopPropagation();
+        onClick?.(edge);
+      }}
+    >
+      <path d={path} fill="none" stroke="transparent" strokeWidth="20" />
+      <path
+        d={path}
+        fill="none"
+        stroke={stroke}
+        strokeWidth={selected ? '3' : '2'}
+        markerEnd={`url(#arrowhead-${marker})`}
+      />
+      {edge.label ? (
+        <text x={midX} y={midY - 6} fontSize={10} fill="#64748b" textAnchor="middle">
+          {edge.label}
+        </text>
+      ) : null}
+    </g>
+  );
+}

package/src/EmptyState.jsx

@@ -0,0 +1,16 @@
+import React from 'react';
+
+/**
+ * @param {{ title: string, detail?: string, action?: React.ReactNode, className?: string }} props
+ */
+export function EmptyState({ title, detail, action, className = '' }) {
+  return (
+    <div
+      className={`flex flex-col items-center justify-center text-center px-4 py-12 ${className}`}
+    >
+      <p className="text-sm font-medium text-slate-700">{title}</p>
+      {detail ? <p className="text-sm text-slate-500 mt-2 max-w-md">{detail}</p> : null}
+      {action ? <div className="mt-4">{action}</div> : null}
+    </div>
+  );
+}

package/src/ErrorState.jsx

@@ -0,0 +1,20 @@
+import React from 'react';
+import { AlertCircle } from 'lucide-react';
+
+/**
+ * @param {{ title: string, detail?: string, action?: React.ReactNode, className?: string }} props
+ */
+export function ErrorState({ title, detail, action, className = '' }) {
+  return (
+    <div
+      className={`flex flex-col items-center justify-center text-center px-4 py-12 bg-slate-100 ${className}`}
+    >
+      <AlertCircle className="w-8 h-8 text-red-500 mb-3" aria-hidden />
+      <p className="text-sm font-medium text-slate-700">{title}</p>
+      {detail ? (
+        <p className="text-xs font-mono text-red-700 mt-2 break-all max-w-lg">{detail}</p>
+      ) : null}
+      {action ? <div className="mt-4">{action}</div> : null}
+    </div>
+  );
+}

package/src/FlowCanvas.jsx

@@ -0,0 +1,103 @@
+import React, { useMemo } from 'react';
+
+/**
+ * @typedef {{ id: string, label: string, role?: string, x?: number, y?: number, meta?: Record<string, unknown> }} FlowNode
+ * @typedef {{ id: string, from: string, to: string, label?: string }} FlowEdge
+ */
+
+/**
+ * @deprecated Use {@link GraphCanvas} for interactive pan/zoom/drag canvas.
+ * @param {{
+ *   nodes: FlowNode[],
+ *   edges: FlowEdge[],
+ *   selectedId?: string | null,
+ *   onSelect?: (id: string | null) => void,
+ *   renderNode?: (node: FlowNode, selected: boolean) => React.ReactNode,
+ *   className?: string,
+ * }} props
+ */
+export function FlowCanvas({
+  nodes = [],
+  edges = [],
+  selectedId = null,
+  onSelect,
+  renderNode,
+  className = '',
+}) {
+  const layout = useMemo(() => {
+    const positioned = nodes.map((n, i) => ({
+      ...n,
+      x: typeof n.x === 'number' ? n.x : 40 + (i % 3) * 220,
+      y: typeof n.y === 'number' ? n.y : 40 + Math.floor(i / 3) * 120,
+    }));
+    const byId = new Map(positioned.map((n) => [n.id, n]));
+    return { positioned, byId };
+  }, [nodes]);
+
+  return (
+    <div className={`relative flex-1 min-h-0 overflow-auto bg-slate-100 ${className}`}>
+      <svg className="absolute inset-0 w-full h-full pointer-events-none min-h-[400px]">
+        {edges.map((e) => {
+          const from = layout.byId.get(e.from);
+          const to = layout.byId.get(e.to);
+          if (!from || !to) return null;
+          const x1 = from.x + 90;
+          const y1 = from.y + 28;
+          const x2 = to.x + 10;
+          const y2 = to.y + 28;
+          return (
+            <g key={e.id}>
+              <line x1={x1} y1={y1} x2={x2} y2={y2} stroke="#94a3b8" strokeWidth={2} markerEnd="url(#arrow)" />
+              {e.label ? (
+                <text x={(x1 + x2) / 2} y={(y1 + y2) / 2 - 6} fontSize={10} fill="#64748b" textAnchor="middle">
+                  {e.label}
+                </text>
+              ) : null}
+            </g>
+          );
+        })}
+        <defs>
+          <marker id="arrow" markerWidth="8" markerHeight="8" refX="6" refY="3" orient="auto">
+            <path d="M0,0 L6,3 L0,6 Z" fill="#94a3b8" />
+          </marker>
+        </defs>
+      </svg>
+      <div className="relative min-h-[400px] p-4">
+        {layout.positioned.map((node) => {
+          const selected = node.id === selectedId;
+          if (renderNode) {
+            return (
+              <div
+                key={node.id}
+                className="absolute"
+                style={{ left: node.x, top: node.y }}
+                onClick={() => onSelect?.(node.id)}
+              >
+                {renderNode(node, selected)}
+              </div>
+            );
+          }
+          return (
+            <button
+              key={node.id}
+              type="button"
+              onClick={() => onSelect?.(node.id)}
+              className={`absolute w-[180px] text-left p-3 rounded-lg border shadow-sm transition-colors ${
+                selected
+                  ? 'border-indigo-500 bg-indigo-50 ring-2 ring-indigo-200'
+                  : 'border-slate-200 bg-white hover:border-slate-300'
+              }`}
+              style={{ left: node.x, top: node.y }}
+            >
+              <div className="text-xs font-mono text-slate-400 truncate">{node.id}</div>
+              <div className="text-sm font-medium text-slate-800 truncate">{node.label}</div>
+              {node.role ? (
+                <div className="text-[10px] uppercase tracking-wide text-slate-500 mt-1">{node.role}</div>
+              ) : null}
+            </button>
+          );
+        })}
+      </div>
+    </div>
+  );
+}