@mmapp/react 0.1.0-alpha.1 → 0.1.0-alpha.3

package/src/hooks/useServerState.ts

@@ -1,284 +0,0 @@
-/**
- * useServerState — subscribe to server-side workflow state via SSE.
- *
- * Connects to the SSE endpoint at /api/v1/workflow/events and filters
- * events for a specific instance ID. Returns the current server state
- * with real-time updates.
- *
- * Usage in .workflow.tsx:
- *   const { state, stateData, loading, error } = useServerState(instanceId);
- *
- *   <Show when={state === 'submitted'}>
- *     <Text>Order has been submitted</Text>
- *   </Show>
- *
- * The compiler extracts this as a server state subscription in the IR.
- * At runtime, the hook opens an SSE connection and filters by instance.
- */
-
-import { useState, useEffect, useRef, useCallback } from 'react';
-
-// =============================================================================
-// Types
-// =============================================================================
-
-export interface ServerStateOptions {
-  /** Disable the SSE connection (manual mode). */
-  enabled?: boolean;
-  /** Called when server state changes. */
-  onStateChange?: (state: ServerStateSnapshot) => void;
-  /** Called on connection error. */
-  onError?: (error: Error) => void;
-}
-
-export interface ServerStateSnapshot {
-  /** Current workflow state name. */
-  currentState: string;
-  /** Current state data (fields). */
-  stateData: Record<string, unknown>;
-  /** Instance status (ACTIVE, COMPLETED, etc.). */
-  status: string;
-  /** Last transition that occurred. */
-  lastTransition?: {
-    name: string;
-    from: string;
-    to: string;
-    timestamp: string;
-  };
-}
-
-export interface ServerStateResult {
-  /** Current workflow state name (empty string until first event). */
-  state: string;
-  /** Current state data. */
-  stateData: Record<string, unknown>;
-  /** Instance status. */
-  status: string;
-  /** Whether the initial state is still loading. */
-  loading: boolean;
-  /** Connection or parse error. */
-  error: Error | null;
-  /** Whether the SSE connection is active. */
-  connected: boolean;
-  /** Last transition info. */
-  lastTransition: ServerStateSnapshot['lastTransition'] | undefined;
-  /** Force-reconnect the SSE stream. */
-  reconnect: () => void;
-}
-
-/**
- * Resolver interface for fetching initial instance state.
- * Falls back to a direct fetch if not configured.
- */
-export interface ServerStateResolver {
-  getInstanceState: (instanceId: string) => Promise<ServerStateSnapshot>;
-}
-
-// Global resolver (set by provider)
-let _globalServerStateResolver: ServerStateResolver | null = null;
-
-export function setServerStateResolver(resolver: ServerStateResolver | null): void {
-  _globalServerStateResolver = resolver;
-}
-
-// =============================================================================
-// Internal helpers
-// =============================================================================
-
-/** Get JWT token from localStorage. */
-function getToken(): string | null {
-  return typeof localStorage !== 'undefined'
-    ? localStorage.getItem('auth_token')
-    : null;
-}
-
-/** Fetch initial instance state from the API. */
-async function fetchInitialState(instanceId: string): Promise<ServerStateSnapshot> {
-  if (_globalServerStateResolver) {
-    return _globalServerStateResolver.getInstanceState(instanceId);
-  }
-
-  const token = getToken();
-  const res = await fetch(
-    `/api/v1/workflow/instances/${encodeURIComponent(instanceId)}`,
-    {
-      headers: token ? { Authorization: `Bearer ${token}` } : {},
-    },
-  );
-
-  if (!res.ok) {
-    throw new Error(`Failed to fetch instance state: ${res.status}`);
-  }
-
-  const data = await res.json();
-  return {
-    currentState: data.current_state || '',
-    stateData: data.state_data || {},
-    status: data.status || 'UNKNOWN',
-  };
-}
-
-// =============================================================================
-// Hook
-// =============================================================================
-
-/**
- * Subscribes to real-time server state for a workflow instance via SSE.
- *
- * @param instanceId - The workflow instance ID to subscribe to.
- * @param options - Optional configuration (enabled, callbacks).
- * @returns Server state with loading/error/connected status.
- */
-export function useServerState(
-  instanceId: string,
-  options: ServerStateOptions = {},
-): ServerStateResult {
-  const [state, setState] = useState('');
-  const [stateData, setStateData] = useState<Record<string, unknown>>({});
-  const [status, setStatus] = useState('UNKNOWN');
-  const [loading, setLoading] = useState(true);
-  const [error, setError] = useState<Error | null>(null);
-  const [connected, setConnected] = useState(false);
-  const [lastTransition, setLastTransition] = useState<ServerStateSnapshot['lastTransition']>();
-  const [reconnectKey, setReconnectKey] = useState(0);
-
-  const optionsRef = useRef(options);
-  optionsRef.current = options;
-
-  const eventSourceRef = useRef<EventSource | null>(null);
-
-  const reconnect = useCallback(() => {
-    setReconnectKey((k) => k + 1);
-  }, []);
-
-  // Fetch initial state
-  useEffect(() => {
-    if (options.enabled === false || !instanceId) return;
-
-    let cancelled = false;
-    setLoading(true);
-
-    fetchInitialState(instanceId)
-      .then((snapshot) => {
-        if (cancelled) return;
-        setState(snapshot.currentState);
-        setStateData(snapshot.stateData);
-        setStatus(snapshot.status);
-        setLoading(false);
-      })
-      .catch((err) => {
-        if (cancelled) return;
-        setError(err instanceof Error ? err : new Error(String(err)));
-        setLoading(false);
-      });
-
-    return () => {
-      cancelled = true;
-    };
-  }, [instanceId, options.enabled, reconnectKey]);
-
-  // SSE subscription
-  useEffect(() => {
-    if (options.enabled === false || !instanceId) return;
-
-    const token = getToken();
-    if (!token) {
-      setError(new Error('useServerState: No auth token found in localStorage'));
-      return;
-    }
-
-    const url = `/api/v1/workflow/events?token=${encodeURIComponent(token)}`;
-    const es = new EventSource(url);
-    eventSourceRef.current = es;
-
-    es.addEventListener('connected', () => {
-      setConnected(true);
-      setError(null);
-    });
-
-    // Listen to relevant SSE event types and filter by instance ID
-    const handleEvent = (eventName: string, e: MessageEvent) => {
-      try {
-        const data = JSON.parse(e.data);
-        // Filter: only process events for our instance
-        if (data.instance_id !== instanceId) return;
-
-        switch (eventName) {
-          case 'workflow:transitioned': {
-            const snapshot: ServerStateSnapshot = {
-              currentState: data.to_state,
-              stateData: stateData, // Keep current, will be updated by data_updated
-              status: 'ACTIVE',
-              lastTransition: {
-                name: data.transition_name,
-                from: data.from_state,
-                to: data.to_state,
-                timestamp: data.timestamp,
-              },
-            };
-            setState(data.to_state);
-            setLastTransition(snapshot.lastTransition);
-            optionsRef.current.onStateChange?.(snapshot);
-            break;
-          }
-          case 'workflow:data_updated': {
-            if (data.state_data) {
-              setStateData((prev) => ({ ...prev, ...data.state_data }));
-            }
-            break;
-          }
-          case 'workflow:state_changed': {
-            if (data.current_state) setState(data.current_state);
-            if (data.status) setStatus(data.status);
-            break;
-          }
-          case 'workflow:instance_deleted': {
-            setStatus('DELETED');
-            break;
-          }
-        }
-      } catch {
-        // Ignore parse errors on individual events
-      }
-    };
-
-    const eventTypes = [
-      'workflow:transitioned',
-      'workflow:data_updated',
-      'workflow:state_changed',
-      'workflow:instance_created',
-      'workflow:instance_deleted',
-      'workflow:blocked',
-      'workflow:unblocked',
-    ];
-
-    for (const eventType of eventTypes) {
-      es.addEventListener(eventType, (e) => handleEvent(eventType, e as MessageEvent));
-    }
-
-    es.onerror = () => {
-      setConnected(false);
-      const err = new Error('SSE connection lost');
-      setError(err);
-      optionsRef.current.onError?.(err);
-    };
-
-    return () => {
-      es.close();
-      eventSourceRef.current = null;
-      setConnected(false);
-    };
-  }, [instanceId, options.enabled, reconnectKey]); // eslint-disable-line react-hooks/exhaustive-deps
-
-  const handle: ServerStateResult = {
-    state,
-    stateData,
-    status,
-    loading,
-    error,
-    connected,
-    lastTransition,
-    reconnect,
-  };
-  return handle;
-}

