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

package/src/hooks/useModule.ts

@@ -1,59 +0,0 @@
-/**
- * useModule — Load and configure a module dependency.
- *
- * Modules are self-contained blueprints that provide their own routes, models,
- * and UI. useModule registers the module's routes and slot contributions at
- * runtime, and passes configuration to the module's config model.
- *
- * The module's views are rendered via the Router when their routes match.
- * Cross-module communication happens via:
- * - Slots: module contributes views to named slots in the parent app
- * - Data queries: parent can useQuery() on module's models
- * - Guards: route guards reference shared context (e.g. context.actor_id)
- */
-
-import { useMemo } from 'react';
-
-export interface UseModuleOptions {
-  /** Whether the module is enabled (default: true) */
-  enabled?: boolean;
-}
-
-export interface ModuleHandle {
-  /** The module slug */
-  slug: string;
-  /** Configuration passed to the module */
-  config: Record<string, unknown>;
-  /** Whether the module is loaded */
-  isLoaded: boolean;
-}
-
-/**
- * Load a module dependency and pass configuration to it.
- *
- * @param slug - The module's slug (e.g. 'mod-authentication')
- * @param config - Configuration values passed to the module (merged with defaults from configSchema)
- * @param options - Additional options
- *
- * @example
- * ```tsx
- * const auth = useModule('mod-authentication', {
- *   appName: 'My App',
- *   layout: 'card',
- *   redirectPath: '/',
- * });
- * ```
- */
-export function useModule(
-  slug: string,
-  config: Record<string, unknown> = {},
-  options: UseModuleOptions = {},
-): ModuleHandle {
-  const { enabled = true } = options;
-
-  return useMemo(() => ({
-    slug,
-    config,
-    isLoaded: enabled,
-  }), [slug, enabled]);
-}

package/src/hooks/useModuleConfig.ts

@@ -1,61 +0,0 @@
-/**
- * useModuleConfig — Read merged module configuration.
- *
- * Merges configSchema.defaults with install-time config overrides.
- * Works both inside and outside a module boundary:
- * - Inside: reads from ModuleContext (no slug needed)
- * - Outside: requires explicit slug, reads from parent's installed_modules metadata
- */
-
-import { useMemo } from 'react';
-
-/**
- * Installed module reference stored in parent definition metadata.
- * This matches the shape written by handleInstallModule in GlassConsoleShell.
- */
-export interface InstalledModuleRef {
-  slug: string;
-  moduleId: string;
-  version?: string;
-  installedAt?: string;
-  config?: Record<string, unknown>;
-  childSlugs?: string[];
-  routeConfig?: { prefix?: string; routes?: Record<string, string | false> };
-  slotMapping?: Record<string, string>;
-}
-
-/** Store for installed modules — populated at runtime by the editor/player */
-let installedModulesStore: InstalledModuleRef[] = [];
-let configDefaultsStore: Map<string, Record<string, unknown>> = new Map();
-
-/** Set the installed modules list (called by editor/player on load) */
-export function setInstalledModules(modules: InstalledModuleRef[]): void {
-  installedModulesStore = modules;
-}
-
-/** Set config defaults for a module (from configSchema.defaults in manifest) */
-export function setModuleConfigDefaults(moduleSlug: string, defaults: Record<string, unknown>): void {
-  configDefaultsStore.set(moduleSlug, defaults);
-}
-
-/** Get the installed module ref by slug */
-export function getInstalledModule(slug: string): InstalledModuleRef | undefined {
-  return installedModulesStore.find(m => m.slug === slug);
-}
-
-/** Get all installed modules */
-export function getInstalledModules(): InstalledModuleRef[] {
-  return installedModulesStore;
-}
-
-/**
- * Read the merged configuration for a module.
- * Merges: configSchema.defaults ← install-time config
- */
-export function useModuleConfig(moduleSlug: string): Record<string, unknown> {
-  return useMemo(() => {
-    const installed = getInstalledModule(moduleSlug);
-    const defaults = configDefaultsStore.get(moduleSlug) ?? {};
-    return { ...defaults, ...installed?.config };
-  }, [moduleSlug]);
-}

