@kiberon-labs/behave-graph-flow 1.0.0 → 3.0.0

package/docs/specifics.md

@@ -0,0 +1,191 @@
+# Creating Custom Specifics for Nodes
+
+Specifics are UI extensions that add custom controls and functionality to specific node types. They allow you to create dynamic interfaces for nodes with configurable sockets, special controls, or custom rendering.
+
+## What are Specifics?
+
+A "specific" is a React component that gets rendered inside a node when certain conditions are met. It's perfect for:
+- Adding/removing dynamic sockets (like the Switch nodes)
+- Custom dropdown controls (like Custom Event selection)
+- Preview panels (like image previews)
+- Any node-specific UI controls
+
+## Creating a Specific
+
+A specific consists of three parts:
+
+1. **Check function** - Determines if this specific applies to a node
+2. **Render component** - The React component to render
+3. **Unique name** - An identifier for the specific
+
+### Example: Dynamic Socket Management
+
+Here's how the SwitchOnString specific works:
+
+```typescript
+import React, { useCallback } from 'react';
+import { VscodeButton } from '@vscode-elements/react-elements';
+import { Plus, Minus } from 'iconoir-react';
+import { useSystem } from '@/system/provider';
+import type { SpecificRenderProps } from '@/store/specific';
+
+const NAME = 'flow/switch/string.dynamicSockets';
+
+export function getSwitchOnStringSpecific() {
+  return {
+    name: NAME,
+    check: (spec: any) => spec?.type === 'flow/switch/string',
+    render: SwitchOnStringSpecific
+  };
+}
+
+const SwitchOnStringSpecific: React.FC<SpecificRenderProps> = ({ node }) => {
+  const system = useSystem();
+  const numCases = node.data?.configuration?.numCases ?? 0;
+
+  const updateNumCases = useCallback(
+    (newNumCases: number) => {
+      if (newNumCases < 0) return;
+
+      // Update the node configuration
+      system.nodeStore.getState().setNodes((prev) =>
+        prev.map((n: any) => {
+          if (n.id !== node.id) return n;
+          return {
+            ...n,
+            data: {
+              ...n.data,
+              configuration: {
+                ...n.data?.configuration,
+                numCases: newNumCases
+              }
+            }
+          };
+        })
+      );
+
+      // Invalidate cache to trigger socket recalculation
+      system.flowStore.getState().invalidateCache();
+    },
+    [node.id, system]
+  );
+
+  const addCase = useCallback(() => {
+    updateNumCases(numCases + 1);
+  }, [numCases, updateNumCases]);
+
+  const removeCase = useCallback(() => {
+    updateNumCases(Math.max(0, numCases - 1));
+  }, [numCases, updateNumCases]);
+
+  return (
+    <div style={{ padding: 8, display: 'flex', flexDirection: 'column', gap: 8 }}>
+      <div style={{ fontSize: 12, opacity: 0.9 }}>Cases: {numCases}</div>
+      <div style={{ display: 'flex', gap: 4 }}>
+        <VscodeButton onClick={addCase}>
+          <Plus width={16} height={16} /> Add Case
+        </VscodeButton>
+        <VscodeButton onClick={removeCase} disabled={numCases === 0}>
+          <Minus width={16} height={16} /> Remove
+        </VscodeButton>
+      </div>
+    </div>
+  );
+};
+```
+
+## Registering Specifics
+
+### Built-in Registration
+
+Default specifics are automatically registered in `registerDefaultSpecifics`. To add yours:
+
+```typescript
+// In registerDefaultSpecifics.ts
+import { getYourCustomSpecific } from './YourCustomSpecific';
+
+export function registerDefaultSpecifics(system: System): () => void {
+  const store = system.specificStore.getState();
+  
+  const yourCustom = getYourCustomSpecific();
+  store.registerSpecific(yourCustom);
+  
+  return () => {
+    system.specificStore.getState().unregisterSpecific(yourCustom.name);
+  };
+}
+```
+
+### External Registration
+
+You can also register specifics from external packages:
+
+```typescript
+import { System } from '@kiberon-labs/behave-graph-flow';
+import { getSwitchOnStringSpecific } from '@kiberon-labs/behave-graph-flow';
+
+export function registerMyPlugin(system: System) {
+  const switchSpecific = getSwitchOnStringSpecific();
+  system.specificStore.getState().registerSpecific(switchSpecific);
+  
+  // Or create your own
+  const mySpecific = {
+    name: 'my-custom-specific',
+    check: (spec) => spec.type === 'my/custom/node',
+    render: MyCustomComponent
+  };
+  
+  system.specificStore.getState().registerSpecific(mySpecific);
+}
+```
+
+## Key Patterns
+
+### Updating Node Configuration
+
+When your specific needs to update node configuration (like changing socket counts):
+
+```typescript
+system.nodeStore.getState().setNodes((prev) =>
+  prev.map((n: any) => {
+    if (n.id !== node.id) return n;
+    return {
+      ...n,
+      data: {
+        ...n.data,
+        configuration: {
+          ...n.data?.configuration,
+          yourConfigKey: newValue
+        }
+      }
+    };
+  })
+);
+
+// Important: Invalidate cache to recalculate sockets
+system.flowStore.getState().invalidateCache();
+```
+
+### Accessing Node Data
+
+The `node` prop contains:
+- `id` - Node ID
+- `data` - Node data (configuration, ports, annotations)
+- `spec` - Node specification
+- `selected` - Whether node is selected
+
+## Available Specifics
+
+Currently registered specifics:
+
+1. **CustomEventOnTriggered** - Dropdown for selecting custom events
+2. **SwitchOnString** - Add/remove string case sockets
+3. **SwitchOnInteger** - Add/remove integer case sockets
+
+## Tips
+
+- Keep specifics focused on a single node type
+- Use unique names to avoid conflicts
+- Always invalidate the flow cache when changing node configuration that affects sockets
+- Use inline styles or CSS modules (not Tailwind per AI instructions)
+- Leverage the `useSystem` hook to access all system stores

