@mmapp/react 0.1.0-alpha.1

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@mmapp/react",
+  "version": "0.1.0-alpha.1",
+  "description": "React integration for the MindMatrix Player — hooks, components, and WebSocket bridge for browser-side workflow engines",
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    },
+    "./atoms": {
+      "types": "./dist/atoms/index.d.ts",
+      "import": "./dist/atoms/index.mjs",
+      "require": "./dist/atoms/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts --external react",
+    "dev": "tsup src/index.ts --format cjs,esm --dts --external react --watch",
+    "test": "vitest run",
+    "test:watch": "vitest --watch",
+    "type-check": "tsc --noEmit"
+  },
+  "peerDependencies": {
+    "react": ">=18.0.0",
+    "@tanstack/react-query": ">=5.0.0"
+  },
+  "dependencies": {
+    "@mmapp/player-core": "^0.1.0-alpha.1"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/package.json.backup

@@ -0,0 +1,41 @@
+{
+  "name": "@mindmatrix/react",
+  "version": "0.1.0",
+  "description": "React integration for the MindMatrix Player — hooks, components, and WebSocket bridge for browser-side workflow engines",
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    },
+    "./atoms": {
+      "types": "./dist/atoms/index.d.ts",
+      "import": "./dist/atoms/index.mjs",
+      "require": "./dist/atoms/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts --external react",
+    "dev": "tsup src/index.ts --format cjs,esm --dts --external react --watch",
+    "test": "vitest run",
+    "test:watch": "vitest --watch",
+    "type-check": "tsc --noEmit"
+  },
+  "peerDependencies": {
+    "react": ">=18.0.0",
+    "@tanstack/react-query": ">=5.0.0"
+  },
+  "dependencies": {
+    "@mindmatrix/player-core": "workspace:*"
+  },
+  "devDependencies": {
+    "@types/react": "^19.0.0",
+    "react": "^19.0.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.4.0",
+    "vitest": "^1.5.0"
+  }
+}

package/src/Blueprint.ts

