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

package/src/system/graph.ts

@@ -0,0 +1,131 @@
+import type { Viewport } from 'reactflow';
+import type { GraphSession } from './graphSession';
+import type { Edge } from 'reactflow';
+import type { UIGraphJSON } from '@/types/graph';
+
+/**
+ * This is our internal graph representation that we use to perform transformations on
+ * It represents the general graph structure, not the underlying behavior graph instance
+ */
+export class Graph {
+  public readonly viewports: Viewport[] = [];
+  private sys: GraphSession;
+
+  constructor(session: GraphSession) {
+    this.sys = session;
+  }
+
+  setViewport(index: number, viewport: Viewport) {
+    this.viewports[index] = viewport;
+    this.sys.pubsub.publish('saveViewport', {
+      index: index,
+      viewport: viewport
+    });
+  }
+
+  /**
+   * Clears the graph
+   */
+  clear() {
+    const nodes = this.sys.nodeStore.getState().nodes;
+    const edges = this.sys.edgeStore.getState().edges;
+    this.sys.undoManager.execute({
+      name: 'Clear graph',
+      undo: () => {
+        this.sys.nodeStore.getState().setNodes(Object.values(nodes));
+        this.sys.edgeStore.getState().setEdges(Object.values(edges));
+      },
+      execute: () => {
+        this.sys.nodeStore.getState().setNodes([]);
+        this.sys.edgeStore.getState().setEdges([]);
+      }
+    });
+  }
+
+  /**
+   * Return all edges that point into the nodes inputs.
+   * O(m) the amount of edges
+   */
+  inEdges(nodeId: string, sourceHandle?: string): Edge[] {
+    //Get the edges
+    const edges = this.sys.edgeStore.getState().edges;
+
+    return Object.values(edges).filter((x) => {
+      if (x.target !== nodeId) {
+        return false;
+      }
+      if (sourceHandle) {
+        return x.targetHandle === sourceHandle;
+      }
+      return true;
+    });
+  }
+
+  /**
+   * Return all edges that are pointed out by node v.
+   * O(m) the amount of edges
+   */
+  outEdges(nodeId: string, targetHandle?: string): Edge[] {
+    //Get the edges
+    const edges = this.sys.edgeStore.getState().edges;
+
+    return Object.values(edges).filter((x) => {
+      if (x.source !== nodeId) {
+        return false;
+      }
+      if (targetHandle) {
+        return x.targetHandle === targetHandle;
+      }
+      return true;
+    });
+  }
+
+  serialize(): UIGraphJSON {
+    const meta = this.sys.metaStore.getState();
+    return {
+      v: '1.0.0',
+      name: meta.name,
+      user: {
+        viewport: this.viewports[0] || { x: 0, y: 0, zoom: 1 }
+      },
+      annotations: { ...meta.metadata },
+      data: {
+        layers: this.sys.layerStore.getState().serialize()
+      },
+      flow: {},
+      nodes: Object.values(this.sys.nodeStore.getState().nodes),
+      edges: Object.values(this.sys.edgeStore.getState().edges)
+    };
+  }
+
+  getAnnotations() {
+    return { ...this.sys.metaStore.getState().metadata };
+  }
+
+  setAnnotations(annotations: { [key: string]: any }) {
+    this.sys.metaStore.getState().mergeMetadata(annotations);
+    this.sys.pubsub.publish('graphAnnotationsChanged', this.getAnnotations());
+  }
+
+  deseralize(data: UIGraphJSON) {
+    //Load nodes
+    this.sys.nodeStore.getState().setNodes(data.nodes);
+    this.sys.edgeStore.getState().setEdges(data.edges);
+    this.sys.metaStore.getState().setMetadata(data.annotations || {});
+    if (data.name) this.sys.metaStore.getState().setName(data.name);
+    this.sys.layerStore.getState().deserialize(data.data?.layers);
+
+    // Restore viewport
+    if (data.user?.viewport) {
+      const reactflow = this.sys.refStore.getState().getRef('reactflow');
+      if (reactflow) {
+        reactflow.setViewport(data.user.viewport);
+      }
+    }
+
+    // Restore multiple viewports if they exist
+    if (data.user?.viewports) {
+      this.viewports.splice(0, this.viewports.length, ...data.user.viewports);
+    }
+  }
+}

package/src/system/graphSession.ts

