@mmapp/player-core 0.1.0-alpha.1

package/src/actions/dispatcher.ts

@@ -0,0 +1,80 @@
+/**
+ * Action Dispatcher — executes action definitions against registered handlers.
+ *
+ * The dispatcher:
+ * - Maintains a registry of handler functions by action type
+ * - Evaluates per-action conditions before execution
+ * - Collects results (success/failure) for each action
+ * - Never throws — errors are captured in ActionResult
+ */
+
+import type { Evaluator, ExpressionContext } from '../expression/types';
+import type { ActionDefinition, ActionHandlerFn, ActionResult } from './types';
+
+export class ActionDispatcher {
+  private readonly handlers = new Map<string, ActionHandlerFn>();
+
+  /** Register a handler for an action type */
+  register(type: string, handler: ActionHandlerFn): void {
+    this.handlers.set(type, handler);
+  }
+
+  /** Unregister a handler */
+  unregister(type: string): void {
+    this.handlers.delete(type);
+  }
+
+  /** Check if a handler is registered for the given type */
+  has(type: string): boolean {
+    return this.handlers.has(type);
+  }
+
+  /**
+   * Execute a list of actions sequentially.
+   * Each action's condition is evaluated first (if present).
+   * Missing handlers are skipped with a warning.
+   */
+  async execute(
+    actions: ActionDefinition[],
+    context: ExpressionContext,
+    evaluator?: Evaluator,
+  ): Promise<ActionResult[]> {
+    const results: ActionResult[] = [];
+
+    for (const action of actions) {
+      // Check per-action condition
+      if (action.condition && evaluator) {
+        const condResult = evaluator.evaluate<boolean>(action.condition, context);
+        if (!condResult.value) continue; // Skip this action
+      }
+
+      const handler = this.handlers.get(action.type);
+      if (!handler) {
+        console.warn(`[player-core] No handler registered for action type "${action.type}"`);
+        results.push({ type: action.type, success: false, error: `No handler for "${action.type}"` });
+        continue;
+      }
+
+      try {
+        await handler(action.config, context);
+        results.push({ type: action.type, success: true });
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        console.warn(`[player-core] Action "${action.type}" failed: ${message}`);
+        results.push({ type: action.type, success: false, error: message });
+      }
+    }
+
+    return results;
+  }
+
+  /** Get count of registered handlers */
+  get size(): number {
+    return this.handlers.size;
+  }
+
+  /** Remove all handlers */
+  clear(): void {
+    this.handlers.clear();
+  }
+}

package/src/actions/index.ts

@@ -0,0 +1,7 @@
+export type {
+  ActionDefinition,
+  ActionHandlerFn,
+  ActionResult,
+} from './types';
+
+export { ActionDispatcher } from './dispatcher';

package/src/actions/types.ts

@@ -0,0 +1,25 @@
+/**
+ * Action System Types — handler registry and dispatch.
+ */
+
+import type { ExpressionContext } from '../expression/types';
+
+/** Action definition from workflow state/transition */
+export interface ActionDefinition {
+  type: string;
+  config: Record<string, unknown>;
+  condition?: string;
+}
+
+/** Registered action handler */
+export type ActionHandlerFn = (
+  config: Record<string, unknown>,
+  context: ExpressionContext,
+) => void | Promise<void>;
+
+/** Result of executing an action */
+export interface ActionResult {
+  type: string;
+  success: boolean;
+  error?: string;
+}

package/src/dsl/compiler/component-mapper.ts

