@almadar/cli 0.3.2 → 0.3.3

package/shells/typescript-shell/packages/client/src/renderer/pattern-resolver.ts

@@ -0,0 +1,209 @@
+/**
+ * Pattern Resolver
+ *
+ * Resolves pattern configurations to component information.
+ * Uses the central pattern registry and component mapping from almadar-shared/patterns/.
+ *
+ * This is the shared logic used by both Builder's PatternRenderer and
+ * the compiled shell's UISlotRenderer.
+ *
+ * @packageDocumentation
+ */
+
+import type { PatternConfig, ResolvedPattern } from './types';
+
+// ============================================================================
+// Component Mapping (imported from almadar-shared/patterns/)
+// ============================================================================
+
+/**
+ * Component mapping entry from component-mapping.json
+ */
+interface ComponentMappingEntry {
+  component: string;
+  importPath: string;
+  category: string;
+  deprecated?: boolean;
+  replacedBy?: string;
+}
+
+/**
+ * Pattern definition from registry.json
+ */
+interface PatternDefinition {
+  type: string;
+  category: string;
+  description: string;
+  propsSchema?: Record<string, {
+    required?: boolean;
+    types?: string[];
+    description?: string;
+  }>;
+}
+
+// These will be populated by the sync process or at runtime
+let componentMapping: Record<string, ComponentMappingEntry> = {};
+let patternRegistry: Record<string, PatternDefinition> = {};
+
+/**
+ * Initialize the pattern resolver with mappings.
+ * Called at app startup with data from JSON files.
+ */
+export function initializePatternResolver(config: {
+  componentMapping: Record<string, ComponentMappingEntry>;
+  patternRegistry: Record<string, PatternDefinition>;
+}): void {
+  componentMapping = config.componentMapping;
+  patternRegistry = config.patternRegistry;
+}
+
+/**
+ * Set component mapping (alternative to full initialization).
+ */
+export function setComponentMapping(
+  mapping: Record<string, ComponentMappingEntry>
+): void {
+  componentMapping = mapping;
+}
+
+/**
+ * Set pattern registry (alternative to full initialization).
+ */
+export function setPatternRegistry(
+  registry: Record<string, PatternDefinition>
+): void {
+  patternRegistry = registry;
+}
+
+// ============================================================================
+// Pattern Resolution
+// ============================================================================
+
+/**
+ * Resolve a pattern configuration to component information.
+ *
+ * @param config - Pattern configuration from render-ui effect
+ * @returns Resolved pattern with component name, import path, and validated props
+ * @throws Error if pattern type is unknown
+ *
+ * @example
+ * ```typescript
+ * const resolved = resolvePattern({
+ *   type: 'entity-table',
+ *   entity: 'Task',
+ *   columns: ['title', 'status']
+ * });
+ * // resolved.component === 'DataTable'
+ * // resolved.importPath === '@/components/organisms/DataTable'
+ * ```
+ */
+export function resolvePattern(config: PatternConfig): ResolvedPattern {
+  const { type, ...props } = config;
+
+  // Look up component mapping
+  const mapping = componentMapping[type];
+  if (!mapping) {
+    // Check if we have any mappings loaded
+    if (Object.keys(componentMapping).length === 0) {
+      console.warn(
+        '[PatternResolver] Component mapping not initialized. ' +
+        'Call initializePatternResolver() at app startup.'
+      );
+    }
+    throw new Error(`Unknown pattern type: ${type}`);
+  }
+
+  // Check for deprecated patterns
+  if (mapping.deprecated) {
+    console.warn(
+      `[PatternResolver] Pattern "${type}" is deprecated.` +
+      (mapping.replacedBy ? ` Use "${mapping.replacedBy}" instead.` : '')
+    );
+  }
+
+  // Validate props against registry schema
+  const validatedProps = validatePatternProps(type, props);
+
+  return {
+    component: mapping.component,
+    importPath: mapping.importPath,
+    category: mapping.category,
+    validatedProps,
+  };
+}
+
+/**
+ * Validate pattern props against the registry schema.
+ * Returns normalized props with defaults applied.
+ */
+function validatePatternProps(
+  patternType: string,
+  props: Record<string, unknown>
+): Record<string, unknown> {
+  const definition = patternRegistry[patternType];
+
+  // If no definition, return props as-is (allow unknown patterns)
+  if (!definition || !definition.propsSchema) {
+    return props;
+  }
+
+  const validated: Record<string, unknown> = { ...props };
+  const schema = definition.propsSchema;
+
+  // Check required props
+  for (const [propName, propDef] of Object.entries(schema)) {
+    if (propDef.required && !(propName in validated)) {
+      // Don't throw, just warn - allows for flexibility
+      console.warn(
+        `[PatternResolver] Missing required prop "${propName}" for pattern "${patternType}"`
+      );
+    }
+  }
+
+  return validated;
+}
+
+// ============================================================================
+// Utility Functions
+// ============================================================================
+
+/**
+ * Check if a pattern type is known.
+ */
+export function isKnownPattern(type: string): boolean {
+  return type in componentMapping;
+}
+
+/**
+ * Get all known pattern types.
+ */
+export function getKnownPatterns(): string[] {
+  return Object.keys(componentMapping);
+}
+
+/**
+ * Get patterns by category.
+ */
+export function getPatternsByCategory(category: string): string[] {
+  return Object.entries(componentMapping)
+    .filter(([, mapping]) => mapping.category === category)
+    .map(([type]) => type);
+}
+
+/**
+ * Get the component mapping for a pattern type.
+ */
+export function getPatternMapping(
+  type: string
+): ComponentMappingEntry | undefined {
+  return componentMapping[type];
+}
+
+/**
+ * Get the pattern definition from the registry.
+ */
+export function getPatternDefinition(
+  type: string
+): PatternDefinition | undefined {
+  return patternRegistry[type];
+}

