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

package/src/hooks/useRouter.ts

@@ -1,347 +0,0 @@
-/**
- * useRouter — Client-side routing with nested routes, dynamic params, and route guards.
- *
- * Provides Next.js-style routing within workflow applications.
- * Supports dynamic segments (/ride/:id), nested routes, query params,
- * and guard functions for auth/permission checks before navigation.
- *
- * Usage in .workflow.tsx:
- *   const router = useRouter();
- *   router.push('/rides/abc123');
- *   router.push('/rides/abc123?tab=details');
- *
- *   // With guard
- *   const router = useRouter({
- *     guards: [requireAuth, requireRole('driver')],
- *   });
- */
-
-import { useState, useEffect, useCallback, useMemo, useRef } from 'react';
-
-// =============================================================================
-// Types
-// =============================================================================
-
-/** Route definition for configuring application routes. */
-export interface RouteDefinition {
-  /** URL path pattern (supports :param dynamic segments). */
-  path: string;
-  /** Route guard functions — must all return true to allow navigation. */
-  guards?: RouteGuard[];
-  /** Redirect path if guards fail. */
-  redirectOnFail?: string;
-  /** Nested child routes. */
-  children?: RouteDefinition[];
-  /** Metadata attached to the route. */
-  meta?: Record<string, unknown>;
-}
-
-/** Guard function that determines if navigation is allowed. */
-export type RouteGuard = (to: RouteLocation, from: RouteLocation | null) => boolean | Promise<boolean>;
-
-/** Represents a parsed route location. */
-export interface RouteLocation {
-  /** The full pathname (e.g., '/rides/abc123'). */
-  pathname: string;
-  /** Parsed dynamic params (e.g., { id: 'abc123' }). */
-  params: Record<string, string>;
-  /** Parsed query string params. */
-  query: Record<string, string>;
-  /** URL hash fragment (without #). */
-  hash: string;
-  /** The matched route definition, if any. */
-  matched?: RouteDefinition;
-  /** Route metadata from matched definition. */
-  meta: Record<string, unknown>;
-}
-
-/** Options for configuring the router. */
-export interface RouterOptions {
-  /** Route definitions for matching and guards. */
-  routes?: RouteDefinition[];
-  /** Global guards applied to every navigation. */
-  guards?: RouteGuard[];
-  /** Called when a guard blocks navigation. */
-  onGuardReject?: (to: RouteLocation) => void;
-  /** Base path prefix (e.g., '/app'). */
-  basePath?: string;
-}
-
-/** Router handle returned by useRouter. */
-export interface RouterHandle {
-  /** Current route location. */
-  location: RouteLocation;
-  /** Current pathname. */
-  pathname: string;
-  /** Current dynamic params. */
-  params: Record<string, string>;
-  /** Current query params. */
-  query: Record<string, string>;
-  /** Current hash. */
-  hash: string;
-  /** Navigate to a new path (pushState). */
-  push: (path: string) => Promise<boolean>;
-  /** Replace current path (replaceState). */
-  replace: (path: string) => Promise<boolean>;
-  /** Go back in history. */
-  back: () => void;
-  /** Go forward in history. */
-  forward: () => void;
-  /** Check if a path matches a pattern. */
-  isActive: (pattern: string) => boolean;
-  /** Whether a navigation is in progress (guards running). */
-  isNavigating: boolean;
-}
-
-// =============================================================================
-// Internal helpers
-// =============================================================================
-
-/** Parse a URL path into segments. */
-function parsePath(fullPath: string, basePath: string): { pathname: string; query: Record<string, string>; hash: string } {
-  let path = fullPath;
-
-  // Strip base path prefix
-  if (basePath && path.startsWith(basePath)) {
-    path = path.slice(basePath.length) || '/';
-  }
-
-  // Extract hash
-  const hashIdx = path.indexOf('#');
-  let hash = '';
-  if (hashIdx !== -1) {
-    hash = path.slice(hashIdx + 1);
-    path = path.slice(0, hashIdx);
-  }
-
-  // Extract query
-  const queryIdx = path.indexOf('?');
-  const query: Record<string, string> = {};
-  if (queryIdx !== -1) {
-    const qs = path.slice(queryIdx + 1);
-    path = path.slice(0, queryIdx);
-    for (const pair of qs.split('&')) {
-      const eqIdx = pair.indexOf('=');
-      if (eqIdx !== -1) {
-        query[decodeURIComponent(pair.slice(0, eqIdx))] = decodeURIComponent(pair.slice(eqIdx + 1));
-      } else if (pair) {
-        query[decodeURIComponent(pair)] = '';
-      }
-    }
-  }
-
-  return { pathname: path || '/', query, hash };
-}
-
-/** Match a path against a route pattern, extracting dynamic params. */
-function matchRoute(
-  pathname: string,
-  pattern: string,
-): { match: boolean; params: Record<string, string> } {
-  const pathParts = pathname.split('/').filter(Boolean);
-  const patternParts = pattern.split('/').filter(Boolean);
-
-  // Wildcard catch-all
-  if (patternParts[patternParts.length - 1] === '*') {
-    const staticParts = patternParts.slice(0, -1);
-    if (pathParts.length < staticParts.length) return { match: false, params: {} };
-    const params: Record<string, string> = {};
-    for (let i = 0; i < staticParts.length; i++) {
-      const pp = staticParts[i];
-      if (pp.startsWith(':')) {
-        params[pp.slice(1)] = pathParts[i];
-      } else if (pp !== pathParts[i]) {
-        return { match: false, params: {} };
-      }
-    }
-    params['*'] = pathParts.slice(staticParts.length).join('/');
-    return { match: true, params };
-  }
-
-  if (pathParts.length !== patternParts.length) return { match: false, params: {} };
-
-  const params: Record<string, string> = {};
-  for (let i = 0; i < patternParts.length; i++) {
-    const pp = patternParts[i];
-    if (pp.startsWith(':')) {
-      params[pp.slice(1)] = pathParts[i];
-    } else if (pp !== pathParts[i]) {
-      return { match: false, params: {} };
-    }
-  }
-
-  return { match: true, params };
-}
-
-/** Find a matching route definition (supports nested routes). */
-function findRoute(
-  pathname: string,
-  routes: RouteDefinition[],
-  parentPath: string = '',
-): { route: RouteDefinition; params: Record<string, string> } | null {
-  for (const route of routes) {
-    const fullPattern = parentPath + route.path;
-    const result = matchRoute(pathname, fullPattern);
-
-    if (result.match) {
-      return { route, params: result.params };
-    }
-
-    // Check children
-    if (route.children) {
-      const childResult = findRoute(pathname, route.children, fullPattern);
-      if (childResult) return childResult;
-    }
-  }
-
-  return null;
-}
-
-/** Build a RouteLocation from current browser state. */
-function buildLocation(basePath: string, routes: RouteDefinition[]): RouteLocation {
-  const { pathname, query, hash } = parsePath(
-    typeof window !== 'undefined' ? window.location.pathname + window.location.search + window.location.hash : '/',
-    basePath,
-  );
-
-  const found = findRoute(pathname, routes);
-
-  return {
-    pathname,
-    params: found?.params ?? {},
-    query,
-    hash,
-    matched: found?.route,
-    meta: found?.route?.meta ?? {},
-  };
-}
-
-// =============================================================================
-// Hook
-// =============================================================================
-
-/**
- * Client-side router with nested routes, dynamic params, and guards.
- *
- * @param options - Router configuration (routes, guards, basePath).
- * @returns Router handle with navigation methods and current location.
- */
-export function useRouter(options: RouterOptions = {}): RouterHandle {
-  const { routes = [], guards: globalGuards = [], onGuardReject, basePath = '' } = options;
-
-  const routesRef = useRef(routes);
-  routesRef.current = routes;
-  const guardsRef = useRef(globalGuards);
-  guardsRef.current = globalGuards;
-  const onRejectRef = useRef(onGuardReject);
-  onRejectRef.current = onGuardReject;
-  const basePathRef = useRef(basePath);
-  basePathRef.current = basePath;
-
-  const [location, setLocation] = useState<RouteLocation>(() =>
-    buildLocation(basePath, routes),
-  );
-  const [isNavigating, setIsNavigating] = useState(false);
-
-  // Listen to popstate (back/forward)
-  useEffect(() => {
-    const handler = () => {
-      setLocation(buildLocation(basePathRef.current, routesRef.current));
-    };
-    window.addEventListener('popstate', handler);
-    return () => window.removeEventListener('popstate', handler);
-  }, []);
-
-  const navigate = useCallback(
-    async (path: string, replace: boolean): Promise<boolean> => {
-      const { pathname, query, hash } = parsePath(path, basePathRef.current);
-      const found = findRoute(pathname, routesRef.current);
-
-      const to: RouteLocation = {
-        pathname,
-        params: found?.params ?? {},
-        query,
-        hash,
-        matched: found?.route,
-        meta: found?.route?.meta ?? {},
-      };
-
-      // Run guards
-      setIsNavigating(true);
-      try {
-        // Global guards
-        for (const guard of guardsRef.current) {
-          const allowed = await guard(to, location);
-          if (!allowed) {
-            onRejectRef.current?.(to);
-            return false;
-          }
-        }
-
-        // Route-specific guards
-        if (found?.route?.guards) {
-          for (const guard of found.route.guards) {
-            const allowed = await guard(to, location);
-            if (!allowed) {
-              if (found.route.redirectOnFail) {
-                const fullRedirect = basePathRef.current + found.route.redirectOnFail;
-                window.history.pushState(null, '', fullRedirect);
-                setLocation(buildLocation(basePathRef.current, routesRef.current));
-              }
-              onRejectRef.current?.(to);
-              return false;
-            }
-          }
-        }
-
-        // Navigate
-        const fullPath = basePathRef.current + path;
-        if (replace) {
-          window.history.replaceState(null, '', fullPath);
-        } else {
-          window.history.pushState(null, '', fullPath);
-        }
-        setLocation(to);
-        return true;
-      } finally {
-        setIsNavigating(false);
-      }
-    },
-    [location],
-  );
-
-  const push = useCallback((path: string) => navigate(path, false), [navigate]);
-  const replace = useCallback((path: string) => navigate(path, true), [navigate]);
-
-  const back = useCallback(() => {
-    window.history.back();
-  }, []);
-
-  const forward = useCallback(() => {
-    window.history.forward();
-  }, []);
-
-  const isActive = useCallback(
-    (pattern: string) => {
-      return matchRoute(location.pathname, pattern).match;
-    },
-    [location.pathname],
-  );
-
-  return useMemo(
-    (): RouterHandle => ({
-      location,
-      pathname: location.pathname,
-      params: location.params,
-      query: location.query,
-      hash: location.hash,
-      push,
-      replace,
-      back,
-      forward,
-      isActive,
-      isNavigating,
-    }),
-    [location, push, replace, back, forward, isActive, isNavigating],
-  );
-}