@@ -0,0 +1,172 @@
+import { type StoreApi } from 'zustand';
+import { UndoManager } from './undoRedo';
+import { PubSub } from './pubsub';
+import { Graph } from './graph';
+import type { System, GraphPubSys } from './system';
+import {
+  edgeStoreFactory,
+  flowStoreFactory,
+  nodeStoreFactory,
+  type EdgeStore,
+  type FlowStore,
+  type NodeStore
+} from '@/store/flow';
+import { controlsStoreFactory, type ControlsStore } from '@/store/controls';
+import { variableStoreFactory, type VariableStore } from '@/store/variables';
+import { selectionStoreFactory, type SelectionStore } from '@/store/selection';
+import { refStoreFactory, type RefStore } from '@/store/refs';
+import { actionStoreFactory, type ActionStore } from '@/store/actions';
+import { traceStoreFactory, type TraceStore } from '@/store/traces';
+import { eventsStoreFactory, type EventsStore } from '@/store/events';
+import { layerStoreFactory, type LayerStore } from '@/store/layers';
+import { logStoreFactory, type LogStore } from '@/store/logs';
+import { graphMetaStoreFactory, type GraphMetaStore } from '@/store/graphMeta';
+import type { UIGraphJSON } from '@/types/graph';
+
+/**
+ * Augmentable surface for per-graph state contributed by plugins. Mirrors
+ * {@link ISystem} at the editor level: a plugin adds typed properties to every
+ * graph by augmenting this interface and assigning them via
+ * {@link GraphSession.decorate} from inside a session extension.
+ *
+ * @example
+ * declare module '@/system/graphSession' {
+ *   interface IGraphSession {
+ *     myController?: MyController;
+ *   }
+ * }
+ */
+export interface IGraphSession {}
+
+/**
+ * Merge the augmentable surface into the class instance type. Declaration
+ * merging (same-named interface + class) makes plugin-added members , set via
+ * {@link GraphSession.decorate} , readable as `session.x`, which `implements`
+ * alone would NOT provide.
+ */
+// eslint-disable-next-line @typescript-eslint/no-empty-interface
+export interface GraphSession extends IGraphSession {}
+
+/**
+ * A single open graph. Owns all per-graph state , nodes, edges, variables,
+ * selection, traces, layers, logs, undo history and a private pubsub , so that
+ * multiple graphs can be open simultaneously in complete isolation.
+ *
+ * Shared, editor-level resources (registry, specs, settings, notifications, ...)
+ * are reached through {@link GraphSession.editor}.
+ *
+ * Per-graph state contributed by editor plugins is attached on creation via
+ * session extensions (`system.registerSessionExtension`), which may register
+ * teardown through {@link GraphSession.onDispose}.
+ */
+export class GraphSession {
+  public readonly id: string;
+  public readonly editor: System;
+  /** Reactive graph-level properties (name + metadata). */
+  public readonly metaStore: StoreApi<GraphMetaStore>;
+  public readonly pubsub = new PubSub<GraphPubSys>();
+  public readonly undoManager = new UndoManager();
+
+  /** Display name, used as the graph tab title. Backed by {@link metaStore}. */
+  get name(): string {
+    return this.metaStore.getState().name;
+  }
+  set name(value: string) {
+    this.metaStore.getState().setName(value);
+  }
+
+  public readonly controlStore: StoreApi<ControlsStore>;
+  public readonly variableStore: StoreApi<VariableStore>;
+  public readonly refStore: StoreApi<RefStore>;
+  public readonly logsStore: StoreApi<LogStore>;
+  public readonly eventsStore: StoreApi<EventsStore>;
+  public readonly nodeStore: StoreApi<NodeStore>;
+  public readonly edgeStore: StoreApi<EdgeStore>;
+  public readonly flowStore: StoreApi<FlowStore>;
+  public readonly selectionStore: StoreApi<SelectionStore>;
+  public readonly actionStore: StoreApi<ActionStore>;
+  public readonly layerStore: StoreApi<LayerStore>;
+  public readonly traceStore: StoreApi<TraceStore>;
+  public readonly graph: Graph;
+
+  /** Cleanups registered by session extensions, run (LIFO) on {@link dispose}. */
+  private readonly disposers: Array<() => void> = [];
+
+  constructor(editor: System, id = 'graph', name = 'Graph') {
+    this.id = id;
+    this.editor = editor;
+    this.metaStore = graphMetaStoreFactory(name);
+
+    // Construction order preserves the dependency wiring of the old System ctor.
+    this.controlStore = controlsStoreFactory();
+    this.variableStore = variableStoreFactory();
+    this.refStore = refStoreFactory();
+    this.logsStore = logStoreFactory();
+    this.eventsStore = eventsStoreFactory();
+    this.nodeStore = nodeStoreFactory(this);
+    this.edgeStore = edgeStoreFactory(this);
+    this.flowStore = flowStoreFactory(this);
+    this.selectionStore = selectionStoreFactory(this);
+    this.actionStore = actionStoreFactory(this);
+    this.layerStore = layerStoreFactory(this);
+    this.traceStore = traceStoreFactory(this);
+    this.graph = new Graph(this);
+
+    // Per-session behaviours (alignment, ...) are contributed by opt-in plugins
+    // via system.registerSessionExtension(...), not wired here. See the
+    // alignment plugin (`@/plugin/alignment`).
+  }
+
+  /**
+   * Convenience access to the shared editor notifications service.
+   */
+  get notifications() {
+    return this.editor.notifications;
+  }
+
+  /**
+   * Attach a plugin-contributed property to this session. The companion to the
+   * {@link IGraphSession} augmentation; mirrors {@link System.decorate}.
+   */
+  decorate<K extends keyof IGraphSession>(
+    name: K,
+    val: IGraphSession[K]
+  ): void {
+    (this as IGraphSession)[name] = val;
+  }
+
+  /**
+   * Register a cleanup to run when this session is disposed. Session extensions
+   * use this (via their returned cleanup) to tear down per-graph state they
+   * attached. Cleanups run in reverse registration order.
+   */
+  onDispose(cleanup: () => void): void {
+    this.disposers.push(cleanup);
+  }
+
+  serialize(): UIGraphJSON {
+    return this.graph.serialize();
+  }
+
+  /**
+   * Tear down this session's reactive wiring. Called when its tab is closed so
+   * its pubsub subscriptions and trace flush loop don't leak. Extension-supplied
+   * cleanups run first (LIFO), then the built-in teardown.
+   */
+  dispose(): void {
+    for (let i = this.disposers.length - 1; i >= 0; i--) {
+      try {
+        this.disposers[i]!();
+      } catch (err) {
+        console.error('GraphSession disposer failed', err);
+      }
+    }
+    this.disposers.length = 0;
+
+    // Per-session plugin state (e.g. the graph runner's runController) is torn
+    // down by the extension cleanups registered above via onDispose , core no
+    // longer reaches into plugin-owned fields here.
+    this.traceStore.getState().connectEngine(undefined);
+    this.pubsub.clearAllSubscriptions();
+  }
+}