package/package.json

@@ -1,42 +1,102 @@
 {
   "name": "@kiberon-labs/behave-graph-flow",
-  "version": "1.0.0",
+  "version": "3.0.0",
   "type": "module",
-  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./entry.css": "./dist/entry.css",
+    "./package.json": "./package.json"
+  },
   "main": "./dist/index.js",
-  "source": "./src/index.ts",
-  "scripts": {
-    "dev": "tsdown --watch src",
-    "build": "tsdown",
-    "test": "vitest",
-    "check": "oxfmt --check",
-    "format": "oxfmt",
-    "lint": "oxlint",
-    "typecheck": "tsc"
+  "types": "./dist/index.d.ts",
+  "publishConfig": {
+    "provenance": true,
+    "access": "public"
   },
   "devDependencies": {
-    "@testing-library/react": "^13.3.0",
-    "@testing-library/user-event": "^13.5.0",
+    "@storybook/addon-a11y": "^10.0.8",
+    "@storybook/addon-docs": "^10.0.8",
+    "@storybook/addon-vitest": "^10.0.8",
+    "@storybook/react-vite": "^10.0.8",
+    "@types/dagre": "^0.7.53",
+    "@types/graphlib": "^2.1.12",
     "@types/react": "^19.2.6",
     "@types/uuid": "^8.3.4",
+    "@vitest/browser": "^4.0.10",
+    "@vitest/browser-playwright": "4.0.10",
     "autoprefixer": "^10.4.22",
+    "fallow": "^2.89.0",
+    "happy-dom": "^20.4.0",
+    "jsdom": "^27.3.0",
+    "oxfmt": "^0.14.0",
     "oxlint": "^1.29.0",
-    "react": "^19.2.0",
-    "tailwindcss": "^4.1.17",
+    "playwright": "^1.60.0",
+    "react": "19.2.3",
+    "react-dom": "19.2.3",
+    "reactflow": "^11.11.4",
+    "storybook": "^10.0.8",
     "tsdown": "^0.16.5",
+    "unplugin-lightningcss": "^0.4.3",
+    "vite": "^7.2.4",
+    "vite-tsconfig-paths": "^5.1.4",
     "vitest": "^4.0.10",
-    "oxfmt": "^0.14.0"
+    "vitest-browser-react": "^2.2.0",
+    "@kiberon-labs/behave-graph": "1.2.0"
   },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Kiberon-Labs/behave-graph",
+    "directory": "packages/flow"
+  },
+  "author": "kiberonlabsdev",
+  "bugs": "https://github.com/Kiberon-Labs/behave-graph/issues",
   "dependencies": {
-    "@fortawesome/fontawesome-svg-core": "^6.1.2",
-    "@fortawesome/free-solid-svg-icons": "^6.1.2",
-    "@fortawesome/react-fontawesome": "^0.2.0",
+    "@radix-ui/react-popover": "^1.1.15",
+    "@reactflow/node-resizer": "^2.2.14",
+    "@tiptap/extension-youtube": "^3.27.1",
+    "@tiptap/react": "^3.19.0",
+    "@tiptap/starter-kit": "^3.19.0",
+    "@vscode-elements/react-elements": "^2.4.0",
     "classnames": "^2.3.1",
-    "downshift": "^6.1.7",
-    "uuid": "^8.3.2"
+    "clsx": "^2.1.1",
+    "copy-to-clipboard": "^3.3.3",
+    "dagre": "^0.8.5",
+    "elkjs": "^0.11.0",
+    "fuse.js": "^7.1.0",
+    "graphlib": "^2.1.8",
+    "iconoir-react": "^7.11.0",
+    "json-edit-react": "^1.29.0",
+    "rc-dock": "4.0.0-alpha.2",
+    "rc-menu": "^9.16.1",
+    "react-colorful": "^5.6.1",
+    "react-error-boundary": "^6.0.0",
+    "react-hot-toast": "^2.6.0",
+    "react-hotkeys": "^2.0.0",
+    "tiptap-markdown": "^0.9.0",
+    "uuid": "^8.3.2",
+    "zustand": "^5.0.8"
   },
   "peerDependencies": {
     "reactflow": "^11.1.1",
-    "@kiberon-labs/behave-graph": "*"
+    "@kiberon-labs/behave-graph": "1.2.0"
+  },
+  "scripts": {
+    "audit": "fallow",
+    "dev": "tsdown --watch src",
+    "build": "tsdown",
+    "release": "npm publish --dry-run",
+    "test": "vitest",
+    "test:visual": "vitest run --config vitest.visual.config.ts",
+    "test:visual:update": "vitest run --config vitest.visual.config.ts --update",
+    "check": "oxfmt --check",
+    "format": "oxfmt",
+    "lint": "oxlint",
+    "storybook": "storybook dev -p 6006",
+    "build-storybook": "storybook build",
+    "typecheck": "tsc --noEmit -p tsconfig.prod.json"
   }
 }

