@mmapp/react 0.1.0-alpha.1

package/src/__tests__/actionCreators.test.ts

@@ -0,0 +1,179 @@
+import { describe, it, expect } from 'vitest';
+import { createActions } from '../actionCreators';
+import { setField } from '../actions';
+import { model, state, transition } from '../builders';
+
+// =============================================================================
+// createActions
+// =============================================================================
+
+describe('createActions', () => {
+  const actions = createActions({
+    authenticate: { handler: 'actions/auth.server.ts' },
+    destroySession: { handler: 'actions/auth.server.ts' },
+    resetPassword: { handler: 'actions/auth.server.ts', functionName: 'handleReset' },
+    sendEmail: { handler: 'actions/email.server.ts', mode: 'manual' },
+  });
+
+  it('returns an object with a creator for each manifest entry', () => {
+    expect(typeof actions.authenticate).toBe('function');
+    expect(typeof actions.destroySession).toBe('function');
+    expect(typeof actions.resetPassword).toBe('function');
+    expect(typeof actions.sendEmail).toBe('function');
+  });
+
+  it('produces a valid ActionDefinition with no config', () => {
+    const result = actions.destroySession();
+
+    expect(result).toEqual({
+      id: 'server-destroy-session',
+      type: 'server:destroySession',
+      mode: 'auto',
+      config: {
+        __handler: 'actions/auth.server.ts',
+      },
+    });
+  });
+
+  it('produces a valid ActionDefinition with config', () => {
+    const result = actions.authenticate({ method: 'login', email: 'test@example.com' });
+
+    expect(result).toEqual({
+      id: 'server-authenticate',
+      type: 'server:authenticate',
+      mode: 'auto',
+      config: {
+        method: 'login',
+        email: 'test@example.com',
+        __handler: 'actions/auth.server.ts',
+      },
+    });
+  });
+
+  it('includes functionName in config when specified', () => {
+    const result = actions.resetPassword({ token: 'abc123' });
+
+    expect(result.config).toEqual({
+      token: 'abc123',
+      __handler: 'actions/auth.server.ts',
+      __functionName: 'handleReset',
+    });
+  });
+
+  it('respects the mode from the manifest entry', () => {
+    const result = actions.sendEmail();
+    expect(result.mode).toBe('manual');
+  });
+
+  it('defaults mode to auto when not specified', () => {
+    const result = actions.authenticate();
+    expect(result.mode).toBe('auto');
+  });
+
+  it('generates kebab-case IDs from camelCase names', () => {
+    const result = actions.destroySession();
+    expect(result.id).toBe('server-destroy-session');
+  });
+
+  it('preserves the original action name in the type', () => {
+    const result = actions.resetPassword();
+    expect(result.type).toBe('server:resetPassword');
+  });
+
+  it('produces actions compatible with .do() / onEnter / onExit arrays', () => {
+    const result = actions.authenticate({ method: 'login' });
+
+    // ActionDefinition requires id, type, and optional mode/config/condition
+    expect(result).toHaveProperty('id');
+    expect(result).toHaveProperty('type');
+    expect(typeof result.id).toBe('string');
+    expect(typeof result.type).toBe('string');
+  });
+
+  it('works with an empty manifest', () => {
+    const empty = createActions({});
+    expect(Object.keys(empty)).toHaveLength(0);
+  });
+
+  it('each call produces a fresh ActionDefinition', () => {
+    const a = actions.authenticate({ method: 'login' });
+    const b = actions.authenticate({ method: 'register' });
+
+    expect(a).not.toBe(b);
+    expect(a.config!.method).toBe('login');
+    expect(b.config!.method).toBe('register');
+  });
+
+  it('user config does not overwrite __handler', () => {
+    const result = actions.authenticate({ __handler: 'hacked.ts' });
+    // User config is spread first, then __handler overwrites
+    expect(result.config!.__handler).toBe('actions/auth.server.ts');
+  });
+});
+
+// =============================================================================
+// Integration: createActions + builder API
+// =============================================================================
+
+describe('createActions integration with model builder', () => {
+  const actions = createActions({
+    authenticate: { handler: 'actions/auth.server.ts' },
+    destroySession: { handler: 'actions/auth.server.ts' },
+  });
+
+  it('works with TransitionBuilder.do()', () => {
+    const result = model('auth')
+      .state('unauthenticated', state.initial())
+      .state('authenticating')
+      .state('authenticated')
+      .transition('login',
+        transition.from('unauthenticated').to('authenticating')
+          .do(actions.authenticate({ method: 'login' }))
+      )
+      .build();
+
+    expect(result.transitions.login.actions).toHaveLength(1);
+    expect(result.transitions.login.actions![0].type).toBe('server:authenticate');
+    expect(result.transitions.login.actions![0].config).toMatchObject({ method: 'login' });
+  });
+
+  it('works with StateBuilder.onEnter()', () => {
+    const result = model('auth')
+      .state('authenticated', state.initial()
+        .onEnter(actions.authenticate({ method: 'token' }))
+      )
+      .build();
+
+    expect(result.states.authenticated.onEnter).toHaveLength(1);
+    expect(result.states.authenticated.onEnter![0].type).toBe('server:authenticate');
+  });
+
+  it('works with StateBuilder.onExit()', () => {
+    const result = model('auth')
+      .state('authenticated', state.initial()
+        .onExit(actions.destroySession())
+      )
+      .build();
+
+    expect(result.states.authenticated.onExit).toHaveLength(1);
+    expect(result.states.authenticated.onExit![0].type).toBe('server:destroySession');
+  });
+
+  it('works alongside plain action helpers', () => {
+    const result = model('auth')
+      .state('unauthenticated', state.initial())
+      .state('authenticated')
+      .transition('login',
+        transition.from('unauthenticated').to('authenticated')
+          .do(
+            actions.authenticate({ method: 'login' }),
+            setField('lastLogin', 'NOW()'),
+          )
+      )
+      .build();
+
+    expect(result.transitions.login.actions).toHaveLength(2);
+    expect(result.transitions.login.actions![0].type).toBe('server:authenticate');
+    expect(result.transitions.login.actions![1].type).toBe('set_field');
+  });
+});