@@ -0,0 +1,216 @@
+/**
+ * Blueprint — base class for declarative workflow module authoring.
+ *
+ * Users extend this class and override define() to declare models,
+ * views, server actions, and sub-modules using a clean imperative API.
+ *
+ * @example
+ * ```typescript
+ * import { Blueprint, field, state, transition } from '@mindmatrix/react';
+ *
+ * class AuthModule extends Blueprint {
+ *   slug = 'mod-authentication';
+ *   version = '1.0.0';
+ *   category = 'module';
+ *
+ *   define() {
+ *     this.model('authentication', m => m
+ *       .field('email', field.email().required())
+ *       .state('unauthenticated', state.initial())
+ *       .state('authenticated')
+ *       .transition('login', transition.from('unauthenticated').to('authenticated'))
+ *     );
+ *     this.view('login', { route: '/login', component: 'LoginForm' });
+ *     this.serverAction('authenticate', { handler: 'actions/auth.server.ts' });
+ *   }
+ * }
+ *
+ * export default new AuthModule().build();
+ * ```
+ */
+
+import {
+  type ModelDefinition,
+} from './config/defineModel';
+import { ModelBuilder } from './builders';
+import { defineBlueprint, type BlueprintConfig, type BlueprintManifest } from './config/defineBlueprint';
+
+// =============================================================================
+// Types
+// =============================================================================
+
+/** A view declaration within a blueprint. */
+export interface BlueprintViewDeclaration {
+  /** Route path (e.g., '/login'). */
+  route?: string;
+  /** Component reference (file path or component name). */
+  component: string;
+  /** Route guard expression. */
+  guard?: string;
+  /** Label for navigation. */
+  label?: string;
+  /** Route group. */
+  group?: string;
+  /** Icon name. */
+  icon?: string;
+}
+
+/** A server action declaration within a blueprint. */
+export interface BlueprintServerActionDeclaration {
+  /** Handler file path. */
+  handler: string;
+  /** Function name in the handler file. */
+  functionName?: string;
+  /** Description. */
+  description?: string;
+}
+
+// =============================================================================
+// Blueprint Base Class
+// =============================================================================
+
+export abstract class Blueprint {
+  /** Unique identifier (kebab-case). Must be set by subclass. */
+  abstract slug: string;
+  /** Semantic version. Must be set by subclass. */
+  abstract version: string;
+
+  /** Display name (defaults to slug). */
+  name?: string;
+  /** Description. */
+  description?: string;
+  /** Category or categories. */
+  category?: string | string[];
+  /** Author. */
+  author?: string;
+  /** Tags. */
+  tags?: string[];
+
+  // Internal collections populated by define()
+  private _models = new Map<string, ModelDefinition>();
+  private _views = new Map<string, BlueprintViewDeclaration>();
+  private _serverActions = new Map<string, BlueprintServerActionDeclaration>();
+  private _dependencies: { slug: string; version?: string }[] = [];
+  private _capabilities: string[] = [];
+
+  /**
+   * Override this method to declare models, views, actions, etc.
+   * Called automatically by build().
+   */
+  abstract define(): void;
+
+  /**
+   * Declare a model within this blueprint.
+   *
+   * @param name - Model name (will be prefixed with blueprint slug)
+   * @param builderFn - Callback that configures a ModelBuilder
+   */
+  protected model(
+    name: string,
+    builderFn: (m: ModelBuilder) => ModelBuilder,
+  ): void {
+    const slug = `${this.slug}-${name}`;
+    const builder = new ModelBuilder(slug);
+    const configured = builderFn(builder);
+    this._models.set(name, configured.build());
+  }
+
+  /**
+   * Declare a view/page within this blueprint.
+   *
+   * @param name - View name
+   * @param declaration - Route, component, guard, etc.
+   */
+  protected view(name: string, declaration: BlueprintViewDeclaration): void {
+    this._views.set(name, declaration);
+  }
+
+  /**
+   * Declare a server action within this blueprint.
+   *
+   * @param name - Action name (becomes server:{name})
+   * @param declaration - Handler file and function
+   */
+  protected serverAction(name: string, declaration: BlueprintServerActionDeclaration): void {
+    this._serverActions.set(name, declaration);
+  }
+
+  /**
+   * Declare a dependency on another module/blueprint.
+   */
+  protected dependency(slug: string, version?: string): void {
+    this._dependencies.push({ slug, version });
+  }
+
+  /**
+   * Declare a required capability.
+   */
+  protected capability(...caps: string[]): void {
+    this._capabilities.push(...caps);
+  }
+
+  /**
+   * Build the blueprint. Calls define(), collects all declarations,
+   * and returns a BlueprintManifest suitable for defineBlueprint().
+   */
+  build(): BlueprintManifest {
+    // Call user's define() to populate collections
+    this._models.clear();
+    this._views.clear();
+    this._serverActions.clear();
+    this._dependencies = [];
+    this._capabilities = [];
+    this.define();
+
+    // Build blueprint config
+    const config: BlueprintConfig = {
+      slug: this.slug,
+      name: this.name || this.slug,
+      version: this.version,
+      description: this.description,
+      author: this.author,
+      tags: this.tags,
+      category: this.category || 'blueprint',
+      models: Array.from(this._models.keys()).map(k => `models/${k}`),
+    };
+
+    // Routes from views
+    if (this._views.size > 0) {
+      config.routes = Array.from(this._views.entries()).map(([name, v]) => ({
+        path: v.route || `/${name}`,
+        view: `app/${name}`,
+        label: v.label,
+        guard: v.guard,
+        group: v.group,
+        icon: v.icon,
+      }));
+    }
+
+    // Actions from server actions
+    if (this._serverActions.size > 0) {
+      config.actions = Array.from(this._serverActions.entries()).map(([name, a]) => ({
+        id: `server:${name}`,
+        handler: a.handler,
+        functionName: a.functionName || name,
+        description: a.description,
+      }));
+    }
+
+    if (this._dependencies.length > 0) {
+      config.dependencies = this._dependencies;
+    }
+    if (this._capabilities.length > 0) {
+      config.capabilities = this._capabilities;
+    }
+
+    return defineBlueprint(config);
+  }
+
+  /**
+   * Get all model definitions declared by this blueprint.
+   */
+  getModels(): Map<string, ModelDefinition> {
+    if (this._models.size === 0) this.define();
+    return new Map(this._models);
+  }
+}

package/src/__tests__/Blueprint.test.ts

