@mmapp/react 0.1.0-alpha.1

package/src/components/ExperienceWorkflowBridge.tsx

@@ -0,0 +1,123 @@
+/**
+ * ExperienceWorkflowBridge — Wrapper component that connects the player engine
+ * to the view rendering layer (ComponentTreeRenderer).
+ *
+ * This component bridges the reactive effects layer (player-core state machine +
+ * event bus + action dispatcher) with the view rendering layer (CTR). It:
+ *
+ * - Creates a player instance from an experience workflow definition
+ * - Provides the PlayerHandle via context to all descendants
+ * - Subscribes to domain events via WebSocket transport
+ * - Renders the appropriate experience tree based on the current state
+ * - Passes transition callbacks that wire through the player engine
+ *
+ * Usage:
+ * ```tsx
+ * <ExperienceWorkflowBridge
+ *   definition={myWorkflowDef}
+ *   transport={socketTransport}
+ *   renderView={(player, viewConfig) => (
+ *     <ComponentTreeRenderer tree={viewConfig.tree} entityType="..." entityId="..." />
+ *   )}
+ * />
+ * ```
+ */
+
+import { useMemo } from 'react';
+import type { ActionHandlerFn } from '@mindmatrix/player-core';
+import type {
+  ExperienceWorkflowDefinition,
+  ExperienceViewConfig,
+  PlayerHandle,
+  DomainSubscriptionConfig,
+} from '../types';
+import { usePlayer } from '../hooks/usePlayer';
+import { useDomainSubscription, type DomainSubscriptionTransport } from '../hooks/useDomainSubscription';
+import { PlayerProvider } from './PlayerProvider';
+
+export interface ExperienceWorkflowBridgeProps {
+  /** Experience workflow definition to run */
+  definition: ExperienceWorkflowDefinition;
+  /** Initial state_data */
+  initialData?: Record<string, unknown>;
+  /** Custom action handlers */
+  actionHandlers?: Record<string, ActionHandlerFn>;
+  /** WebSocket transport for domain events */
+  transport?: DomainSubscriptionTransport | null;
+  /** Domain subscription configuration */
+  subscription?: Omit<DomainSubscriptionConfig, 'onEvent'>;
+  /** Render function — receives the player handle and view config for current state */
+  renderView: (player: PlayerHandle, viewConfig: ExperienceViewConfig | undefined) => React.ReactNode;
+  /** Enable debug logging */
+  debug?: boolean;
+  /** Callback for domain events */
+  onDomainEvent?: DomainSubscriptionConfig['onEvent'];
+}
+
+/**
+ * Hook to access the event bus for domain subscription wiring.
+ * Internal — used by ExperienceWorkflowBridge only.
+ */
+function ExperienceWorkflowBridgeInner({
+  definition,
+  initialData,
+  actionHandlers,
+  transport,
+  subscription,
+  renderView,
+  debug,
+  onDomainEvent,
+}: ExperienceWorkflowBridgeProps) {
+  const player = usePlayer({
+    definition,
+    initialData,
+    actionHandlers,
+    debug,
+  });
+
+  // Get the view config for the current state
+  const viewConfig = useMemo(() => {
+    if (!definition.state_views) return undefined;
+    return definition.state_views[player.currentState];
+  }, [definition.state_views, player.currentState]);
+
+  return (
+    <PlayerProvider player={player}>
+      <DomainSubscriptionBridge
+        player={player}
+        transport={transport ?? null}
+        subscription={subscription}
+        onDomainEvent={onDomainEvent}
+      />
+      {renderView(player, viewConfig)}
+    </PlayerProvider>
+  );
+}
+
+/**
+ * Internal component that wires domain subscriptions.
+ * Separated to avoid re-creating subscriptions on view re-renders.
+ */
+function DomainSubscriptionBridge({
+  player,
+  transport,
+  subscription,
+  onDomainEvent,
+}: {
+  player: PlayerHandle;
+  transport: DomainSubscriptionTransport | null;
+  subscription?: Omit<DomainSubscriptionConfig, 'onEvent'>;
+  onDomainEvent?: DomainSubscriptionConfig['onEvent'];
+}) {
+  useDomainSubscription(player.eventBus, transport, {
+    ...subscription,
+    onEvent: onDomainEvent,
+    enabled: subscription?.enabled ?? true,
+  });
+
+  return null;
+}
+
+export function ExperienceWorkflowBridge(props: ExperienceWorkflowBridgeProps) {
+  return <ExperienceWorkflowBridgeInner {...props} />;
+}

package/src/components/PlayerProvider.tsx