package/postcss.config.ts

@@ -1,6 +1,5 @@
-import autoprefixer from 'autoprefixer';
-import tailwindcss from 'tailwindcss';
-
 export default {
-  plugins: [tailwindcss, autoprefixer]
+  plugins: {
+    autoprefixer: {}
+  }
 };

package/src/annotations/index.ts

@@ -0,0 +1,32 @@
+//Used on ports to indicate meta from a ui
+
+/**
+ * Indicates that the port can be completely deleted
+ */
+export const nonDeletable = 'ui.nonDeletable';
+/**
+ * Indicates that the port can be reset to its default value / type
+ */
+export const resetable = 'ui.resetable';
+/**
+ * Indicates that the port cannot be edited
+ */
+export const readonly = 'ui.readonly';
+/**
+ * Indicates that the port is hidden from the user
+ */
+export const hidden = 'ui.hidden';
+
+//Used on nodes and graph
+export const annotatedTitle = 'ui.title';
+export const description = 'ui.description';
+export const executing = 'ui.executing';
+export const pinned = 'ui.pinned';
+export const layerId = 'ui.layerId';
+
+//Used exclusively on graph
+export const uiVersion = 'ui.version';
+
+export const realtime = 'ui.realtime';
+//UI annotation to detect realtime output nodes, which are used to display outputs in the UI without affecting the actual graph outputs
+export const AnnotatedOutput = 'ui.annotatedOutput';

package/src/components/FloatingToolbar/index.module.css