package/src/system/index.ts

@@ -0,0 +1,6 @@
+export * from './system';
+export * from './persistence';
+export * from './graphSession';
+export * from './provider';
+export * from './plugin';
+export { subscribeToRef, useRefFromStore } from '@/store/refs';

package/src/system/notifications.ts

@@ -0,0 +1,111 @@
+import type { System } from '@/system/system';
+import type { Renderable, Toast } from 'react-hot-toast';
+
+export type NotificationType = 'info' | 'success' | 'error' | 'loading';
+
+export interface NotificationData {
+  type: NotificationType;
+  message: string;
+  options?: {
+    id?: string;
+    duration?: number;
+    position?: any;
+    icon?: Renderable;
+    style?: React.CSSProperties;
+    className?: string;
+    ariaLive?: any;
+  };
+}
+export interface NotificationOptions {
+  /**
+   * Toast ID for programmatic dismissal
+   */
+  id?: string;
+  /**
+   * Duration in milliseconds. Set to Infinity to persist until manually dismissed
+   */
+  duration?: number;
+  /**
+   * Position on screen
+   */
+  position?: Toast['position'];
+  /**
+   * Custom icon
+   */
+  icon?: Renderable;
+  /**
+   * Custom styles
+   */
+  style?: React.CSSProperties;
+  /**
+   * Custom class name
+   */
+  className?: string;
+  /**
+   * Accessible aria-live value
+   */
+  ariaLive?: Toast['ariaProps'];
+}
+
+export class Notifications {
+  private readonly system: System;
+  constructor(system: System) {
+    this.system = system;
+  }
+  /**
+   * Dismiss a specific toast or all toasts
+   */
+  dismissNotification(toastId?: string): void {
+    this.system.pubsub.publish('notification:dismiss', { toastId });
+  }
+
+  /**
+   * Show a notification toast
+   */
+  notify(
+    message: string,
+    type: NotificationType = 'info',
+    options?: NotificationOptions
+  ): void {
+    this.system.pubsub.publish('notification', {
+      type,
+      message,
+      options
+    });
+  }
+
+  /**
+   * Show a success notification
+   */
+  success(message: string, options?: NotificationOptions): void {
+    this.notify(message, 'success', options);
+  }
+
+  /**
+   * Show an error notification
+   */
+  error(message: string, options?: NotificationOptions): void {
+    this.notify(message, 'error', options);
+  }
+
+  /**
+   * Show a loading notification
+   */
+  loading(message: string, options?: NotificationOptions): void {
+    this.notify(message, 'loading', options);
+  }
+
+  /**
+   * Show an info notification
+   */
+  info(message: string, options?: NotificationOptions): void {
+    this.notify(message, 'info', options);
+  }
+
+  /**
+   * Dismiss a specific toast or all toasts
+   */
+  dismiss(toastId?: string): void {
+    this.system.pubsub.publish('notification:dismiss', { toastId });
+  }
+}

