@mmapp/react-compiler 0.1.0-alpha.1

package/dist/vite/index.mjs

@@ -0,0 +1,8 @@
+import {
+  mindmatrixReact
+} from "../chunk-46YKSHQR.mjs";
+import "../chunk-HLRGCCIL.mjs";
+import "../chunk-Y6FXYEAI.mjs";
+export {
+  mindmatrixReact
+};

package/examples/README.md

@@ -0,0 +1,72 @@
+# @mindmatrix/react-compiler — Examples
+
+Sample `.workflow.tsx` files demonstrating the React framework for MindMatrix workflows.
+
+## Files
+
+| File | What it demonstrates |
+|------|---------------------|
+| `counter.workflow.tsx` | State fields (`useState`), transitions (`useTransition`), enter hooks (`useOnEnter`), field watchers (`useOnChange`), `sx` prop styling, JSX experience tree |
+| `todo-app.workflow.tsx` | Data sources (`useQuery`), mutations (`useMutation`), role guards (`useRole`), polling (`useWhileIn`), conditional rendering, list mapping (`Each`), multi-state transitions |
+| `dashboard.workflow.tsx` | Blueprint with multi-route layout (`/dashboard`, `/data`, `/settings`), 3 roles (`admin`, `viewer`, `editor`), 5 data sources, event subscriptions (`useOnEvent`), visualization atoms (`Chart`, `MetricCard`, `ServerGrid`), complex state machine (4 states, 7 transitions) |
+
+## Quick start
+
+### Compile a single file
+
+```bash
+cd packages/react-compiler
+npx babel --plugins ./src/babel examples/counter.workflow.tsx
+```
+
+### Build all workflow files
+
+```bash
+# From the react-compiler package
+npx mmrc build --src examples --out dist/examples
+
+# Output: dist/examples/counter.json, dist/examples/todo-app.json
+```
+
+### Dev server (watch + hot reload)
+
+```bash
+npx mmrc dev --src examples --port 5199
+
+# Watches for changes, recompiles on save, notifies connected editors via WebSocket
+```
+
+### Run tests
+
+```bash
+npx mmrc test --src examples
+```
+
+## What the compiler extracts
+
+Each `.workflow.tsx` compiles to an IR (Intermediate Representation) containing:
+
+- **fields** — from `useState()` calls (name, type, default value)
+- **states** — from `useOnEnter()`, `useOnExit()`, `useTransition()` (name, type, enter/exit actions)
+- **transitions** — from `useTransition()` (name, from, to, conditions)
+- **experience** — from the JSX return (component tree with bindings, layout, config)
+- **dataSources** — from `useQuery()` (slug, filters, pagination, sort)
+- **mutationTargets** — from `useMutation()` (slugs this workflow writes to)
+- **roleDependencies** — from `useRole()` (roles this workflow checks)
+- **fieldWatchers** — from `useOnChange()` (reactive field observers)
+
+## Hooks reference
+
+| Hook | Compiler output | Description |
+|------|----------------|-------------|
+| `useState(init)` | `fields[]` | Declares a workflow field with inferred type |
+| `useTransition(name, { from, to })` | `transitions[]` | Declares a state transition |
+| `useOnEnter(state, fn)` | `states[].on_enter[]` | Action when entering a state |
+| `useOnExit(state, fn)` | `states[].on_exit[]` | Action when leaving a state |
+| `useOnEvent(event, fn)` | `on_event[]` | Subscribe to external events |
+| `useWhileIn(state, ms, fn)` | `states[].during[]` | Polling action while in state |
+| `useOnChange(field, fn)` | `metadata.fieldWatchers[]` | React to field value changes |
+| `useOnTransition(fn)` | `metadata.transitionEffects[]` | Run on any transition |
+| `useQuery(slug, opts)` | `metadata.dataSources[]` | Bind to a data workflow |
+| `useMutation(slug)` | `metadata.mutationTargets[]` | Declare write access to a workflow |
+| `useRole(role)` | `metadata.roleDependencies[]` | Check role-based access |

package/examples/authentication/main.workflow.tsx

