@mmapp/react 0.1.0-alpha.1

package/src/__tests__/factories.test.ts

@@ -0,0 +1,229 @@
+import { describe, it, expect } from 'vitest';
+import { model, field, state } from '../builders';
+import { approval, escalation, review, crud } from '../factories';
+
+describe('approval factory', () => {
+  it('adds approve/reject transitions with defaults', () => {
+    const def = model('invoice')
+      .field('amount', field.currency())
+      .state('draft', state.initial())
+      .state('pending_approval')
+      .mixin(approval())
+      .build();
+
+    expect(def.transitions.approve).toBeDefined();
+    expect(def.transitions.approve.from).toBe('pending_approval');
+    expect(def.transitions.approve.to).toBe('approved');
+    expect(def.transitions.approve.roles).toContain('approver');
+
+    expect(def.transitions.reject).toBeDefined();
+    expect(def.transitions.reject.from).toBe('pending_approval');
+    expect(def.transitions.reject.to).toBe('rejected');
+  });
+
+  it('adds approval-related fields', () => {
+    const def = model('invoice')
+      .state('draft', state.initial())
+      .mixin(approval())
+      .build();
+
+    expect(def.fields.approvalStatus).toBeDefined();
+    expect(def.fields.approvedBy).toBeDefined();
+    expect(def.fields.approvedAt).toBeDefined();
+    expect(def.fields.rejectionReason).toBeDefined();
+  });
+
+  it('respects custom config', () => {
+    const def = model('invoice')
+      .state('draft', state.initial())
+      .state('review')
+      .mixin(approval({
+        approverRole: 'manager',
+        field: 'status',
+        fromState: 'review',
+        approvedState: 'done',
+        rejectedState: 'cancelled',
+      }))
+      .build();
+
+    expect(def.transitions.approve.from).toBe('review');
+    expect(def.transitions.approve.to).toBe('done');
+    expect(def.transitions.approve.roles).toContain('manager');
+    expect(def.transitions.reject.to).toBe('cancelled');
+    expect(def.fields.status).toBeDefined();
+  });
+
+  it('adds approver role', () => {
+    const def = model('invoice')
+      .state('draft', state.initial())
+      .mixin(approval())
+      .build();
+
+    expect(def.roles!.approver).toBeDefined();
+    expect(def.roles!.approver.permissions).toContain('approve');
+  });
+});
+
+describe('escalation factory', () => {
+  it('adds escalate transition with timeout', () => {
+    const def = model('ticket')
+      .state('pending_approval', state.initial())
+      .mixin(escalation({ timeout: '24h' }))
+      .build();
+
+    expect(def.transitions.escalate).toBeDefined();
+    expect(def.transitions.escalate.from).toBe('pending_approval');
+    expect(def.transitions.escalate.to).toBe('escalated');
+    expect(def.transitions.escalate.auto).toBe(true);
+  });
+
+  it('sets timeout on the source state', () => {
+    const def = model('ticket')
+      .state('pending_approval', state.initial())
+      .mixin(escalation({ timeout: '2d', fromState: 'pending_approval' }))
+      .build();
+
+    expect(def.states.pending_approval.timeout).toBeDefined();
+    expect(def.states.pending_approval.timeout!.duration).toBe('2d');
+    expect(def.states.pending_approval.timeout!.fallback?.transition).toBe('escalate');
+  });
+
+  it('adds escalation fields', () => {
+    const def = model('ticket')
+      .state('open', state.initial())
+      .mixin(escalation({ timeout: '1h', fromState: 'open' }))
+      .build();
+
+    expect(def.fields.escalatedAt).toBeDefined();
+    expect(def.fields.escalationLevel).toBeDefined();
+  });
+});
+
+describe('review factory', () => {
+  it('adds submit/approve/revise cycle', () => {
+    const def = model('article')
+      .field('content', field.string())
+      .state('draft', state.initial())
+      .mixin(review())
+      .build();
+
+    expect(def.transitions.submit_for_review).toBeDefined();
+    expect(def.transitions.submit_for_review.from).toBe('draft');
+    expect(def.transitions.submit_for_review.to).toBe('in_review');
+
+    expect(def.transitions.approve_review).toBeDefined();
+    expect(def.transitions.approve_review.from).toBe('in_review');
+    expect(def.transitions.approve_review.to).toBe('approved');
+
+    expect(def.transitions.request_revisions).toBeDefined();
+    expect(def.transitions.request_revisions.from).toBe('in_review');
+    expect(def.transitions.request_revisions.to).toBe('revisions_requested');
+
+    expect(def.transitions.resubmit).toBeDefined();
+    expect(def.transitions.resubmit.from).toBe('revisions_requested');
+    expect(def.transitions.resubmit.to).toBe('in_review');
+  });
+
+  it('adds review fields', () => {
+    const def = model('article')
+      .state('draft', state.initial())
+      .mixin(review())
+      .build();
+
+    expect(def.fields.reviewNotes).toBeDefined();
+    expect(def.fields.reviewedBy).toBeDefined();
+    expect(def.fields.reviewedAt).toBeDefined();
+    expect(def.fields.revisionCount).toBeDefined();
+  });
+
+  it('adds author and reviewer roles', () => {
+    const def = model('article')
+      .state('draft', state.initial())
+      .mixin(review())
+      .build();
+
+    expect(def.roles!.author).toBeDefined();
+    expect(def.roles!.reviewer).toBeDefined();
+  });
+
+  it('respects custom role names', () => {
+    const def = model('article')
+      .state('draft', state.initial())
+      .mixin(review({ authorRole: 'writer', reviewerRole: 'editor' }))
+      .build();
+
+    expect(def.roles!.writer).toBeDefined();
+    expect(def.roles!.editor).toBeDefined();
+    expect(def.transitions.submit_for_review.roles).toContain('writer');
+    expect(def.transitions.approve_review.roles).toContain('editor');
+  });
+});
+
+describe('crud factory', () => {
+  it('adds draft/active/archived lifecycle (soft delete)', () => {
+    const def = model('product')
+      .field('name', field.string().required())
+      .mixin(crud())
+      .build();
+
+    expect(def.states.draft).toBeDefined();
+    expect(def.states.draft.type).toBe('initial');
+    expect(def.states.active).toBeDefined();
+    expect(def.states.archived).toBeDefined();
+
+    expect(def.transitions.publish).toBeDefined();
+    expect(def.transitions.update).toBeDefined();
+    expect(def.transitions.archive).toBeDefined();
+    expect(def.transitions.restore).toBeDefined();
+  });
+
+  it('adds hard delete when softDelete=false', () => {
+    const def = model('temp')
+      .field('data', field.string())
+      .mixin(crud({ softDelete: false }))
+      .build();
+
+    expect(def.states.deleted).toBeDefined();
+    expect(def.states.deleted.type).toBe('end');
+    expect(def.transitions.delete_record).toBeDefined();
+    expect(def.transitions.archive).toBeUndefined();
+    expect(def.transitions.restore).toBeUndefined();
+  });
+
+  it('adds CRUD fields', () => {
+    const def = model('product')
+      .mixin(crud())
+      .build();
+
+    expect(def.fields.createdBy).toBeDefined();
+    expect(def.fields.createdAt).toBeDefined();
+    expect(def.fields.updatedAt).toBeDefined();
+  });
+
+  it('does not overwrite existing fields', () => {
+    const def = model('product')
+      .field('createdBy', field.string('system'))
+      .mixin(crud())
+      .build();
+
+    // Our manually set field should be preserved
+    expect(def.fields.createdBy.default).toBe('system');
+  });
+
+  it('composable: approval + escalation', () => {
+    const def = model('po')
+      .field('amount', field.currency())
+      .state('draft', state.initial())
+      .state('pending_approval')
+      .mixin(approval({ approverRole: 'manager' }))
+      .mixin(escalation({ timeout: '48h' }))
+      .build();
+
+    // Both patterns should coexist
+    expect(def.transitions.approve).toBeDefined();
+    expect(def.transitions.reject).toBeDefined();
+    expect(def.transitions.escalate).toBeDefined();
+    expect(def.states.escalated).toBeDefined();
+    expect(def.states.approved).toBeDefined();
+  });
+});