@@ -0,0 +1,289 @@
+/**
+ * Component Mapper — maps DSL content/iteration patterns to ExperienceNode IR.
+ *
+ * Maps to the 34 frozen component IDs from the component registry (§9).
+ */
+
+import type {
+  ContentData,
+  StringLiteralData,
+  IterationData,
+  SectionData,
+  SearchData,
+  NavigationData,
+} from '../types';
+import type { IRExperienceNode } from '../ir-types';
+import { snakeCase, slugify, generateId } from './utils';
+
+// =============================================================================
+// Instance-level fields (NOT in state_data)
+// =============================================================================
+
+const INSTANCE_FIELDS = new Set([
+  'id', 'current_state', 'state', 'status',
+  'created_at', 'updated_at', 'entity_type', 'entity_id',
+]);
+
+// =============================================================================
+// Content → ExperienceNode
+// =============================================================================
+
+/**
+ * Map a content node to an ExperienceNode.
+ * @param data - parsed content data
+ * @param insideEach - whether this content is inside an iteration (changes binding scope)
+ * @param parentId - parent ID for generating unique child IDs
+ * @param index - child index for ID uniqueness
+ */
+export function mapContent(
+  data: ContentData,
+  insideEach: boolean,
+  parentId: string,
+  index: number,
+): IRExperienceNode {
+  const fieldSnake = snakeCase(data.field);
+  const nodeId = generateId(parentId, data.field, String(index));
+  const prefix = insideEach ? '$item' : '$instance';
+
+  // Determine binding path
+  const isInstanceField = INSTANCE_FIELDS.has(fieldSnake);
+  const bindingPath = isInstanceField
+    ? `${prefix}.${fieldSnake === 'state' ? 'current_state' : fieldSnake}`
+    : `${prefix}.state_data.${fieldSnake}`;
+
+  // Special component based on role
+  if (data.role) {
+    return mapContentWithRole(data, nodeId, bindingPath);
+  }
+
+  // Default: Text component
+  const node: IRExperienceNode = {
+    id: nodeId,
+    component: 'Text',
+    bindings: { value: bindingPath },
+  };
+
+  if (data.emphasis === 'big') {
+    node.config = { variant: 'heading' };
+  } else if (data.emphasis === 'small') {
+    node.config = { variant: 'caption' };
+  }
+
+  if (data.label) {
+    if (!node.config) node.config = {};
+    node.config.label = data.label;
+  }
+
+  return node;
+}
+
+function mapContentWithRole(
+  data: ContentData,
+  nodeId: string,
+  bindingPath: string,
+): IRExperienceNode {
+  switch (data.role) {
+    case 'tag':
+      return {
+        id: nodeId,
+        component: 'Badge',
+        bindings: { value: bindingPath },
+      };
+
+    case 'progress':
+    case 'meter':
+      return {
+        id: nodeId,
+        component: 'ProgressTracker',
+        bindings: { value: bindingPath },
+      };
+
+    case 'image':
+      return {
+        id: nodeId,
+        component: 'Image',
+        bindings: { src: bindingPath },
+      };
+
+    case 'number': {
+      const node: IRExperienceNode = {
+        id: nodeId,
+        component: 'Text',
+        config: { variant: 'metric' },
+        bindings: { value: bindingPath },
+      };
+      if (data.label) {
+        node.config!.label = data.label;
+      }
+      return node;
+    }
+
+    default:
+      return {
+        id: nodeId,
+        component: 'Text',
+        bindings: { value: bindingPath },
+      };
+  }
+}
+
+// =============================================================================
+// String Literal → ExperienceNode
+// =============================================================================
+
+export function mapStringLiteral(
+  data: StringLiteralData,
+  parentId: string,
+  index: number,
+): IRExperienceNode {
+  const nodeId = generateId(parentId, 'text', String(index));
+  const node: IRExperienceNode = {
+    id: nodeId,
+    component: 'Text',
+    bindings: { value: `"${data.text}"` },
+  };
+
+  if (data.emphasis === 'big') {
+    node.config = { variant: 'heading' };
+  } else if (data.emphasis === 'small') {
+    node.config = { variant: 'caption' };
+  }
+
+  return node;
+}
+
+// =============================================================================
+// Iteration → ExperienceNode
+// =============================================================================
+
+export function mapIteration(
+  data: IterationData,
+  children: IRExperienceNode[],
+  parentId: string,
+  index: number,
+): IRExperienceNode {
+  const nodeId = generateId(parentId, 'each', data.subject);
+  const eachNode: IRExperienceNode = {
+    id: nodeId,
+    component: 'Each',
+  };
+
+  if (data.role === 'card') {
+    // Wrap children in a Card
+    const cardNode: IRExperienceNode = {
+      id: generateId(nodeId, 'card'),
+      component: 'Card',
+      children,
+    };
+    if (data.emphasis === 'small') {
+      cardNode.config = { size: 'small' };
+    }
+    if (children.length > 1) {
+      cardNode.layout = 'stack';
+    }
+    eachNode.children = [cardNode];
+  } else {
+    eachNode.children = children;
+  }
+
+  return eachNode;
+}
+
+// =============================================================================
+// Section → ExperienceNode
+// =============================================================================
+
+export function mapSection(
+  data: SectionData,
+  children: IRExperienceNode[],
+  parentId: string,
+): IRExperienceNode {
+  switch (data.name) {
+    case 'numbers':
+      return {
+        id: generateId(parentId, 'numbers'),
+        component: 'MetricsGrid',
+        children,
+      };
+
+    case 'tabs':
+      return {
+        id: generateId(parentId, 'tabs'),
+        component: 'TabbedLayout',
+        children,
+      };
+
+    case 'actions':
+      return {
+        id: generateId(parentId, 'actions'),
+        component: 'TransitionActions',
+      };
+
+    case 'controls':
+      return {
+        id: generateId(parentId, 'controls'),
+        layout: 'row',
+        children,
+      };
+
+    default:
+      return {
+        id: generateId(parentId, data.name),
+        children,
+      };
+  }
+}
+
+// =============================================================================
+// Search → ExperienceNode
+// =============================================================================
+
+export function mapSearch(
+  data: SearchData,
+  parentId: string,
+  index: number,
+): IRExperienceNode {
+  return {
+    id: generateId(parentId, 'search', String(index)),
+    component: 'SearchInput',
+    config: { target: data.target },
+  };
+}
+
+// =============================================================================
+// Navigation → ExperienceNode binding
+// =============================================================================
+
+export function mapNavigation(
+  data: NavigationData,
+  insideEach: boolean,
+  parentId: string,
+  index: number,
+): IRExperienceNode {
+  const nodeId = generateId(parentId, 'nav', String(index));
+  const prefix = insideEach ? '$item' : '$instance';
+
+  // Replace {its id} with binding template
+  const target = data.target.replace(
+    /\{its\s+id\}/g,
+    `\${${prefix}.id}`,
+  );
+
+  return {
+    id: nodeId,
+    component: 'Link',
+    bindings: { onClick: `$action.navigate("${target}")` },
+    config: { trigger: data.trigger },
+  };
+}
+
+// =============================================================================
+// Pages → ExperienceNode
+// =============================================================================
+
+export function mapPages(parentId: string, index: number): IRExperienceNode {
+  return {
+    id: generateId(parentId, 'pages', String(index)),
+    component: 'Pagination',
+  };
+}

