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

package/src/hooks/useRealtimeQuery.ts

@@ -1,222 +0,0 @@
-/**
- * useRealtimeQuery — Reactive data fetching with SSE live updates.
- *
- * Wraps useQuery with a Server-Sent Events subscription for real-time
- * data updates. When the server pushes an event matching the slug,
- * the query automatically refetches.
- *
- * Critical for ride tracking, driver location, order status, etc.
- *
- * Usage in .workflow.tsx:
- *   const { data: rides, loading, connected } = useRealtimeQuery('ride', {
- *     state: 'in_progress',
- *     filter: { driver_id: currentUser.id },
- *   });
- */
-
-import { useState, useEffect, useCallback, useRef } from 'react';
-import type { QueryParams, QueryResult, WorkflowInstance } from './useQuery';
-
-// =============================================================================
-// Types
-// =============================================================================
-
-export interface RealtimeQueryParams extends QueryParams {
-  /** SSE event channel to listen on (defaults to slug). */
-  channel?: string;
-  /** SSE endpoint URL (defaults to /api/v1/workflow/events). */
-  sseUrl?: string;
-  /** Auto-reconnect on disconnect. */
-  reconnect?: boolean;
-  /** Reconnect delay in ms (default: 3000). */
-  reconnectDelay?: number;
-  /** Debounce refetch on rapid events (ms, default: 100). */
-  debounce?: number;
-}
-
-export interface RealtimeQueryResult<T> extends QueryResult<T> {
-  /** Whether the SSE connection is active. */
-  connected: boolean;
-  /** Force reconnect the SSE stream. */
-  reconnect: () => void;
-}
-
-// Re-use the global query resolver from useQuery
-interface InternalQueryResolver {
-  query: <T>(slug: string, params: QueryParams) => Promise<{ data: T[]; total?: number }>;
-}
-
-let _queryResolver: InternalQueryResolver | null = null;
-
-export function setRealtimeQueryResolver(resolver: InternalQueryResolver | null): void {
-  _queryResolver = resolver;
-}
-
-// =============================================================================
-// Internal
-// =============================================================================
-
-function getToken(): string | null {
-  return typeof localStorage !== 'undefined' ? localStorage.getItem('auth_token') : null;
-}
-
-// =============================================================================
-// Hook
-// =============================================================================
-
-/**
- * Fetches workflow instances with real-time SSE updates.
- *
- * @param slug - Workflow definition slug to query.
- * @param params - Query params + SSE configuration.
- * @returns Query result with connected status and reconnect.
- */
-export function useRealtimeQuery<T = Record<string, unknown>>(
-  slug: string,
-  params: RealtimeQueryParams = {},
-): RealtimeQueryResult<T> {
-  const {
-    channel,
-    sseUrl,
-    reconnect: autoReconnect = true,
-    reconnectDelay = 3000,
-    debounce = 100,
-    enabled,
-    ...queryParams
-  } = params;
-
-  const [data, setData] = useState<WorkflowInstance<T>[]>([]);
-  const [loading, setLoading] = useState(true);
-  const [error, setError] = useState<Error | null>(null);
-  const [total, setTotal] = useState<number | undefined>(undefined);
-  const [connected, setConnected] = useState(false);
-  const [reconnectKey, setReconnectKey] = useState(0);
-
-  const queryParamsRef = useRef(queryParams);
-  queryParamsRef.current = queryParams;
-  const debounceRef = useRef<ReturnType<typeof setTimeout> | null>(null);
-
-  // Fetch data from resolver
-  const fetchData = useCallback(async () => {
-    if (enabled === false) {
-      setLoading(false);
-      return;
-    }
-
-    const resolver = _queryResolver;
-    if (!resolver) {
-      setError(new Error('useRealtimeQuery: No query resolver configured.'));
-      setLoading(false);
-      return;
-    }
-
-    try {
-      setLoading(true);
-      setError(null);
-      const result = await resolver.query<WorkflowInstance<T>>(slug, queryParamsRef.current);
-      setData(result.data);
-      setTotal(result.total);
-    } catch (err) {
-      setError(err instanceof Error ? err : new Error(String(err)));
-    } finally {
-      setLoading(false);
-    }
-  }, [slug, enabled]);
-
-  // Initial fetch
-  useEffect(() => {
-    fetchData();
-  }, [fetchData]);
-
-  // SSE subscription for live updates
-  useEffect(() => {
-    if (enabled === false) return;
-
-    const token = getToken();
-    if (!token) return;
-
-    const eventChannel = channel ?? slug;
-    const url = sseUrl ?? `/api/v1/workflow/events?token=${encodeURIComponent(token)}`;
-
-    let es: EventSource | null = null;
-    let reconnectTimer: ReturnType<typeof setTimeout> | null = null;
-
-    const connect = () => {
-      es = new EventSource(url);
-
-      es.addEventListener('connected', () => {
-        setConnected(true);
-        setError(null);
-      });
-
-      // Listen for events that match our channel/slug
-      const relevantEvents = [
-        'workflow:transitioned',
-        'workflow:data_updated',
-        'workflow:instance_created',
-        'workflow:instance_deleted',
-        'workflow:state_changed',
-      ];
-
-      for (const eventType of relevantEvents) {
-        es.addEventListener(eventType, (e: Event) => {
-          const messageEvent = e as MessageEvent;
-          try {
-            const eventData = JSON.parse(messageEvent.data);
-            // Filter: only process events matching our slug/channel
-            if (
-              eventData.definition_slug === eventChannel ||
-              eventData.slug === eventChannel ||
-              eventData.channel === eventChannel
-            ) {
-              // Debounced refetch
-              if (debounceRef.current) clearTimeout(debounceRef.current);
-              debounceRef.current = setTimeout(() => {
-                fetchData();
-              }, debounce);
-            }
-          } catch {
-            // Ignore parse errors
-          }
-        });
-      }
-
-      es.onerror = () => {
-        setConnected(false);
-        es?.close();
-        es = null;
-
-        if (autoReconnect) {
-          reconnectTimer = setTimeout(connect, reconnectDelay);
-        }
-      };
-    };
-
-    connect();
-
-    return () => {
-      es?.close();
-      if (reconnectTimer) clearTimeout(reconnectTimer);
-      if (debounceRef.current) clearTimeout(debounceRef.current);
-      setConnected(false);
-    };
-  }, [slug, channel, sseUrl, enabled, autoReconnect, reconnectDelay, debounce, fetchData, reconnectKey]);
-
-  const forceReconnect = useCallback(() => {
-    setReconnectKey((k) => k + 1);
-  }, []);
-
-  const hasMore = total !== undefined && data.length < total;
-
-  const handle: RealtimeQueryResult<T> = {
-    data,
-    loading,
-    error,
-    refetch: fetchData,
-    total,
-    hasMore,
-    connected,
-    reconnect: forceReconnect,
-  };
-  return handle;
-}

