@almadar/cli 1.0.5 → 1.0.7

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

@@ -1,209 +0,0 @@
-/**
- * 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

@@ -1,154 +0,0 @@
-/**
- * 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

@@ -1,214 +0,0 @@
-/**
- * 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;
-}