@mmapp/react-compiler 0.1.0-alpha.1

package/examples/dashboard.workflow.tsx

@@ -0,0 +1,419 @@
+/**
+ * @workflow slug="dashboard" version="1.0.0" category="blueprint"
+ * @description Real-world dashboard blueprint with multi-route layout, role-based access,
+ *   data source bindings, state management, and conditional rendering based on state.
+ */
+import { useState } from 'react';
+import {
+  useTransition,
+  useOnEnter,
+  useOnExit,
+  useOnChange,
+  useWhileIn,
+  useOnEvent,
+  useQuery,
+  useMutation,
+  useRole,
+} from '@mindmatrix/react';
+
+export function Dashboard() {
+  // --- Fields ---
+  const [activeRoute, setActiveRoute] = useState('/dashboard');
+  const [sidebarOpen, setSidebarOpen] = useState(true);
+  const [searchQuery, setSearchQuery] = useState('');
+  const [notificationCount, setNotificationCount] = useState(0);
+  const [selectedRecordId, setSelectedRecordId] = useState('');
+  const [theme, setTheme] = useState('light');
+  const [refreshInterval, setRefreshInterval] = useState(30000);
+  const [lastRefreshed, setLastRefreshed] = useState('');
+
+  // --- Data Sources ---
+
+  // Main metrics for the dashboard overview
+  const { data: metrics } = useQuery('dashboard-metric', {
+    limit: 20,
+    orderBy: 'priority',
+    filter: { visible: true },
+  });
+
+  // Recent activity feed
+  const { data: activities } = useQuery('activity-log', {
+    limit: 50,
+    orderBy: 'created_at',
+    order: 'desc',
+    filter: { archived: false },
+  });
+
+  // Workflow definitions for the data browser
+  const { data: definitions } = useQuery('workflow-definition', {
+    limit: 100,
+    filter: { category: 'data' },
+    orderBy: 'name',
+  });
+
+  // Notifications
+  const { data: notifications } = useQuery('notification', {
+    limit: 10,
+    filter: { read: false },
+    orderBy: 'created_at',
+    order: 'desc',
+  });
+
+  // User settings
+  const { data: userSettings } = useQuery('user-setting', {
+    limit: 1,
+    filter: { scope: 'dashboard' },
+  });
+
+  const settingsMutation = useMutation('user-setting');
+  const activityMutation = useMutation('activity-log');
+
+  // --- Roles ---
+  const isAdmin = useRole('admin');
+  const isViewer = useRole('viewer');
+  const isEditor = useRole('editor');
+
+  // --- States & Hooks ---
+
+  // When the dashboard initializes, clear stale state
+  useOnEnter('active', () => {
+    setNotificationCount(0);
+    setLastRefreshed('');
+  });
+
+  // When entering settings, record the visit
+  useOnEnter('settings', () => {
+    setSearchQuery('');
+  });
+
+  // When leaving active state, persist preferences
+  useOnExit('active', () => {
+    setSelectedRecordId('');
+  });
+
+  // Auto-refresh metrics while dashboard is active
+  useWhileIn('active', 30000, () => {
+    setLastRefreshed('now');
+  });
+
+  // Track route changes for analytics
+  useOnChange('activeRoute', () => {
+    setSearchQuery('');
+  });
+
+  // Track notification count changes
+  useOnChange('notificationCount', () => {
+    // Could trigger toast or badge update
+  });
+
+  // Listen for real-time updates from the backend
+  useOnEvent('data:updated', () => {
+    setLastRefreshed('now');
+  });
+
+  useOnEvent('notification:received', () => {
+    setNotificationCount(notificationCount + 1);
+  });
+
+  // --- Transitions ---
+
+  // Lifecycle transitions
+  useTransition('initialize', { from: 'draft', to: 'active' });
+  useTransition('suspend', { from: 'active', to: 'suspended' });
+  useTransition('resume', { from: 'suspended', to: 'active' });
+  useTransition('deactivate', { from: 'active', to: 'archived' });
+
+  // Route transitions (self-transitions that change activeRoute)
+  useTransition('navigate', { from: 'active', to: 'active' });
+
+  // Settings mode
+  useTransition('open-settings', { from: 'active', to: 'settings' });
+  useTransition('close-settings', { from: 'settings', to: 'active' });
+
+  // --- Derived state ---
+  const isOnDashboard = activeRoute === '/dashboard';
+  const isOnSettings = activeRoute === '/settings';
+  const isOnData = activeRoute === '/data';
+  const hasNotifications = notificationCount > 0;
+
+  // --- UI ---
+
+  return (
+    <Stack className="dashboard-app" sx={{ height: '100vh', direction: 'row' }}>
+      {/* ---- Sidebar Navigation ---- */}
+      {sidebarOpen && (
+        <Stack sx={{ width: '240px', bg: 'gray.900', color: 'white', p: 4, gap: 2 }}>
+          <Heading sx={{ fontSize: 'lg', fontWeight: 'bold', mb: 4 }}>
+            MindMatrix
+          </Heading>
+
+          {/* Nav items */}
+          <Button
+            onClick={() => setActiveRoute('/dashboard')}
+            sx={{ variant: isOnDashboard ? 'solid' : 'ghost', colorScheme: 'blue', justifyContent: 'start' }}
+          >
+            Dashboard
+          </Button>
+
+          <Button
+            onClick={() => setActiveRoute('/data')}
+            sx={{ variant: isOnData ? 'solid' : 'ghost', colorScheme: 'blue', justifyContent: 'start' }}
+          >
+            Data Browser
+          </Button>
+
+          <Button
+            onClick={() => setActiveRoute('/settings')}
+            sx={{ variant: isOnSettings ? 'solid' : 'ghost', colorScheme: 'blue', justifyContent: 'start' }}
+          >
+            Settings
+          </Button>
+
+          <Spacer />
+
+          {/* Notification badge */}
+          {hasNotifications && (
+            <Badge sx={{ colorScheme: 'red' }}>
+              {notificationCount} new
+            </Badge>
+          )}
+
+          {/* Admin-only: system status */}
+          {isAdmin && (
+            <Card sx={{ bg: 'gray.800', p: 2 }}>
+              <Text sx={{ fontSize: 'xs', color: 'gray.400' }}>System Status</Text>
+              <Text sx={{ fontSize: 'sm', color: 'green.400' }}>All services operational</Text>
+            </Card>
+          )}
+        </Stack>
+      )}
+
+      {/* ---- Main Content Area ---- */}
+      <Stack sx={{ flex: 1, overflow: 'auto' }}>
+        {/* Top bar */}
+        <Stack sx={{ direction: 'row', alignItems: 'center', p: 4, borderBottom: '1px solid', borderColor: 'gray.200', gap: 4 }}>
+          <Button onClick={() => setSidebarOpen(!sidebarOpen)} sx={{ variant: 'ghost', size: 'sm' }}>
+            Menu
+          </Button>
+
+          <TextInput
+            bind="searchQuery"
+            placeholder="Search..."
+            sx={{ flex: 1, maxWidth: '400px' }}
+          />
+
+          <Spacer />
+
+          <Text sx={{ fontSize: 'sm', color: 'gray.500' }}>
+            Last refreshed: {lastRefreshed}
+          </Text>
+
+          {isAdmin && (
+            <Button onClick={() => setRefreshInterval(15000)} sx={{ variant: 'outline', size: 'sm' }}>
+              Turbo Refresh
+            </Button>
+          )}
+        </Stack>
+
+        {/* ---- Route: /dashboard ---- */}
+        {isOnDashboard && (
+          <Stack sx={{ p: 6, gap: 6 }}>
+            <Heading sx={{ fontSize: '2xl', fontWeight: 'bold' }}>
+              Dashboard Overview
+            </Heading>
+
+            {/* Metrics grid */}
+            <Grid sx={{ columns: 4, gap: 4 }}>
+              <Each items={metrics}>
+                {(metric: any) => (
+                  <MetricCard
+                    label={metric.name}
+                    value={metric.value}
+                    format={metric.format}
+                    trend={metric.trend}
+                    sparkline={true}
+                    sx={{ bg: 'white', shadow: 'sm', rounded: 'lg', p: 4 }}
+                  />
+                )}
+              </Each>
+            </Grid>
+
+            {/* Activity + Notifications side by side */}
+            <Stack sx={{ direction: 'row', gap: 6 }}>
+              {/* Recent activity */}
+              <Stack sx={{ flex: 2, gap: 3 }}>
+                <Heading sx={{ fontSize: 'lg', fontWeight: 'semibold' }}>
+                  Recent Activity
+                </Heading>
+                <ScrollArea sx={{ maxHeight: '400px' }}>
+                  <Each items={activities}>
+                    {(activity: any) => (
+                      <Stack sx={{ direction: 'row', gap: 3, py: 2, borderBottom: '1px solid', borderColor: 'gray.100' }}>
+                        <Badge variant={activity.type === 'error' ? 'error' : 'default'}>
+                          {activity.type}
+                        </Badge>
+                        <Stack sx={{ flex: 1 }}>
+                          <Text sx={{ fontWeight: 'medium' }}>{activity.title}</Text>
+                          <Text sx={{ fontSize: 'sm', color: 'gray.500' }}>{activity.description}</Text>
+                        </Stack>
+                        {isEditor && (
+                          <Button sx={{ variant: 'ghost', size: 'sm' }}>
+                            View
+                          </Button>
+                        )}
+                      </Stack>
+                    )}
+                  </Each>
+                </ScrollArea>
+              </Stack>
+
+              {/* Notifications panel */}
+              <Stack sx={{ flex: 1, gap: 3 }}>
+                <Heading sx={{ fontSize: 'lg', fontWeight: 'semibold' }}>
+                  Notifications
+                </Heading>
+                <Each items={notifications}>
+                  {(notification: any) => (
+                    <Card sx={{ p: 3, mb: 2 }}>
+                      <Text sx={{ fontWeight: 'medium' }}>{notification.title}</Text>
+                      <Text sx={{ fontSize: 'sm', color: 'gray.500' }}>{notification.message}</Text>
+                    </Card>
+                  )}
+                </Each>
+                {!notifications && (
+                  <Text sx={{ color: 'gray.400', textAlign: 'center', py: 4 }}>
+                    No new notifications
+                  </Text>
+                )}
+              </Stack>
+            </Stack>
+
+            {/* Admin-only: system charts */}
+            {isAdmin && (
+              <Stack sx={{ gap: 4 }}>
+                <Heading sx={{ fontSize: 'lg', fontWeight: 'semibold' }}>
+                  System Analytics
+                </Heading>
+                <Stack sx={{ direction: 'row', gap: 4 }}>
+                  <Chart type="line" bind="metrics" xField="date" yField="value" sx={{ flex: 1, height: '300px' }} />
+                  <Chart type="bar" bind="activities" xField="type" yField="count" sx={{ flex: 1, height: '300px' }} />
+                </Stack>
+              </Stack>
+            )}
+          </Stack>
+        )}
+
+        {/* ---- Route: /data ---- */}
+        {isOnData && (
+          <Stack sx={{ p: 6, gap: 4 }}>
+            <Stack sx={{ direction: 'row', alignItems: 'center', gap: 4 }}>
+              <Heading sx={{ fontSize: '2xl', fontWeight: 'bold' }}>
+                Data Browser
+              </Heading>
+              {isEditor && (
+                <Button sx={{ colorScheme: 'blue' }}>
+                  New Definition
+                </Button>
+              )}
+            </Stack>
+
+            {/* Definition list with server grid */}
+            <ServerGrid
+              bind="definitions"
+              endpoint="/api/v1/workflow/definitions"
+              columns={[
+                { field: 'name', header: 'Name', sortable: true },
+                { field: 'category', header: 'Category', sortable: true },
+                { field: 'version', header: 'Version', sortable: false },
+                { field: 'updated_at', header: 'Last Updated', sortable: true },
+              ]}
+              pageSize={25}
+            />
+
+            {/* Viewer restriction notice */}
+            {isViewer && !isEditor && (
+              <Card sx={{ bg: 'yellow.50', p: 4 }}>
+                <Text sx={{ color: 'yellow.800' }}>
+                  You have read-only access. Contact an admin to request edit permissions.
+                </Text>
+              </Card>
+            )}
+          </Stack>
+        )}
+
+        {/* ---- Route: /settings ---- */}
+        {isOnSettings && (
+          <Stack sx={{ p: 6, gap: 6, maxWidth: '800px' }}>
+            <Heading sx={{ fontSize: '2xl', fontWeight: 'bold' }}>
+              Settings
+            </Heading>
+
+            {/* General settings */}
+            <Section title="General" description="Configure your dashboard preferences">
+              <Stack sx={{ gap: 4 }}>
+                <Stack sx={{ direction: 'row', alignItems: 'center', gap: 4 }}>
+                  <Text sx={{ width: '150px', fontWeight: 'medium' }}>Theme</Text>
+                  <Select
+                    bind="theme"
+                    options={['light', 'dark', 'system']}
+                  />
+                </Stack>
+
+                <Stack sx={{ direction: 'row', alignItems: 'center', gap: 4 }}>
+                  <Text sx={{ width: '150px', fontWeight: 'medium' }}>Refresh Rate</Text>
+                  <Select
+                    bind="refreshInterval"
+                    options={['15000', '30000', '60000', '300000']}
+                  />
+                </Stack>
+              </Stack>
+            </Section>
+
+            {/* Admin-only settings */}
+            {isAdmin && (
+              <Section title="Administration" description="System-level configuration (admin only)">
+                <Stack sx={{ gap: 4 }}>
+                  <Card sx={{ p: 4 }}>
+                    <Stack sx={{ gap: 3 }}>
+                      <Text sx={{ fontWeight: 'medium' }}>User Management</Text>
+                      <Text sx={{ fontSize: 'sm', color: 'gray.500' }}>
+                        Manage users, roles, and permissions for this workspace.
+                      </Text>
+                      <Button sx={{ colorScheme: 'blue', variant: 'outline' }}>
+                        Manage Users
+                      </Button>
+                    </Stack>
+                  </Card>
+
+                  <Card sx={{ p: 4 }}>
+                    <Stack sx={{ gap: 3 }}>
+                      <Text sx={{ fontWeight: 'medium' }}>Data Retention</Text>
+                      <Text sx={{ fontSize: 'sm', color: 'gray.500' }}>
+                        Configure how long activity logs and archived records are retained.
+                      </Text>
+                      <Button sx={{ colorScheme: 'red', variant: 'outline' }}>
+                        Configure Retention
+                      </Button>
+                    </Stack>
+                  </Card>
+                </Stack>
+              </Section>
+            )}
+
+            {/* Save button */}
+            {isEditor && (
+              <Stack sx={{ direction: 'row', justifyContent: 'end', gap: 2 }}>
+                <Button onClick={() => setActiveRoute('/dashboard')} sx={{ variant: 'outline' }}>
+                  Cancel
+                </Button>
+                <Button sx={{ colorScheme: 'blue' }}>
+                  Save Settings
+                </Button>
+              </Stack>
+            )}
+          </Stack>
+        )}
+      </Stack>
+    </Stack>
+  );
+}