@@ -0,0 +1,106 @@
+import { describe, it, expect } from 'vitest';
+import { Blueprint } from '../Blueprint';
+import { field, state, transition } from '../builders';
+
+class TestModule extends Blueprint {
+  slug = 'test-module';
+  version = '1.0.0';
+  name = 'Test Module';
+  category = 'module';
+
+  define() {
+    this.model('user', m => m
+      .field('email', field.email().required())
+      .field('name', field.string())
+      .state('active', state.initial())
+      .state('inactive', state.end())
+      .transition('deactivate', transition.from('active').to('inactive'))
+    );
+
+    this.view('login', { route: '/login', component: 'LoginForm', label: 'Login' });
+    this.view('profile', { route: '/profile', component: 'Profile', guard: 'context.actor_id != null' });
+
+    this.serverAction('authenticate', { handler: 'actions/auth.server.ts', description: 'Validate credentials' });
+
+    this.dependency('other-module', '>=1.0.0');
+    this.capability('email');
+  }
+}
+
+describe('Blueprint', () => {
+  it('builds a valid BlueprintManifest', () => {
+    const module = new TestModule();
+    const manifest = module.build();
+
+    expect(manifest.slug).toBe('test-module');
+    expect(manifest.version).toBe('1.0.0');
+    expect(manifest.name).toBe('Test Module');
+    expect(manifest.category).toBe('module');
+  });
+
+  it('collects model declarations', () => {
+    const module = new TestModule();
+    const manifest = module.build();
+
+    expect(manifest.models).toEqual(['models/user']);
+  });
+
+  it('collects view declarations as routes', () => {
+    const module = new TestModule();
+    const manifest = module.build();
+
+    expect(manifest.routes).toHaveLength(2);
+    expect(manifest.routes![0].path).toBe('/login');
+    expect(manifest.routes![0].label).toBe('Login');
+    expect(manifest.routes![1].path).toBe('/profile');
+    expect(manifest.routes![1].guard).toBe('context.actor_id != null');
+  });
+
+  it('collects server action declarations', () => {
+    const module = new TestModule();
+    const manifest = module.build();
+
+    expect(manifest.actions).toHaveLength(1);
+    expect(manifest.actions![0].id).toBe('server:authenticate');
+    expect(manifest.actions![0].handler).toBe('actions/auth.server.ts');
+  });
+
+  it('collects dependencies and capabilities', () => {
+    const module = new TestModule();
+    const manifest = module.build();
+
+    expect(manifest.dependencies).toHaveLength(1);
+    expect(manifest.dependencies![0].slug).toBe('other-module');
+    expect(manifest.capabilities).toEqual(['email']);
+  });
+
+  it('provides model definitions via getModels()', () => {
+    const module = new TestModule();
+    const models = module.getModels();
+
+    expect(models.size).toBe(1);
+    const userModel = models.get('user')!;
+    expect(userModel.slug).toBe('test-module-user');
+    expect(Object.keys(userModel.fields)).toContain('email');
+    expect(Object.keys(userModel.states)).toContain('active');
+    expect(Object.keys(userModel.transitions)).toContain('deactivate');
+  });
+
+  it('resets state on each build() call', () => {
+    const module = new TestModule();
+    const m1 = module.build();
+    const m2 = module.build();
+
+    // Should not accumulate
+    expect(m1.routes).toHaveLength(2);
+    expect(m2.routes).toHaveLength(2);
+  });
+
+  it('applies default mode and runtime', () => {
+    const module = new TestModule();
+    const manifest = module.build();
+
+    expect(manifest.mode).toBe('infer');
+    expect(manifest.defaultRuntime).toBe('local');
+  });
+});

package/src/__tests__/action-context.test.ts