package/src/system/persistence.ts

@@ -0,0 +1,82 @@
+import type { LayoutBase } from 'rc-dock';
+import type { GraphJSON } from '@kiberon-labs/behave-graph';
+import type { UIGraphJSON } from '@/types/graph';
+import { downloadJson } from '@/util/downloadJson';
+import type { System } from './system';
+
+/**
+ * Sinks invoked when the editor emits its save events. Each entry maps one
+ * editor-level pubsub topic to the side effect that persists it (write the JSON
+ * somewhere). Override any subset to redirect where saved data goes; sinks left
+ * unspecified keep the built-in file-download behaviour.
+ *
+ * Loading is not represented here: the menubar's "Load" items already read a
+ * file from disk and deserialize it into the focused graph by default, so there
+ * is nothing host-specific to wire for the common case.
+ */
+export interface PersistenceAdapter {
+  /** Persist a full UI graph save (`graph:saved`). */
+  saveGraph: (graph: UIGraphJSON) => void;
+  /** Persist a raw inner behave-graph save (`graph:inner:saved`). */
+  saveInnerGraph: (graph: GraphJSON) => void;
+  /** Persist a dock layout save (`layout:saved`). */
+  saveLayout: (layout: LayoutBase) => void;
+}
+
+/**
+ * Whether the file-download default can run. Guards the built-in sinks so that
+ * constructing a `System` in a non-DOM context (tests, SSR, the compiler) never
+ * throws , the subscriptions are harmless, only the download body is skipped.
+ */
+const canDownload = (): boolean =>
+  typeof document !== 'undefined' && typeof URL !== 'undefined';
+
+/**
+ * The built-in persistence: saving triggers a browser download of the
+ * corresponding JSON file. This is the default so a freshly constructed editor
+ * has working Save actions without any per-host or per-story wiring.
+ */
+export const defaultPersistenceAdapter: PersistenceAdapter = {
+  saveGraph: (graph) => {
+    if (canDownload()) downloadJson('graph.json', graph);
+  },
+  saveInnerGraph: (graph) => {
+    if (canDownload()) downloadJson('graph.behave.json', graph);
+  },
+  saveLayout: (layout) => {
+    if (canDownload()) downloadJson('layout.json', layout);
+  }
+};
+
+/**
+ * Subscribe the given (or default) persistence sinks to the editor's save
+ * topics. Any sink not provided falls back to {@link defaultPersistenceAdapter}.
+ * Returns a disposer that removes every subscription it added.
+ */
+export function installPersistence(
+  system: System,
+  adapter: Partial<PersistenceAdapter> = {}
+): () => void {
+  const resolved: PersistenceAdapter = {
+    ...defaultPersistenceAdapter,
+    ...adapter
+  };
+
+  const tokens = [
+    system.pubsub.subscribe('graph:saved', (_, graph) =>
+      resolved.saveGraph(graph)
+    ),
+    system.pubsub.subscribe('graph:inner:saved', (_, graph) =>
+      resolved.saveInnerGraph(graph)
+    ),
+    system.pubsub.subscribe('layout:saved', (_, layout) =>
+      resolved.saveLayout(layout)
+    )
+  ];
+
+  return () => {
+    for (const token of tokens) {
+      if (typeof token === 'string') system.pubsub.unsubscribe(token);
+    }
+  };
+}

package/src/system/plugin.ts

