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

package/src/system/notifications.ts

@@ -3,6 +3,19 @@ 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

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

@@ -1,4 +1,5 @@
 import type { System } from '.';
+import type { GraphSession } from './graphSession';
 
 /**
  * Plugin initialization function type
@@ -7,6 +8,33 @@ import type { System } from '.';
 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;
 };

package/src/system/provider.tsx

@@ -1,5 +1,11 @@
 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);
 
@@ -7,10 +13,20 @@ 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);
 
@@ -20,3 +36,51 @@ export function useSystem(): System {
 
   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
+  );
+}