package/examples/invoice-approval/actions/invoice.server.ts

@@ -0,0 +1,72 @@
+/**
+ * Server actions — backend handlers for invoice approval transitions.
+ *
+ * These functions run server-side during state transitions.
+ * Each receives a TransitionContext with instance data and utilities.
+ */
+
+import type { TransitionContext } from '@mindmatrix/react';
+
+/** Send approval notification to the invoice submitter. */
+export async function sendApprovalNotification(ctx: TransitionContext): Promise<void> {
+  const { instance, env } = ctx;
+  await env.notify({
+    message: `Invoice #${instance.id} has been approved`,
+    instanceId: instance.id,
+  });
+
+  // Also emit an event for audit trail
+  await env.emit('invoice:approved', {
+    instanceId: instance.id,
+    approvedBy: ctx.actor?.id,
+    approvedAt: new Date().toISOString(),
+  });
+}
+
+/** Send rejection notification with reason. */
+export async function sendRejectionNotification(ctx: TransitionContext): Promise<void> {
+  const { instance, env } = ctx;
+  const reason = instance.state_data?.rejectionReason ?? 'No reason provided';
+
+  await env.notify({
+    message: `Invoice #${instance.id} was rejected: ${reason}`,
+    instanceId: instance.id,
+  });
+
+  await env.emit('invoice:rejected', {
+    instanceId: instance.id,
+    rejectedBy: ctx.actor?.id,
+    reason,
+  });
+}
+
+/** Validate invoice data before submission. */
+export async function validateInvoice(ctx: TransitionContext): Promise<void> {
+  const { instance } = ctx;
+  const data = instance.state_data;
+
+  if (!data?.amount || data.amount <= 0) {
+    throw new Error('Invoice amount must be greater than zero');
+  }
+  if (!data?.vendor) {
+    throw new Error('Vendor name is required');
+  }
+  if (!data?.date) {
+    throw new Error('Invoice date is required');
+  }
+}
+
+/** Send webhook to accounting system on approval. */
+export async function syncToAccounting(ctx: TransitionContext): Promise<void> {
+  const { instance } = ctx;
+  await fetch('https://api.example.com/accounting/invoices', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({
+      externalId: instance.id,
+      amount: instance.state_data?.amount,
+      vendor: instance.state_data?.vendor,
+      approvedAt: new Date().toISOString(),
+    }),
+  });
+}