package/src/__tests__/builders.test.ts

@@ -0,0 +1,336 @@
+import { describe, it, expect } from 'vitest';
+import { model, field, state, transition, StateBuilder } from '../builders';
+import { setField, logEvent, serverAction } from '../actions';
+
+describe('StateBuilder.to() — inline transitions', () => {
+  it('declares a single outgoing transition', () => {
+    const result = model('test')
+      .state('draft', state.initial().to('review', 'submit'))
+      .state('review')
+      .build();
+
+    expect(result.transitions.submit).toBeDefined();
+    expect(result.transitions.submit.from).toBe('draft');
+    expect(result.transitions.submit.to).toBe('review');
+  });
+
+  it('declares multiple outgoing transitions from one state', () => {
+    const result = model('test')
+      .state('review', new StateBuilder()
+        .to('approved', 'approve')
+        .to('rejected', 'reject')
+      )
+      .build();
+
+    expect(result.transitions.approve).toEqual({ from: 'review', to: 'approved' });
+    expect(result.transitions.reject).toEqual({ from: 'review', to: 'rejected' });
+  });
+
+  it('supports transition configuration via callback', () => {
+    const result = model('test')
+      .state('draft', state.initial()
+        .to('review', 'submit', t => t.require('title', 'body').roles('author'))
+      )
+      .state('review')
+      .build();
+
+    expect(result.transitions.submit.requiredFields).toEqual(['title', 'body']);
+    expect(result.transitions.submit.roles).toEqual(['author']);
+  });
+
+  it('standalone transitions override inline transitions', () => {
+    const result = model('test')
+      .state('draft', state.initial().to('review', 'submit'))
+      .state('review')
+      .transition('submit', transition.from('draft').to('review').roles('admin'))
+      .build();
+
+    expect(result.transitions.submit.roles).toEqual(['admin']);
+  });
+
+  it('inline transitions work with actions', () => {
+    const result = model('test')
+      .state('active', new StateBuilder()
+        .to('inactive', 'deactivate', t =>
+          t.do(setField('active', 'false'), logEvent('deactivated'))
+        )
+      )
+      .build();
+
+    expect(result.transitions.deactivate.actions).toHaveLength(2);
+    expect(result.transitions.deactivate.actions![0].type).toBe('set_field');
+    expect(result.transitions.deactivate.actions![1].type).toBe('log_event');
+  });
+
+  it('coexists with standalone transitions on the same model', () => {
+    const result = model('test')
+      .state('draft', state.initial().to('review', 'submit'))
+      .state('review')
+      .state('published')
+      .transition('publish', transition.from('review').to('published'))
+      .build();
+
+    expect(result.transitions.submit.from).toBe('draft');
+    expect(result.transitions.publish.from).toBe('review');
+  });
+});
+
+describe('ModelBuilder.line() — auto-named transitions', () => {
+  it('auto-generates transition names from state pairs', () => {
+    const result = model('order')
+      .line(
+        ['placed', state.initial()],
+        'confirmed',
+        'shipped',
+        ['delivered', state.end()],
+      )
+      .build();
+
+    expect(Object.keys(result.states).sort()).toEqual(
+      ['confirmed', 'delivered', 'placed', 'shipped'].sort()
+    );
+    expect(result.states.placed.type).toBe('initial');
+    expect(result.states.delivered.type).toBe('end');
+    expect(result.transitions.placed_to_confirmed).toEqual({ from: 'placed', to: 'confirmed' });
+    expect(result.transitions.confirmed_to_shipped).toEqual({ from: 'confirmed', to: 'shipped' });
+    expect(result.transitions.shipped_to_delivered).toEqual({ from: 'shipped', to: 'delivered' });
+  });
+
+  it('configures incoming edge via tuple callback', () => {
+    const result = model('test')
+      .line(
+        'draft',
+        ['review', t => t.require('title', 'body')],
+        ['approved', t => t.roles('manager')],
+      )
+      .build();
+
+    expect(result.transitions.draft_to_review.requiredFields).toEqual(['title', 'body']);
+    expect(result.transitions.review_to_approved.roles).toEqual(['manager']);
+  });
+
+  it('branching via multiple lines', () => {
+    const result = model('order')
+      .line(
+        ['placed', state.initial()],
+        'confirmed',
+        'shipped',
+      )
+      .line('placed', 'cancelled')
+      .line('confirmed', 'cancelled')
+      .build();
+
+    expect(Object.keys(result.transitions).sort()).toEqual([
+      'confirmed_to_cancelled',
+      'confirmed_to_shipped',
+      'placed_to_cancelled',
+      'placed_to_confirmed',
+    ].sort());
+  });
+
+  it('two-state line', () => {
+    const result = model('test')
+      .line('active', 'inactive')
+      .build();
+
+    expect(result.transitions.active_to_inactive).toEqual({ from: 'active', to: 'inactive' });
+  });
+
+  it('self-loop', () => {
+    const result = model('test')
+      .line('active', 'active')
+      .build();
+
+    expect(result.transitions.active_to_active).toEqual({ from: 'active', to: 'active' });
+  });
+
+  it('with actions on edges', () => {
+    const result = model('test')
+      .line(
+        'draft',
+        ['published', t => t.do(logEvent('published'), setField('publishedAt', 'NOW()'))],
+      )
+      .build();
+
+    const tr = result.transitions.draft_to_published;
+    expect(tr.actions).toHaveLength(2);
+    expect(tr.actions![0].type).toBe('log_event');
+    expect(tr.actions![1].type).toBe('set_field');
+  });
+
+  it('works with field definitions', () => {
+    const result = model('invoice')
+      .field('amount', field.currency().required())
+      .line(
+        ['draft', state.initial()],
+        ['sent', t => t.require('amount')],
+        ['paid', state.end()],
+      )
+      .build();
+
+    expect(result.fields.amount.type).toBe('currency');
+    expect(result.transitions.draft_to_sent.requiredFields).toEqual(['amount']);
+  });
+
+  it('mixes with .state() and .transition() methods', () => {
+    const result = model('test')
+      .state('error', new StateBuilder().onEnter(setField('hasError', 'true')))
+      .line(
+        ['draft', state.initial()],
+        'review',
+        ['published', state.end()],
+      )
+      .transition('fail', transition.from('review').to('error'))
+      .build();
+
+    expect(result.states.error.onEnter).toHaveLength(1);
+    expect(result.states.draft.type).toBe('initial');
+    expect(result.transitions.draft_to_review).toBeDefined();
+    expect(result.transitions.fail.from).toBe('review');
+  });
+
+  it('shared states across lines are unified', () => {
+    const result = model('auth')
+      .line(
+        ['unauthenticated', state.initial()],
+        'authenticating',
+        'authenticated',
+      )
+      .line(
+        'unauthenticated',
+        'authenticating',
+        'authenticated',
+      )
+      .build();
+
+    // States appear only once
+    expect(Object.keys(result.states)).toEqual([
+      'unauthenticated', 'authenticating', 'authenticated',
+    ]);
+    expect(result.states.unauthenticated.type).toBe('initial');
+  });
+});
+
+describe('ModelBuilder.line() — named transitions via tuple', () => {
+  it('overrides auto-name with explicit transition name', () => {
+    const result = model('test')
+      .line(
+        'draft',
+        ['review', 'submit'],
+        ['published', 'approve'],
+      )
+      .build();
+
+    expect(result.transitions.submit).toEqual({ from: 'draft', to: 'review' });
+    expect(result.transitions.approve).toEqual({ from: 'review', to: 'published' });
+    // Auto-named versions should NOT exist
+    expect(result.transitions.draft_to_review).toBeUndefined();
+    expect(result.transitions.review_to_published).toBeUndefined();
+  });
+
+  it('named transition with configuration', () => {
+    const result = model('test')
+      .line(
+        'draft',
+        ['review', 'submit', t => t.require('title')],
+        ['published', 'approve', t => t.roles('manager')],
+      )
+      .build();
+
+    expect(result.transitions.submit.requiredFields).toEqual(['title']);
+    expect(result.transitions.approve.roles).toEqual(['manager']);
+  });
+
+  it('mix named and auto-named in same line', () => {
+    const result = model('test')
+      .line(
+        'draft',
+        ['review', 'submit'],      // named
+        'published',                // auto-named: review_to_published
+      )
+      .build();
+
+    expect(result.transitions.submit).toBeDefined();
+    expect(result.transitions.review_to_published).toBeDefined();
+  });
+
+  it('merges from-states for named transitions across lines', () => {
+    const result = model('order')
+      .line('placed', ['cancelled', 'cancel'])
+      .line('confirmed', ['cancelled', 'cancel'])
+      .build();
+
+    const cancelFrom = result.transitions.cancel.from;
+    expect(Array.isArray(cancelFrom)).toBe(true);
+    expect(cancelFrom).toContain('placed');
+    expect(cancelFrom).toContain('confirmed');
+  });
+});
+
+describe('ModelBuilder.line() — complete auth example', () => {
+  it('models auth with auto-named transitions', () => {
+    const result = model('mod-authentication')
+      .field('errorMessage', field.string(''))
+
+      // Login flow
+      .line(
+        ['unauthenticated', state.initial().onEnter(setField('errorMessage', '""'))],
+        ['authenticating', t => t.do(serverAction('authenticate', { method: 'login' }))],
+        'authenticated',
+      )
+
+      // Error handling
+      .line('authenticating', 'error')
+      .line('error', 'unauthenticated')
+
+      // Logout
+      .line(
+        'authenticated',
+        ['unauthenticated', t => t.do(serverAction('destroy_session'))],
+      )
+      .build();
+
+    expect(result.states.unauthenticated.type).toBe('initial');
+    expect(result.transitions.unauthenticated_to_authenticating.actions![0].type).toBe('server:authenticate');
+    expect(result.transitions.authenticated_to_unauthenticated.actions![0].type).toBe('server:destroy_session');
+    expect(result.transitions.authenticating_to_error).toBeDefined();
+    expect(result.transitions.error_to_unauthenticated).toBeDefined();
+  });
+
+  it('models auth with named transitions', () => {
+    const result = model('mod-authentication')
+      .field('errorMessage', field.string(''))
+
+      .line(
+        ['unauthenticated', state.initial().onEnter(setField('errorMessage', '""'))],
+        ['authenticating', 'login', t => t.do(serverAction('authenticate', { method: 'login' }))],
+        ['authenticated', 'login_success'],
+      )
+      .line(
+        'unauthenticated',
+        ['authenticating', 'signup', t => t.do(serverAction('authenticate', { method: 'signup' }))],
+        ['authenticated', 'signup_success'],
+      )
+      .line('authenticating', ['error', 'login_error'])
+      .line('authenticating', ['error', 'signup_error'])
+      .line('error', ['unauthenticated', 'retry'])
+      .line(
+        'authenticated',
+        ['unauthenticated', 'logout', t => t.do(serverAction('destroy_session'))],
+      )
+      .build();
+
+    expect(result.states.unauthenticated.type).toBe('initial');
+    expect(result.transitions.login.actions![0].type).toBe('server:authenticate');
+    expect(result.transitions.signup.actions![0].type).toBe('server:authenticate');
+    expect(result.transitions.logout.actions![0].type).toBe('server:destroy_session');
+    expect(result.transitions.login_success.from).toBe('authenticating');
+    expect(result.transitions.signup_success.from).toBe('authenticating');
+    expect(result.transitions.retry.from).toBe('error');
+    expect(result.transitions.retry.to).toBe('unauthenticated');
+
+    // login_error and signup_error merge from-states
+    const loginErrorFrom = result.transitions.login_error.from;
+    expect(loginErrorFrom).toBe('authenticating');
+  });
+});

