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

package/src/mixins.ts

@@ -1,1160 +0,0 @@
-/**
- * Model Mixins — higher-order functions that enhance ModelDefinitions.
- *
- * Mixins compose reusable cross-cutting concerns (audit trails, soft delete,
- * versioning, RBAC, etc.) into workflow model definitions. Each mixin takes
- * a ModelDefinition and returns a new ModelDefinition with additional fields,
- * states, and/or transitions — without mutating the input.
- *
- * @example
- * ```typescript
- * import { defineModel } from '@mindmatrix/react';
- * import { pipe, withAuditTrail, withSoftDelete, withTags } from '@mindmatrix/react/mixins';
- *
- * export default defineModel(pipe(
- *   {
- *     slug: 'invoice',
- *     fields: { amount: { type: 'currency', required: true } },
- *     states: { draft: { type: 'initial' }, sent: {}, paid: { type: 'end' } },
- *     transitions: {
- *       send: { from: 'draft', to: 'sent' },
- *       pay: { from: 'sent', to: 'paid' },
- *     },
- *   },
- *   withAuditTrail(),
- *   withSoftDelete({ retentionDays: 90 }),
- *   withTags(),
- * ));
- * ```
- *
- * @module @mindmatrix/react/mixins
- */
-
-import type {
-  ModelDefinition,
-  WorkflowFieldDescriptor,
-  StateDescriptor,
-  TransitionDescriptor,
-  ActionDefinition,
-  RoleDefinition,
-} from './config/defineModel';
-
-// =============================================================================
-// Core Types
-// =============================================================================
-
-/**
- * A mixin function that takes a ModelDefinition and returns an enhanced one.
- *
- * Mixins MUST be pure — they never mutate the input definition. They return
- * a new object with merged fields, states, transitions, and roles.
- */
-export type ModelMixin = (def: ModelDefinition) => ModelDefinition;
-
-// =============================================================================
-// Deep Merge Helpers (internal)
-// =============================================================================
-
-/**
- * Deep-merge two records of fields, preserving existing entries.
- * New fields are added; existing fields are NOT overwritten.
- */
-function mergeFields(
-  existing: Record<string, WorkflowFieldDescriptor>,
-  incoming: Record<string, WorkflowFieldDescriptor>,
-): Record<string, WorkflowFieldDescriptor> {
-  const result = { ...existing };
-  for (const [key, value] of Object.entries(incoming)) {
-    if (!(key in result)) {
-      result[key] = value;
-    }
-  }
-  return result;
-}
-
-/**
- * Deep-merge two records of states. For existing states, onEnter/onExit
- * actions from `incoming` are appended (not replaced).
- */
-function mergeStates(
-  existing: Record<string, StateDescriptor>,
-  incoming: Record<string, StateDescriptor>,
-): Record<string, StateDescriptor> {
-  const result: Record<string, StateDescriptor> = {};
-  // Copy all existing states
-  for (const [key, value] of Object.entries(existing)) {
-    result[key] = { ...value };
-  }
-  // Merge incoming states
-  for (const [key, value] of Object.entries(incoming)) {
-    if (key in result) {
-      const merged: StateDescriptor = { ...result[key] };
-      if (value.onEnter && value.onEnter.length > 0) {
-        merged.onEnter = [...(merged.onEnter ?? []), ...value.onEnter];
-      }
-      if (value.onExit && value.onExit.length > 0) {
-        merged.onExit = [...(merged.onExit ?? []), ...value.onExit];
-      }
-      result[key] = merged;
-    } else {
-      result[key] = { ...value };
-    }
-  }
-  return result;
-}
-
-/**
- * Merge transitions — new transitions are added; existing ones are NOT overwritten.
- */
-function mergeTransitions(
-  existing: Record<string, TransitionDescriptor>,
-  incoming: Record<string, TransitionDescriptor>,
-): Record<string, TransitionDescriptor> {
-  const result = { ...existing };
-  for (const [key, value] of Object.entries(incoming)) {
-    if (!(key in result)) {
-      result[key] = value;
-    }
-  }
-  return result;
-}
-
-/**
- * Merge role definitions — new roles are added; existing ones are NOT overwritten.
- */
-function mergeRoles(
-  existing: Record<string, RoleDefinition> | undefined,
-  incoming: Record<string, RoleDefinition> | undefined,
-): Record<string, RoleDefinition> | undefined {
-  if (!incoming) return existing;
-  if (!existing) return incoming;
-  const result = { ...existing };
-  for (const [key, value] of Object.entries(incoming)) {
-    if (!(key in result)) {
-      result[key] = value;
-    }
-  }
-  return result;
-}
-
-/**
- * Collect all non-terminal state names from a definition.
- * Non-terminal = not type 'end' and not type 'cancelled'.
- */
-function getNonTerminalStates(def: ModelDefinition): string[] {
-  return Object.entries(def.states)
-    .filter(([, s]) => s.type !== 'end' && s.type !== 'cancelled')
-    .map(([name]) => name);
-}
-
-// =============================================================================
-// Core Infrastructure
-// =============================================================================
-
-/**
- * Apply multiple mixins to a model definition, left to right.
- *
- * Each mixin receives the output of the previous mixin, allowing
- * composed enhancements to build on each other.
- *
- * @param def - The base model definition.
- * @param mixins - One or more mixin functions to apply.
- * @returns A new ModelDefinition with all mixins applied.
- *
- * @example
- * ```typescript
- * import { defineModel } from '@mindmatrix/react';
- * import { applyMixins, withTimestamps, withTags } from '@mindmatrix/react/mixins';
- *
- * const base = {
- *   slug: 'article',
- *   fields: { title: { type: 'string' } },
- *   states: { draft: { type: 'initial' as const }, published: { type: 'end' as const } },
- *   transitions: { publish: { from: 'draft', to: 'published' } },
- * };
- *
- * export default defineModel(applyMixins(base, withTimestamps(), withTags()));
- * ```
- */
-export function applyMixins(def: ModelDefinition, ...mixins: ModelMixin[]): ModelDefinition {
-  return mixins.reduce<ModelDefinition>((acc, mixin) => mixin(acc), def);
-}
-
-/**
- * Functional composition helper — alias for `applyMixins`.
- *
- * Reads naturally as a pipeline: start with a definition, then pipe
- * it through a series of mixins.
- *
- * @param def - The base model definition.
- * @param mixins - One or more mixin functions to apply.
- * @returns A new ModelDefinition with all mixins applied.
- *
- * @example
- * ```typescript
- * import { defineModel } from '@mindmatrix/react';
- * import { pipe, withAuditTrail, withSoftDelete, withOwnership } from '@mindmatrix/react/mixins';
- *
- * export default defineModel(pipe(
- *   {
- *     slug: 'task',
- *     fields: { title: { type: 'string', required: true } },
- *     states: { open: { type: 'initial' }, done: { type: 'end' } },
- *     transitions: { complete: { from: 'open', to: 'done' } },
- *   },
- *   withOwnership(),
- *   withAuditTrail(),
- *   withSoftDelete(),
- * ));
- * ```
- */
-export function pipe(def: ModelDefinition, ...mixins: ModelMixin[]): ModelDefinition {
-  return applyMixins(def, ...mixins);
-}
-
-// =============================================================================
-// withAuditTrail
-// =============================================================================
-
-/**
- * Options for the {@link withAuditTrail} mixin.
- */
-export interface WithAuditTrailOptions {
-  /**
-   * If specified, adds a `changeLog` array field that records which
-   * tracked fields changed on each transition.
-   *
-   * @example `{ trackFields: ['status', 'amount', 'assignee'] }`
-   */
-  trackFields?: string[];
-}
-
-/**
- * Adds audit trail fields and auto-set actions to a model definition.
- *
- * Injects:
- * - `createdAt` (datetime) — set on initial state entry
- * - `createdBy` (string) — set on initial state entry from `context.actor_id`
- * - `updatedAt` (datetime) — set on every transition
- * - `updatedBy` (string) — set on every transition from `context.actor_id`
- * - `changeLog` (array, optional) — records field-level changes if `trackFields` is set
- *
- * @param options - Optional configuration.
- * @returns A {@link ModelMixin} function.
- *
- * @example
- * ```typescript
- * import { defineModel } from '@mindmatrix/react';
- * import { pipe, withAuditTrail } from '@mindmatrix/react/mixins';
- *
- * export default defineModel(pipe(
- *   {
- *     slug: 'order',
- *     fields: { total: { type: 'currency' } },
- *     states: { draft: { type: 'initial' }, placed: { type: 'end' } },
- *     transitions: { place: { from: 'draft', to: 'placed' } },
- *   },
- *   withAuditTrail({ trackFields: ['total'] }),
- * ));
- * ```
- */
-export function withAuditTrail(options: WithAuditTrailOptions = {}): ModelMixin {
-  return (def: ModelDefinition): ModelDefinition => {
-    const auditFields: Record<string, WorkflowFieldDescriptor> = {
-      createdAt: { type: 'datetime', label: 'Created At' },
-      createdBy: { type: 'string', label: 'Created By' },
-      updatedAt: { type: 'datetime', label: 'Updated At' },
-      updatedBy: { type: 'string', label: 'Updated By' },
-    };
-
-    if (options.trackFields && options.trackFields.length > 0) {
-      auditFields.changeLog = {
-        type: 'array',
-        items: { type: 'object' },
-        label: 'Change Log',
-        description: `Tracks changes to: ${options.trackFields.join(', ')}`,
-      };
-    }
-
-    // Build set_fields actions for transitions
-    const updateAction: ActionDefinition = {
-      id: '_audit_update',
-      type: 'set_fields',
-      mode: 'auto',
-      config: {
-        fields: {
-          updatedAt: { expression: 'NOW()' },
-          updatedBy: { expression: 'context.actor_id' },
-        },
-      },
-    };
-
-    // Inject updatedAt/updatedBy into all existing transitions
-    const transitions: Record<string, TransitionDescriptor> = {};
-    for (const [name, t] of Object.entries(def.transitions)) {
-      transitions[name] = {
-        ...t,
-        actions: [...(t.actions ?? []), updateAction],
-      };
-    }
-
-    // Inject createdAt/createdBy into onEnter of the initial state
-    const states: Record<string, StateDescriptor> = {};
-    for (const [name, s] of Object.entries(def.states)) {
-      if (s.type === 'initial') {
-        const creationAction: ActionDefinition = {
-          id: '_audit_create',
-          type: 'set_fields',
-          mode: 'auto',
-          config: {
-            fields: {
-              createdAt: { expression: 'NOW()' },
-              createdBy: { expression: 'context.actor_id' },
-              updatedAt: { expression: 'NOW()' },
-              updatedBy: { expression: 'context.actor_id' },
-            },
-          },
-        };
-        states[name] = {
-          ...s,
-          onEnter: [...(s.onEnter ?? []), creationAction],
-        };
-      } else {
-        states[name] = { ...s };
-      }
-    }
-
-    return {
-      ...def,
-      fields: mergeFields(def.fields, auditFields),
-      states: mergeStates(def.states, states),
-      transitions,
-    };
-  };
-}
-
-// =============================================================================
-// withSoftDelete
-// =============================================================================
-
-/**
- * Options for the {@link withSoftDelete} mixin.
- */
-export interface WithSoftDeleteOptions {
-  /**
-   * Number of days to retain soft-deleted records before permanent deletion.
-   * Stored as metadata; enforcement is handled by the engine or a scheduled job.
-   */
-  retentionDays?: number;
-
-  /**
-   * Whether restore (un-delete) is allowed. Default: `true`.
-   */
-  restoreAllowed?: boolean;
-
-  /**
-   * Roles allowed to perform delete/restore. If omitted, any role can.
-   */
-  roles?: string[];
-}
-
-/**
- * Adds soft-delete capability to a model definition.
- *
- * Injects:
- * - A `deleted` end state
- * - `deletedAt` (datetime) and `deletedBy` (string) fields
- * - A `delete` transition from all non-terminal states to `deleted`
- * - A `restore` transition from `deleted` back to the initial state (if `restoreAllowed`)
- *
- * @param options - Optional configuration.
- * @returns A {@link ModelMixin} function.
- *
- * @example
- * ```typescript
- * import { defineModel } from '@mindmatrix/react';
- * import { pipe, withSoftDelete } from '@mindmatrix/react/mixins';
- *
- * export default defineModel(pipe(
- *   {
- *     slug: 'document',
- *     fields: { title: { type: 'string' } },
- *     states: { active: { type: 'initial' }, archived: { type: 'end' } },
- *     transitions: { archive: { from: 'active', to: 'archived' } },
- *   },
- *   withSoftDelete({ retentionDays: 30, roles: ['admin'] }),
- * ));
- * ```
- */
-export function withSoftDelete(options: WithSoftDeleteOptions = {}): ModelMixin {
-  const { retentionDays, restoreAllowed = true, roles } = options;
-
-  return (def: ModelDefinition): ModelDefinition => {
-    const deleteFields: Record<string, WorkflowFieldDescriptor> = {
-      deletedAt: { type: 'datetime', label: 'Deleted At' },
-      deletedBy: { type: 'string', label: 'Deleted By' },
-    };
-
-    const deleteState: Record<string, StateDescriptor> = {
-      deleted: { type: 'end', description: 'Soft-deleted record' },
-    };
-
-    const nonTerminalStates = getNonTerminalStates(def);
-
-    const deleteTransition: TransitionDescriptor = {
-      from: nonTerminalStates,
-      to: 'deleted',
-      description: 'Soft-delete this record',
-      ...(roles ? { roles } : {}),
-      actions: [
-        {
-          id: '_soft_delete_stamp',
-          type: 'set_fields',
-          mode: 'auto',
-          config: {
-            fields: {
-              deletedAt: { expression: 'NOW()' },
-              deletedBy: { expression: 'context.actor_id' },
-            },
-          },
-        },
-      ],
-    };
-
-    const newTransitions: Record<string, TransitionDescriptor> = {
-      delete: deleteTransition,
-    };
-
-    // Find the initial state for restore target
-    if (restoreAllowed) {
-      const initialState = Object.entries(def.states).find(([, s]) => s.type === 'initial');
-      if (initialState) {
-        // Restore goes back to initial state; change type to regular (not end)
-        deleteState.deleted = { description: 'Soft-deleted record' };
-        newTransitions.restore = {
-          from: 'deleted',
-          to: initialState[0],
-          description: 'Restore a soft-deleted record',
-          ...(roles ? { roles } : {}),
-          actions: [
-            {
-              id: '_soft_delete_clear',
-              type: 'set_fields',
-              mode: 'auto',
-              config: {
-                fields: {
-                  deletedAt: { expression: 'null' },
-                  deletedBy: { expression: 'null' },
-                },
-              },
-            },
-          ],
-        };
-      }
-    }
-
-    const result: ModelDefinition = {
-      ...def,
-      fields: mergeFields(def.fields, deleteFields),
-      states: mergeStates(def.states, deleteState),
-      transitions: mergeTransitions(def.transitions, newTransitions),
-    };
-
-    if (retentionDays !== undefined) {
-      result.metadata = {
-        ...def.metadata,
-        softDelete: { retentionDays },
-      };
-    }
-
-    return result;
-  };
-}
-
-// =============================================================================
-// withVersioning
-// =============================================================================
-
-/**
- * Options for the {@link withVersioning} mixin.
- */
-export interface WithVersioningOptions {
-  /**
-   * Transition names that should automatically create a version snapshot
-   * before executing. A `set_fields` action incrementing `version` is
-   * prepended to these transitions.
-   *
-   * @example `{ autoVersionOnTransitions: ['publish', 'approve'] }`
-   */
-  autoVersionOnTransitions?: string[];
-}
-
-/**
- * Adds version tracking to a model definition.
- *
- * Injects:
- * - `version` (number, default 1) — incremented on version-creating transitions
- * - `previousVersionId` (string) — ID of the prior version snapshot
- * - A `create_version` self-transition on the initial state that spawns
- *   a snapshot sub-workflow and increments the version counter
- *
- * @param options - Optional configuration.
- * @returns A {@link ModelMixin} function.
- *
- * @example
- * ```typescript
- * import { defineModel } from '@mindmatrix/react';
- * import { pipe, withVersioning } from '@mindmatrix/react/mixins';
- *
- * export default defineModel(pipe(
- *   {
- *     slug: 'policy',
- *     fields: { content: { type: 'string' } },
- *     states: { draft: { type: 'initial' }, published: {} },
- *     transitions: { publish: { from: 'draft', to: 'published' } },
- *   },
- *   withVersioning({ autoVersionOnTransitions: ['publish'] }),
- * ));
- * ```
- */
-export function withVersioning(options: WithVersioningOptions = {}): ModelMixin {
-  return (def: ModelDefinition): ModelDefinition => {
-    const versionFields: Record<string, WorkflowFieldDescriptor> = {
-      version: { type: 'number', default: 1, label: 'Version' },
-      previousVersionId: { type: 'string', label: 'Previous Version ID' },
-    };
-
-    const nonTerminalStates = getNonTerminalStates(def);
-
-    const newTransitions: Record<string, TransitionDescriptor> = {
-      create_version: {
-        from: nonTerminalStates,
-        to: nonTerminalStates[0],
-        description: 'Create a version snapshot',
-        actions: [
-          {
-            id: '_version_snapshot',
-            type: 'spawn_subworkflow',
-            mode: 'auto',
-            config: {
-              definition_slug: def.slug,
-              blocking: false,
-              input_mapping: { _snapshot: 'true' },
-            },
-          },
-          {
-            id: '_version_increment',
-            type: 'set_fields',
-            mode: 'auto',
-            config: {
-              fields: {
-                version: { expression: 'state_data.version + 1' },
-              },
-            },
-          },
-        ],
-      },
-    };
-
-    // If autoVersionOnTransitions is specified, inject version increment
-    // into those transitions
-    const transitions: Record<string, TransitionDescriptor> = { ...def.transitions };
-    if (options.autoVersionOnTransitions) {
-      const versionAction: ActionDefinition = {
-        id: '_auto_version',
-        type: 'set_fields',
-        mode: 'auto',
-        config: {
-          fields: {
-            version: { expression: 'state_data.version + 1' },
-          },
-        },
-      };
-
-      for (const transName of options.autoVersionOnTransitions) {
-        if (transName in transitions) {
-          const existing = transitions[transName];
-          transitions[transName] = {
-            ...existing,
-            actions: [versionAction, ...(existing.actions ?? [])],
-          };
-        }
-      }
-    }
-
-    return {
-      ...def,
-      fields: mergeFields(def.fields, versionFields),
-      transitions: mergeTransitions(transitions, newTransitions),
-    };
-  };
-}
-
-// =============================================================================
-// withRBAC
-// =============================================================================
-
-/**
- * Options for the {@link withRBAC} mixin.
- */
-export interface WithRBACOptions {
-  /**
-   * Role definitions to add to the model. Each role can have permissions
-   * and can inherit from other roles.
-   *
-   * @example
-   * ```typescript
-   * roles: {
-   *   admin: { permissions: ['manage_users', 'delete'], inherits: ['editor'] },
-   *   editor: { permissions: ['read', 'write'] },
-   *   viewer: { permissions: ['read'] },
-   * }
-   * ```
-   */
-  roles: Record<string, { permissions?: string[]; inherits?: string[] }>;
-
-  /**
-   * Map of transition names to the roles allowed to trigger them.
-   * Injects role guards into the specified transitions.
-   *
-   * @example `{ transitionRoles: { approve: ['admin', 'manager'], delete: ['admin'] } }`
-   */
-  transitionRoles?: Record<string, string[]>;
-}
-
-/**
- * Adds role-based access control (RBAC) to a model definition.
- *
- * Injects:
- * - Role definitions into `roles`
- * - Role guards (via `roles` property) into specified transitions
- *
- * @param options - RBAC configuration (required).
- * @returns A {@link ModelMixin} function.
- *
- * @example
- * ```typescript
- * import { defineModel } from '@mindmatrix/react';
- * import { pipe, withRBAC } from '@mindmatrix/react/mixins';
- *
- * export default defineModel(pipe(
- *   {
- *     slug: 'expense-report',
- *     fields: { amount: { type: 'currency' } },
- *     states: { draft: { type: 'initial' }, approved: { type: 'end' } },
- *     transitions: { approve: { from: 'draft', to: 'approved' } },
- *   },
- *   withRBAC({
- *     roles: {
- *       admin: { permissions: ['approve', 'delete'] },
- *       submitter: { permissions: ['create', 'read'] },
- *     },
- *     transitionRoles: { approve: ['admin'] },
- *   }),
- * ));
- * ```
- */
-export function withRBAC(options: WithRBACOptions): ModelMixin {
-  return (def: ModelDefinition): ModelDefinition => {
-    const newRoles: Record<string, RoleDefinition> = {};
-    for (const [name, role] of Object.entries(options.roles)) {
-      newRoles[name] = {
-        permissions: role.permissions,
-        inherits: role.inherits,
-      };
-    }
-
-    // Inject role guards into transitions
-    const transitions: Record<string, TransitionDescriptor> = { ...def.transitions };
-    if (options.transitionRoles) {
-      for (const [transName, allowedRoles] of Object.entries(options.transitionRoles)) {
-        if (transName in transitions) {
-          transitions[transName] = {
-            ...transitions[transName],
-            roles: allowedRoles,
-          };
-        }
-      }
-    }
-
-    return {
-      ...def,
-      roles: mergeRoles(def.roles, newRoles),
-      transitions,
-    };
-  };
-}
-
-// =============================================================================
-// withTimestamps
-// =============================================================================
-
-/**
- * Adds simple timestamp fields (`createdAt`, `updatedAt`) with auto-set logic.
- *
- * This is a lighter alternative to {@link withAuditTrail} when you only need
- * timestamps without `createdBy`/`updatedBy` tracking.
- *
- * Injects:
- * - `createdAt` (datetime) — set on initial state entry
- * - `updatedAt` (datetime) — set on every transition
- *
- * @returns A {@link ModelMixin} function.
- *
- * @example
- * ```typescript
- * import { defineModel } from '@mindmatrix/react';
- * import { pipe, withTimestamps } from '@mindmatrix/react/mixins';
- *
- * export default defineModel(pipe(
- *   {
- *     slug: 'note',
- *     fields: { body: { type: 'string' } },
- *     states: { active: { type: 'initial' } },
- *     transitions: {},
- *   },
- *   withTimestamps(),
- * ));
- * ```
- */
-export function withTimestamps(): ModelMixin {
-  return (def: ModelDefinition): ModelDefinition => {
-    const timestampFields: Record<string, WorkflowFieldDescriptor> = {
-      createdAt: { type: 'datetime', label: 'Created At' },
-      updatedAt: { type: 'datetime', label: 'Updated At' },
-    };
-
-    // Set createdAt on initial state entry
-    const states: Record<string, StateDescriptor> = {};
-    for (const [name, s] of Object.entries(def.states)) {
-      if (s.type === 'initial') {
-        states[name] = {
-          ...s,
-          onEnter: [
-            ...(s.onEnter ?? []),
-            {
-              id: '_timestamps_create',
-              type: 'set_fields',
-              mode: 'auto' as const,
-              config: {
-                fields: {
-                  createdAt: { expression: 'NOW()' },
-                  updatedAt: { expression: 'NOW()' },
-                },
-              },
-            },
-          ],
-        };
-      } else {
-        states[name] = { ...s };
-      }
-    }
-
-    // Set updatedAt on every transition
-    const transitions: Record<string, TransitionDescriptor> = {};
-    const updateAction: ActionDefinition = {
-      id: '_timestamps_update',
-      type: 'set_fields',
-      mode: 'auto',
-      config: {
-        fields: {
-          updatedAt: { expression: 'NOW()' },
-        },
-      },
-    };
-    for (const [name, t] of Object.entries(def.transitions)) {
-      transitions[name] = {
-        ...t,
-        actions: [...(t.actions ?? []), updateAction],
-      };
-    }
-
-    return {
-      ...def,
-      fields: mergeFields(def.fields, timestampFields),
-      states: mergeStates(def.states, states),
-      transitions,
-    };
-  };
-}
-
-// =============================================================================
-// withSlug
-// =============================================================================
-
-/**
- * Options for the {@link withSlug} mixin.
- */
-export interface WithSlugOptions {
-  /**
-   * The field name to derive the slug from (e.g., `'title'`, `'name'`).
-   */
-  sourceField: string;
-}
-
-/**
- * Adds an auto-generated `slug` field derived from a source field.
- *
- * The slug is computed as a kebab-case, URL-safe version of the source field.
- * It is set via a computed expression.
- *
- * Injects:
- * - `slug` (string) — computed from the source field
- *
- * @param options - Configuration specifying the source field.
- * @returns A {@link ModelMixin} function.
- *
- * @example
- * ```typescript
- * import { defineModel } from '@mindmatrix/react';
- * import { pipe, withSlug } from '@mindmatrix/react/mixins';
- *
- * export default defineModel(pipe(
- *   {
- *     slug: 'article',
- *     fields: { title: { type: 'string', required: true } },
- *     states: { draft: { type: 'initial' }, published: { type: 'end' } },
- *     transitions: { publish: { from: 'draft', to: 'published' } },
- *   },
- *   withSlug({ sourceField: 'title' }),
- * ));
- * ```
- */
-export function withSlug(options: WithSlugOptions): ModelMixin {
-  return (def: ModelDefinition): ModelDefinition => {
-    const slugField: Record<string, WorkflowFieldDescriptor> = {
-      slug: {
-        type: 'string',
-        label: 'Slug',
-        description: `Auto-generated from ${options.sourceField}`,
-        computed: `SLUGIFY(state_data.${options.sourceField})`,
-        computedDeps: [options.sourceField],
-      },
-    };
-
-    return {
-      ...def,
-      fields: mergeFields(def.fields, slugField),
-    };
-  };
-}
-
-// =============================================================================
-// withOwnership
-// =============================================================================
-
-/**
- * Options for the {@link withOwnership} mixin.
- */
-export interface WithOwnershipOptions {
-  /**
-   * Field name for the owner ID. Default: `'ownerId'`.
-   */
-  ownerField?: string;
-}
-
-/**
- * Adds ownership fields auto-set from context on creation.
- *
- * Injects:
- * - `ownerId` (string, or custom name) — set to `context.actor_id` on initial state entry
- * - `ownerName` (string) — set to `context.actor_name` on initial state entry
- *
- * @param options - Optional configuration.
- * @returns A {@link ModelMixin} function.
- *
- * @example
- * ```typescript
- * import { defineModel } from '@mindmatrix/react';
- * import { pipe, withOwnership } from '@mindmatrix/react/mixins';
- *
- * export default defineModel(pipe(
- *   {
- *     slug: 'project',
- *     fields: { name: { type: 'string' } },
- *     states: { active: { type: 'initial' }, completed: { type: 'end' } },
- *     transitions: { complete: { from: 'active', to: 'completed' } },
- *   },
- *   withOwnership(),
- * ));
- * ```
- */
-export function withOwnership(options: WithOwnershipOptions = {}): ModelMixin {
-  const ownerField = options.ownerField ?? 'ownerId';
-
-  return (def: ModelDefinition): ModelDefinition => {
-    const ownerFields: Record<string, WorkflowFieldDescriptor> = {
-      [ownerField]: { type: 'string', label: 'Owner ID' },
-      ownerName: { type: 'string', label: 'Owner Name' },
-    };
-
-    // Set ownership fields on initial state entry
-    const states: Record<string, StateDescriptor> = {};
-    for (const [name, s] of Object.entries(def.states)) {
-      if (s.type === 'initial') {
-        states[name] = {
-          ...s,
-          onEnter: [
-            ...(s.onEnter ?? []),
-            {
-              id: '_ownership_set',
-              type: 'set_fields',
-              mode: 'auto' as const,
-              config: {
-                fields: {
-                  [ownerField]: { expression: 'context.actor_id' },
-                  ownerName: { expression: 'context.actor_name' },
-                },
-              },
-            },
-          ],
-        };
-      } else {
-        states[name] = { ...s };
-      }
-    }
-
-    return {
-      ...def,
-      fields: mergeFields(def.fields, ownerFields),
-      states: mergeStates(def.states, states),
-    };
-  };
-}
-
-// =============================================================================
-// withTags
-// =============================================================================
-
-/**
- * Adds a `tags` array field with `add_tag` and `remove_tag` self-transitions.
- *
- * The self-transitions are available from all non-terminal states, allowing
- * tags to be managed at any point in the workflow lifecycle.
- *
- * Injects:
- * - `tags` (array of strings) — default empty array
- * - `add_tag` transition — appends a tag (self-transition)
- * - `remove_tag` transition — removes a tag (self-transition)
- *
- * @returns A {@link ModelMixin} function.
- *
- * @example
- * ```typescript
- * import { defineModel } from '@mindmatrix/react';
- * import { pipe, withTags } from '@mindmatrix/react/mixins';
- *
- * export default defineModel(pipe(
- *   {
- *     slug: 'ticket',
- *     fields: { title: { type: 'string' } },
- *     states: { open: { type: 'initial' }, closed: { type: 'end' } },
- *     transitions: { close: { from: 'open', to: 'closed' } },
- *   },
- *   withTags(),
- * ));
- * ```
- */
-export function withTags(): ModelMixin {
-  return (def: ModelDefinition): ModelDefinition => {
-    const tagFields: Record<string, WorkflowFieldDescriptor> = {
-      tags: {
-        type: 'array',
-        items: { type: 'string' },
-        default: [],
-        label: 'Tags',
-      },
-    };
-
-    const nonTerminalStates = getNonTerminalStates(def);
-
-    const tagTransitions: Record<string, TransitionDescriptor> = {};
-
-    if (nonTerminalStates.length > 0) {
-      tagTransitions.add_tag = {
-        from: nonTerminalStates,
-        to: nonTerminalStates[0],
-        description: 'Add a tag',
-        actions: [
-          {
-            id: '_tag_add',
-            type: 'set_field',
-            mode: 'auto',
-            config: {
-              field: 'tags',
-              expression: 'APPEND(state_data.tags, input.tag)',
-            },
-          },
-        ],
-      };
-
-      tagTransitions.remove_tag = {
-        from: nonTerminalStates,
-        to: nonTerminalStates[0],
-        description: 'Remove a tag',
-        actions: [
-          {
-            id: '_tag_remove',
-            type: 'set_field',
-            mode: 'auto',
-            config: {
-              field: 'tags',
-              expression: 'FILTER(state_data.tags, item != input.tag)',
-            },
-          },
-        ],
-      };
-    }
-
-    return {
-      ...def,
-      fields: mergeFields(def.fields, tagFields),
-      transitions: mergeTransitions(def.transitions, tagTransitions),
-    };
-  };
-}
-
-// =============================================================================
-// withSearch
-// =============================================================================
-
-/**
- * Options for the {@link withSearch} mixin.
- */
-export interface WithSearchOptions {
-  /**
-   * Field names to include in the full-text search index.
-   * These fields are concatenated into a single `searchText` computed field.
-   *
-   * @example `{ fields: ['title', 'description', 'content'] }`
-   */
-  fields: string[];
-}
-
-/**
- * Adds a `searchText` computed field that concatenates specified fields
- * for full-text search indexing.
- *
- * Injects:
- * - `searchText` (string, computed) — concatenation of the specified fields
- *
- * @param options - Configuration specifying which fields to index.
- * @returns A {@link ModelMixin} function.
- *
- * @example
- * ```typescript
- * import { defineModel } from '@mindmatrix/react';
- * import { pipe, withSearch } from '@mindmatrix/react/mixins';
- *
- * export default defineModel(pipe(
- *   {
- *     slug: 'article',
- *     fields: {
- *       title: { type: 'string' },
- *       body: { type: 'string' },
- *       author: { type: 'string' },
- *     },
- *     states: { draft: { type: 'initial' } },
- *     transitions: {},
- *   },
- *   withSearch({ fields: ['title', 'body', 'author'] }),
- * ));
- * ```
- */
-export function withSearch(options: WithSearchOptions): ModelMixin {
-  return (def: ModelDefinition): ModelDefinition => {
-    const concatExpr = options.fields
-      .map((f) => `COALESCE(state_data.${f}, "")`)
-      .join(' + " " + ');
-
-    const searchFields: Record<string, WorkflowFieldDescriptor> = {
-      searchText: {
-        type: 'string',
-        label: 'Search Text',
-        description: `Full-text search index over: ${options.fields.join(', ')}`,
-        computed: concatExpr,
-        computedDeps: options.fields,
-      },
-    };
-
-    return {
-      ...def,
-      fields: mergeFields(def.fields, searchFields),
-    };
-  };
-}
-
-// =============================================================================
-// withPagination
-// =============================================================================
-
-/**
- * Adds pagination and sorting fields for collection querying patterns.
- *
- * These fields are typically used by views and data grids to control
- * how records are fetched and displayed. They live at the ephemeral scope
- * (not persisted to the database).
- *
- * Injects:
- * - `sortField` (string, default `'createdAt'`) — field name to sort by
- * - `sortOrder` (string, default `'desc'`) — sort direction (`'asc'` or `'desc'`)
- * - `page` (number, default 1) — current page number
- * - `pageSize` (number, default 25) — records per page
- *
- * @returns A {@link ModelMixin} function.
- *
- * @example
- * ```typescript
- * import { defineModel } from '@mindmatrix/react';
- * import { pipe, withPagination, withTimestamps } from '@mindmatrix/react/mixins';
- *
- * export default defineModel(pipe(
- *   {
- *     slug: 'product-catalog',
- *     fields: { name: { type: 'string' }, price: { type: 'currency' } },
- *     states: { active: { type: 'initial' } },
- *     transitions: {},
- *   },
- *   withTimestamps(),
- *   withPagination(),
- * ));
- * ```
- */
-export function withPagination(): ModelMixin {
-  return (def: ModelDefinition): ModelDefinition => {
-    const paginationFields: Record<string, WorkflowFieldDescriptor> = {
-      sortField: {
-        type: 'string',
-        default: 'createdAt',
-        label: 'Sort Field',
-        stateHome: { scope: 'ephemeral', persistence: 'none' },
-      },
-      sortOrder: {
-        type: 'string',
-        default: 'desc',
-        enum: ['asc', 'desc'],
-        label: 'Sort Order',
-        stateHome: { scope: 'ephemeral', persistence: 'none' },
-      },
-      page: {
-        type: 'number',
-        default: 1,
-        label: 'Page',
-        validation: { min: 1 },
-        stateHome: { scope: 'ephemeral', persistence: 'none' },
-      },
-      pageSize: {
-        type: 'number',
-        default: 25,
-        label: 'Page Size',
-        validation: { min: 1, max: 100 },
-        stateHome: { scope: 'ephemeral', persistence: 'none' },
-      },
-    };
-
-    return {
-      ...def,
-      fields: mergeFields(def.fields, paginationFields),
-    };
-  };
-}