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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mmapp/react",
-  "version": "0.1.0-alpha.1",
+  "version": "0.1.0-alpha.4",
   "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",
@@ -22,14 +22,15 @@
     "dev": "tsup src/index.ts --format cjs,esm --dts --external react --watch",
     "test": "vitest run",
     "test:watch": "vitest --watch",
-    "type-check": "tsc --noEmit"
+    "type-check": "tsc --noEmit",
+    "publish:alpha": "cd ../.. && ./scripts/publish-npm.sh"
   },
   "peerDependencies": {
     "react": ">=18.0.0",
     "@tanstack/react-query": ">=5.0.0"
   },
   "dependencies": {
-    "@mmapp/player-core": "^0.1.0-alpha.1"
+    "@mmapp/player-core": "workspace:*"
   },
   "publishConfig": {
     "access": "public"

package/package.json.backup

@@ -1,41 +0,0 @@
-{
-  "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

@@ -1,216 +0,0 @@
-/**
- * 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

@@ -1,106 +0,0 @@
-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

@@ -1,166 +0,0 @@
-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);
-    });
-  });
-});