@invect/ui 0.0.1

package/src/contexts/NodeRegistryContext.tsx

@@ -0,0 +1,54 @@
+import React, { createContext, useContext, useCallback, useMemo } from 'react';
+import { useAvailableNodes } from '../api/node-data.api';
+import { NodeDefinition } from '../types/node-definition.types';
+
+interface NodeRegistryContextType {
+  nodeDefinitions: NodeDefinition[];
+  isLoading: boolean;
+  error: Error | null;
+  getNodeDefinition: (type: string) => NodeDefinition | undefined;
+  refreshDefinitions: () => Promise<void>;
+}
+
+const NodeRegistryContext = createContext<NodeRegistryContextType | undefined>(undefined);
+
+export const NodeRegistryProvider: React.FC<{ children: React.ReactNode }> = ({ children }) => {
+  const { data: nodeDefinitions = [], isLoading, error, refetch } = useAvailableNodes();
+
+  const getNodeDefinition = useCallback(
+    (type: string) => {
+      return nodeDefinitions.find((def) => def.type === type);
+    },
+    [nodeDefinitions],
+  );
+
+  const refreshDefinitions = useCallback(async () => {
+    await refetch();
+  }, [refetch]);
+
+  const value = useMemo(
+    () => ({
+      nodeDefinitions,
+      isLoading,
+      error:
+        error instanceof Error
+          ? error
+          : error
+            ? new Error('Failed to fetch node definitions')
+            : null,
+      getNodeDefinition,
+      refreshDefinitions,
+    }),
+    [nodeDefinitions, isLoading, error, getNodeDefinition, refreshDefinitions],
+  );
+
+  return <NodeRegistryContext.Provider value={value}>{children}</NodeRegistryContext.Provider>;
+};
+
+export const useNodeRegistry = () => {
+  const context = useContext(NodeRegistryContext);
+  if (context === undefined) {
+    throw new Error('useNodeRegistry must be used within a NodeRegistryProvider');
+  }
+  return context;
+};

package/src/contexts/PluginRegistryContext.tsx