package/src/hooks/useToast.ts

@@ -1,164 +0,0 @@
-/**
- * useToast — In-app toast notification hook.
- *
- * Manages a queue of toast messages with auto-dismiss, stacking,
- * and manual dismiss. Framework-agnostic — provides state only,
- * the actual rendering is done by the host application's toast component.
- *
- * Usage in .workflow.tsx:
- *   const { toast, toasts, dismiss } = useToast();
- *
- *   // Show a success toast
- *   toast({ title: 'Ride booked!', variant: 'success' });
- *
- *   // Show an error toast
- *   toast({ title: 'Payment failed', description: 'Please try again', variant: 'error' });
- *
- *   // Render toasts (in your layout)
- *   {toasts.map(t => <ToastComponent key={t.id} {...t} onDismiss={() => dismiss(t.id)} />)}
- */
-
-import { useState, useCallback, useRef, useMemo } from 'react';
-
-// =============================================================================
-// Types
-// =============================================================================
-
-/** Toast variant for styling. */
-export type ToastVariant = 'default' | 'success' | 'error' | 'warning' | 'info';
-
-/** Toast configuration for creating a new toast. */
-export interface ToastConfig {
-  /** Toast title (required). */
-  title: string;
-  /** Optional description/body. */
-  description?: string;
-  /** Visual variant (default: 'default'). */
-  variant?: ToastVariant;
-  /** Auto-dismiss after ms (default: 5000, 0 = no auto-dismiss). */
-  duration?: number;
-  /** Action button configuration. */
-  action?: {
-    label: string;
-    onClick: () => void;
-  };
-}
-
-/** A toast instance in the queue. */
-export interface ToastInstance extends ToastConfig {
-  /** Unique toast ID. */
-  id: string;
-  /** When the toast was created. */
-  createdAt: number;
-}
-
-/** Toast handle returned by useToast. */
-export interface ToastHandle {
-  /** Show a new toast. Returns the toast ID. */
-  toast: (config: ToastConfig) => string;
-  /** All active toasts. */
-  toasts: ToastInstance[];
-  /** Dismiss a specific toast by ID. */
-  dismiss: (id: string) => void;
-  /** Dismiss all toasts. */
-  dismissAll: () => void;
-}
-
-// =============================================================================
-// Global toast store (shared across all useToast instances)
-// =============================================================================
-
-type ToastListener = (toasts: ToastInstance[]) => void;
-
-let _nextId = 0;
-let _toasts: ToastInstance[] = [];
-const _listeners = new Set<ToastListener>();
-const _timers = new Map<string, ReturnType<typeof setTimeout>>();
-
-function notifyListeners(): void {
-  for (const listener of _listeners) {
-    listener([..._toasts]);
-  }
-}
-
-function addToast(config: ToastConfig): string {
-  const id = `toast-${++_nextId}`;
-  const instance: ToastInstance = {
-    ...config,
-    id,
-    createdAt: Date.now(),
-  };
-  _toasts = [..._toasts, instance];
-
-  const duration = config.duration ?? 5000;
-  if (duration > 0) {
-    const timer = setTimeout(() => {
-      removeToast(id);
-    }, duration);
-    _timers.set(id, timer);
-  }
-
-  notifyListeners();
-  return id;
-}
-
-function removeToast(id: string): void {
-  const timer = _timers.get(id);
-  if (timer) {
-    clearTimeout(timer);
-    _timers.delete(id);
-  }
-  _toasts = _toasts.filter((t) => t.id !== id);
-  notifyListeners();
-}
-
-function clearAllToasts(): void {
-  for (const timer of _timers.values()) {
-    clearTimeout(timer);
-  }
-  _timers.clear();
-  _toasts = [];
-  notifyListeners();
-}
-
-// =============================================================================
-// Hook
-// =============================================================================
-
-/**
- * In-app toast notification manager.
- *
- * @returns Toast handle with toast(), toasts, dismiss, and dismissAll.
- */
-export function useToast(): ToastHandle {
-  const [toasts, setToasts] = useState<ToastInstance[]>(() => [..._toasts]);
-  const listenerRef = useRef<ToastListener | null>(null);
-
-  // Subscribe to global toast store
-  if (!listenerRef.current) {
-    const listener: ToastListener = (newToasts) => setToasts(newToasts);
-    listenerRef.current = listener;
-    _listeners.add(listener);
-  }
-
-  // Note: we intentionally don't clean up the listener in useEffect
-  // because the component will re-subscribe anyway. Using a ref-based
-  // approach avoids the stale closure problem with useEffect + useState.
-
-  const toast = useCallback((config: ToastConfig): string => {
-    return addToast(config);
-  }, []);
-
-  const dismiss = useCallback((id: string): void => {
-    removeToast(id);
-  }, []);
-
-  const dismissAll = useCallback((): void => {
-    clearAllToasts();
-  }, []);
-
-  return useMemo(
-    (): ToastHandle => ({ toast, toasts, dismiss, dismissAll }),
-    [toast, toasts, dismiss, dismissAll],
-  );
-}