package/src/__tests__/defineBlueprint-composition.test.ts

@@ -0,0 +1,106 @@
+/**
+ * Tests for BlueprintDependency composition types — routeConfig, slotMapping.
+ */
+
+import { describe, it, expect } from 'vitest';
+import { defineBlueprint, type BlueprintDependency, type ModuleRouteConfig } from '../config/defineBlueprint';
+
+describe('BlueprintDependency composition types', () => {
+  it('accepts routeConfig with prefix', () => {
+    const dep: BlueprintDependency = {
+      slug: 'mod-authentication',
+      version: '>=3.0.0',
+      routeConfig: {
+        prefix: '/auth',
+      },
+    };
+    expect(dep.routeConfig?.prefix).toBe('/auth');
+  });
+
+  it('accepts routeConfig with per-route remapping', () => {
+    const dep: BlueprintDependency = {
+      slug: 'mod-authentication',
+      routeConfig: {
+        prefix: '/auth',
+        routes: {
+          '/login': '/',
+          '/signup': '/join',
+          '/profile': false,
+        },
+      },
+    };
+    expect(dep.routeConfig?.routes?.['/login']).toBe('/');
+    expect(dep.routeConfig?.routes?.['/profile']).toBe(false);
+  });
+
+  it('accepts slotMapping', () => {
+    const dep: BlueprintDependency = {
+      slug: 'mod-authentication',
+      slotMapping: {
+        'auth:login-providers': 'app:social-login',
+        'auth:profile-sections': 'app:settings-tabs',
+      },
+    };
+    expect(dep.slotMapping?.['auth:login-providers']).toBe('app:social-login');
+  });
+
+  it('accepts config', () => {
+    const dep: BlueprintDependency = {
+      slug: 'mod-authentication',
+      config: {
+        layout: 'card',
+        methods: ['email-password', 'google'],
+      },
+    };
+    expect(dep.config?.layout).toBe('card');
+  });
+
+  it('works in defineBlueprint with full dependency config', () => {
+    const blueprint = defineBlueprint({
+      slug: 'employee-salary-tracking',
+      name: 'Employee Salary Tracking',
+      version: '1.0.0',
+      dependencies: [
+        {
+          slug: 'mod-authentication',
+          version: '>=3.0.0',
+          required: true,
+          routeConfig: {
+            prefix: '/auth',
+            routes: { '/login': '/' },
+          },
+          slotMapping: {
+            'auth:profile-sections': 'app:settings-tabs',
+          },
+          config: {
+            layout: 'split',
+          },
+        },
+      ],
+    });
+
+    expect(blueprint.dependencies).toHaveLength(1);
+    expect(blueprint.dependencies![0].routeConfig?.prefix).toBe('/auth');
+    expect(blueprint.dependencies![0].slotMapping?.['auth:profile-sections']).toBe('app:settings-tabs');
+  });
+
+  it('ModuleRouteConfig type works independently', () => {
+    const config: ModuleRouteConfig = {
+      prefix: '/account',
+      routes: {
+        '/login': '/signin',
+        '/register': false,
+      },
+    };
+    expect(config.prefix).toBe('/account');
+  });
+
+  it('backward compatible — all new fields are optional', () => {
+    const dep: BlueprintDependency = {
+      slug: 'mod-auth',
+    };
+    expect(dep.routeConfig).toBeUndefined();
+    expect(dep.slotMapping).toBeUndefined();
+    expect(dep.config).toBeUndefined();
+  });
+});