@@ -0,0 +1,43 @@
+/**
+ * PlayerProvider — React context provider for the player engine.
+ *
+ * Wraps children with a PlayerHandle context, making the engine
+ * available to any descendant component via usePlayerContext().
+ */
+
+import { createContext, useContext } from 'react';
+import type { PlayerHandle } from '../types';
+
+const PlayerContext = createContext<PlayerHandle | null>(null);
+
+export interface PlayerProviderProps {
+  player: PlayerHandle;
+  children: React.ReactNode;
+}
+
+export function PlayerProvider({ player, children }: PlayerProviderProps) {
+  return (
+    <PlayerContext.Provider value={player}>
+      {children}
+    </PlayerContext.Provider>
+  );
+}
+
+/**
+ * Access the PlayerHandle from context.
+ * Must be used within a <PlayerProvider>.
+ */
+export function usePlayerContext(): PlayerHandle {
+  const ctx = useContext(PlayerContext);
+  if (!ctx) {
+    throw new Error('usePlayerContext must be used within a <PlayerProvider>');
+  }
+  return ctx;
+}
+
+/**
+ * Optionally access the PlayerHandle (returns null if not in provider).
+ */
+export function usePlayerContextSafe(): PlayerHandle | null {
+  return useContext(PlayerContext);
+}

package/src/components/atoms/index.tsx