package/examples/invoice-approval/main.workflow.tsx

@@ -0,0 +1,168 @@
+/**
+ * @workflow slug="invoice-approval" version="1.0.0" category="blueprint"
+ * @description Invoice approval workflow with multi-page views, data model, and server actions.
+ *
+ * States: draft → submitted → approved | rejected
+ * Pages: InvoiceList, InvoiceDetail, InvoiceForm
+ * Model: Invoice (amount, vendor, date, status, notes)
+ * Server Action: sendNotification (on approval/rejection)
+ */
+import {
+  Stack,
+  Row,
+  Heading,
+  Text,
+  Button,
+  Show,
+  useOnEnter,
+  useOnExit,
+  useTransition,
+  useRole,
+} from '@mindmatrix/react';
+import { useState } from 'react';
+import type { Invoice } from './models/invoice';
+import { sendApprovalNotification, sendRejectionNotification } from './actions/invoice.server';
+import { InvoiceListPage } from './pages/InvoiceListPage';
+import { InvoiceDetailPage } from './pages/InvoiceDetailPage';
+import { InvoiceFormPage } from './pages/InvoiceFormPage';
+
+export default function InvoiceApproval() {
+  // --- Fields ---
+  const [activeRoute, setActiveRoute] = useState('/invoices');
+  const [selectedInvoiceId, setSelectedInvoiceId] = useState('');
+  const [filterStatus, setFilterStatus] = useState('all');
+  const [totalPending, setTotalPending] = useState(0);
+  const [lastAction, setLastAction] = useState('');
+
+  // --- Roles ---
+  const isApprover = useRole('approver');
+  const isSubmitter = useRole('submitter');
+
+  // --- State Effects ---
+  useOnEnter('draft', () => {
+    setLastAction('created');
+  });
+
+  useOnEnter('submitted', () => {
+    setLastAction('submitted');
+    setTotalPending(totalPending + 1);
+  });
+
+  useOnEnter('approved', () => {
+    setLastAction('approved');
+    setTotalPending(Math.max(0, totalPending - 1));
+  });
+
+  useOnEnter('rejected', () => {
+    setLastAction('rejected');
+    setTotalPending(Math.max(0, totalPending - 1));
+  });
+
+  useOnExit('draft', () => {
+    // Clear form state when leaving draft
+    setSelectedInvoiceId('');
+  });
+
+  // --- Transitions ---
+  const submit = useTransition('submit', {
+    from: 'draft',
+    to: 'submitted',
+    requiredFields: ['amount', 'vendor', 'date'],
+    roles: ['submitter'],
+  });
+
+  const approve = useTransition('approve', {
+    from: 'submitted',
+    to: 'approved',
+    roles: ['approver'],
+  });
+
+  const reject = useTransition('reject', {
+    from: 'submitted',
+    to: 'rejected',
+    roles: ['approver'],
+  });
+
+  const revise = useTransition('revise', {
+    from: 'rejected',
+    to: 'draft',
+    roles: ['submitter'],
+  });
+
+  // --- Navigation ---
+  const isOnList = activeRoute === '/invoices';
+  const isOnDetail = activeRoute === '/invoices/detail';
+  const isOnForm = activeRoute === '/invoices/new';
+
+  return (
+    <Stack sx={{ minHeight: '100vh', bg: 'gray.50' }}>
+      {/* Header */}
+      <Row sx={{ alignItems: 'center', justifyContent: 'space-between', p: 16, bg: 'white', borderBottom: '1px solid', borderColor: 'gray.200' }}>
+        <Row sx={{ alignItems: 'center', gap: 12 }}>
+          <Heading sx={{ fontSize: 20, fontWeight: 'bold' }}>Invoice Approval</Heading>
+          <Show when={totalPending > 0}>
+            <Text sx={{ bg: 'orange.100', color: 'orange.800', px: 8, py: 2, rounded: 'full', fontSize: 12 }}>
+              {totalPending} pending
+            </Text>
+          </Show>
+        </Row>
+        <Row sx={{ gap: 8 }}>
+          <Button
+            onClick={() => setActiveRoute('/invoices')}
+            sx={{ variant: isOnList ? 'solid' : 'ghost' }}
+          >
+            All Invoices
+          </Button>
+          <Show when={isSubmitter}>
+            <Button
+              onClick={() => setActiveRoute('/invoices/new')}
+              sx={{ variant: isOnForm ? 'solid' : 'ghost', colorScheme: 'blue' }}
+            >
+              New Invoice
+            </Button>
+          </Show>
+        </Row>
+      </Row>
+
+      {/* Route Pages */}
+      <Show when={isOnList}>
+        <InvoiceListPage
+          filterStatus={filterStatus}
+          onFilterChange={setFilterStatus}
+          onSelect={(id: string) => {
+            setSelectedInvoiceId(id);
+            setActiveRoute('/invoices/detail');
+          }}
+        />
+      </Show>
+
+      <Show when={isOnDetail}>
+        <InvoiceDetailPage
+          invoiceId={selectedInvoiceId}
+          isApprover={isApprover}
+          onApprove={() => approve.fire()}
+          onReject={() => reject.fire()}
+          onRevise={() => revise.fire()}
+          onBack={() => setActiveRoute('/invoices')}
+        />
+      </Show>
+
+      <Show when={isOnForm}>
+        <InvoiceFormPage
+          onSubmit={() => {
+            submit.fire();
+            setActiveRoute('/invoices');
+          }}
+          onCancel={() => setActiveRoute('/invoices')}
+        />
+      </Show>
+
+      {/* Status bar */}
+      <Row sx={{ p: 8, bg: 'gray.100', justifyContent: 'end', gap: 8, mt: 'auto' }}>
+        <Text sx={{ fontSize: 11, color: 'gray.500' }}>
+          Last action: {lastAction || 'none'}
+        </Text>
+      </Row>
+    </Stack>
+  );
+}

package/examples/invoice-approval/mm.config.ts

@@ -0,0 +1,18 @@
+/**
+ * Blueprint configuration for "Invoice Approval".
+ */
+
+import { defineBlueprint } from '@mindmatrix/react';
+
+export default defineBlueprint({
+  slug: 'invoice-approval',
+  name: 'Invoice Approval',
+  version: '1.0.0',
+  category: 'blueprint',
+  description: 'Invoice approval workflow with multi-page views, data model, and server actions.',
+  roles: [
+    { name: 'submitter', permissions: ['view', 'edit', 'transition'] },
+    { name: 'approver', permissions: ['view', 'transition'] },
+    { name: 'admin', permissions: ['view', 'edit', 'transition', 'delete'] },
+  ],
+});