package/src/__tests__/loader.test.ts

@@ -0,0 +1,159 @@
+import { describe, it, expect } from 'vitest';
+import { validateExperienceWorkflow, normalizeDefinition } from '../loader';
+
+const validDef = {
+  id: 'test-1',
+  slug: 'test-workflow',
+  states: [
+    { name: 'start', type: 'START' },
+    { name: 'active', type: 'REGULAR' },
+    { name: 'done', type: 'END' },
+  ],
+  transitions: [
+    { name: 'begin', from: ['start'], to: 'active' },
+    { name: 'finish', from: ['active'], to: 'done' },
+  ],
+};
+
+describe('validateExperienceWorkflow', () => {
+  it('validates a correct definition', () => {
+    const result = validateExperienceWorkflow(validDef);
+    expect(result.valid).toBe(true);
+    expect(result.errors).toHaveLength(0);
+  });
+
+  it('rejects non-object input', () => {
+    expect(validateExperienceWorkflow(null).valid).toBe(false);
+    expect(validateExperienceWorkflow('string').valid).toBe(false);
+    expect(validateExperienceWorkflow(42).valid).toBe(false);
+  });
+
+  it('requires id and slug', () => {
+    const result = validateExperienceWorkflow({ states: [{ name: 'x', type: 'START' }], transitions: [] });
+    expect(result.valid).toBe(false);
+    expect(result.errors.some(e => e.includes('id'))).toBe(true);
+    expect(result.errors.some(e => e.includes('slug'))).toBe(true);
+  });
+
+  it('requires at least one state', () => {
+    const result = validateExperienceWorkflow({ id: '1', slug: 's', states: [], transitions: [] });
+    expect(result.valid).toBe(false);
+    expect(result.errors.some(e => e.includes('at least one state'))).toBe(true);
+  });
+
+  it('requires a START state', () => {
+    const result = validateExperienceWorkflow({
+      id: '1', slug: 's',
+      states: [{ name: 'x', type: 'REGULAR' }],
+      transitions: [],
+    });
+    expect(result.valid).toBe(false);
+    expect(result.errors.some(e => e.includes('START'))).toBe(true);
+  });
+
+  it('detects duplicate state names', () => {
+    const result = validateExperienceWorkflow({
+      id: '1', slug: 's',
+      states: [{ name: 'x', type: 'START' }, { name: 'x', type: 'REGULAR' }],
+      transitions: [],
+    });
+    expect(result.valid).toBe(false);
+    expect(result.errors.some(e => e.includes('Duplicate'))).toBe(true);
+  });
+
+  it('detects unknown transition target states', () => {
+    const result = validateExperienceWorkflow({
+      id: '1', slug: 's',
+      states: [{ name: 'start', type: 'START' }],
+      transitions: [{ name: 't', from: ['start'], to: 'nonexistent' }],
+    });
+    expect(result.valid).toBe(false);
+    expect(result.errors.some(e => e.includes('unknown state'))).toBe(true);
+  });
+
+  it('detects unknown transition from states', () => {
+    const result = validateExperienceWorkflow({
+      id: '1', slug: 's',
+      states: [{ name: 'start', type: 'START' }, { name: 'end', type: 'END' }],
+      transitions: [{ name: 't', from: ['ghost'], to: 'end' }],
+    });
+    expect(result.valid).toBe(false);
+    expect(result.errors.some(e => e.includes('unknown "from" state'))).toBe(true);
+  });
+
+  it('validates on_event subscriptions', () => {
+    const result = validateExperienceWorkflow({
+      id: '1', slug: 's',
+      states: [{
+        name: 'start', type: 'START',
+        on_event: [{ actions: [{ type: 'log', config: {} }] }], // missing match
+      }],
+      transitions: [],
+    });
+    expect(result.valid).toBe(false);
+    expect(result.errors.some(e => e.includes('match'))).toBe(true);
+  });
+
+  it('warns on on_event with empty actions', () => {
+    const result = validateExperienceWorkflow({
+      id: '1', slug: 's',
+      states: [{
+        name: 'start', type: 'START',
+        on_event: [{ match: 'test.*', actions: [] }],
+      }],
+      transitions: [],
+    });
+    expect(result.valid).toBe(true); // warning, not error
+    expect(result.warnings.some(w => w.includes('no actions'))).toBe(true);
+  });
+});
+
+describe('normalizeDefinition', () => {
+  it('normalizes a valid definition', () => {
+    const def = normalizeDefinition(validDef);
+    expect(def.id).toBe('test-1');
+    expect(def.slug).toBe('test-workflow');
+    expect(def.states).toHaveLength(3);
+    expect(def.transitions).toHaveLength(2);
+  });
+
+  it('defaults state type to REGULAR', () => {
+    const def = normalizeDefinition({
+      id: '1', slug: 's',
+      states: [{ name: 'x' }],
+      transitions: [],
+    });
+    expect(def.states[0].type).toBe('REGULAR');
+  });
+
+  it('coerces string "from" to array', () => {
+    const def = normalizeDefinition({
+      id: '1', slug: 's',
+      states: [{ name: 'a', type: 'START' }, { name: 'b', type: 'END' }],
+      transitions: [{ name: 't', from: 'a', to: 'b' }],
+    });
+    expect(def.transitions[0].from).toEqual(['a']);
+  });
+
+  it('normalizes on_event with "pattern" field to "match"', () => {
+    const def = normalizeDefinition({
+      id: '1', slug: 's',
+      states: [{
+        name: 'x', type: 'START',
+        on_event: [{ pattern: 'test.*', actions: [{ type: 'log', config: {} }] }],
+      }],
+      transitions: [],
+    });
+    expect(def.states[0].on_event?.[0].match).toBe('test.*');
+  });
+
+  it('preserves state_views and experience metadata', () => {
+    const def = normalizeDefinition({
+      ...validDef,
+      state_views: { active: { title: 'Active View' } },
+      experience: { default_layout: 'grid' },
+    });
+    expect(def.state_views?.active.title).toBe('Active View');
+    expect(def.experience?.default_layout).toBe('grid');
+  });
+});