package/src/hooks/useMutation.ts

@@ -1,237 +0,0 @@
-/**
- * useMutation — imperative mutation hook for workflow instances.
- *
- * Provides create, update, and transition operations against the workflow engine.
- *
- * Usage in .workflow.tsx:
- *   const mutation = useMutation('channel');
- *
- *   // Create a new instance
- *   const id = await mutation.create({ name: 'General', isPublic: true });
- *
- *   // Update fields
- *   await mutation.update(id, { name: 'Updated Name' });
- *
- *   // Fire a transition
- *   await mutation.transition(id, 'activate');
- *
- * The compiler extracts useMutation calls as action stubs in the IR.
- * The runtime resolves them via the configured mutation adapter.
- */
-
-import { useState, useCallback, useRef } from 'react';
-import type { ModelDefinition } from '../config/defineModel';
-import type { InferFields, InferTransitions } from '../types/workflow-inference';
-
-// =============================================================================
-// Types
-// =============================================================================
-
-/** Typed mutation handle — field names and transition names are constrained. */
-export interface TypedMutationHandle<Fields, Transitions extends string> {
-  /** Create a new workflow instance. Returns the instance ID. */
-  create: (input?: Partial<Fields>) => Promise<string>;
-  /** Update fields on an existing instance. */
-  update: (instanceId: string, fields: Partial<Fields>) => Promise<void>;
-  /** Fire a transition on an instance. */
-  transition: (instanceId: string, transitionName: Transitions, input?: Record<string, unknown>) => Promise<void>;
-  /** Fire a transition on an instance (alias for transition). */
-  trigger: (instanceId: string, transitionName: Transitions, input?: Record<string, unknown>) => Promise<void>;
-  /**
-   * Advance to the next state automatically.
-   * The engine evaluates all outgoing transitions from the current state
-   * and fires the first one whose conditions are satisfied (evaluated in definition order).
-   * If only one outgoing transition exists, it fires unconditionally.
-   */
-  next: (instanceId: string, input?: Record<string, unknown>) => Promise<void>;
-  /** Delete an instance. */
-  remove: (instanceId: string) => Promise<void>;
-  /** Whether any mutation is currently in progress. */
-  isPending: boolean;
-  /** Error from the last mutation attempt. */
-  error: Error | null;
-  /** Reset the error state. */
-  reset: () => void;
-}
-
-export interface MutationHandle {
-  /** Create a new workflow instance. Returns the instance ID. */
-  create: (input?: Record<string, unknown>) => Promise<string>;
-  /** Update fields on an existing instance. */
-  update: (instanceId: string, fields: Record<string, unknown>) => Promise<void>;
-  /** Fire a transition on an instance. */
-  transition: (instanceId: string, transitionName: string, input?: Record<string, unknown>) => Promise<void>;
-  /** Fire a transition on an instance (alias for transition). */
-  trigger: (instanceId: string, transitionName: string, input?: Record<string, unknown>) => Promise<void>;
-  /**
-   * Advance to the next state automatically.
-   * The engine evaluates all outgoing transitions from the current state
-   * and fires the first one whose conditions are satisfied (evaluated in definition order).
-   * If only one outgoing transition exists, it fires unconditionally.
-   */
-  next: (instanceId: string, input?: Record<string, unknown>) => Promise<void>;
-  /** Delete an instance. */
-  remove: (instanceId: string) => Promise<void>;
-  /** Whether any mutation is currently in progress. */
-  isPending: boolean;
-  /** Error from the last mutation attempt. */
-  error: Error | null;
-  /** Reset the error state. */
-  reset: () => void;
-}
-
-/**
- * Mutation resolver interface — the runtime must provide an implementation.
- */
-export interface MutationResolver {
-  create: (slug: string, input?: Record<string, unknown>) => Promise<string>;
-  update: (slug: string, instanceId: string, fields: Record<string, unknown>) => Promise<void>;
-  transition: (slug: string, instanceId: string, transitionName: string, input?: Record<string, unknown>) => Promise<void>;
-  /** Advance to next state. The engine picks the first valid outgoing transition. */
-  next?: (slug: string, instanceId: string, input?: Record<string, unknown>) => Promise<void>;
-  remove: (slug: string, instanceId: string) => Promise<void>;
-}
-
-// Global resolver (set by provider)
-let _globalMutationResolver: MutationResolver | null = null;
-
-export function setMutationResolver(resolver: MutationResolver | null): void {
-  _globalMutationResolver = resolver;
-}
-
-// =============================================================================
-// Hook
-// =============================================================================
-
-/**
- * Provides mutation operations for a workflow definition.
- *
- * Overload 1: Type-safe — pass a model definition for typed transitions.
- * Overload 2: String slug — backward-compatible, untyped.
- *
- * @example
- * ```tsx
- * // Typed (recommended)
- * import channelModel from '../models/channel';
- * const mutation = useMutation(channelModel);
- * mutation.trigger(id, 'activate');     // ✓ valid
- * mutation.trigger(id, 'nonexistent');  // ✗ TS error
- *
- * // Untyped (backward compatible)
- * const mutation = useMutation('chat-channel');
- * ```
- */
-export function useMutation<D extends ModelDefinition>(
-  definition: D,
-): TypedMutationHandle<InferFields<D>, InferTransitions<D> & string>;
-export function useMutation(slug: string): MutationHandle;
-export function useMutation(slugOrDef: string | ModelDefinition): MutationHandle {
-  const slug = typeof slugOrDef === 'string' ? slugOrDef : slugOrDef.slug;
-  const [isPending, setIsPending] = useState(false);
-  const [error, setError] = useState<Error | null>(null);
-  const slugRef = useRef(slug);
-  slugRef.current = slug;
-
-  const getResolver = useCallback((): MutationResolver => {
-    const resolver = _globalMutationResolver;
-    if (!resolver) {
-      throw new Error(`useMutation: No mutation resolver configured. Wrap your app in a WorkflowProvider.`);
-    }
-    return resolver;
-  }, []);
-
-  const create = useCallback(async (input?: Record<string, unknown>): Promise<string> => {
-    try {
-      setIsPending(true);
-      setError(null);
-      const resolver = getResolver();
-      return await resolver.create(slugRef.current, input);
-    } catch (err) {
-      const e = err instanceof Error ? err : new Error(String(err));
-      setError(e);
-      throw e;
-    } finally {
-      setIsPending(false);
-    }
-  }, [getResolver]);
-
-  const update = useCallback(async (instanceId: string, fields: Record<string, unknown>): Promise<void> => {
-    try {
-      setIsPending(true);
-      setError(null);
-      const resolver = getResolver();
-      await resolver.update(slugRef.current, instanceId, fields);
-    } catch (err) {
-      const e = err instanceof Error ? err : new Error(String(err));
-      setError(e);
-      throw e;
-    } finally {
-      setIsPending(false);
-    }
-  }, [getResolver]);
-
-  const transitionFn = useCallback(async (instanceId: string, transitionName: string, input?: Record<string, unknown>): Promise<void> => {
-    try {
-      setIsPending(true);
-      setError(null);
-      const resolver = getResolver();
-      await resolver.transition(slugRef.current, instanceId, transitionName, input);
-    } catch (err) {
-      const e = err instanceof Error ? err : new Error(String(err));
-      setError(e);
-      throw e;
-    } finally {
-      setIsPending(false);
-    }
-  }, [getResolver]);
-
-  const next = useCallback(async (instanceId: string, input?: Record<string, unknown>): Promise<void> => {
-    try {
-      setIsPending(true);
-      setError(null);
-      const resolver = getResolver();
-      if (resolver.next) {
-        await resolver.next(slugRef.current, instanceId, input);
-      } else {
-        // Fallback: transition with special '__next__' name — engine resolves it
-        await resolver.transition(slugRef.current, instanceId, '__next__', input);
-      }
-    } catch (err) {
-      const e = err instanceof Error ? err : new Error(String(err));
-      setError(e);
-      throw e;
-    } finally {
-      setIsPending(false);
-    }
-  }, [getResolver]);
-
-  const remove = useCallback(async (instanceId: string): Promise<void> => {
-    try {
-      setIsPending(true);
-      setError(null);
-      const resolver = getResolver();
-      await resolver.remove(slugRef.current, instanceId);
-    } catch (err) {
-      const e = err instanceof Error ? err : new Error(String(err));
-      setError(e);
-      throw e;
-    } finally {
-      setIsPending(false);
-    }
-  }, [getResolver]);
-
-  const reset = useCallback(() => setError(null), []);
-
-  const handle: MutationHandle = {
-    create,
-    update,
-    transition: transitionFn,
-    trigger: transitionFn,
-    next,
-    remove,
-    isPending,
-    error,
-    reset,
-  };
-  return handle;
-}