@@ -0,0 +1,166 @@
+import { describe, it, expect } from 'vitest';
+import { model, state, field, transition } from '../builders';
+import type { ActionHandler } from '../builders';
+import { setField } from '../actions';
+
+describe('Inline action bodies — ActionContext handlers', () => {
+  describe('StateBuilder.onEnter with handler', () => {
+    it('stores handler as inline_handler action', () => {
+      const handler: ActionHandler = async (ctx) => {
+        ctx.setField('activatedAt', new Date().toISOString());
+        ctx.log('User activated');
+      };
+
+      const result = model('test')
+        .state('active', state.initial().onEnter(handler))
+        .state('done', state.end())
+        .transition('finish', transition.from('active').to('done'))
+        .build();
+
+      const actions = result.states.active.onEnter!;
+      expect(actions).toHaveLength(1);
+      expect(actions[0].type).toBe('inline_handler');
+      expect(actions[0].id).toMatch(/^inline-on-enter-/);
+      expect(actions[0].config!.handler).toContain('setField');
+      expect(actions[0].config!.handler).toContain('activatedAt');
+    });
+
+    it('still accepts regular ActionDefinition array', () => {
+      const result = model('test')
+        .state('active', state.initial().onEnter(
+          setField('status', '"active"'),
+        ))
+        .state('done', state.end())
+        .transition('finish', transition.from('active').to('done'))
+        .build();
+
+      const actions = result.states.active.onEnter!;
+      expect(actions).toHaveLength(1);
+      expect(actions[0].type).toBe('set_field');
+    });
+  });
+
+  describe('StateBuilder.onExit with handler', () => {
+    it('stores handler as inline_handler action', () => {
+      const handler: ActionHandler = (ctx) => {
+        ctx.log('Leaving state');
+        ctx.setFields({ cleanedUp: true });
+      };
+
+      const result = model('test')
+        .state('active', state.initial().onExit(handler))
+        .state('done', state.end())
+        .transition('finish', transition.from('active').to('done'))
+        .build();
+
+      const actions = result.states.active.onExit!;
+      expect(actions).toHaveLength(1);
+      expect(actions[0].type).toBe('inline_handler');
+      expect(actions[0].id).toMatch(/^inline-on-exit-/);
+      expect(actions[0].config!.handler).toContain('cleanedUp');
+    });
+  });
+
+  describe('TransitionBuilder.do with handler', () => {
+    it('stores handler as inline_handler action on transition', () => {
+      const handler: ActionHandler = async (ctx) => {
+        ctx.setField('approvedAt', new Date().toISOString());
+        await ctx.notify('requester', 'Your request was approved');
+        await ctx.serverAction('send_email', { template: 'approved' });
+      };
+
+      const result = model('test')
+        .state('review', state.initial())
+        .state('approved', state.end())
+        .transition('approve', transition.from('review').to('approved').do(handler))
+        .build();
+
+      const actions = result.transitions.approve.actions!;
+      expect(actions).toHaveLength(1);
+      expect(actions[0].type).toBe('inline_handler');
+      expect(actions[0].config!.handler).toContain('notify');
+      expect(actions[0].config!.handler).toContain('serverAction');
+      expect(actions[0].config!.handler).toContain('send_email');
+    });
+
+    it('can mix handler with regular actions', () => {
+      const result = model('test')
+        .state('a', state.initial())
+        .state('b', state.end())
+        .transition('go', transition.from('a').to('b')
+          .do(setField('step', '"1"'))
+          .do(async (ctx) => { ctx.log('step 2'); })
+        )
+        .build();
+
+      const actions = result.transitions.go.actions!;
+      expect(actions).toHaveLength(2);
+      expect(actions[0].type).toBe('set_field');
+      expect(actions[1].type).toBe('inline_handler');
+    });
+  });
+
+  describe('TypedTransitionBuilder.do with handler', () => {
+    it('stores handler via typed callback form', () => {
+      const result = model('test')
+        .state('draft', state.initial())
+        .state('published', state.end())
+        .transition('publish', t =>
+          t.from('draft').to('published').do(async (ctx) => {
+            ctx.setField('publishedAt', new Date().toISOString());
+            await ctx.spawn('notification', { type: 'published' });
+          })
+        )
+        .build();
+
+      const actions = result.transitions.publish.actions!;
+      expect(actions).toHaveLength(1);
+      expect(actions[0].type).toBe('inline_handler');
+      expect(actions[0].config!.handler).toContain('spawn');
+      expect(actions[0].config!.handler).toContain('publishedAt');
+    });
+  });
+
+  describe('Handler function serialization', () => {
+    it('serializes arrow functions', () => {
+      const result = model('test')
+        .state('a', state.initial().onEnter((ctx) => { ctx.log('hello'); }))
+        .state('b', state.end())
+        .transition('go', transition.from('a').to('b'))
+        .build();
+
+      const handler = result.states.a.onEnter![0].config!.handler as string;
+      expect(handler).toContain('log');
+      expect(handler).toContain('hello');
+    });
+
+    it('serializes async arrow functions', () => {
+      const result = model('test')
+        .state('a', state.initial().onEnter(async (ctx) => {
+          await ctx.notify('user', 'hi');
+        }))
+        .state('b', state.end())
+        .transition('go', transition.from('a').to('b'))
+        .build();
+
+      const handler = result.states.a.onEnter![0].config!.handler as string;
+      expect(handler).toContain('notify');
+    });
+
+    it('each handler gets a unique id', () => {
+      const result = model('test')
+        .state('a', state.initial()
+          .onEnter((ctx) => { ctx.log('enter'); })
+        )
+        .state('b', state.end())
+        .transition('go', transition.from('a').to('b')
+          .do((ctx) => { ctx.log('transition'); })
+        )
+        .build();
+
+      const enterId = result.states.a.onEnter![0].id;
+      const transId = result.transitions.go.actions![0].id;
+      expect(enterId).not.toBe(transId);
+    });
+  });
+});