package/src/hooks/useTransition.ts

@@ -1,39 +0,0 @@
-/**
- * useTransition — Helper hook for firing transitions
- *
- * Returns a handle to fire a specific transition with pending state.
- * Must be used within a RuntimeContext (e.g., WorkflowProvider).
- */
-
-import { useCallback, useState } from 'react';
-import { useRuntimeContext } from '../providers/RuntimeContext';
-import type { TransitionResult } from '@mindmatrix/player-core';
-
-export interface TransitionHandle {
-  fire: (data?: Record<string, unknown>) => Promise<TransitionResult>;
-  available: boolean;
-  pending: boolean;
-}
-
-/**
- * @param transitionName - Name of the transition.
- * @param _config - Optional authoring config (from/to/requiredFields).
- *   Used by the Babel plugin at compile time; ignored at runtime.
- */
-export function useTransition(transitionName: string, _config?: { from?: string; to?: string; requiredFields?: string[] }): TransitionHandle {
-  const runtime = useRuntimeContext();
-  const [pending, setPending] = useState(false);
-  const available = runtime.sm.getAvailableTransitions().some(t => t.name === transitionName);
-
-  const fire = useCallback(async (data?: Record<string, unknown>) => {
-    setPending(true);
-    try {
-      return await runtime.transition(transitionName, data);
-    } finally {
-      setPending(false);
-    }
-  }, [runtime, transitionName]);
-
-  const handle: TransitionHandle = { fire, available, pending };
-  return handle;
-}