package/src/hooks/useNotification.ts

@@ -1,151 +0,0 @@
-/**
- * useNotification — Push notification hook for workflow applications.
- *
- * Wraps the browser Notification API with permission management
- * and a React-friendly interface.
- *
- * Usage in .workflow.tsx:
- *   const { notify, permission, requestPermission, supported } = useNotification();
- *
- *   // Request permission on first use
- *   if (permission === 'default') {
- *     await requestPermission();
- *   }
- *
- *   // Send notification when ride arrives
- *   useOnChange('rideStatus', (status) => {
- *     if (status === 'arrived') {
- *       notify('Your ride has arrived!', {
- *         body: 'Your driver is waiting outside.',
- *         icon: '/icons/car.png',
- *       });
- *     }
- *   });
- */
-
-import { useState, useCallback, useEffect, useMemo } from 'react';
-
-// =============================================================================
-// Types
-// =============================================================================
-
-/** Notification options (mirrors the browser Notification API). */
-export interface NotifyOptions {
-  /** Notification body text. */
-  body?: string;
-  /** Notification icon URL. */
-  icon?: string;
-  /** Badge icon URL (for mobile). */
-  badge?: string;
-  /** Notification image URL. */
-  image?: string;
-  /** Notification tag (for grouping/replacing). */
-  tag?: string;
-  /** Whether to require user interaction to dismiss. */
-  requireInteraction?: boolean;
-  /** Vibration pattern (ms array). */
-  vibrate?: number[];
-  /** Auto-close after ms (default: 5000, 0 = no auto-close). */
-  autoClose?: number;
-  /** Data payload attached to the notification. */
-  data?: unknown;
-  /** Click handler. */
-  onClick?: (notification: Notification) => void;
-  /** Close handler. */
-  onClose?: () => void;
-  /** Error handler. */
-  onError?: (error: Error) => void;
-}
-
-/** Notification result returned by useNotification. */
-export interface NotificationResult {
-  /** Current permission state: 'default' | 'granted' | 'denied'. */
-  permission: NotificationPermission;
-  /** Whether the browser supports notifications. */
-  supported: boolean;
-  /** Request notification permission from the user. */
-  requestPermission: () => Promise<NotificationPermission>;
-  /** Show a notification. Returns the Notification instance (or null if not permitted). */
-  notify: (title: string, options?: NotifyOptions) => Notification | null;
-}
-
-// =============================================================================
-// Hook
-// =============================================================================
-
-/**
- * Push notification management via the browser Notification API.
- *
- * @returns Notification handle with permission state and notify method.
- */
-export function useNotification(): NotificationResult {
-  const supported = typeof window !== 'undefined' && 'Notification' in window;
-
-  const [permission, setPermission] = useState<NotificationPermission>(
-    supported ? Notification.permission : 'denied',
-  );
-
-  // Sync permission state (can change externally)
-  useEffect(() => {
-    if (!supported) return;
-
-    const interval = setInterval(() => {
-      if (Notification.permission !== permission) {
-        setPermission(Notification.permission);
-      }
-    }, 1000);
-
-    return () => clearInterval(interval);
-  }, [supported, permission]);
-
-  const requestPermission = useCallback(async (): Promise<NotificationPermission> => {
-    if (!supported) return 'denied';
-
-    const result = await Notification.requestPermission();
-    setPermission(result);
-    return result;
-  }, [supported]);
-
-  const notify = useCallback(
-    (title: string, options: NotifyOptions = {}): Notification | null => {
-      if (!supported || permission !== 'granted') return null;
-
-      const {
-        onClick,
-        onClose,
-        onError,
-        autoClose = 5000,
-        ...notificationOptions
-      } = options;
-
-      try {
-        const notification = new Notification(title, notificationOptions);
-
-        if (onClick) {
-          notification.onclick = () => onClick(notification);
-        }
-        if (onClose) {
-          notification.onclose = onClose;
-        }
-        if (onError) {
-          notification.onerror = () => onError(new Error('Notification error'));
-        }
-
-        if (autoClose > 0) {
-          setTimeout(() => notification.close(), autoClose);
-        }
-
-        return notification;
-      } catch (err) {
-        options.onError?.(err instanceof Error ? err : new Error(String(err)));
-        return null;
-      }
-    },
-    [supported, permission],
-  );
-
-  return useMemo(
-    (): NotificationResult => ({ permission, supported, requestPermission, notify }),
-    [permission, supported, requestPermission, notify],
-  );
-}