package/src/__tests__/logger.test.ts

@@ -0,0 +1,70 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { setPlayerDebug, isPlayerDebug, playerLog } from '../logger';
+
+describe('Player Logger', () => {
+  beforeEach(() => {
+    setPlayerDebug(false);
+  });
+
+  it('toggles debug mode', () => {
+    expect(isPlayerDebug()).toBe(false);
+    setPlayerDebug(true);
+    expect(isPlayerDebug()).toBe(true);
+  });
+
+  it('suppresses debug logs when debug is off', () => {
+    const spy = vi.spyOn(console, 'debug').mockImplementation(() => {});
+    playerLog({ level: 'debug', category: 'event_match', message: 'test' });
+    expect(spy).not.toHaveBeenCalled();
+    spy.mockRestore();
+  });
+
+  it('emits debug logs when debug is on', () => {
+    setPlayerDebug(true);
+    const spy = vi.spyOn(console, 'debug').mockImplementation(() => {});
+    playerLog({ level: 'debug', category: 'event_match', message: 'test' });
+    expect(spy).toHaveBeenCalledOnce();
+    spy.mockRestore();
+  });
+
+  it('emits warn logs regardless of debug setting', () => {
+    const spy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    playerLog({ level: 'warn', category: 'action_dispatch', message: 'warning' });
+    expect(spy).toHaveBeenCalledOnce();
+    spy.mockRestore();
+  });
+
+  it('emits error logs', () => {
+    const spy = vi.spyOn(console, 'error').mockImplementation(() => {});
+    playerLog({ level: 'error', category: 'transition', message: 'error msg' });
+    expect(spy).toHaveBeenCalledOnce();
+    spy.mockRestore();
+  });
+
+  it('emits info logs', () => {
+    const spy = vi.spyOn(console, 'info').mockImplementation(() => {});
+    playerLog({ level: 'info', category: 'lifecycle', message: 'info msg' });
+    expect(spy).toHaveBeenCalledOnce();
+    spy.mockRestore();
+  });
+
+  it('includes category prefix in log message', () => {
+    const spy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    playerLog({ level: 'warn', category: 'event_match', message: 'matched' });
+    expect(spy).toHaveBeenCalledWith(
+      expect.stringContaining('[player-web:event_match]'),
+      expect.anything(),
+    );
+    spy.mockRestore();
+  });
+
+  it('passes data object to console', () => {
+    const spy = vi.spyOn(console, 'info').mockImplementation(() => {});
+    playerLog({ level: 'info', category: 'lifecycle', message: 'test', data: { key: 'val' } });
+    expect(spy).toHaveBeenCalledWith(
+      expect.any(String),
+      { key: 'val' },
+    );
+    spy.mockRestore();
+  });
+});