package/src/dsl/compiler/field-mapper.ts

@@ -0,0 +1,187 @@
+/**
+ * Field Mapper — converts DSL FieldDefData to IR field definitions.
+ *
+ * Handles base type mapping, adjective→property mapping,
+ * and constraint→validation mapping.
+ */
+
+import type { FieldDefData } from '../types';
+import type { IRFieldDefinition, IRFieldValidation, IRWorkflowFieldType } from '../ir-types';
+import { snakeCase } from './utils';
+
+// =============================================================================
+// Base Type Mapping
+// =============================================================================
+
+const BASE_TYPE_MAP: Record<string, IRWorkflowFieldType> = {
+  'text': 'text',
+  'rich text': 'rich_text',
+  'number': 'number',
+  'integer': 'number',
+  'time': 'datetime',
+};
+
+function isTextLikeType(irType: IRWorkflowFieldType): boolean {
+  return irType === 'text' || irType === 'rich_text';
+}
+
+// =============================================================================
+// Public API
+// =============================================================================
+
+/**
+ * Map a DSL field definition to an IR field definition.
+ */
+export function mapField(data: FieldDefData): IRFieldDefinition {
+  const field: IRFieldDefinition = {
+    name: snakeCase(data.name),
+    type: resolveType(data.baseType),
+  };
+
+  // Adjective mapping
+  for (const adj of data.adjectives) {
+    applyAdjective(field, adj);
+  }
+
+  // Constraint mapping
+  const validation = buildValidation(data, field.type);
+  if (validation) {
+    field.validation = mergeValidation(field.validation, validation);
+  }
+
+  // Integer → add validation rule for whole numbers
+  if (data.baseType === 'integer') {
+    if (!field.validation) field.validation = {};
+    if (!field.validation.rules) field.validation.rules = [];
+    field.validation.rules.push({
+      expression: 'eq(round($value), $value)',
+      message: 'Must be a whole number',
+      severity: 'error',
+    });
+  }
+
+  // Choice of [...] → extract options
+  if (data.baseType.startsWith('choice of')) {
+    field.type = 'select';
+    const optionsMatch = data.baseType.match(/\[(.+)\]/);
+    if (optionsMatch) {
+      if (!field.validation) field.validation = {};
+      field.validation.options = optionsMatch[1]
+        .split(',')
+        .map(o => o.trim());
+    }
+  }
+
+  // Default value from constraints
+  const defaultConstraint = data.constraints.find(c => c.kind === 'default');
+  if (defaultConstraint) {
+    field.default_value = defaultConstraint.value;
+  }
+
+  return field;
+}
+
+// =============================================================================
+// Type Resolution
+// =============================================================================
+
+function resolveType(baseType: string): IRWorkflowFieldType {
+  if (baseType.startsWith('choice of')) return 'select';
+  // Known types map to canonical slugs; unknown types pass through as-is
+  // (custom Element-based field types use slugs like 'email', 'currency', 'my-org/address')
+  return BASE_TYPE_MAP[baseType] ?? baseType;
+}
+
+// =============================================================================
+// Adjective Application
+// =============================================================================
+
+function applyAdjective(field: IRFieldDefinition, adjective: string): void {
+  switch (adjective) {
+    case 'required':
+      field.required = true;
+      break;
+    case 'optional':
+      field.required = false;
+      break;
+    case 'non-negative':
+      if (!field.validation) field.validation = {};
+      field.validation.min = 0;
+      break;
+    case 'positive':
+      if (!field.validation) field.validation = {};
+      field.validation.min = 1;
+      break;
+    case 'computed':
+      field.computed = '';
+      break;
+    // lowercase, uppercase, readonly — stored but no direct IR mapping
+    default:
+      break;
+  }
+}
+
+// =============================================================================
+// Constraint → Validation
+// =============================================================================
+
+function buildValidation(
+  data: FieldDefData,
+  irType: IRWorkflowFieldType,
+): IRFieldValidation | null {
+  if (data.constraints.length === 0) return null;
+
+  const validation: IRFieldValidation = {};
+  let hasProps = false;
+
+  for (const c of data.constraints) {
+    switch (c.kind) {
+      case 'max':
+        if (isTextLikeType(irType)) {
+          validation.maxLength = c.value as number;
+        } else {
+          validation.max = c.value as number;
+        }
+        hasProps = true;
+        break;
+
+      case 'min':
+        if (isTextLikeType(irType)) {
+          validation.minLength = c.value as number;
+        } else {
+          validation.min = c.value as number;
+        }
+        hasProps = true;
+        break;
+
+      case 'between':
+        validation.min = c.value as number;
+        validation.max = c.value2 as number;
+        hasProps = true;
+        break;
+
+      case 'default':
+        // default_value is set on the field itself, not validation
+        break;
+
+      case 'unique':
+        // metadata flag — not a validation rule
+        break;
+    }
+  }
+
+  // Handle default_value separately (on the field, not in validation)
+  return hasProps ? validation : null;
+}
+
+/**
+ * Extract default_value from constraints.
+ * Called internally by mapField — the default_value is set on the field.
+ */
+function mergeValidation(
+  existing: IRFieldValidation | undefined,
+  incoming: IRFieldValidation,
+): IRFieldValidation {
+  if (!existing) return incoming;
+  return { ...existing, ...incoming };
+}

