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

package/src/hooks/useExperienceState.ts

@@ -1,59 +0,0 @@
-/**
- * useExperienceState — Reactive accessor for experience workflow state.
- *
- * Provides fine-grained access to the player's state with optional
- * selector for render optimization. Components only re-render when
- * their selected slice of state actually changes.
- */
-
-import { useCallback, useRef } from 'react';
-import type { PlayerHandle } from '../types';
-
-type Selector<T> = (state: {
-  currentState: string;
-  stateData: Record<string, unknown>;
-  status: string;
-  availableTransitions: string[];
-}) => T;
-
-/**
- * Subscribe to a slice of player state with a selector.
- *
- * @example
- * ```tsx
- * const title = useExperienceState(player, s => s.stateData.title as string);
- * const canAdvance = useExperienceState(player, s => s.availableTransitions.includes('advance'));
- * ```
- */
-export function useExperienceState<T>(player: PlayerHandle, selector: Selector<T>): T {
-  const selectorRef = useRef(selector);
-  selectorRef.current = selector;
-
-  const getSnapshot = useCallback(() => {
-    return selectorRef.current({
-      currentState: player.currentState,
-      stateData: player.stateData,
-      status: player.status,
-      availableTransitions: player.availableTransitions,
-    });
-  }, [player.currentState, player.stateData, player.status, player.availableTransitions]);
-
-  return getSnapshot();
-}
-
-/**
- * Access a single field from state_data.
- *
- * @example
- * ```tsx
- * const count = useStateField(player, 'count', 0);
- * ```
- */
-export function useStateField<T = unknown>(
-  player: PlayerHandle,
-  field: string,
-  defaultValue?: T,
-): T {
-  const value = player.stateData[field];
-  return (value !== undefined ? value : defaultValue) as T;
-}

package/src/hooks/useExpressionLibrary.ts

@@ -1,129 +0,0 @@
-/**
- * useExpressionLibrary — Load an expression library by slug
- *
- * Fetches a workflow definition with category='expression-library' and
- * returns its expression + metadata for use in computed fields.
- * Supports I3 expression library system.
- *
- * Usage in .workflow.tsx:
- *   const { expression, functions, loading } = useExpressionLibrary('pricing/bulk-discount');
- *   // Use in computed field: call "pricing/bulk-discount"(subtotal, quantity)
- */
-
-import { useState, useEffect, useCallback, useRef } from 'react';
-
-// =============================================================================
-// Types
-// =============================================================================
-
-export interface ExpressionLibraryResult {
-  /** The expression string from the library. */
-  expression: string | null;
-  /** Library name. */
-  name: string | null;
-  /** Library description. */
-  description: string | null;
-  /** Parameter signature (from metadata). */
-  params: LibraryParam[];
-  /** Return type hint (from metadata). */
-  returnType: string | null;
-  /** Whether the library is currently loading. */
-  loading: boolean;
-  /** Error from the last fetch attempt. */
-  error: Error | null;
-  /** Manually trigger a refetch. */
-  refetch: () => Promise<void>;
-}
-
-export interface LibraryParam {
-  name: string;
-  type?: string;
-  description?: string;
-}
-
-export interface ExpressionLibraryRecord {
-  id: string;
-  slug: string;
-  name: string;
-  description?: string;
-  metadata?: {
-    expression?: string;
-    params?: LibraryParam[];
-    returnType?: string;
-  };
-}
-
-/**
- * Expression library resolver — the runtime must provide an implementation.
- */
-export interface ExpressionLibraryResolver {
-  getLibrary: (slug: string) => Promise<ExpressionLibraryRecord | null>;
-}
-
-// Global resolver (set by provider)
-let _globalExpressionLibraryResolver: ExpressionLibraryResolver | null = null;
-
-export function setExpressionLibraryResolver(resolver: ExpressionLibraryResolver | null): void {
-  _globalExpressionLibraryResolver = resolver;
-}
-
-// =============================================================================
-// Hook
-// =============================================================================
-
-/**
- * Fetches an expression library definition by slug.
- *
- * @param slug - The expression library slug (e.g., 'pricing/bulk-discount').
- * @returns Library result with expression, params, loading state, and error.
- */
-export function useExpressionLibrary(slug: string | null): ExpressionLibraryResult {
-  const [record, setRecord] = useState<ExpressionLibraryRecord | null>(null);
-  const [loading, setLoading] = useState(!!slug);
-  const [error, setError] = useState<Error | null>(null);
-  const slugRef = useRef(slug);
-  slugRef.current = slug;
-
-  const fetchLibrary = useCallback(async () => {
-    const s = slugRef.current;
-    if (!s) {
-      setRecord(null);
-      setLoading(false);
-      return;
-    }
-
-    const resolver = _globalExpressionLibraryResolver;
-    if (!resolver) {
-      setError(new Error('useExpressionLibrary: No resolver configured. Wrap your app in a WorkflowProvider.'));
-      setLoading(false);
-      return;
-    }
-
-    try {
-      setLoading(true);
-      setError(null);
-      const result = await resolver.getLibrary(s);
-      setRecord(result);
-    } catch (err) {
-      setError(err instanceof Error ? err : new Error(String(err)));
-    } finally {
-      setLoading(false);
-    }
-  }, []);
-
-  useEffect(() => {
-    fetchLibrary();
-  }, [slug, fetchLibrary]);
-
-  const handle: ExpressionLibraryResult = {
-    expression: record?.metadata?.expression ?? null,
-    name: record?.name ?? null,
-    description: record?.description ?? null,
-    params: record?.metadata?.params ?? [],
-    returnType: record?.metadata?.returnType ?? null,
-    loading,
-    error,
-    refetch: fetchLibrary,
-  };
-  return handle;
-}