@@ -0,0 +1,139 @@
+/**
+ * @workflow slug="mod-authentication" version="1.0.0" category="module"
+ * @description Login & signup pages with configurable layout, routing, and features.
+ *
+ * States: unauthenticated → authenticating → authenticated | error
+ * Pages: Login, Signup (optional)
+ * Config: appName, layout, showSignup, showForgotPassword, redirectPath
+ *
+ * This is a system module — it ships with the platform and can be inserted
+ * into any blueprint project. Configuration fields control the generated
+ * experience tree (layout variant, feature toggles, app branding).
+ */
+import {
+  Stack,
+  Row,
+  Card,
+  Heading,
+  Text,
+  Route,
+  Show,
+  useOnEnter,
+  useTransition,
+} from '@mindmatrix/react';
+import { useState } from 'react';
+import { LoginPage } from './pages/LoginPage';
+import { SignupPage } from './pages/SignupPage';
+
+export default function Authentication() {
+  // -------------------------------------------------------------------------
+  // Config fields — set at module insertion time, stored as workflow fields
+  // -------------------------------------------------------------------------
+  const [appName, setAppName] = useState('My App');
+  const [layout, setLayout] = useState('card');
+  const [showSignup, setShowSignup] = useState(true);
+  const [showForgotPassword, setShowForgotPassword] = useState(true);
+  const [redirectPath, setRedirectPath] = useState('/');
+
+  // -------------------------------------------------------------------------
+  // Runtime fields — managed during auth flow
+  // -------------------------------------------------------------------------
+  const [email, setEmail] = useState('');
+  const [password, setPassword] = useState('');
+  const [confirmPassword, setConfirmPassword] = useState('');
+  const [firstName, setFirstName] = useState('');
+  const [lastName, setLastName] = useState('');
+  const [errorMessage, setErrorMessage] = useState('');
+
+  // -------------------------------------------------------------------------
+  // State effects
+  // -------------------------------------------------------------------------
+  useOnEnter('unauthenticated', () => {
+    setErrorMessage('');
+  });
+
+  useOnEnter('error', () => {
+    setErrorMessage('Authentication failed. Please try again.');
+  });
+
+  useOnEnter('authenticated', () => {
+    setEmail('');
+    setPassword('');
+    setConfirmPassword('');
+    setErrorMessage('');
+  });
+
+  // -------------------------------------------------------------------------
+  // Transitions — auth state machine
+  // -------------------------------------------------------------------------
+  const login = useTransition('login', {
+    from: 'unauthenticated',
+    to: 'authenticating',
+    requiredFields: ['email', 'password'],
+  });
+
+  const loginSuccess = useTransition('login_success', {
+    from: 'authenticating',
+    to: 'authenticated',
+  });
+
+  const loginError = useTransition('login_error', {
+    from: 'authenticating',
+    to: 'error',
+  });
+
+  const signup = useTransition('signup', {
+    from: 'unauthenticated',
+    to: 'authenticating',
+    requiredFields: ['email', 'password', 'firstName', 'lastName'],
+  });
+
+  const signupSuccess = useTransition('signup_success', {
+    from: 'authenticating',
+    to: 'authenticated',
+  });
+
+  const signupError = useTransition('signup_error', {
+    from: 'authenticating',
+    to: 'error',
+  });
+
+  const logout = useTransition('logout', {
+    from: 'authenticated',
+    to: 'unauthenticated',
+  });
+
+  const retry = useTransition('retry', {
+    from: 'error',
+    to: 'unauthenticated',
+  });
+
+  // -------------------------------------------------------------------------
+  // View — Router with login + optional signup routes
+  // -------------------------------------------------------------------------
+  return (
+    <Stack sx={{ minHeight: '100vh', display: 'flex', alignItems: 'center', justifyContent: 'center', bg: '#f8fafc', p: [24, 16] }}>
+      <Card sx={{ p: [32, 28], maxWidth: 420, width: '100%', rounded: 12 }}>
+        <Route path="/login">
+          <LoginPage
+            appName={appName}
+            showForgotPassword={showForgotPassword}
+            showSignup={showSignup}
+            onLogin={() => login.fire()}
+            errorMessage={errorMessage}
+          />
+        </Route>
+
+        <Show when={showSignup}>
+          <Route path="/signup">
+            <SignupPage
+              appName={appName}
+              onSignup={() => signup.fire()}
+              errorMessage={errorMessage}
+            />
+          </Route>
+        </Show>
+      </Card>
+    </Stack>
+  );
+}

package/examples/authentication/mm.config.ts

@@ -0,0 +1,22 @@
+/**
+ * Module configuration for "Authentication".
+ *
+ * This is a system module — it ships with the platform and provides
+ * login/signup pages with configurable layout, routing, and features.
+ */
+
+import { defineBlueprint } from '@mindmatrix/react';
+
+export default defineBlueprint({
+  slug: 'mod-authentication',
+  name: 'Authentication',
+  version: '1.0.0',
+  category: 'module',
+  description:
+    'Login & signup pages with configurable layout, routing, and features. ' +
+    'Supports card, split, and minimal layouts with optional signup and forgot-password flows.',
+  roles: [
+    { name: 'anonymous', permissions: ['view'] },
+    { name: 'user', permissions: ['view', 'transition'] },
+  ],
+});