package/src/dsl/compiler/index.ts

@@ -0,0 +1,82 @@
+/**
+ * DSL Compiler — entry point.
+ *
+ * Pipeline: tokenize → parse → collectSymbols → compileWorkflows → compileViews → compileManifest
+ */
+
+import { tokenize } from '../lexer';
+import { parse } from '../parser';
+import type { ASTNode, ParseError } from '../types';
+import type { CompilationResult, CompilerError } from '../ir-types';
+import { collectSymbols } from './symbol-table';
+import { compileWorkflows } from './workflow-compiler';
+import { compileViews } from './view-compiler';
+import { compileManifest } from './manifest-compiler';
+
+// =============================================================================
+// Public API
+// =============================================================================
+
+/**
+ * Compile DSL source text into the full IR.
+ */
+export function compile(source: string): CompilationResult {
+  const tokens = tokenize(source);
+  const { nodes, errors: parseErrors } = parse(tokens);
+  return compileAST(nodes, parseErrors);
+}
+
+/**
+ * Compile pre-parsed AST nodes into the full IR.
+ */
+export function compileAST(
+  nodes: ASTNode[],
+  parseErrors?: ParseError[],
+): CompilationResult {
+  const allErrors: CompilerError[] = [];
+  const allWarnings: CompilerError[] = [];
+
+  // Convert parse errors
+  if (parseErrors) {
+    for (const pe of parseErrors) {
+      allErrors.push({
+        code: 'INVALID_EXPRESSION',
+        message: pe.message,
+        lineNumber: pe.lineNumber,
+        severity: 'error',
+      });
+    }
+  }
+
+  // Pass 1: Symbol collection
+  const symbols = collectSymbols(nodes);
+
+  // Pass 2: Workflow compilation
+  const { workflows, errors: wfErrors } = compileWorkflows(symbols);
+  for (const e of wfErrors) {
+    if (e.severity === 'error') allErrors.push(e);
+    else allWarnings.push(e);
+  }
+
+  // Pass 3: View compilation
+  const { experiences, errors: viewErrors } = compileViews(symbols);
+  for (const e of viewErrors) {
+    if (e.severity === 'error') allErrors.push(e);
+    else allWarnings.push(e);
+  }
+
+  // Pass 4: Manifest compilation
+  const { manifest, errors: mfErrors } = compileManifest(symbols);
+  for (const e of mfErrors) {
+    if (e.severity === 'error') allErrors.push(e);
+    else allWarnings.push(e);
+  }
+
+  return {
+    workflows,
+    experiences,
+    manifest,
+    errors: allErrors,
+    warnings: allWarnings,
+  };
+}