package/shells/typescript-shell/packages/client/src/renderer/slot-definitions.ts

@@ -0,0 +1,154 @@
+/**
+ * Slot Definitions
+ *
+ * Defines the available UI slots and their rendering behavior.
+ * Slots are either inline (rendered in the component tree) or
+ * portal (rendered to document.body via React Portal).
+ *
+ * @packageDocumentation
+ */
+
+import type { UISlot, SlotDefinition, SlotType } from './types';
+
+// ============================================================================
+// Slot Definitions
+// ============================================================================
+
+/**
+ * Definitions for all available UI slots.
+ *
+ * Inline slots render within the component hierarchy.
+ * Portal slots render to document.body, breaking out of overflow containers.
+ */
+export const SLOT_DEFINITIONS: Record<UISlot, SlotDefinition> = {
+  // -------------------------------------------------------------------------
+  // Inline Slots - Render in place within the component tree
+  // -------------------------------------------------------------------------
+
+  main: {
+    name: 'main',
+    type: 'inline',
+  },
+
+  sidebar: {
+    name: 'sidebar',
+    type: 'inline',
+  },
+
+  // -------------------------------------------------------------------------
+  // Portal Slots - Render to document.body via React Portal
+  // -------------------------------------------------------------------------
+
+  modal: {
+    name: 'modal',
+    type: 'portal',
+    portalTarget: 'body',
+    zIndex: 1000,
+  },
+
+  drawer: {
+    name: 'drawer',
+    type: 'portal',
+    portalTarget: 'body',
+    zIndex: 900,
+  },
+
+  overlay: {
+    name: 'overlay',
+    type: 'portal',
+    portalTarget: 'body',
+    zIndex: 1100,
+  },
+
+  center: {
+    name: 'center',
+    type: 'portal',
+    portalTarget: 'body',
+    zIndex: 1000,
+  },
+
+  toast: {
+    name: 'toast',
+    type: 'portal',
+    portalTarget: 'body',
+    zIndex: 1200,
+  },
+
+  // -------------------------------------------------------------------------
+  // Game HUD Slots - Portal for game overlay UI
+  // -------------------------------------------------------------------------
+
+  'hud-top': {
+    name: 'hud-top',
+    type: 'portal',
+    portalTarget: 'body',
+    zIndex: 500,
+  },
+
+  'hud-bottom': {
+    name: 'hud-bottom',
+    type: 'portal',
+    portalTarget: 'body',
+    zIndex: 500,
+  },
+
+  floating: {
+    name: 'floating',
+    type: 'portal',
+    portalTarget: 'body',
+    zIndex: 800,
+  },
+};
+
+// ============================================================================
+// Helper Functions
+// ============================================================================
+
+/**
+ * Get the slot definition for a slot name.
+ */
+export function getSlotDefinition(slot: UISlot): SlotDefinition {
+  return SLOT_DEFINITIONS[slot];
+}
+
+/**
+ * Check if a slot is a portal slot.
+ */
+export function isPortalSlot(slot: UISlot): boolean {
+  return SLOT_DEFINITIONS[slot]?.type === 'portal';
+}
+
+/**
+ * Check if a slot is an inline slot.
+ */
+export function isInlineSlot(slot: UISlot): boolean {
+  return SLOT_DEFINITIONS[slot]?.type === 'inline';
+}
+
+/**
+ * Get all slots of a specific type.
+ */
+export function getSlotsByType(type: SlotType): UISlot[] {
+  return Object.entries(SLOT_DEFINITIONS)
+    .filter(([, def]) => def.type === type)
+    .map(([name]) => name as UISlot);
+}
+
+/**
+ * Get all inline slots.
+ */
+export function getInlineSlots(): UISlot[] {
+  return getSlotsByType('inline');
+}
+
+/**
+ * Get all portal slots.
+ */
+export function getPortalSlots(): UISlot[] {
+  return getSlotsByType('portal');
+}
+
+/**
+ * All valid slot names.
+ */
+export const ALL_SLOTS: UISlot[] = Object.keys(SLOT_DEFINITIONS) as UISlot[];