package/examples/authentication/models/auth.ts

@@ -0,0 +1,45 @@
+/**
+ * Auth — data model interface.
+ *
+ * Fields map directly to workflow definition fields (parameters).
+ * Config fields control how the module renders (layout, feature toggles).
+ * Runtime fields track auth state during execution.
+ */
+
+/** Configuration parameters — set at module insertion time */
+export interface AuthConfig {
+  /** Application name displayed in headings */
+  appName: string;
+  /** Layout variant: card (centered), split (image + form), minimal (inline) */
+  layout: 'card' | 'split' | 'minimal';
+  /** Whether to include a signup page/route */
+  showSignup: boolean;
+  /** Whether to show the forgot-password link on login */
+  showForgotPassword: boolean;
+  /** Where to redirect after successful login */
+  redirectPath: string;
+}
+
+/** Runtime fields — managed during auth flow */
+export interface AuthRuntime {
+  /** User email input */
+  email: string;
+  /** User password input */
+  password: string;
+  /** Confirm password (signup only) */
+  confirmPassword: string;
+  /** First name (signup only) */
+  firstName: string;
+  /** Last name (signup only) */
+  lastName: string;
+  /** Error message from failed auth attempt */
+  errorMessage: string;
+}
+
+/** Auth lifecycle states */
+export enum AuthState {
+  Unauthenticated = 'unauthenticated',
+  Authenticating = 'authenticating',
+  Authenticated = 'authenticated',
+  Error = 'error',
+}

package/examples/authentication/pages/LoginPage.tsx

@@ -0,0 +1,79 @@
+/**
+ * LoginPage — login form with email/password fields and action buttons.
+ *
+ * Uses @mindmatrix/react atoms: Stack, Heading, Text, TextInput, Button.
+ * Bindings connect to workflow fields; transition fires move through auth states.
+ */
+import {
+  Stack,
+  Heading,
+  Text,
+  TextInput,
+  Button,
+  Show,
+  Link,
+} from '@mindmatrix/react';
+
+interface LoginPageProps {
+  appName: string;
+  showForgotPassword: boolean;
+  showSignup: boolean;
+  onLogin: () => void;
+  errorMessage: string;
+}
+
+export function LoginPage({
+  appName,
+  showForgotPassword,
+  showSignup,
+  onLogin,
+  errorMessage,
+}: LoginPageProps) {
+  return (
+    <Stack sx={{ gap: 16 }}>
+      <Heading sx={{ fontSize: 24, fontWeight: 'bold', textAlign: 'center' }}>
+        Sign in to {appName}
+      </Heading>
+      <Text sx={{ fontSize: 14, textAlign: 'center', color: '#64748b' }}>
+        Enter your credentials to continue
+      </Text>
+
+      <Show when={!!errorMessage}>
+        <Text sx={{ fontSize: 13, color: '#dc2626', textAlign: 'center', bg: '#fef2f2', p: 8, rounded: 8 }}>
+          {errorMessage}
+        </Text>
+      </Show>
+
+      <TextInput
+        bind="email"
+        placeholder="you@example.com"
+        sx={{ width: '100%' }}
+      />
+
+      <TextInput
+        bind="password"
+        placeholder="••••••••"
+        sx={{ width: '100%' }}
+      />
+
+      <Show when={showForgotPassword}>
+        <Text sx={{ fontSize: 13, textAlign: 'right', color: '#2563eb', cursor: 'pointer' }}>
+          Forgot your password?
+        </Text>
+      </Show>
+
+      <Button onClick={onLogin} sx={{ width: '100%', mt: 8 }}>
+        Sign In
+      </Button>
+
+      <Show when={showSignup}>
+        <Text sx={{ fontSize: 13, textAlign: 'center', color: '#64748b', mt: 8 }}>
+          Don't have an account?{' '}
+          <Link to="/signup" sx={{ color: '#2563eb', fontWeight: 'medium' }}>
+            Sign up
+          </Link>
+        </Text>
+      </Show>
+    </Stack>
+  );
+}

package/examples/authentication/pages/SignupPage.tsx