@@ -0,0 +1,55 @@
+import type { System } from '.';
+import type { GraphSession } from './graphSession';
+
+/**
+ * Plugin initialization function type
+ * @template TOptions - Type of options object passed to the plugin
+ */
+export interface Plugin<TOptions = void> {
+  (system: System, options: TOptions): void | Promise<void>;
+}
+
+/**
+ * Cleanup returned by a {@link SessionExtension}. Run when the session it was
+ * applied to is disposed (its tab closed).
+ */
+export type SessionExtensionCleanup = () => void;
+
+/**
+ * Extends a single {@link GraphSession}. Registered at the editor level via
+ * `system.registerSessionExtension(...)`, it runs against every graph , those
+ * already open at registration time and any created afterwards , so an editor
+ * plugin can attach per-graph state (extra stores, controllers, pubsub
+ * subscriptions) to each new graph instance.
+ *
+ * Return a cleanup to tear that per-graph state down when the session is
+ * disposed.
+ *
+ * @example
+ * system.registerSessionExtension((session) => {
+ *   const controller = new MyController(session);
+ *   session.decorate('myController', controller);
+ *   return () => controller.dispose();
+ * });
+ */
+export interface SessionExtension {
+  (session: GraphSession): void | SessionExtensionCleanup;
+}
+export type PluginOpts = {
+  name: string;
+};
+
+export type LoadablePlugin<TOptions = void> = {
+  loader: Plugin<TOptions>;
+  opts: PluginOpts;
+};
+
+export const plugin = <TOptions = void>(
+  registerfunc: Plugin<TOptions>,
+  opts: PluginOpts
+): LoadablePlugin<TOptions> => {
+  return {
+    loader: registerfunc,
+    opts: opts
+  };
+};

package/src/system/provider.tsx

@@ -0,0 +1,86 @@
+import React, { createContext, useContext, type ReactNode } from 'react';
+import { useStore } from 'zustand';
+import type { System } from './system';
+import type { GraphSession } from './graphSession';
+
+// ---------------------------------------------------------------------------
+// Editor system context
+// ---------------------------------------------------------------------------
+
+export const SystemContext = createContext<System | undefined>(undefined);
+
+export type SystemProviderProps = {
+  children: ReactNode;
+  value: System;
+};
+
+/**
+ * Provides the editor-level {@link System} to the React tree.
+ */
+export function SystemProvider({ children, value }: SystemProviderProps) {
+  return <SystemContext value={value}>{children}</SystemContext>;
+}
+
+/** Alias for {@link SystemProvider} expressing its editor-level role. */
+export const EditorProvider = SystemProvider;
+
+/**
+ * Access the editor-level {@link System}.
+ */
+export function useSystem(): System {
+  const context = useContext(SystemContext);
+
+  if (context === undefined) {
+    throw new Error('useSystem must be used within a SystemProvider');
+  }
+
+  return context;
+}
+
+/** Alias for {@link useSystem}. */
+export const useEditor = useSystem;
+
+// ---------------------------------------------------------------------------
+// Per-graph session context
+// ---------------------------------------------------------------------------
+
+const GraphContext = createContext<GraphSession | undefined>(undefined);
+
+export type GraphProviderProps = {
+  children: ReactNode;
+  value: GraphSession;
+};
+
+/**
+ * Provides a single {@link GraphSession} to the subtree rendered inside a graph
+ * tab. Components within use {@link useGraph} to read per-graph state bound to
+ * their own tab, regardless of which tab is currently focused.
+ */
+export function GraphProvider({ children, value }: GraphProviderProps) {
+  return <GraphContext value={value}>{children}</GraphContext>;
+}
+
+/**
+ * Access the {@link GraphSession} of the surrounding graph tab.
+ */
+export function useGraph(): GraphSession {
+  const context = useContext(GraphContext);
+
+  if (context === undefined) {
+    throw new Error('useGraph must be used within a GraphProvider');
+  }
+
+  return context;
+}
+
+/**
+ * Access the currently focused {@link GraphSession}, or undefined when no graph
+ * is open. Subscribes to the editor's active-graph store, so panels rendered
+ * outside of a graph tab re-render when the focused graph changes.
+ */
+export function useActiveGraph(): GraphSession | undefined {
+  const editor = useSystem();
+  return useStore(editor.activeGraph, (s) =>
+    s.activeGraphId ? s.sessions[s.activeGraphId] : undefined
+  );
+}