@@ -0,0 +1,182 @@
+/**
+ * PluginRegistryContext — Collects and resolves contributions from frontend plugins.
+ *
+ * Provides `usePluginRegistry()` to any component in the tree so they
+ * can read sidebar items, routes, panel tabs, header actions, and
+ * permission checks contributed by plugins.
+ */
+
+import React, { createContext, useContext, useMemo, type ReactNode } from 'react';
+import type {
+  InvectFrontendPlugin,
+  PluginSidebarContribution,
+  PluginRouteContribution,
+  PluginPanelTabContribution,
+  PluginHeaderActionContribution,
+  PermissionContext,
+} from '../types/plugin.types';
+
+// ─────────────────────────────────────────────────────────────
+// Registry Interface
+// ─────────────────────────────────────────────────────────────
+
+export interface PluginRegistry {
+  /** All sidebar items from plugins, grouped by position */
+  sidebarItems: PluginSidebarContribution[];
+  /** Component for the sidebar footer (user menu). First plugin to provide wins. */
+  SidebarFooter: React.ComponentType<{ collapsed: boolean; basePath: string }> | null;
+  /** All routes contributed by plugins */
+  routes: PluginRouteContribution[];
+  /** Panel tabs grouped by context (e.g. 'flowEditor', 'nodeConfig') */
+  panelTabs: Record<string, PluginPanelTabContribution[]>;
+  /** Header actions grouped by context (e.g. 'flowHeader', 'flowList') */
+  headerActions: Record<string, PluginHeaderActionContribution[]>;
+  /** All provider wrappers from plugins (in registration order) */
+  providers: React.ComponentType<{ children: ReactNode }>[];
+  /**
+   * Permission checker — first plugin to return non-undefined wins.
+   * Returns true if no plugin overrides (default: allow everything).
+   */
+  checkPermission: (permission: string, context?: PermissionContext) => boolean;
+  /** Whether any plugins are registered */
+  hasPlugins: boolean;
+}
+
+// ─────────────────────────────────────────────────────────────
+// Context
+// ─────────────────────────────────────────────────────────────
+
+const defaultRegistry: PluginRegistry = {
+  sidebarItems: [],
+  SidebarFooter: null,
+  routes: [],
+  panelTabs: {},
+  headerActions: {},
+  providers: [],
+  checkPermission: () => true,
+  hasPlugins: false,
+};
+
+const PluginRegistryContext = createContext<PluginRegistry>(defaultRegistry);
+
+// ─────────────────────────────────────────────────────────────
+// Provider
+// ─────────────────────────────────────────────────────────────
+
+interface PluginRegistryProviderProps {
+  plugins: InvectFrontendPlugin[];
+  children: ReactNode;
+}
+
+export function PluginRegistryProvider({ plugins, children }: PluginRegistryProviderProps) {
+  const registry = useMemo(() => buildRegistry(plugins), [plugins]);
+
+  // Wrap children in all plugin providers (outermost = first plugin)
+  let wrapped = <>{children}</>;
+  for (let i = registry.providers.length - 1; i >= 0; i--) {
+    const Provider = registry.providers[i];
+    wrapped = <Provider>{wrapped}</Provider>;
+  }
+
+  return (
+    <PluginRegistryContext.Provider value={registry}>{wrapped}</PluginRegistryContext.Provider>
+  );
+}
+
+// ─────────────────────────────────────────────────────────────
+// Hook
+// ─────────────────────────────────────────────────────────────
+
+/**
+ * Access the plugin registry from any component inside `<Invect />`.
+ * Returns a default (empty) registry if no plugins are registered.
+ */
+export function usePluginRegistry(): PluginRegistry {
+  return useContext(PluginRegistryContext);
+}
+
+// ─────────────────────────────────────────────────────────────
+// Registry Builder
+// ─────────────────────────────────────────────────────────────
+
+function buildRegistry(plugins: InvectFrontendPlugin[]): PluginRegistry {
+  const sidebarItems: PluginSidebarContribution[] = [];
+  let SidebarFooter: React.ComponentType<{ collapsed: boolean; basePath: string }> | null = null;
+  const routes: PluginRouteContribution[] = [];
+  const panelTabs: Record<string, PluginPanelTabContribution[]> = {};
+  const headerActions: Record<string, PluginHeaderActionContribution[]> = {};
+  const providers: React.ComponentType<{ children: ReactNode }>[] = [];
+  const permissionCheckers: Array<
+    (permission: string, context?: PermissionContext) => boolean | undefined
+  > = [];
+
+  for (const plugin of plugins) {
+    // Collect sidebar items
+    if (plugin.sidebar) {
+      sidebarItems.push(...plugin.sidebar);
+    }
+
+    // Collect sidebar footer (first plugin to provide wins)
+    if (plugin.sidebarFooter && !SidebarFooter) {
+      SidebarFooter = plugin.sidebarFooter;
+    }
+
+    // Collect routes
+    if (plugin.routes) {
+      routes.push(...plugin.routes);
+    }
+
+    // Collect panel tabs
+    if (plugin.panelTabs) {
+      for (const tab of plugin.panelTabs) {
+        if (!panelTabs[tab.context]) {
+          panelTabs[tab.context] = [];
+        }
+        panelTabs[tab.context].push(tab);
+      }
+    }
+
+    // Collect header actions
+    if (plugin.headerActions) {
+      for (const action of plugin.headerActions) {
+        if (!headerActions[action.context]) {
+          headerActions[action.context] = [];
+        }
+        headerActions[action.context].push(action);
+      }
+    }
+
+    // Collect providers
+    if (plugin.providers) {
+      providers.push(...plugin.providers);
+    }
+
+    // Collect permission checkers
+    if (plugin.checkPermission) {
+      permissionCheckers.push(plugin.checkPermission);
+    }
+  }
+
+  // Build composite permission checker
+  const checkPermission = (permission: string, context?: PermissionContext): boolean => {
+    for (const checker of permissionCheckers) {
+      const result = checker(permission, context);
+      if (result !== undefined) {
+        return result;
+      }
+    }
+    // Default: allow everything when no plugin overrides
+    return true;
+  };
+
+  return {
+    sidebarItems,
+    SidebarFooter,
+    routes,
+    panelTabs,
+    headerActions,
+    providers,
+    checkPermission,
+    hasPlugins: plugins.length > 0,
+  };
+}

package/src/contexts/ThemeProvider.tsx