package/src/hooks/useOnChange.ts

@@ -1,30 +0,0 @@
-/**
- * useOnChange — React to state data field changes
- *
- * Runs handler when a specific field in stateData changes.
- * Provides both newValue and oldValue to the handler.
- */
-
-import { useEffect, useRef } from 'react';
-import { useRuntimeContext } from '../providers/RuntimeContext';
-
-export function useOnChange(
-  field: string,
-  handler: (newValue: unknown, oldValue: unknown) => void | Promise<void>
-): void {
-  const runtime = useRuntimeContext();
-  const handlerRef = useRef(handler);
-  handlerRef.current = handler;
-  const prevRef = useRef<unknown>(runtime.sm.stateData[field]);
-
-  useEffect(() => {
-    const unsub = runtime.subscribe((snap) => {
-      const newVal = snap.stateData[field];
-      if (newVal !== prevRef.current) {
-        handlerRef.current(newVal, prevRef.current);
-        prevRef.current = newVal;
-      }
-    });
-    return unsub;
-  }, [runtime, field]);
-}

package/src/hooks/useOnEnter.ts

@@ -1,59 +0,0 @@
-/**
- * useOnEnter — Fire effect when entering a state
- *
- * Runs effect when the workflow enters the specified state(s).
- * If already in the target state, fires immediately.
- * Cleanup fires when exiting the state.
- */
-
-import { useEffect, useRef } from 'react';
-import { useRuntimeContext } from '../providers/RuntimeContext';
-
-type EffectCleanup = void | (() => void);
-type EffectCallback = () => EffectCleanup | Promise<EffectCleanup>;
-
-export function useOnEnter(stateName: string | string[], effect: EffectCallback): void {
-  const runtime = useRuntimeContext();
-  const effectRef = useRef(effect);
-  effectRef.current = effect;
-  const cleanupRef = useRef<(() => void) | null>(null);
-  const states = Array.isArray(stateName) ? stateName : [stateName];
-
-  useEffect(() => {
-    // If already in target state, fire immediately
-    if (states.includes(runtime.sm.currentState)) {
-      const result = effectRef.current();
-      if (result instanceof Promise) {
-        result.then(cleanup => {
-          if (cleanup && typeof cleanup === 'function') cleanupRef.current = cleanup;
-        });
-      } else if (result && typeof result === 'function') {
-        cleanupRef.current = result;
-      }
-    }
-
-    const unsub = runtime.sm.on((event) => {
-      if (event.type === 'state_enter' && event.to_state && states.includes(event.to_state)) {
-        // Cleanup previous if re-entering
-        cleanupRef.current?.();
-        const result = effectRef.current();
-        if (result instanceof Promise) {
-          result.then(cleanup => {
-            if (cleanup && typeof cleanup === 'function') cleanupRef.current = cleanup;
-          });
-        } else if (result && typeof result === 'function') {
-          cleanupRef.current = result;
-        }
-      }
-      if (event.type === 'state_exit' && event.from_state && states.includes(event.from_state)) {
-        cleanupRef.current?.();
-        cleanupRef.current = null;
-      }
-    });
-
-    return () => {
-      unsub();
-      cleanupRef.current?.();
-    };
-  }, [runtime, ...states]);
-}