package/src/hooks/useRole.ts

@@ -1,191 +0,0 @@
-/**
- * useRole — Check if the current user has a given role (with hierarchy support).
- *
- * Reads the runtime's current state to determine the user's roles
- * and permissions. Supports role hierarchies where higher roles
- * automatically include lower role permissions.
- *
- * Usage in .workflow.tsx:
- *   const { hasRole, permissions } = useRole('admin');
- *   if (hasRole) { ... }
- *
- *   // With role hierarchy: admin > manager > driver > rider
- *   const { hasRole, isAbove, isBelow } = useRole('driver', {
- *     hierarchy: ['admin', 'manager', 'driver', 'rider'],
- *   });
- *   isAbove('rider')   // true if user is driver or higher
- *   isBelow('manager') // true if user is driver or lower
- */
-
-import { useMemo, useCallback } from 'react';
-import { useRuntimeContext } from '../providers/RuntimeContext';
-
-// =============================================================================
-// Types
-// =============================================================================
-
-/** Options for role hierarchy configuration. */
-export interface RoleOptions {
-  /** Role hierarchy from highest to lowest (e.g., ['admin', 'manager', 'user']). */
-  hierarchy?: string[];
-  /** Include permissions from all roles below in the hierarchy. */
-  inheritPermissions?: boolean;
-}
-
-export interface RoleResult {
-  /** Whether the current user has the specified role. */
-  hasRole: boolean;
-  /** Permissions granted by this role (from definition.roles). */
-  permissions: string[];
-  /** All roles the current user has. */
-  roles: string[];
-  /** Check if user's highest role is above the given role in the hierarchy. */
-  isAbove: (role: string) => boolean;
-  /** Check if user's highest role is below the given role in the hierarchy. */
-  isBelow: (role: string) => boolean;
-  /** Check if user has a specific permission. */
-  hasPermission: (permission: string) => boolean;
-  /** The user's highest role in the hierarchy (or first role if no hierarchy). */
-  highestRole: string | null;
-}
-
-// Global role hierarchy (set by provider)
-let _globalHierarchy: string[] | null = null;
-
-export function setRoleHierarchy(hierarchy: string[] | null): void {
-  _globalHierarchy = hierarchy;
-}
-
-// =============================================================================
-// Hook
-// =============================================================================
-
-export function useRole(roleName: string, options: RoleOptions = {}): RoleResult {
-  const runtime = useRuntimeContext();
-  const hierarchy = options.hierarchy ?? _globalHierarchy ?? [];
-  const inheritPermissions = options.inheritPermissions ?? true;
-
-  const result = useMemo(() => {
-    const snapshot = runtime.getSnapshot();
-    const definition = (runtime as any).config?.definition;
-
-    // Resolve user roles from state_data or context
-    const userRoles: string[] =
-      (snapshot.stateData as any)?._userRoles ??
-      (snapshot.stateData as any)?.user_roles ??
-      [];
-
-    // Direct role check
-    let hasRole = userRoles.includes(roleName);
-
-    // Hierarchy-based role check: if user has a higher role, they also "have" lower roles
-    if (!hasRole && hierarchy.length > 0) {
-      const targetIdx = hierarchy.indexOf(roleName);
-      if (targetIdx !== -1) {
-        for (const userRole of userRoles) {
-          const userIdx = hierarchy.indexOf(userRole);
-          if (userIdx !== -1 && userIdx <= targetIdx) {
-            // User has a role at same level or higher (lower index = higher rank)
-            hasRole = true;
-            break;
-          }
-        }
-      }
-    }
-
-    // Find permissions for this role from definition.roles
-    let permissions: string[] = [];
-    if (definition?.roles && Array.isArray(definition.roles)) {
-      if (inheritPermissions && hierarchy.length > 0) {
-        // Collect permissions from this role and all roles below in hierarchy
-        const targetIdx = hierarchy.indexOf(roleName);
-        const rolesToCheck = targetIdx !== -1
-          ? hierarchy.slice(targetIdx)
-          : [roleName];
-
-        for (const r of rolesToCheck) {
-          const roleDef = definition.roles.find((rd: any) => rd.name === r);
-          if (roleDef?.permissions && Array.isArray(roleDef.permissions)) {
-            permissions = [...permissions, ...roleDef.permissions];
-          }
-        }
-        // Deduplicate
-        permissions = [...new Set(permissions)];
-      } else {
-        const roleDef = definition.roles.find(
-          (r: any) => r.name === roleName,
-        );
-        if (roleDef?.permissions && Array.isArray(roleDef.permissions)) {
-          permissions = roleDef.permissions;
-        }
-      }
-    }
-
-    // Find highest role
-    let highestRole: string | null = userRoles[0] ?? null;
-    if (hierarchy.length > 0) {
-      let bestIdx = Infinity;
-      for (const role of userRoles) {
-        const idx = hierarchy.indexOf(role);
-        if (idx !== -1 && idx < bestIdx) {
-          bestIdx = idx;
-          highestRole = role;
-        }
-      }
-    }
-
-    return { hasRole, permissions, roles: userRoles, highestRole };
-  }, [runtime, roleName, hierarchy, inheritPermissions]);
-
-  const isAbove = useCallback(
-    (role: string): boolean => {
-      if (hierarchy.length === 0) return false;
-      const targetIdx = hierarchy.indexOf(role);
-      if (targetIdx === -1) return false;
-
-      for (const userRole of result.roles) {
-        const userIdx = hierarchy.indexOf(userRole);
-        if (userIdx !== -1 && userIdx < targetIdx) return true;
-      }
-      return false;
-    },
-    [hierarchy, result.roles],
-  );
-
-  const isBelow = useCallback(
-    (role: string): boolean => {
-      if (hierarchy.length === 0) return false;
-      const targetIdx = hierarchy.indexOf(role);
-      if (targetIdx === -1) return false;
-
-      // User is below if ALL their roles are lower
-      let hasAnyHierarchyRole = false;
-      for (const userRole of result.roles) {
-        const userIdx = hierarchy.indexOf(userRole);
-        if (userIdx !== -1) {
-          hasAnyHierarchyRole = true;
-          if (userIdx <= targetIdx) return false; // Has same or higher role
-        }
-      }
-      return hasAnyHierarchyRole;
-    },
-    [hierarchy, result.roles],
-  );
-
-  const hasPermission = useCallback(
-    (permission: string): boolean => {
-      return result.permissions.includes(permission);
-    },
-    [result.permissions],
-  );
-
-  return useMemo(
-    (): RoleResult => ({
-      ...result,
-      isAbove,
-      isBelow,
-      hasPermission,
-    }),
-    [result, isAbove, isBelow, hasPermission],
-  );
-}