package/src/__tests__/type-inference.test.ts

@@ -0,0 +1,160 @@
+import { describe, it, expect, expectTypeOf } from 'vitest';
+import { defineModel } from '../config/defineModel';
+import type {
+  InferFields,
+  InferTransitions,
+  InferStates,
+  InferSlug,
+  InferFieldNames,
+} from '../types/workflow-inference';
+
+// =============================================================================
+// Test model definition
+// =============================================================================
+
+const employeeModel = defineModel({
+  slug: 'employee',
+  version: '1.0.0',
+  category: 'data',
+  fields: {
+    name: { type: 'string', required: true },
+    email: { type: 'email', required: true },
+    salary: { type: 'currency', default: 0 },
+    isActive: { type: 'boolean', default: true },
+    startDate: { type: 'date' },
+    tags: { type: 'array' },
+    metadata: { type: 'object' },
+    department: { type: 'string', enum: ['engineering', 'sales', 'hr'] as const },
+    rating: { type: 'rating' },
+  },
+  states: {
+    onboarding: { type: 'initial' },
+    active: {},
+    on_leave: {},
+    terminated: { type: 'end' },
+  },
+  transitions: {
+    activate: { from: 'onboarding', to: 'active' },
+    request_leave: { from: 'active', to: 'on_leave' },
+    return_from_leave: { from: 'on_leave', to: 'active' },
+    terminate: { from: ['active', 'on_leave'], to: 'terminated' },
+  },
+} as const);
+
+type EmployeeFields = InferFields<typeof employeeModel>;
+type EmployeeTransitions = InferTransitions<typeof employeeModel>;
+type EmployeeStates = InferStates<typeof employeeModel>;
+
+// =============================================================================
+// Type-level tests
+// =============================================================================
+
+describe('InferFields', () => {
+  it('maps string-family types to string', () => {
+    expectTypeOf<EmployeeFields['name']>().toEqualTypeOf<string>();
+    expectTypeOf<EmployeeFields['email']>().toEqualTypeOf<string>();
+    expectTypeOf<EmployeeFields['department']>().toEqualTypeOf<string>();
+    expectTypeOf<EmployeeFields['startDate']>().toEqualTypeOf<string>();
+  });
+
+  it('maps numeric types to number', () => {
+    expectTypeOf<EmployeeFields['salary']>().toEqualTypeOf<number>();
+    expectTypeOf<EmployeeFields['rating']>().toEqualTypeOf<number>();
+  });
+
+  it('maps boolean type to boolean', () => {
+    expectTypeOf<EmployeeFields['isActive']>().toEqualTypeOf<boolean>();
+  });
+
+  it('maps complex types correctly', () => {
+    expectTypeOf<EmployeeFields['tags']>().toEqualTypeOf<unknown[]>();
+    expectTypeOf<EmployeeFields['metadata']>().toEqualTypeOf<Record<string, unknown>>();
+  });
+
+  it('produces an object with all field keys', () => {
+    expectTypeOf<EmployeeFields>().toHaveProperty('name');
+    expectTypeOf<EmployeeFields>().toHaveProperty('email');
+    expectTypeOf<EmployeeFields>().toHaveProperty('salary');
+    expectTypeOf<EmployeeFields>().toHaveProperty('isActive');
+    expectTypeOf<EmployeeFields>().toHaveProperty('startDate');
+    expectTypeOf<EmployeeFields>().toHaveProperty('tags');
+    expectTypeOf<EmployeeFields>().toHaveProperty('metadata');
+    expectTypeOf<EmployeeFields>().toHaveProperty('department');
+    expectTypeOf<EmployeeFields>().toHaveProperty('rating');
+  });
+
+  it('falls back to Record<string, unknown> for non-model types', () => {
+    type NoFields = InferFields<{ slug: 'x' }>;
+    expectTypeOf<NoFields>().toEqualTypeOf<Record<string, unknown>>();
+  });
+});
+
+describe('InferTransitions', () => {
+  it('extracts transition names as a union', () => {
+    expectTypeOf<EmployeeTransitions>().toEqualTypeOf<
+      'activate' | 'request_leave' | 'return_from_leave' | 'terminate'
+    >();
+  });
+
+  it('falls back to string for non-model types', () => {
+    type NoTrans = InferTransitions<{ slug: 'x' }>;
+    expectTypeOf<NoTrans>().toEqualTypeOf<string>();
+  });
+});
+
+describe('InferStates', () => {
+  it('extracts state names as a union', () => {
+    expectTypeOf<EmployeeStates>().toEqualTypeOf<
+      'onboarding' | 'active' | 'on_leave' | 'terminated'
+    >();
+  });
+
+  it('falls back to string for non-model types', () => {
+    type NoStates = InferStates<{ slug: 'x' }>;
+    expectTypeOf<NoStates>().toEqualTypeOf<string>();
+  });
+});
+
+describe('InferSlug', () => {
+  it('extracts the literal slug type', () => {
+    expectTypeOf<InferSlug<typeof employeeModel>>().toEqualTypeOf<'employee'>();
+  });
+});
+
+describe('InferFieldNames', () => {
+  it('extracts field name union', () => {
+    expectTypeOf<InferFieldNames<typeof employeeModel>>().toEqualTypeOf<
+      'name' | 'email' | 'salary' | 'isActive' | 'startDate' | 'tags' | 'metadata' | 'department' | 'rating'
+    >();
+  });
+});
+
+describe('defineModel', () => {
+  it('returns the definition unchanged at runtime', () => {
+    expect(employeeModel.slug).toBe('employee');
+    expect(Object.keys(employeeModel.fields)).toHaveLength(9);
+    expect(Object.keys(employeeModel.states)).toHaveLength(4);
+    expect(Object.keys(employeeModel.transitions)).toHaveLength(4);
+  });
+
+  it('preserves const literal types', () => {
+    // The slug should be the literal 'employee', not string
+    expectTypeOf(employeeModel.slug).toEqualTypeOf<'employee'>();
+    // Field keys should be literal union
+    expectTypeOf<keyof typeof employeeModel.fields>().toEqualTypeOf<
+      'name' | 'email' | 'salary' | 'isActive' | 'startDate' | 'tags' | 'metadata' | 'department' | 'rating'
+    >();
+  });
+
+  it('throws in dev mode when slug is missing', () => {
+    expect(() => defineModel({ slug: '', fields: {}, states: {}, transitions: {} })).toThrow(
+      'slug is required',
+    );
+  });
+
+  it('throws in dev mode when fields is missing', () => {
+    expect(() => defineModel({ slug: 'x', fields: null as any, states: {}, transitions: {} })).toThrow(
+      'fields object is required',
+    );
+  });
+});