@@ -0,0 +1,269 @@
+/**
+ * Layout Atoms — the building blocks for workflow views.
+ *
+ * These components are recognized by the @mindmatrix/react-compiler's
+ * component-extractor and compiled into Pure Form [view] nodes.
+ *
+ * Per Design 12 Section 17.3.
+ */
+import React from 'react';
+
+// =============================================================================
+// Layout Containers
+// =============================================================================
+
+export interface StackProps {
+  children?: React.ReactNode;
+  gap?: number | string;
+  style?: React.CSSProperties;
+  className?: string;
+}
+
+/** Vertical layout container. Renders children in a column. */
+export function Stack({ children, gap, style, className }: StackProps) {
+  return (
+    <div
+      className={className}
+      style={{ display: 'flex', flexDirection: 'column', gap, ...style }}
+    >
+      {children}
+    </div>
+  );
+}
+
+export interface RowProps {
+  children?: React.ReactNode;
+  gap?: number | string;
+  align?: 'start' | 'center' | 'end' | 'stretch';
+  style?: React.CSSProperties;
+  className?: string;
+}
+
+/** Horizontal layout container. Renders children in a row. */
+export function Row({ children, gap, align, style, className }: RowProps) {
+  return (
+    <div
+      className={className}
+      style={{
+        display: 'flex',
+        flexDirection: 'row',
+        gap,
+        alignItems: align,
+        ...style,
+      }}
+    >
+      {children}
+    </div>
+  );
+}
+
+export interface ColumnProps {
+  children?: React.ReactNode;
+  span?: number;
+  style?: React.CSSProperties;
+  className?: string;
+}
+
+/** Column within a Row. */
+export function Column({ children, span, style, className }: ColumnProps) {
+  return (
+    <div
+      className={className}
+      style={{ flex: span ?? 1, ...style }}
+    >
+      {children}
+    </div>
+  );
+}
+
+// =============================================================================
+// Typography
+// =============================================================================
+
+export interface TextProps {
+  children?: React.ReactNode;
+  bold?: boolean;
+  size?: 'sm' | 'md' | 'lg';
+  color?: string;
+  style?: React.CSSProperties;
+  className?: string;
+}
+
+/** Text display component. */
+export function Text({ children, bold, size, color, style, className }: TextProps) {
+  const fontSize = size === 'sm' ? '0.875rem' : size === 'lg' ? '1.25rem' : '1rem';
+  return (
+    <span
+      className={className}
+      style={{ fontWeight: bold ? 700 : 400, fontSize, color, ...style }}
+    >
+      {children}
+    </span>
+  );
+}
+
+export interface HeadingProps {
+  children?: React.ReactNode;
+  level?: 1 | 2 | 3 | 4 | 5 | 6;
+  style?: React.CSSProperties;
+  className?: string;
+}
+
+/** Heading component. */
+export function Heading({ children, level = 2, style, className }: HeadingProps) {
+  const Tag = `h${level}` as 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6';
+  return React.createElement(Tag, { className, style }, children);
+}
+
+// =============================================================================
+// Interactive
+// =============================================================================
+
+export interface ButtonProps {
+  children?: React.ReactNode;
+  onPress?: () => void;
+  variant?: 'primary' | 'secondary' | 'ghost' | 'danger';
+  disabled?: boolean;
+  style?: React.CSSProperties;
+  className?: string;
+}
+
+/** Button component. Uses onPress (not onClick) per the spec. */
+export function Button({ children, onPress, variant = 'primary', disabled, style, className }: ButtonProps) {
+  return (
+    <button
+      className={className}
+      onClick={onPress}
+      disabled={disabled}
+      data-variant={variant}
+      style={style}
+    >
+      {children}
+    </button>
+  );
+}
+
+export interface TextInputProps {
+  value?: string;
+  onChange?: (value: string) => void;
+  placeholder?: string;
+  disabled?: boolean;
+  style?: React.CSSProperties;
+  className?: string;
+}
+
+/** Text input component. onChange receives value string directly. */
+export function TextInput({ value, onChange, placeholder, disabled, style, className }: TextInputProps) {
+  return (
+    <input
+      type="text"
+      className={className}
+      value={value}
+      onChange={(e) => onChange?.(e.target.value)}
+      placeholder={placeholder}
+      disabled={disabled}
+      style={style}
+    />
+  );
+}
+
+// =============================================================================
+// Control Flow
+// =============================================================================
+
+export interface EachProps<T> {
+  items?: T[];
+  keyBy?: string;
+  children: (item: T, index: number) => React.ReactNode;
+}
+
+/** Iterates over items, rendering children for each one. */
+export function Each<T>({ items, keyBy, children }: EachProps<T>) {
+  if (!items || items.length === 0) return null;
+  return (
+    <>
+      {items.map((item, i) => {
+        const key = keyBy ? (item as any)[keyBy] : i;
+        return <React.Fragment key={key}>{children(item, i)}</React.Fragment>;
+      })}
+    </>
+  );
+}
+
+export interface ShowProps {
+  when?: unknown;
+  fallback?: React.ReactNode;
+  children?: React.ReactNode;
+}
+
+/** Conditional rendering. Shows children when condition is truthy. */
+export function Show({ when, fallback, children }: ShowProps) {
+  if (!when) return fallback ? <>{fallback}</> : null;
+  return <>{children}</>;
+}
+
+// =============================================================================
+// Composition
+// =============================================================================
+
+export interface SlotProps {
+  name: string;
+  children?: React.ReactNode;
+}
+
+/** Named slot for hub/spoke composition. */
+export function Slot({ children }: SlotProps) {
+  return <>{children}</>;
+}
+
+// =============================================================================
+// Display
+// =============================================================================
+
+export interface BadgeProps {
+  children?: React.ReactNode;
+  variant?: 'default' | 'success' | 'warning' | 'error';
+  style?: React.CSSProperties;
+  className?: string;
+}
+
+/** Badge/chip display component. */
+export function Badge({ children, variant = 'default', style, className }: BadgeProps) {
+  return (
+    <span className={className} data-variant={variant} style={style}>
+      {children}
+    </span>
+  );
+}
+
+export interface CardProps {
+  children?: React.ReactNode;
+  style?: React.CSSProperties;
+  className?: string;
+}
+
+/** Card container with visual boundary. */
+export function Card({ children, style, className }: CardProps) {
+  return (
+    <div
+      className={className}
+      style={{
+        border: '1px solid #e2e8f0',
+        borderRadius: '0.5rem',
+        padding: '1rem',
+        ...style,
+      }}
+    >
+      {children}
+    </div>
+  );
+}
+
+export interface DividerProps {
+  style?: React.CSSProperties;
+}
+
+/** Visual divider/separator. */
+export function Divider({ style }: DividerProps) {
+  return <hr style={{ border: 'none', borderTop: '1px solid #e2e8f0', ...style }} />;
+}

package/src/components/index.ts

@@ -0,0 +1,36 @@
+export { PlayerProvider, usePlayerContext, usePlayerContextSafe } from './PlayerProvider';
+export type { PlayerProviderProps } from './PlayerProvider';
+export { ExperienceWorkflowBridge } from './ExperienceWorkflowBridge';
+export type { ExperienceWorkflowBridgeProps } from './ExperienceWorkflowBridge';
+
+// Layout Atoms (Design 12 Section 17.3)
+export {
+  Stack,
+  Row,
+  Column,
+  Text,
+  Heading,
+  Button,
+  TextInput,
+  Each,
+  Show,
+  Slot,
+  Badge,
+  Card,
+  Divider,
+} from './atoms';
+export type {
+  StackProps,
+  RowProps,
+  ColumnProps,
+  TextProps,
+  HeadingProps,
+  ButtonProps,
+  TextInputProps,
+  EachProps,
+  ShowProps,
+  SlotProps,
+  BadgeProps,
+  CardProps,
+  DividerProps,
+} from './atoms';