package/src/hooks/useRouteParams.ts

@@ -1,100 +0,0 @@
-/**
- * useRouteParams — Access dynamic URL route parameters.
- *
- * Parses the current URL pathname against a route pattern and
- * returns extracted dynamic segments. Like Next.js useParams().
- *
- * Note: The existing useParams() hook reads workflow invocation params
- * from stateData. This hook reads URL route params.
- *
- * Usage in .workflow.tsx:
- *   // Given URL: /rides/abc123/tracking
- *   // Pattern: /rides/:rideId/:tab
- *   const { rideId, tab } = useRouteParams<{ rideId: string; tab: string }>();
- *   // rideId = 'abc123', tab = 'tracking'
- */
-
-import { useState, useEffect, useMemo, useRef } from 'react';
-
-// =============================================================================
-// Types
-// =============================================================================
-
-export interface RouteParamsOptions {
-  /** Route pattern to match against (e.g., '/rides/:id'). If omitted, extracts all :segments from path. */
-  pattern?: string;
-  /** Base path to strip before matching. */
-  basePath?: string;
-}
-
-// =============================================================================
-// Internal
-// =============================================================================
-
-function extractParams(pathname: string, pattern: string): Record<string, string> {
-  const pathParts = pathname.split('/').filter(Boolean);
-  const patternParts = pattern.split('/').filter(Boolean);
-
-  const params: Record<string, string> = {};
-
-  for (let i = 0; i < patternParts.length && i < pathParts.length; i++) {
-    if (patternParts[i].startsWith(':')) {
-      params[patternParts[i].slice(1)] = decodeURIComponent(pathParts[i]);
-    }
-  }
-
-  return params;
-}
-
-/** Simple segment extraction — treats every path segment as a positional param. */
-function extractAllSegments(pathname: string): Record<string, string> {
-  const parts = pathname.split('/').filter(Boolean);
-  const params: Record<string, string> = {};
-  for (let i = 0; i < parts.length; i++) {
-    params[`$${i}`] = decodeURIComponent(parts[i]);
-  }
-  return params;
-}
-
-// =============================================================================
-// Hook
-// =============================================================================
-
-/**
- * Reads dynamic URL route parameters from the current pathname.
- *
- * @param options - Optional pattern and basePath configuration.
- * @returns Parsed route parameters.
- */
-export function useRouteParams<T extends Record<string, string> = Record<string, string>>(
-  options: RouteParamsOptions = {},
-): T {
-  const { pattern, basePath = '' } = options;
-  const patternRef = useRef(pattern);
-  patternRef.current = pattern;
-
-  const getPathname = () => {
-    if (typeof window === 'undefined') return '/';
-    let path = window.location.pathname;
-    if (basePath && path.startsWith(basePath)) {
-      path = path.slice(basePath.length) || '/';
-    }
-    return path;
-  };
-
-  const [pathname, setPathname] = useState(getPathname);
-
-  useEffect(() => {
-    const handler = () => setPathname(getPathname());
-    window.addEventListener('popstate', handler);
-    return () => window.removeEventListener('popstate', handler);
-  // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [basePath]);
-
-  return useMemo(() => {
-    if (patternRef.current) {
-      return extractParams(pathname, patternRef.current) as T;
-    }
-    return extractAllSegments(pathname) as T;
-  }, [pathname]);
-}