package/src/hooks/useServerAction.ts

@@ -1,178 +0,0 @@
-/**
- * useServerAction — invoke server-side workflow actions from .workflow.tsx.
- *
- * Registers a named action that POSTs to the Rust API for server-side execution.
- * Handles loading, error, and optimistic state.
- *
- * Usage in .workflow.tsx:
- *   const approve = useServerAction('approve-order', {
- *     instanceId: orderId,
- *     onSuccess: () => refetch(),
- *   });
- *
- *   <Button onClick={() => approve.execute({ comment: 'Looks good' })}>
- *     {approve.loading ? 'Approving...' : 'Approve'}
- *   </Button>
- *
- * The compiler extracts this as a server action dependency in the IR.
- * At runtime, the hook POSTs to /api/v1/workflow/instances/{id}/actions/{name}.
- */
-
-import { useState, useCallback, useRef } from 'react';
-
-// =============================================================================
-// Types
-// =============================================================================
-
-export interface ServerActionOptions {
-  /** The workflow instance ID to execute the action against. */
-  instanceId: string;
-  /** Optional definition ID — when present, uses the path-param endpoint. */
-  definitionId?: string;
-  /** Called after a successful action execution. */
-  onSuccess?: (result: ServerActionResult) => void;
-  /** Called after a failed action execution. */
-  onError?: (error: Error) => void;
-}
-
-export interface ServerActionResult {
-  success: boolean;
-  action_id: string;
-  action_type?: string;
-  triggered_by?: string;
-  data?: Record<string, unknown>;
-}
-
-export interface ServerActionHandle {
-  /** Execute the server action with optional input payload. */
-  execute: (input?: Record<string, unknown>) => Promise<ServerActionResult>;
-  /** Whether the action is currently executing. */
-  loading: boolean;
-  /** Error from the last execution attempt. */
-  error: Error | null;
-  /** Result from the last successful execution. */
-  result: ServerActionResult | null;
-  /** Reset error and result state. */
-  reset: () => void;
-}
-
-/**
- * Resolver interface — the runtime must provide an implementation.
- * Typically set by WorkflowProvider or a top-level setup call.
- */
-export interface ServerActionResolver {
-  executeAction: (
-    instanceId: string,
-    actionName: string,
-    input?: Record<string, unknown>,
-    definitionId?: string,
-  ) => Promise<ServerActionResult>;
-}
-
-// Global resolver (set by provider)
-let _globalServerActionResolver: ServerActionResolver | null = null;
-
-export function setServerActionResolver(resolver: ServerActionResolver | null): void {
-  _globalServerActionResolver = resolver;
-}
-
-/**
- * Default resolver that POSTs to the Rust API.
- * Used when no custom resolver is configured.
- */
-function getDefaultResolver(): ServerActionResolver {
-  return {
-    async executeAction(instanceId, actionName, input, definitionId) {
-      const token = typeof localStorage !== 'undefined'
-        ? localStorage.getItem('auth_token')
-        : null;
-
-      // Use path-param endpoint when definitionId is provided
-      const url = definitionId
-        ? `/api/v1/workflow/server-actions/${encodeURIComponent(definitionId)}/${encodeURIComponent(actionName)}`
-        : `/api/v1/workflow/instances/${encodeURIComponent(instanceId)}/actions/${encodeURIComponent(actionName)}`;
-
-      const body = definitionId
-        ? JSON.stringify({ instance_id: instanceId || undefined, payload: input })
-        : input ? JSON.stringify(input) : undefined;
-
-      const res = await fetch(url, {
-        method: 'POST',
-        headers: {
-          'Content-Type': 'application/json',
-          ...(token ? { Authorization: `Bearer ${token}` } : {}),
-        },
-        body,
-      });
-
-      if (!res.ok) {
-        const errBody = await res.json().catch(() => ({ message: res.statusText }));
-        throw new Error(errBody.message || errBody.error || `Server action failed: ${res.status}`);
-      }
-
-      return res.json();
-    },
-  };
-}
-
-// =============================================================================
-// Hook
-// =============================================================================
-
-/**
- * Registers a server-side action and returns a callable handle.
- *
- * @param actionName - The action identifier (matches pending_actions or transition name).
- * @param options - Instance ID and optional callbacks.
- * @returns Handle with execute(), loading, error, and result.
- */
-export function useServerAction(
-  actionName: string,
-  options: ServerActionOptions,
-): ServerActionHandle {
-  const [loading, setLoading] = useState(false);
-  const [error, setError] = useState<Error | null>(null);
-  const [result, setResult] = useState<ServerActionResult | null>(null);
-
-  const optionsRef = useRef(options);
-  optionsRef.current = options;
-
-  const execute = useCallback(
-    async (input?: Record<string, unknown>): Promise<ServerActionResult> => {
-      const resolver = _globalServerActionResolver || getDefaultResolver();
-      const { instanceId, definitionId, onSuccess, onError } = optionsRef.current;
-
-      try {
-        setLoading(true);
-        setError(null);
-
-        const actionResult = await resolver.executeAction(instanceId, actionName, input, definitionId);
-        setResult(actionResult);
-        onSuccess?.(actionResult);
-        return actionResult;
-      } catch (err) {
-        const e = err instanceof Error ? err : new Error(String(err));
-        setError(e);
-        onError?.(e);
-        throw e;
-      } finally {
-        setLoading(false);
-      }
-    },
-    [actionName],
-  );
-
-  const reset = useCallback(() => {
-    setError(null);
-    setResult(null);
-  }, []);
-
-  const handle: ServerActionHandle = {
-    execute,
-    loading,
-    error,
-    result,
-    reset,
-  };
-  return handle;
-}