package/src/hooks/useOnEvent.ts

@@ -1,37 +0,0 @@
-/**
- * useOnEvent — Subscribe to EventBus events with optional state filtering
- *
- * Runs handler when events matching the pattern are emitted.
- * Optionally filters events to only fire while in a specific state.
- */
-
-import { useEffect, useRef } from 'react';
-import { useRuntimeContext } from '../providers/RuntimeContext';
-
-export interface EventPayload {
-  topic: string;
-  payload?: Record<string, unknown>;
-}
-
-export interface UseOnEventOptions {
-  while?: string;
-}
-
-export function useOnEvent(
-  pattern: string,
-  handler: (event: EventPayload) => void | Promise<void>,
-  options?: UseOnEventOptions
-): void {
-  const runtime = useRuntimeContext();
-  const handlerRef = useRef(handler);
-  handlerRef.current = handler;
-
-  useEffect(() => {
-    const unsub = runtime.eventBus.subscribe(pattern, (event) => {
-      // If { while: state } option, only fire when in that state
-      if (options?.while && runtime.sm.currentState !== options.while) return;
-      handlerRef.current(event);
-    });
-    return unsub;
-  }, [runtime, pattern, options?.while]);
-}

package/src/hooks/useOnExit.ts

@@ -1,27 +0,0 @@
-/**
- * useOnExit — Fire effect when exiting a state
- *
- * Runs effect when the workflow exits the specified state(s).
- */
-
-import { useEffect, useRef } from 'react';
-import { useRuntimeContext } from '../providers/RuntimeContext';
-
-type EffectCallback = () => void | Promise<void>;
-
-export function useOnExit(stateName: string | string[], effect: EffectCallback): void {
-  const runtime = useRuntimeContext();
-  const effectRef = useRef(effect);
-  effectRef.current = effect;
-  const states = Array.isArray(stateName) ? stateName : [stateName];
-
-  useEffect(() => {
-    const unsub = runtime.sm.on((event) => {
-      if (event.type === 'state_exit' && event.from_state && states.includes(event.from_state)) {
-        effectRef.current();
-      }
-    });
-
-    return unsub;
-  }, [runtime, ...states]);
-}

package/src/hooks/useOnTransition.ts

@@ -1,30 +0,0 @@
-/**
- * useOnTransition — Fire effect on any state transition
- *
- * Runs effect whenever a transition occurs.
- * Receives { from, to } as parameters.
- */
-
-import { useEffect, useRef } from 'react';
-import { useRuntimeContext } from '../providers/RuntimeContext';
-
-type TransitionCallback = (transition: { from?: string; to?: string }) => void | Promise<void>;
-
-export function useOnTransition(effect: TransitionCallback): void {
-  const runtime = useRuntimeContext();
-  const effectRef = useRef(effect);
-  effectRef.current = effect;
-
-  useEffect(() => {
-    const unsub = runtime.sm.on((event) => {
-      if (event.type === 'transition') {
-        effectRef.current({
-          from: event.from_state,
-          to: event.to_state,
-        });
-      }
-    });
-
-    return unsub;
-  }, [runtime]);
-}