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

package/src/hooks/useMiddleware.ts

@@ -1,291 +0,0 @@
-/**
- * useMiddleware — Pre-render middleware pipeline for workflow pages.
- *
- * Runs a sequence of middleware functions before a page/component renders.
- * Similar to Next.js middleware — used for auth checks, data prefetch,
- * feature flags, A/B testing, etc.
- *
- * Each middleware can:
- * - Allow (continue to next middleware)
- * - Redirect (navigate to a different path)
- * - Block (prevent rendering, show loading/error)
- *
- * Usage in .workflow.tsx:
- *   const { ready, redirect, error } = useMiddleware([
- *     requireAuth('/login'),
- *     requireRole('driver', '/unauthorized'),
- *     prefetchData('ride', { state: 'active' }),
- *   ]);
- *
- *   if (!ready) return <LoadingSpinner />;
- *   // ... render page
- *
- * Factory functions for common middleware:
- *   import { requireAuth, requireRole, prefetchData } from '@mindmatrix/react';
- */
-
-import { useState, useEffect, useRef, useMemo } from 'react';
-
-// =============================================================================
-// Types
-// =============================================================================
-
-/** Result of a middleware function. */
-export interface MiddlewareResult {
-  /** Whether to continue to the next middleware. */
-  ok: boolean;
-  /** Redirect path (if ok is false and redirect is needed). */
-  redirect?: string;
-  /** Error message (if ok is false and no redirect). */
-  error?: string;
-  /** Data to pass to the next middleware or component. */
-  data?: Record<string, unknown>;
-}
-
-/** Middleware context available to each middleware function. */
-export interface MiddlewareContext {
-  /** Current URL pathname. */
-  pathname: string;
-  /** Current query params. */
-  query: Record<string, string>;
-  /** Data accumulated from previous middleware. */
-  data: Record<string, unknown>;
-  /** Auth token from localStorage (if available). */
-  token: string | null;
-}
-
-/** A middleware function. */
-export type MiddlewareFn = (
-  ctx: MiddlewareContext,
-) => MiddlewareResult | Promise<MiddlewareResult>;
-
-/** Options for useMiddleware. */
-export interface MiddlewareOptions {
-  /** Enable/disable the middleware pipeline (default: true). */
-  enabled?: boolean;
-  /** Re-run middleware when pathname changes (default: true). */
-  watchPathname?: boolean;
-  /** Called when middleware redirects. */
-  onRedirect?: (path: string) => void;
-}
-
-/** Middleware result returned by useMiddleware. */
-export interface MiddlewareHandle {
-  /** Whether all middleware have passed and the page is ready to render. */
-  ready: boolean;
-  /** Whether middleware are still running. */
-  loading: boolean;
-  /** Redirect path if any middleware requested a redirect. */
-  redirect: string | null;
-  /** Error message if any middleware failed. */
-  error: string | null;
-  /** Accumulated data from all middleware. */
-  data: Record<string, unknown>;
-  /** Re-run the middleware pipeline. */
-  rerun: () => void;
-}
-
-// =============================================================================
-// Middleware Factories
-// =============================================================================
-
-/**
- * Factory: Require authentication. Redirects to loginPath if no token.
- */
-export function requireAuth(loginPath: string = '/login'): MiddlewareFn {
-  return (ctx) => {
-    if (!ctx.token) {
-      return { ok: false, redirect: loginPath };
-    }
-    return { ok: true };
-  };
-}
-
-/**
- * Factory: Require a specific role. Checks auth token for role claim.
- */
-export function requireRole(role: string, redirectPath: string = '/unauthorized'): MiddlewareFn {
-  return async (ctx) => {
-    if (!ctx.token) {
-      return { ok: false, redirect: '/login' };
-    }
-
-    try {
-      // Decode JWT payload (no verification — server validates)
-      const parts = ctx.token.split('.');
-      if (parts.length !== 3) {
-        return { ok: false, redirect: redirectPath };
-      }
-
-      const payload = JSON.parse(atob(parts[1]));
-      const roles: string[] = payload.roles ?? payload.role ?? [];
-      const roleList = Array.isArray(roles) ? roles : [roles];
-
-      if (!roleList.includes(role)) {
-        return { ok: false, redirect: redirectPath };
-      }
-
-      return { ok: true, data: { userRoles: roleList } };
-    } catch {
-      return { ok: false, redirect: redirectPath };
-    }
-  };
-}
-
-/**
- * Factory: Prefetch data before rendering.
- */
-export function prefetchData(slug: string, params: Record<string, unknown> = {}): MiddlewareFn {
-  return async (ctx) => {
-    try {
-      const queryString = new URLSearchParams(
-        Object.entries(params).map(([k, v]) => [k, String(v)]),
-      ).toString();
-
-      const url = `/api/v1/data/${encodeURIComponent(slug)}${queryString ? `?${queryString}` : ''}`;
-      const res = await fetch(url, {
-        headers: ctx.token ? { Authorization: `Bearer ${ctx.token}` } : {},
-      });
-
-      if (!res.ok) {
-        return { ok: false, error: `Failed to prefetch ${slug}: ${res.status}` };
-      }
-
-      const data = await res.json();
-      return { ok: true, data: { [slug]: data } };
-    } catch (err) {
-      return { ok: false, error: `Prefetch failed: ${err instanceof Error ? err.message : String(err)}` };
-    }
-  };
-}
-
-// =============================================================================
-// Hook
-// =============================================================================
-
-function getPathname(): string {
-  return typeof window !== 'undefined' ? window.location.pathname : '/';
-}
-
-function getQuery(): Record<string, string> {
-  if (typeof window === 'undefined') return {};
-  const params: Record<string, string> = {};
-  const search = new URLSearchParams(window.location.search);
-  search.forEach((value, key) => {
-    params[key] = value;
-  });
-  return params;
-}
-
-function getToken(): string | null {
-  return typeof localStorage !== 'undefined' ? localStorage.getItem('auth_token') : null;
-}
-
-/**
- * Pre-render middleware pipeline.
- *
- * @param middlewares - Array of middleware functions to run in order.
- * @param options - Configuration options.
- * @returns Middleware result with ready/loading/redirect/error states.
- */
-export function useMiddleware(
-  middlewares: MiddlewareFn[],
-  options: MiddlewareOptions = {},
-): MiddlewareHandle {
-  const {
-    enabled = true,
-    watchPathname = true,
-    onRedirect,
-  } = options;
-
-  const [ready, setReady] = useState(false);
-  const [loading, setLoading] = useState(true);
-  const [redirect, setRedirect] = useState<string | null>(null);
-  const [error, setError] = useState<string | null>(null);
-  const [data, setData] = useState<Record<string, unknown>>({});
-  const [runKey, setRunKey] = useState(0);
-
-  const middlewaresRef = useRef(middlewares);
-  middlewaresRef.current = middlewares;
-  const onRedirectRef = useRef(onRedirect);
-  onRedirectRef.current = onRedirect;
-
-  // Track pathname for re-running
-  const [pathname, setPathname] = useState(getPathname);
-
-  useEffect(() => {
-    if (!watchPathname) return;
-    const handler = () => setPathname(getPathname());
-    window.addEventListener('popstate', handler);
-    return () => window.removeEventListener('popstate', handler);
-  }, [watchPathname]);
-
-  // Run middleware pipeline
-  useEffect(() => {
-    if (!enabled) {
-      setReady(true);
-      setLoading(false);
-      return;
-    }
-
-    let cancelled = false;
-    setLoading(true);
-    setReady(false);
-    setRedirect(null);
-    setError(null);
-
-    const run = async () => {
-      const ctx: MiddlewareContext = {
-        pathname,
-        query: getQuery(),
-        data: {},
-        token: getToken(),
-      };
-
-      for (const mw of middlewaresRef.current) {
-        if (cancelled) return;
-
-        const result = await mw(ctx);
-
-        if (result.data) {
-          Object.assign(ctx.data, result.data);
-        }
-
-        if (!result.ok) {
-          if (cancelled) return;
-
-          if (result.redirect) {
-            setRedirect(result.redirect);
-            onRedirectRef.current?.(result.redirect);
-          }
-          if (result.error) {
-            setError(result.error);
-          }
-          setLoading(false);
-          return;
-        }
-      }
-
-      if (cancelled) return;
-      setData(ctx.data);
-      setReady(true);
-      setLoading(false);
-    };
-
-    run();
-
-    return () => {
-      cancelled = true;
-    };
-  }, [enabled, pathname, runKey]);
-
-  const rerun = useMemo(
-    () => () => setRunKey((k) => k + 1),
-    [],
-  );
-
-  return useMemo(
-    (): MiddlewareHandle => ({ ready, loading, redirect, error, data, rerun }),
-    [ready, loading, redirect, error, data, rerun],
-  );
-}