@@ -0,0 +1,106 @@
+import React, { createContext, useContext, useEffect, useMemo, useState } from 'react';
+
+type Theme = 'dark' | 'light' | 'system';
+type ResolvedTheme = 'dark' | 'light';
+
+interface ThemeProviderProps {
+  children: React.ReactNode;
+  defaultTheme?: Theme;
+  storageKey?: string;
+  className?: string;
+}
+
+interface ThemeContextValue {
+  theme: Theme;
+  resolvedTheme: ResolvedTheme;
+  setTheme: (theme: Theme) => void;
+}
+
+const ThemeContext = createContext<ThemeContextValue | undefined>(undefined);
+
+function isTheme(value: string | null): value is Theme {
+  return value === 'light' || value === 'dark' || value === 'system';
+}
+
+function getSystemTheme(): ResolvedTheme {
+  if (typeof window === 'undefined') {
+    return 'light';
+  }
+
+  return window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light';
+}
+
+export function ThemeProvider({
+  children,
+  defaultTheme = 'dark',
+  storageKey = 'invect-ui-theme',
+  className,
+}: ThemeProviderProps) {
+  const [theme, setTheme] = useState<Theme>(() => {
+    if (typeof window !== 'undefined') {
+      const storedTheme = localStorage.getItem(storageKey);
+      if (isTheme(storedTheme)) {
+        return storedTheme;
+      }
+    }
+
+    return defaultTheme;
+  });
+  const [resolvedTheme, setResolvedTheme] = useState<ResolvedTheme>(() =>
+    theme === 'system' ? getSystemTheme() : theme,
+  );
+
+  useEffect(() => {
+    if (theme === 'system') {
+      const mediaQuery = window.matchMedia('(prefers-color-scheme: dark)');
+      const handleChange = (event: MediaQueryListEvent) => {
+        setResolvedTheme(event.matches ? 'dark' : 'light');
+      };
+
+      setResolvedTheme(mediaQuery.matches ? 'dark' : 'light');
+      mediaQuery.addEventListener('change', handleChange);
+
+      return () => {
+        mediaQuery.removeEventListener('change', handleChange);
+      };
+    }
+
+    setResolvedTheme(theme);
+  }, [theme]);
+
+  const value = useMemo<ThemeContextValue>(
+    () => ({
+      theme,
+      resolvedTheme,
+      setTheme: (newTheme: Theme) => {
+        localStorage.setItem(storageKey, newTheme);
+        setTheme(newTheme);
+      },
+    }),
+    [resolvedTheme, storageKey, theme],
+  );
+
+  return (
+    <ThemeContext.Provider value={value}>
+      <div
+        className={['invect', resolvedTheme, 'flex-1 w-full h-full min-h-0', className]
+          .filter(Boolean)
+          .join(' ')}
+      >
+        {children}
+      </div>
+    </ThemeContext.Provider>
+  );
+}
+
+export function useOptionalTheme() {
+  return useContext(ThemeContext);
+}
+
+export function useTheme() {
+  const context = useContext(ThemeContext);
+  if (context === undefined) {
+    throw new Error('useTheme must be used within a ThemeProvider');
+  }
+  return context;
+}

package/src/contexts/ValidationContext.tsx