@@ -0,0 +1,37 @@
+.panel {
+  margin: 0.5rem;
+  pointer-events: auto;
+}
+
+.toolbar {
+  display: flex;
+  gap: 0.5rem;
+  padding: 0.25rem;
+  background: var(--ds-widget-bg, #292929);
+  border: 1px solid var(--ds-border-subtle, #454545);
+  border-radius: 0.375rem;
+  box-shadow: 0 2px 8px rgba(0, 0, 0, 0.36);
+}
+
+.buttonGroup {
+  display: flex;
+  gap: 0.125rem;
+  padding: 0.125rem;
+}
+
+.buttonGroup vscode-button {
+  min-width: 28px;
+  height: 28px;
+}
+
+.zoomLevel {
+  display: flex;
+  align-items: center;
+  padding: 0 0.5rem;
+  font-size: var(--fs-label, 0.8rem);
+  font-weight: 500;
+  color: var(--ds-fg);
+  user-select: none;
+  min-width: 3rem;
+  justify-content: center;
+}

package/src/components/FloatingToolbar/index.tsx

@@ -0,0 +1,256 @@
+import React, { useCallback, useState, useRef } from 'react';
+import { Panel, useViewport } from 'reactflow';
+import {
+  VscodeButton,
+  VscodeContextMenu
+} from '@vscode-elements/react-elements';
+import { ZoomIn, ZoomOut, AlignLeft, LayoutRight } from 'iconoir-react';
+import { useGraph } from '@/system/provider';
+import { useStore } from 'zustand';
+import styles from './index.module.css';
+import { useRefFromStore } from '@/system';
+import type { ToolbarButton } from '@/store/toolbar';
+import type { AlignmentAxis, AlignmentType } from '@/plugin/alignment';
+
+export const FloatingToolbar: React.FC = () => {
+  const session = useGraph();
+  const visible = useStore(session.editor.toolbarStore, (x) => x.visible);
+  const customGroups = useStore(session.editor.toolbarStore, (x) => x.groups);
+  const reactFlowInstance = useRefFromStore(session.refStore, 'reactflow');
+  const { zoom } = useViewport();
+  const currentZoom = Math.round(zoom * 100);
+  const [alignMenuOpen, setAlignMenuOpen] = useState(false);
+  const [distributeMenuOpen, setDistributeMenuOpen] = useState(false);
+  const [menuPosition, setMenuPosition] = useState({ top: 0, left: 0 });
+  const alignBtnRef = useRef<any>(null);
+  const distributeBtnRef = useRef<any>(null);
+
+  const publishAlignment = useCallback(
+    (type: AlignmentType, axis: AlignmentAxis) => {
+      session.pubsub.publishSync('alignment:align', { type, axis });
+    },
+    [session]
+  );
+
+  const publishDistribution = useCallback(
+    (type: AlignmentType, axis: AlignmentAxis) => {
+      session.pubsub.publishSync('alignment:distribute', { type, axis });
+    },
+    [session]
+  );
+
+  const handleZoomIn = useCallback(() => {
+    reactFlowInstance?.zoomIn();
+  }, [reactFlowInstance]);
+
+  const handleZoomOut = useCallback(() => {
+    reactFlowInstance?.zoomOut();
+  }, [reactFlowInstance]);
+
+  const handleAlignSelect = useCallback(
+    (e: any) => {
+      setAlignMenuOpen(false);
+      const value = e.detail?.value;
+      switch (value) {
+        case 'left':
+          publishAlignment('start', 'x');
+          break;
+        case 'center-h':
+          publishAlignment('center', 'x');
+          break;
+        case 'right':
+          publishAlignment('end', 'x');
+          break;
+        case 'top':
+          publishAlignment('start', 'y');
+          break;
+        case 'center-v':
+          publishAlignment('center', 'y');
+          break;
+        case 'bottom':
+          publishAlignment('end', 'y');
+          break;
+      }
+    },
+    [publishAlignment]
+  );
+
+  const handleDistributeSelect = useCallback(
+    (e: any) => {
+      setDistributeMenuOpen(false);
+      const value = e.detail?.value;
+      switch (value) {
+        case 'left':
+          publishDistribution('start', 'x');
+          break;
+        case 'center-h':
+          publishDistribution('center', 'x');
+          break;
+        case 'right':
+          publishDistribution('end', 'x');
+          break;
+        case 'top':
+          publishDistribution('start', 'y');
+          break;
+        case 'center-v':
+          publishDistribution('center', 'y');
+          break;
+        case 'bottom':
+          publishDistribution('end', 'y');
+          break;
+      }
+    },
+    [publishDistribution]
+  );
+
+  if (!visible) return null;
+
+  return (
+    <>
+      <Panel position="top-center" className={styles.panel}>
+        <div className={styles.toolbar}>
+          {/* Zoom Controls */}
+          <div className={styles.buttonGroup}>
+            <VscodeButton
+              secondary
+              iconOnly
+              title="Zoom In"
+              onClick={handleZoomIn}
+            >
+              <ZoomIn />
+            </VscodeButton>
+            <span className={styles.zoomLevel}>{currentZoom}%</span>
+            <VscodeButton
+              secondary
+              iconOnly
+              title="Zoom Out"
+              onClick={handleZoomOut}
+            >
+              <ZoomOut />
+            </VscodeButton>
+          </div>
+
+          {/* Align Button */}
+          <div className={styles.buttonGroup}>
+            <VscodeButton
+              ref={alignBtnRef}
+              secondary
+              iconOnly
+              title="Align"
+              onClick={() => {
+                const rect = alignBtnRef.current?.getBoundingClientRect();
+                if (rect) {
+                  setMenuPosition({ top: rect.bottom, left: rect.left });
+                  setAlignMenuOpen(!alignMenuOpen);
+                }
+              }}
+            >
+              <AlignLeft />
+            </VscodeButton>
+          </div>
+
+          {/* Distribute Button */}
+          <div className={styles.buttonGroup}>
+            <VscodeButton
+              ref={distributeBtnRef}
+              secondary
+              iconOnly
+              title="Distribute"
+              onClick={() => {
+                const rect = distributeBtnRef.current?.getBoundingClientRect();
+                if (rect) {
+                  setMenuPosition({ top: rect.bottom, left: rect.left });
+                  setDistributeMenuOpen(!distributeMenuOpen);
+                }
+              }}
+            >
+              <LayoutRight />
+            </VscodeButton>
+          </div>
+
+          {/* Custom Groups */}
+          {customGroups.map((group) => (
+            <div key={group.id} className={styles.buttonGroup}>
+              {(Array.isArray(group.buttons) ? group.buttons : []).map(
+                (button: ToolbarButton | React.ReactNode, index: number) => {
+                  // Support custom ReactNode buttons
+                  if (React.isValidElement(button)) {
+                    return (
+                      <React.Fragment key={index}>{button}</React.Fragment>
+                    );
+                  }
+
+                  // Standard button definition
+                  const typedButton = button as ToolbarButton;
+                  const isDisabled =
+                    typeof typedButton.disabled === 'function'
+                      ? typedButton.disabled()
+                      : typedButton.disabled;
+
+                  return (
+                    <VscodeButton
+                      key={typedButton.id}
+                      secondary
+                      iconOnly
+                      title={typedButton.label}
+                      onClick={typedButton.onClick}
+                      disabled={isDisabled}
+                    >
+                      {typedButton.icon}
+                    </VscodeButton>
+                  );
+                }
+              )}
+            </div>
+          ))}
+        </div>
+      </Panel>
+
+      {/* Align Context Menu */}
+      {alignMenuOpen && (
+        <VscodeContextMenu
+          show
+          onVscContextMenuSelect={handleAlignSelect}
+          style={{
+            position: 'fixed',
+            top: `${menuPosition.top}px`,
+            left: `${menuPosition.left}px`,
+            zIndex: 2000
+          }}
+          data={[
+            { label: 'Align Left', value: 'left' },
+            { label: 'Align Center Horizontal', value: 'center-h' },
+            { label: 'Align Right', value: 'right' },
+            { separator: true },
+            { label: 'Align Top', value: 'top' },
+            { label: 'Align Center Vertical', value: 'center-v' },
+            { label: 'Align Bottom', value: 'bottom' }
+          ]}
+        />
+      )}
+
+      {/* Distribute Context Menu */}
+      {distributeMenuOpen && (
+        <VscodeContextMenu
+          show
+          onVscContextMenuSelect={handleDistributeSelect}
+          style={{
+            position: 'fixed',
+            top: `${menuPosition.top}px`,
+            left: `${menuPosition.left}px`,
+            zIndex: 2000
+          }}
+          data={[
+            { label: 'Distribute Horizontal Left', value: 'left' },
+            { label: 'Distribute Horizontal Center', value: 'center-h' },
+            { label: 'Distribute Horizontal Right', value: 'right' },
+            { separator: true },
+            { label: 'Distribute Vertical Top', value: 'top' },
+            { label: 'Distribute Vertical Center', value: 'center-v' },
+            { label: 'Distribute Vertical Bottom', value: 'bottom' }
+          ]}
+        />
+      )}
+    </>
+  );
+};