package/src/hooks/useView.ts

@@ -1,102 +0,0 @@
-/**
- * useView — Load a view definition by ID or slug
- *
- * Fetches a view definition (category='view') from the workflow API.
- * Supports B1 views-as-definitions — views are standalone workflow
- * definitions with category='view'.
- *
- * Usage in .workflow.tsx:
- *   const { view, loading, error } = useView('my-custom-view');
- */
-
-import { useState, useEffect, useCallback, useRef } from 'react';
-
-// =============================================================================
-// Types
-// =============================================================================
-
-export interface ViewDefinitionResult {
-  /** The loaded view definition (component tree). */
-  view: ViewRecord | null;
-  /** Whether the view is currently loading. */
-  loading: boolean;
-  /** Error from the last fetch attempt. */
-  error: Error | null;
-  /** Manually trigger a refetch. */
-  refetch: () => Promise<void>;
-}
-
-export interface ViewRecord {
-  id: string;
-  slug: string;
-  name: string;
-  category: string;
-  view?: Record<string, unknown>;
-  metadata?: Record<string, unknown>;
-}
-
-/**
- * View resolver interface — the runtime must provide an implementation.
- */
-export interface ViewResolver {
-  getView: (idOrSlug: string) => Promise<ViewRecord | null>;
-}
-
-// Global resolver (set by provider)
-let _globalViewResolver: ViewResolver | null = null;
-
-export function setViewResolver(resolver: ViewResolver | null): void {
-  _globalViewResolver = resolver;
-}
-
-// =============================================================================
-// Hook
-// =============================================================================
-
-/**
- * Fetches a view definition by ID or slug.
- *
- * @param idOrSlug - The view definition ID or slug to load.
- * @returns View result with definition, loading state, error, and refetch.
- */
-export function useView(idOrSlug: string | null): ViewDefinitionResult {
-  const [view, setView] = useState<ViewRecord | null>(null);
-  const [loading, setLoading] = useState(!!idOrSlug);
-  const [error, setError] = useState<Error | null>(null);
-  const idRef = useRef(idOrSlug);
-  idRef.current = idOrSlug;
-
-  const fetchView = useCallback(async () => {
-    const id = idRef.current;
-    if (!id) {
-      setView(null);
-      setLoading(false);
-      return;
-    }
-
-    const resolver = _globalViewResolver;
-    if (!resolver) {
-      setError(new Error('useView: No view resolver configured. Wrap your app in a WorkflowProvider.'));
-      setLoading(false);
-      return;
-    }
-
-    try {
-      setLoading(true);
-      setError(null);
-      const result = await resolver.getView(id);
-      setView(result);
-    } catch (err) {
-      setError(err instanceof Error ? err : new Error(String(err)));
-    } finally {
-      setLoading(false);
-    }
-  }, []);
-
-  useEffect(() => {
-    fetchView();
-  }, [idOrSlug, fetchView]);
-
-  const result: ViewDefinitionResult = { view, loading, error, refetch: fetchView };
-  return result;
-}