@@ -0,0 +1,122 @@
+import React, { createContext, useContext, useState, ReactNode } from 'react';
+import type {
+  FlowValidationResult,
+  FlowValidationError,
+  FlowValidationWarning,
+} from '@invect/core/types';
+
+interface ValidationContextValue {
+  validationResult: FlowValidationResult | null;
+  setValidationResult: (result: FlowValidationResult | null) => void;
+  clearValidation: () => void;
+
+  // Helper methods for checking validation state
+  hasErrors: boolean;
+  hasWarnings: boolean;
+
+  // Methods to get errors/warnings by element
+  getNodeErrors: (nodeId: string) => FlowValidationError[];
+  getNodeWarnings: (nodeId: string) => FlowValidationWarning[];
+  getEdgeErrors: (edgeId: string) => FlowValidationError[];
+  getEdgeWarnings: (edgeId: string) => FlowValidationWarning[];
+
+  // Check if specific elements have validation issues
+  isNodeInvalid: (nodeId: string) => boolean;
+  isEdgeInvalid: (edgeId: string) => boolean;
+  hasNodeWarnings: (nodeId: string) => boolean;
+  hasEdgeWarnings: (edgeId: string) => boolean;
+}
+
+const ValidationContext = createContext<ValidationContextValue | null>(null);
+
+export function ValidationProvider({ children }: { children: ReactNode }) {
+  const [validationResult, setValidationResult] = useState<FlowValidationResult | null>(null);
+
+  const clearValidation = () => setValidationResult(null);
+
+  // Helper methods
+  const hasErrors = validationResult
+    ? !validationResult.isValid && validationResult.errors?.length > 0
+    : false;
+  const hasWarnings = validationResult ? (validationResult.warnings?.length || 0) > 0 : false;
+
+  const getNodeErrors = (nodeId: string): FlowValidationError[] => {
+    if (!validationResult || validationResult.isValid) {
+      return [];
+    }
+    return validationResult.errors.filter(
+      (error: FlowValidationError) =>
+        error.nodeId === nodeId || error.sourceNodeId === nodeId || error.targetNodeId === nodeId,
+    );
+  };
+
+  const getNodeWarnings = (nodeId: string): FlowValidationWarning[] => {
+    if (!validationResult || !validationResult.warnings) {
+      return [];
+    }
+    return validationResult.warnings.filter(
+      (warning: FlowValidationWarning) =>
+        warning.nodeId === nodeId ||
+        warning.sourceNodeId === nodeId ||
+        warning.targetNodeId === nodeId,
+    );
+  };
+
+  const getEdgeErrors = (edgeId: string): FlowValidationError[] => {
+    if (!validationResult || validationResult.isValid) {
+      return [];
+    }
+    return validationResult.errors.filter((error: FlowValidationError) => error.edgeId === edgeId);
+  };
+
+  const getEdgeWarnings = (edgeId: string): FlowValidationWarning[] => {
+    if (!validationResult || !validationResult.warnings) {
+      return [];
+    }
+    return validationResult.warnings.filter(
+      (warning: FlowValidationWarning) => warning.edgeId === edgeId,
+    );
+  };
+
+  const isNodeInvalid = (nodeId: string): boolean => {
+    return getNodeErrors(nodeId).length > 0;
+  };
+
+  const isEdgeInvalid = (edgeId: string): boolean => {
+    return getEdgeErrors(edgeId).length > 0;
+  };
+
+  const hasNodeWarnings = (nodeId: string): boolean => {
+    return getNodeWarnings(nodeId).length > 0;
+  };
+
+  const hasEdgeWarnings = (edgeId: string): boolean => {
+    return getEdgeWarnings(edgeId).length > 0;
+  };
+
+  const value: ValidationContextValue = {
+    validationResult,
+    setValidationResult,
+    clearValidation,
+    hasErrors,
+    hasWarnings,
+    getNodeErrors,
+    getNodeWarnings,
+    getEdgeErrors,
+    getEdgeWarnings,
+    isNodeInvalid,
+    isEdgeInvalid,
+    hasNodeWarnings,
+    hasEdgeWarnings,
+  };
+
+  return <ValidationContext.Provider value={value}>{children}</ValidationContext.Provider>;
+}
+
+export function useValidation() {
+  const context = useContext(ValidationContext);
+  if (!context) {
+    throw new Error('useValidation must be used within a ValidationProvider');
+  }
+  return context;
+}

package/src/demo/DemoInvect.tsx

@@ -0,0 +1,42 @@
+/**
+ * DemoInvect — Full Invect UI powered by static demo data.
+ *
+ * Renders the complete Invect dashboard (sidebar, flow editor, credentials page, etc.)
+ * without requiring a backend server. All API calls resolve from the provided DemoData.
+ *
+ * @example
+ * ```tsx
+ * import { DemoInvect } from '@invect/ui/demo';
+ * import '@invect/ui/styles';
+ *
+ * const demoData = {
+ *   flows: [{ id: 'flow-1', name: 'My Flow', ... }],
+ *   flowReactFlowData: { 'flow-1': { nodes: [...], edges: [...], ... } },
+ *   nodeDefinitions: [...],
+ * };
+ *
+ * <div style={{ height: '600px' }}>
+ *   <DemoInvect data={demoData} />
+ * </div>
+ * ```
+ */
+
+import React, { useMemo } from 'react';
+import { Invect, type InvectProps } from '../Invect';
+import { createDemoApiClient, type DemoData } from './demo-api-client';
+import type { ApiClient } from '../api/client';
+
+export interface DemoInvectProps extends Omit<InvectProps, 'apiBaseUrl' | 'apiClient'> {
+  /** Static data to power the demo UI */
+  data: DemoData;
+}
+
+/**
+ * Full Invect UI with no backend — all data comes from the `data` prop.
+ * Uses MemoryRouter by default so it doesn't affect the host page's URL.
+ */
+export function DemoInvect({ data, useMemoryRouter = true, ...rest }: DemoInvectProps) {
+  const mockClient = useMemo(() => createDemoApiClient(data) as unknown as ApiClient, [data]);
+
+  return <Invect apiClient={mockClient} useMemoryRouter={useMemoryRouter} {...rest} />;
+}