package/shells/typescript-shell/packages/client/src/renderer/types.ts

@@ -0,0 +1,214 @@
+/**
+ * Shared Renderer Types
+ *
+ * Type definitions used by both Builder and compiled shells for
+ * the dual execution model. These types define the contract between
+ * server and client for effect execution.
+ *
+ * @packageDocumentation
+ */
+
+// ============================================================================
+// Client Effect Types
+// ============================================================================
+
+/**
+ * A client effect is a tuple where the first element is the effect type
+ * and the remaining elements are the arguments.
+ *
+ * @example
+ * ['render-ui', 'main', { type: 'entity-table', ... }]
+ * ['navigate', '/tasks/123']
+ * ['notify', 'Task created!', { type: 'success' }]
+ * ['emit', 'TASK_CREATED', { id: '123' }]
+ */
+export type ClientEffect =
+  | ['render-ui', string, PatternConfig | null]
+  | ['navigate', string, Record<string, unknown>?]
+  | ['notify', string, NotifyOptions?]
+  | ['emit', string, unknown?];
+
+/**
+ * Options for notify effect
+ */
+export interface NotifyOptions {
+  type?: 'success' | 'error' | 'info' | 'warning';
+  duration?: number;
+}
+
+// ============================================================================
+// Pattern Types
+// ============================================================================
+
+/**
+ * Configuration for a pattern to render in a slot.
+ * This is what render-ui effects carry as their payload.
+ */
+export interface PatternConfig {
+  /** Pattern type from registry (e.g., 'entity-table', 'form-section') */
+  type: string;
+  /** Entity name for data binding */
+  entity?: string;
+  /** Additional props for the pattern component */
+  [key: string]: unknown;
+}
+
+/**
+ * Resolved pattern with component information from component-mapping.json
+ */
+export interface ResolvedPattern {
+  /** Component name (e.g., 'DataTable') */
+  component: string;
+  /** Import path for the component */
+  importPath: string;
+  /** Pattern category (e.g., 'display', 'form') */
+  category: string;
+  /** Validated and normalized props */
+  validatedProps: Record<string, unknown>;
+}
+
+// ============================================================================
+// Event Response Types
+// ============================================================================
+
+/**
+ * Response from server after processing an event.
+ * This is the unified response format for both Builder and compiled shells.
+ */
+export interface EventResponse {
+  /** Whether the event was processed successfully */
+  success: boolean;
+  /** New state after transition (if transition occurred) */
+  newState?: string;
+  /** Data fetched by server effects (e.g., { Task: [...] }) */
+  data?: Record<string, unknown[]>;
+  /** Client effects to execute (render-ui, navigate, notify, emit) */
+  clientEffects?: ClientEffect[];
+  /** Results of individual effect executions (for debugging) */
+  effectResults?: Array<{
+    effect: string;
+    success: boolean;
+    data?: unknown;
+    error?: string;
+  }>;
+  /** Error message if success is false */
+  error?: string;
+}
+
+// ============================================================================
+// Executor Configuration Types
+// ============================================================================
+
+/**
+ * Configuration for the client effect executor.
+ * Provides implementations for each effect type.
+ */
+export interface ClientEffectExecutorConfig {
+  /**
+   * Render a pattern to a slot.
+   * Called for 'render-ui' effects.
+   */
+  renderToSlot: (slot: string, pattern: PatternConfig | null) => void;
+
+  /**
+   * Navigate to a route.
+   * Called for 'navigate' effects.
+   */
+  navigate: (path: string, params?: Record<string, unknown>) => void;
+
+  /**
+   * Show a notification.
+   * Called for 'notify' effects.
+   */
+  notify: (message: string, options?: NotifyOptions) => void;
+
+  /**
+   * Emit an event to the event bus.
+   * Called for 'emit' effects.
+   */
+  eventBus: {
+    emit: (event: string, payload?: unknown) => void;
+  };
+
+  /**
+   * Optional: Data from server response for render-ui.
+   * Components can use this to access fetched entity data.
+   */
+  data?: Record<string, unknown[]>;
+
+  /**
+   * Optional: Callback when all effects have been executed.
+   */
+  onComplete?: () => void;
+}
+
+// ============================================================================
+// Slot Types (re-exported from useUISlots for convenience)
+// ============================================================================
+
+/**
+ * Valid UI slot names
+ */
+export type UISlot =
+  | 'main'
+  | 'sidebar'
+  | 'modal'
+  | 'drawer'
+  | 'overlay'
+  | 'center'
+  | 'toast'
+  | 'hud-top'
+  | 'hud-bottom'
+  | 'floating';
+
+/**
+ * Slot type classification
+ */
+export type SlotType = 'inline' | 'portal';
+
+/**
+ * Definition of a slot including its rendering behavior
+ */
+export interface SlotDefinition {
+  /** Slot name */
+  name: UISlot;
+  /** Whether to render inline or via portal */
+  type: SlotType;
+  /** For portal slots: where to render (default: document.body) */
+  portalTarget?: string;
+  /** Z-index for portal slots */
+  zIndex?: number;
+}
+
+// ============================================================================
+// Data Resolution Types
+// ============================================================================
+
+/**
+ * Context for resolving entity data.
+ * Supports multiple data sources with priority.
+ */
+export interface DataContext {
+  /** Server-provided data (highest priority) */
+  fetchedData?: Record<string, unknown[]>;
+  /** In-memory mock data (for Builder preview) */
+  entityStore?: {
+    getRecords: (entityName: string) => unknown[];
+  };
+  /** Query singleton for filtering */
+  querySingleton?: {
+    getFilters: (queryRef: string) => Record<string, unknown>;
+  };
+}
+
+/**
+ * Result of data resolution
+ */
+export interface DataResolution {
+  /** Resolved data array */
+  data: unknown[];
+  /** Whether data is still loading */
+  loading: boolean;
+  /** Error if resolution failed */
+  error?: Error;
+}