@@ -0,0 +1,87 @@
+/**
+ * SignupPage — registration form with name, email, password fields.
+ *
+ * Uses @mindmatrix/react atoms: Stack, Row, Heading, Text, TextInput, Button.
+ * Bindings connect to workflow fields; transition fires move through auth states.
+ */
+import {
+  Stack,
+  Row,
+  Heading,
+  Text,
+  TextInput,
+  Button,
+  Show,
+  Link,
+} from '@mindmatrix/react';
+
+interface SignupPageProps {
+  appName: string;
+  onSignup: () => void;
+  errorMessage: string;
+}
+
+export function SignupPage({
+  appName,
+  onSignup,
+  errorMessage,
+}: SignupPageProps) {
+  return (
+    <Stack sx={{ gap: 16 }}>
+      <Heading sx={{ fontSize: 24, fontWeight: 'bold', textAlign: 'center' }}>
+        Create your {appName} account
+      </Heading>
+      <Text sx={{ fontSize: 14, textAlign: 'center', color: '#64748b' }}>
+        Fill in your details to get started
+      </Text>
+
+      <Show when={!!errorMessage}>
+        <Text sx={{ fontSize: 13, color: '#dc2626', textAlign: 'center', bg: '#fef2f2', p: 8, rounded: 8 }}>
+          {errorMessage}
+        </Text>
+      </Show>
+
+      <Row sx={{ gap: 12 }}>
+        <TextInput
+          bind="firstName"
+          placeholder="First name"
+          sx={{ flex: 1 }}
+        />
+        <TextInput
+          bind="lastName"
+          placeholder="Last name"
+          sx={{ flex: 1 }}
+        />
+      </Row>
+
+      <TextInput
+        bind="email"
+        placeholder="you@example.com"
+        sx={{ width: '100%' }}
+      />
+
+      <TextInput
+        bind="password"
+        placeholder="Min 8 characters"
+        sx={{ width: '100%' }}
+      />
+
+      <TextInput
+        bind="confirmPassword"
+        placeholder="Repeat password"
+        sx={{ width: '100%' }}
+      />
+
+      <Button onClick={onSignup} sx={{ width: '100%', mt: 8 }}>
+        Create Account
+      </Button>
+
+      <Text sx={{ fontSize: 13, textAlign: 'center', color: '#64748b', mt: 8 }}>
+        Already have an account?{' '}
+        <Link to="/login" sx={{ color: '#2563eb', fontWeight: 'medium' }}>
+          Sign in
+        </Link>
+      </Text>
+    </Stack>
+  );
+}

package/examples/counter.workflow.tsx

@@ -0,0 +1,65 @@
+/**
+ * @workflow slug="counter" version="1.0.0" category="workflow"
+ * @description A simple counter demonstrating state, transitions, hooks, and sx styling.
+ */
+import { useState } from 'react';
+import { useOnEnter, useTransition, useOnChange } from '@mindmatrix/react';
+
+export function Counter() {
+  const [count, setCount] = useState(0);
+  const [status, setStatus] = useState('idle');
+  const [lastAction, setLastAction] = useState('');
+
+  // --- States & Hooks ---
+
+  // When entering the 'counting' state, reset the counter to zero
+  useOnEnter('counting', () => {
+    setCount(0);
+    setLastAction('reset');
+  });
+
+  // Watch for count changes — tracks field mutations
+  useOnChange('count', () => {
+    setLastAction('counted');
+  });
+
+  // --- Transitions ---
+
+  // Start counting from idle
+  useTransition('start', { from: 'idle', to: 'counting' });
+
+  // Increment stays in the counting state
+  useTransition('increment', { from: 'counting', to: 'counting' });
+
+  // Decrement stays in the counting state
+  useTransition('decrement', { from: 'counting', to: 'counting' });
+
+  // Reset returns to idle
+  useTransition('reset', { from: 'counting', to: 'idle' });
+
+  // --- UI ---
+
+  return (
+    <Stack className="counter-app" data-slot="main">
+      <Heading sx={{ fontSize: '2xl', fontWeight: 'bold', mb: 4 }}>
+        Counter: {count}
+      </Heading>
+
+      <Text sx={{ color: 'gray.500', mb: 2 }}>
+        Status: {status} | Last: {lastAction}
+      </Text>
+
+      <Stack sx={{ direction: 'row', gap: 2 }}>
+        <Button onClick={() => setCount(count + 1)} sx={{ colorScheme: 'blue' }}>
+          +1
+        </Button>
+        <Button onClick={() => setCount(count - 1)} sx={{ colorScheme: 'red' }}>
+          -1
+        </Button>
+        <Button onClick={() => setCount(0)} sx={{ variant: 'outline' }}>
+          Reset
+        </Button>
+      </Stack>
+    </Stack>
+  );
+}