package/src/hooks/useWhileIn.ts

@@ -1,48 +0,0 @@
-/**
- * useWhileIn — Run effect on interval while in state
- *
- * Starts an interval when entering the specified state.
- * Stops the interval when exiting the state.
- */
-
-import { useEffect, useRef } from 'react';
-import { useRuntimeContext } from '../providers/RuntimeContext';
-
-export function useWhileIn(
-  stateName: string,
-  intervalMs: number,
-  effect: () => void | Promise<void>
-): void {
-  const runtime = useRuntimeContext();
-  const effectRef = useRef(effect);
-  effectRef.current = effect;
-
-  useEffect(() => {
-    let timer: ReturnType<typeof setInterval> | null = null;
-
-    function startInterval() {
-      if (timer) clearInterval(timer);
-      timer = setInterval(() => effectRef.current(), intervalMs);
-    }
-
-    function stopInterval() {
-      if (timer) {
-        clearInterval(timer);
-        timer = null;
-      }
-    }
-
-    // If already in target state, start immediately
-    if (runtime.sm.currentState === stateName) startInterval();
-
-    const unsub = runtime.sm.on((event) => {
-      if (event.type === 'state_enter' && event.to_state === stateName) startInterval();
-      if (event.type === 'state_exit' && event.from_state === stateName) stopInterval();
-    });
-
-    return () => {
-      unsub();
-      stopInterval();
-    };
-  }, [runtime, stateName, intervalMs]);
-}

package/src/hooks/useWorkflow.ts

@@ -1,63 +0,0 @@
-/**
- * useWorkflow — Create and manage a WorkflowRuntime instance
- *
- * Creates a standalone WorkflowRuntime from a definition and returns
- * a handle with snapshot state and methods to interact with the runtime.
- */
-
-import { useState, useEffect, useMemo, useCallback } from 'react';
-import { WorkflowRuntime } from '../core/WorkflowRuntime';
-import type { RuntimeSnapshot } from '../core/WorkflowRuntime';
-import type { PlayerWorkflowDefinition, TransitionResult, ExpressionContext } from '@mindmatrix/player-core';
-
-export interface UseWorkflowOptions {
-  initialData?: Record<string, unknown>;
-  actionHandlers?: Record<string, (config: Record<string, unknown>, ctx: ExpressionContext) => void | Promise<void>>;
-  onTransition?: (result: TransitionResult) => void;
-}
-
-export interface WorkflowHandle {
-  slug: string;
-  currentState: string;
-  stateData: Record<string, unknown>;
-  memory: Record<string, unknown>;
-  status: 'ACTIVE' | 'COMPLETED' | 'CANCELLED';
-  availableTransitions: string[];
-  transition: (name: string, data?: Record<string, unknown>) => Promise<TransitionResult>;
-  setField: (field: string, value: unknown) => void;
-  setMemory: (key: string, value: unknown) => void;
-  publishEvent: (topic: string, payload?: Record<string, unknown>) => void;
-  runtime: WorkflowRuntime;
-}
-
-export function useWorkflow(definition: PlayerWorkflowDefinition, options?: UseWorkflowOptions): WorkflowHandle {
-  const runtime = useMemo(() => new WorkflowRuntime({
-    definition,
-    initialData: options?.initialData,
-    actionHandlers: options?.actionHandlers,
-  }), [definition.id]);
-
-  const [snapshot, setSnapshot] = useState<RuntimeSnapshot>(() => runtime.getSnapshot());
-
-  useEffect(() => {
-    const unsub = runtime.subscribe(setSnapshot);
-    return unsub;
-  }, [runtime]);
-
-  const transition = useCallback(async (name: string, data?: Record<string, unknown>) => {
-    const result = await runtime.transition(name, data);
-    options?.onTransition?.(result);
-    return result;
-  }, [runtime, options?.onTransition]);
-
-  const handle: WorkflowHandle = {
-    slug: definition.slug,
-    ...snapshot,
-    transition,
-    setField: runtime.setField.bind(runtime),
-    setMemory: runtime.setMemory.bind(runtime),
-    publishEvent: runtime.publishEvent.bind(runtime),
-    runtime,
-  };
-  return handle;
-}