package/src/hooks/useForm.ts

@@ -1,352 +0,0 @@
-/**
- * useForm — Form state management with validation, dirty tracking, and submit handling.
- *
- * Provides a complete form solution with field-level and form-level validation,
- * dirty/touched tracking, and async submit handling.
- *
- * Usage in .workflow.tsx:
- *   const form = useForm({
- *     initialValues: { pickup: '', destination: '', rideType: 'standard' },
- *     validate: (values) => {
- *       const errors: Record<string, string> = {};
- *       if (!values.pickup) errors.pickup = 'Pickup location is required';
- *       if (!values.destination) errors.destination = 'Destination is required';
- *       return errors;
- *     },
- *     onSubmit: async (values) => {
- *       await createRide(values);
- *     },
- *   });
- *
- *   <TextInput bind="pickup" {...form.register('pickup')} />
- *   <Button onClick={form.handleSubmit} disabled={!form.isValid}>
- *     Request Ride
- *   </Button>
- */
-
-import { useState, useCallback, useMemo, useRef } from 'react';
-
-// =============================================================================
-// Types
-// =============================================================================
-
-/** Validation function. Returns error messages keyed by field name. */
-export type FormValidator<T extends Record<string, unknown>> = (
-  values: T,
-) => Record<string, string> | Promise<Record<string, string>>;
-
-/** Field-level validator. Returns error message or empty string. */
-export type FieldValidator = (value: unknown, fieldName: string) => string | Promise<string>;
-
-/** Form configuration. */
-export interface FormConfig<T extends Record<string, unknown>> {
-  /** Initial form values. */
-  initialValues: T;
-  /** Form-level validation function. */
-  validate?: FormValidator<T>;
-  /** Field-level validators. */
-  fieldValidators?: Partial<Record<keyof T, FieldValidator>>;
-  /** Called on valid form submission. */
-  onSubmit?: (values: T) => void | Promise<void>;
-  /** Called when submit fails validation. */
-  onError?: (errors: Record<string, string>) => void;
-  /** Validate on every change (default: false). */
-  validateOnChange?: boolean;
-  /** Validate on blur (default: true). */
-  validateOnBlur?: boolean;
-}
-
-/** Field registration props (spread onto input components). */
-export interface FieldRegistration {
-  value: unknown;
-  onChange: (valueOrEvent: unknown) => void;
-  onBlur: () => void;
-  name: string;
-  error?: string;
-}
-
-/** Form handle returned by useForm. */
-export interface FormHandle<T extends Record<string, unknown>> {
-  /** Current form values. */
-  values: T;
-  /** Current validation errors (keyed by field name). */
-  errors: Record<string, string>;
-  /** Which fields have been touched (blurred). */
-  touched: Record<string, boolean>;
-  /** Whether any field has been modified from initial values. */
-  dirty: boolean;
-  /** Which specific fields are dirty. */
-  dirtyFields: Record<string, boolean>;
-  /** Whether the form passes validation. */
-  isValid: boolean;
-  /** Whether the form is currently submitting. */
-  isSubmitting: boolean;
-  /** Number of times the form has been submitted. */
-  submitCount: number;
-  /** Set a specific field's value. */
-  setField: (name: keyof T, value: unknown) => void;
-  /** Set a specific field's error. */
-  setError: (name: string, message: string) => void;
-  /** Clear a field's error. */
-  clearError: (name: string) => void;
-  /** Set multiple values at once. */
-  setValues: (values: Partial<T>) => void;
-  /** Reset form to initial values. */
-  reset: (newInitial?: T) => void;
-  /** Trigger form submission. */
-  handleSubmit: () => Promise<void>;
-  /** Validate the entire form manually. */
-  validateForm: () => Promise<Record<string, string>>;
-  /** Register a field (returns props to spread on input). */
-  register: (name: keyof T) => FieldRegistration;
-  /** Get a specific field's value. */
-  getField: (name: keyof T) => unknown;
-}
-
-// =============================================================================
-// Hook
-// =============================================================================
-
-/**
- * Form state management with validation and submit handling.
- *
- * @param config - Form configuration with initial values, validators, and submit handler.
- * @returns Form handle with values, errors, and control methods.
- */
-export function useForm<T extends Record<string, unknown>>(
-  config: FormConfig<T>,
-): FormHandle<T> {
-  const {
-    initialValues,
-    validate,
-    fieldValidators,
-    onSubmit,
-    onError,
-    validateOnChange = false,
-    validateOnBlur = true,
-  } = config;
-
-  const [values, setValuesState] = useState<T>(initialValues);
-  const [errors, setErrors] = useState<Record<string, string>>({});
-  const [touched, setTouched] = useState<Record<string, boolean>>({});
-  const [isSubmitting, setIsSubmitting] = useState(false);
-  const [submitCount, setSubmitCount] = useState(0);
-
-  const initialRef = useRef(initialValues);
-  const validateRef = useRef(validate);
-  validateRef.current = validate;
-  const fieldValidatorsRef = useRef(fieldValidators);
-  fieldValidatorsRef.current = fieldValidators;
-  const onSubmitRef = useRef(onSubmit);
-  onSubmitRef.current = onSubmit;
-  const onErrorRef = useRef(onError);
-  onErrorRef.current = onError;
-
-  // Compute dirty fields
-  const dirtyFields = useMemo(() => {
-    const result: Record<string, boolean> = {};
-    for (const key of Object.keys(values)) {
-      result[key] = values[key] !== initialRef.current[key as keyof T];
-    }
-    return result;
-  }, [values]);
-
-  const dirty = useMemo(
-    () => Object.values(dirtyFields).some(Boolean),
-    [dirtyFields],
-  );
-
-  const isValid = useMemo(
-    () => Object.keys(errors).length === 0,
-    [errors],
-  );
-
-  // Validate a single field
-  const validateField = useCallback(
-    async (name: string, value: unknown): Promise<string> => {
-      const validator = fieldValidatorsRef.current?.[name as keyof T];
-      if (validator) {
-        return await validator(value, name);
-      }
-      return '';
-    },
-    [],
-  );
-
-  // Validate entire form
-  const validateForm = useCallback(async (): Promise<Record<string, string>> => {
-    let formErrors: Record<string, string> = {};
-
-    // Run form-level validator
-    if (validateRef.current) {
-      formErrors = await validateRef.current(values);
-    }
-
-    // Run field-level validators
-    if (fieldValidatorsRef.current) {
-      for (const [name, validator] of Object.entries(fieldValidatorsRef.current)) {
-        if (validator && !formErrors[name]) {
-          const fieldError = await (validator as FieldValidator)(values[name as keyof T], name);
-          if (fieldError) {
-            formErrors[name] = fieldError;
-          }
-        }
-      }
-    }
-
-    setErrors(formErrors);
-    return formErrors;
-  }, [values]);
-
-  const setField = useCallback(
-    (name: keyof T, value: unknown) => {
-      setValuesState((prev) => ({ ...prev, [name]: value }));
-
-      if (validateOnChange) {
-        validateField(name as string, value).then((fieldError) => {
-          setErrors((prev) => {
-            if (fieldError) {
-              return { ...prev, [name]: fieldError };
-            }
-            const next = { ...prev };
-            delete next[name as string];
-            return next;
-          });
-        });
-      }
-    },
-    [validateOnChange, validateField],
-  );
-
-  const setError = useCallback((name: string, message: string) => {
-    setErrors((prev) => ({ ...prev, [name]: message }));
-  }, []);
-
-  const clearError = useCallback((name: string) => {
-    setErrors((prev) => {
-      const next = { ...prev };
-      delete next[name];
-      return next;
-    });
-  }, []);
-
-  const setValues = useCallback((partial: Partial<T>) => {
-    setValuesState((prev) => ({ ...prev, ...partial }));
-  }, []);
-
-  const reset = useCallback((newInitial?: T) => {
-    const resetTo = newInitial ?? initialRef.current;
-    if (newInitial) {
-      initialRef.current = newInitial;
-    }
-    setValuesState(resetTo);
-    setErrors({});
-    setTouched({});
-    setIsSubmitting(false);
-  }, []);
-
-  const handleSubmit = useCallback(async () => {
-    setSubmitCount((c) => c + 1);
-
-    // Touch all fields
-    const allTouched: Record<string, boolean> = {};
-    for (const key of Object.keys(values)) {
-      allTouched[key] = true;
-    }
-    setTouched(allTouched);
-
-    // Validate
-    const formErrors = await validateForm();
-    if (Object.keys(formErrors).length > 0) {
-      onErrorRef.current?.(formErrors);
-      return;
-    }
-
-    // Submit
-    if (!onSubmitRef.current) return;
-
-    setIsSubmitting(true);
-    try {
-      await onSubmitRef.current(values);
-    } catch (err) {
-      const submitError = err instanceof Error ? err : new Error(String(err));
-      setErrors((prev) => ({ ...prev, _form: submitError.message }));
-    } finally {
-      setIsSubmitting(false);
-    }
-  }, [values, validateForm]);
-
-  const register = useCallback(
-    (name: keyof T): FieldRegistration => {
-      return {
-        name: name as string,
-        value: values[name],
-        onChange: (valueOrEvent: unknown) => {
-          // Handle both raw values and React synthetic events
-          let newValue: unknown;
-          if (
-            valueOrEvent &&
-            typeof valueOrEvent === 'object' &&
-            'target' in valueOrEvent
-          ) {
-            const target = (valueOrEvent as { target: { type?: string; checked?: boolean; value?: unknown } }).target;
-            newValue = target.type === 'checkbox' ? target.checked : target.value;
-          } else {
-            newValue = valueOrEvent;
-          }
-          setField(name, newValue);
-        },
-        onBlur: () => {
-          setTouched((prev) => ({ ...prev, [name]: true }));
-
-          if (validateOnBlur) {
-            validateField(name as string, values[name]).then((fieldError) => {
-              setErrors((prev) => {
-                if (fieldError) {
-                  return { ...prev, [name]: fieldError };
-                }
-                const next = { ...prev };
-                delete next[name as string];
-                return next;
-              });
-            });
-          }
-        },
-        error: errors[name as string],
-      };
-    },
-    [values, errors, setField, validateOnBlur, validateField],
-  );
-
-  const getField = useCallback(
-    (name: keyof T): unknown => values[name],
-    [values],
-  );
-
-  return useMemo(
-    (): FormHandle<T> => ({
-      values,
-      errors,
-      touched,
-      dirty,
-      dirtyFields,
-      isValid,
-      isSubmitting,
-      submitCount,
-      setField,
-      setError,
-      clearError,
-      setValues,
-      reset,
-      handleSubmit,
-      validateForm,
-      register,
-      getField,
-    }),
-    [
-      values, errors, touched, dirty, dirtyFields, isValid, isSubmitting,
-      submitCount, setField, setError, clearError, setValues, reset,
-      handleSubmit, validateForm, register, getField,
-    ],
-  );
-}