package/src/hooks/useModel.ts

@@ -1,363 +0,0 @@
-/**
- * useModel — unified hook for connecting a view to a workflow model.
- *
- * Combines useQuery + useMutation into a single, ergonomic, fully-typed handle.
- * This is the recommended API for views that interact with a single model.
- *
- * For multi-instance patterns (collections), use useCollection().
- *
- * @example
- * ```tsx
- * import auth from '../models/authentication.workflow';
- * import { useModel } from '@mindmatrix/react';
- *
- * export default function LoginPage() {
- *   const { fields, state, trigger, loading } = useModel(auth);
- *
- *   fields.appName;              // string — typed, autocomplete
- *   fields.errorMessage;         // string — typed
- *   trigger('login', { email }); // 'login' autocompletes, typos are TS errors
- *   state === 'authenticating';  // 'authenticating' autocompletes
- * }
- * ```
- */
-
-import { useCallback, useRef, useMemo } from 'react';
-import type { ModelDefinition } from '../config/defineModel';
-import type { InferFields, InferStates, InferTransitions } from '../types/workflow-inference';
-import type { QueryParams } from './useQuery';
-import { useQuery } from './useQuery';
-import { useMutation } from './useMutation';
-
-// =============================================================================
-// Types
-// =============================================================================
-
-/** Options for useModel(). */
-export interface UseModelOptions {
-  /** Specific instance ID to load (instead of limit: 1). */
-  instanceId?: string;
-  /** Additional query filters. */
-  filter?: Record<string, unknown>;
-  /** Filter by state. */
-  state?: string | string[];
-  /** Disable auto-fetching. */
-  enabled?: boolean;
-  /** Refetch interval in milliseconds. */
-  refetchInterval?: number;
-}
-
-/**
- * Handle returned by `useModel()`.
- *
- * Provides typed access to a single workflow instance's fields, current state,
- * and transition triggers. All field names, state names, and transition names
- * are inferred from the model definition passed to `useModel()`.
- *
- * @example
- * ```tsx
- * const auth = useModel(authModel);
- * auth.fields.appName;              // string — autocomplete works
- * auth.state;                       // 'unauthenticated' | 'authenticating' | ...
- * auth.trigger('login', { email }); // transition names autocomplete
- * ```
- */
-export interface ModelHandle<
-  Fields,
-  States extends string,
-  Transitions extends string,
-> {
-  /**
-   * Current field values, typed from the model definition.
-   *
-   * Each property corresponds to a field declared in `defineModel({ fields: { ... } })`.
-   * Values are typed based on the field's `type` property (e.g., `'string'` → `string`).
-   */
-  fields: Fields;
-  /**
-   * Current workflow state name.
-   *
-   * One of the state names declared in `defineModel({ states: { ... } })`,
-   * or `''` if no instance is loaded yet.
-   */
-  state: States | '';
-  /** The loaded instance ID, or `null` if no instance is loaded. */
-  instanceId: string | null;
-  /**
-   * Fire a named transition on the current instance.
-   *
-   * @param name - Transition name (autocompletes from the model's transitions).
-   * @param input - Optional input data passed to the transition's actions/conditions.
-   * @throws If no instance is loaded.
-   *
-   * @example
-   * ```tsx
-   * auth.trigger('login', { email: 'user@example.com', password: '...' });
-   * auth.trigger('logout');
-   * ```
-   */
-  trigger: (name: Transitions, input?: Record<string, unknown>) => Promise<void>;
-  /** Alias for `trigger` — same behavior, alternate name. */
-  transition: (name: Transitions, input?: Record<string, unknown>) => Promise<void>;
-  /**
-   * Create a new workflow instance with optional initial field values.
-   * @returns The ID of the newly created instance.
-   */
-  create: (input?: Record<string, unknown>) => Promise<string>;
-  /**
-   * Update fields on the current instance (partial update).
-   * @param fields - Object with field names and new values.
-   */
-  update: (fields: Partial<Fields>) => Promise<void>;
-  /** `true` while the initial query is loading. */
-  loading: boolean;
-  /** The last error from query or mutation, or `null`. */
-  error: Error | null;
-  /** Refetch data from the backend. */
-  refetch: () => Promise<void>;
-  /** `true` while a mutation (trigger/create/update) is in progress. */
-  isPending: boolean;
-  /** Reset the error state to `null`. */
-  reset: () => void;
-  /** Raw query result — use for advanced scenarios (pagination, counts). */
-  raw: { data: unknown[]; total?: number };
-}
-
-// =============================================================================
-// Default Fields Helper
-// =============================================================================
-
-function getDefaultFields(definition: ModelDefinition): Record<string, unknown> {
-  const defaults: Record<string, unknown> = {};
-  for (const [key, field] of Object.entries(definition.fields)) {
-    if (field.default !== undefined) {
-      defaults[key] = field.default;
-    } else {
-      // Sensible defaults by type
-      switch (field.type) {
-        case 'string': case 'text': case 'email': case 'url': case 'phone':
-        case 'color': case 'select': case 'rich_text':
-          defaults[key] = '';
-          break;
-        case 'number': case 'integer': case 'float': case 'currency':
-        case 'percentage': case 'rating': case 'duration':
-          defaults[key] = 0;
-          break;
-        case 'boolean':
-          defaults[key] = false;
-          break;
-        case 'array':
-          defaults[key] = [];
-          break;
-        case 'object': case 'json':
-          defaults[key] = {};
-          break;
-        default:
-          defaults[key] = undefined;
-      }
-    }
-  }
-  return defaults;
-}
-
-// =============================================================================
-// Hook Implementation
-// =============================================================================
-
-/**
- * Connect a view to a workflow model with full type inference.
- *
- * @param definition - The model definition (from defineModel() or import).
- * @param options - Optional configuration (instanceId, filter, etc.).
- * @returns Fully typed model handle with fields, state, trigger, etc.
- */
-export function useModel<D extends ModelDefinition>(
-  definition: D,
-  options: UseModelOptions = {},
-): ModelHandle<InferFields<D>, InferStates<D> & string, InferTransitions<D> & string> {
-  const slug = definition.slug;
-
-  // Build query params
-  const queryParams: QueryParams = {
-    limit: 1,
-    enabled: options.enabled,
-    refetchInterval: options.refetchInterval,
-  };
-  if (options.filter) queryParams.filter = options.filter;
-  if (options.state) queryParams.state = options.state;
-
-  // Query + mutation
-  const query = useQuery(slug, queryParams);
-  const mutation = useMutation(slug);
-
-  // Extract instance data
-  const instance = query.data?.[0] as Record<string, unknown> | undefined;
-  const instanceId = (instance?.id as string) ?? null;
-  const currentState = (instance?.currentState as string) ?? '';
-  const instanceFields = (instance?.fields as Record<string, unknown>) ?? null;
-
-  // Compute defaults once
-  const defaultFields = useMemo(() => getDefaultFields(definition), [definition]);
-
-  // Merge instance fields with defaults
-  const fields = useMemo(() => {
-    if (!instanceFields) return defaultFields;
-    return { ...defaultFields, ...instanceFields };
-  }, [instanceFields, defaultFields]);
-
-  // Trigger function
-  const instanceIdRef = useRef(instanceId);
-  instanceIdRef.current = instanceId;
-
-  const trigger = useCallback(async (name: string, input?: Record<string, unknown>) => {
-    const id = instanceIdRef.current;
-    if (!id) {
-      throw new Error(`useModel(${slug}): No instance loaded. Cannot trigger '${name}'.`);
-    }
-    await mutation.transition(id, name, input);
-    // Refetch after transition to get updated state
-    await query.refetch();
-  }, [slug, mutation, query]);
-
-  // Create function
-  const create = useCallback(async (input?: Record<string, unknown>) => {
-    const id = await mutation.create(input);
-    await query.refetch();
-    return id;
-  }, [mutation, query]);
-
-  // Update function
-  const update = useCallback(async (fieldUpdates: Record<string, unknown>) => {
-    const id = instanceIdRef.current;
-    if (!id) {
-      throw new Error(`useModel(${slug}): No instance loaded. Cannot update.`);
-    }
-    await mutation.update(id, fieldUpdates);
-    await query.refetch();
-  }, [slug, mutation, query]);
-
-  type Handle = ModelHandle<InferFields<D>, InferStates<D> & string, InferTransitions<D> & string>;
-
-  const handle: Handle = {
-    fields: fields as Handle['fields'],
-    state: currentState as Handle['state'],
-    instanceId,
-    trigger: trigger as Handle['trigger'],
-    transition: trigger as Handle['transition'],
-    create,
-    update: update as Handle['update'],
-    loading: query.loading,
-    error: query.error ?? mutation.error,
-    refetch: query.refetch,
-    isPending: mutation.isPending,
-    reset: mutation.reset,
-    raw: { data: query.data, total: query.total },
-  };
-
-  return handle;
-}
-
-// =============================================================================
-// useCollection — multi-instance variant
-// =============================================================================
-
-/** Handle returned by useCollection(). */
-export interface CollectionHandle<
-  Fields,
-  States extends string,
-  Transitions extends string,
-> {
-  /** Array of instances with typed fields. */
-  items: Array<{ id: string; fields: Fields; state: States }>;
-  /** Total count of matching instances. */
-  total: number;
-  /** Whether data is loading. */
-  loading: boolean;
-  /** Last error. */
-  error: Error | null;
-  /** Refetch data. */
-  refetch: () => Promise<void>;
-  /** Whether there are more results. */
-  hasMore: boolean;
-  /** Fire a transition on a specific instance. */
-  trigger: (instanceId: string, name: Transitions, input?: Record<string, unknown>) => Promise<void>;
-  /** Create a new instance. */
-  create: (input?: Record<string, unknown>) => Promise<string>;
-  /** Update fields on a specific instance. */
-  update: (instanceId: string, fields: Partial<Fields>) => Promise<void>;
-  /** Remove an instance. */
-  remove: (instanceId: string) => Promise<void>;
-  /** Whether a mutation is in progress. */
-  isPending: boolean;
-}
-
-/** Options for useCollection(). */
-export interface UseCollectionOptions extends QueryParams {}
-
-/**
- * Connect a view to a collection of workflow model instances.
- *
- * @example
- * ```tsx
- * import channelModel from '../models/channel';
- * const { items, trigger, create } = useCollection(channelModel, { state: 'active' });
- *
- * items.map(ch => ch.fields.name); // string[] — typed
- * trigger(ch.id, 'archive');       // transition name typed
- * ```
- */
-export function useCollection<D extends ModelDefinition>(
-  definition: D,
-  options: UseCollectionOptions = {},
-): CollectionHandle<InferFields<D>, InferStates<D> & string, InferTransitions<D> & string> {
-  const slug = definition.slug;
-  const query = useQuery(slug, options);
-  const mutation = useMutation(slug);
-
-  const items = useMemo(() => {
-    return (query.data || []).map((instance: any) => ({
-      id: instance.id as string,
-      fields: (instance.fields ?? {}) as InferFields<D>,
-      state: (instance.currentState ?? '') as InferStates<D> & string,
-    }));
-  }, [query.data]);
-
-  const trigger = useCallback(async (instanceId: string, name: string, input?: Record<string, unknown>) => {
-    await mutation.transition(instanceId, name, input);
-    await query.refetch();
-  }, [mutation, query]);
-
-  const create = useCallback(async (input?: Record<string, unknown>) => {
-    const id = await mutation.create(input);
-    await query.refetch();
-    return id;
-  }, [mutation, query]);
-
-  const update = useCallback(async (instanceId: string, fieldUpdates: Record<string, unknown>) => {
-    await mutation.update(instanceId, fieldUpdates);
-    await query.refetch();
-  }, [mutation, query]);
-
-  const remove = useCallback(async (instanceId: string) => {
-    await mutation.remove(instanceId);
-    await query.refetch();
-  }, [mutation, query]);
-
-  type CHandle = CollectionHandle<InferFields<D>, InferStates<D> & string, InferTransitions<D> & string>;
-
-  const handle: CHandle = {
-    items: items as CHandle['items'],
-    total: query.total ?? items.length,
-    loading: query.loading,
-    error: query.error ?? mutation.error,
-    refetch: query.refetch,
-    hasMore: query.hasMore ?? false,
-    trigger: trigger as CHandle['trigger'],
-    create,
-    update: update as CHandle['update'],
-    remove,
-    isPending: mutation.isPending,
-  };
-
-  return handle;
-}