@almadar/cli 0.3.1 → 0.3.3

package/shells/typescript-shell/packages/client/src/providers/SelectionProvider.tsx

@@ -0,0 +1,232 @@
+/**
+ * SelectionProvider - Manages selected entity state
+ *
+ * Separates selection state from the EventBusProvider to maintain
+ * clean architecture (event bus stays pure pub/sub).
+ *
+ * This provider:
+ * - Listens to UI:VIEW and UI:SELECT events to track selected entity
+ * - Listens to UI:CLOSE, UI:DESELECT, UI:CANCEL to clear selection
+ * - Provides the selected entity to any component that needs it
+ *
+ * @packageDocumentation
+ */
+
+import React, {
+  createContext,
+  useContext,
+  useState,
+  useEffect,
+  useCallback,
+  type ReactNode,
+} from 'react';
+import { useEventBus, type KFlowEvent } from '../hooks/useEventBus';
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export interface SelectionContextType<T = unknown> {
+  /** The currently selected entity */
+  selected: T | null;
+  /** Manually set the selected entity */
+  setSelected: (entity: T | null) => void;
+  /** Clear the selection */
+  clearSelection: () => void;
+  /** Check if an entity is selected */
+  isSelected: (entity: T) => boolean;
+}
+
+// ============================================================================
+// Context
+// ============================================================================
+
+const SelectionContext = createContext<SelectionContextType | null>(null);
+
+// ============================================================================
+// Provider
+// ============================================================================
+
+interface SelectionProviderProps {
+  children: ReactNode;
+  /** Enable debug logging */
+  debug?: boolean;
+  /** Custom comparison function for isSelected */
+  compareEntities?: (a: unknown, b: unknown) => boolean;
+}
+
+/**
+ * Default entity comparison - compares by id field
+ */
+const defaultCompareEntities = (a: unknown, b: unknown): boolean => {
+  if (a === b) return true;
+  if (!a || !b) return false;
+  if (typeof a === 'object' && typeof b === 'object') {
+    const aId = (a as Record<string, unknown>).id;
+    const bId = (b as Record<string, unknown>).id;
+    return aId !== undefined && aId === bId;
+  }
+  return false;
+};
+
+/**
+ * Provider component for selection state.
+ *
+ * Must be used within an EventBusProvider.
+ *
+ * @example
+ * ```tsx
+ * function OrderListPage() {
+ *   return (
+ *     <EventBusProvider>
+ *       <SelectionProvider debug={process.env.NODE_ENV === 'development'}>
+ *         <OrderTable />
+ *         <OrderDetailDrawer />
+ *       </SelectionProvider>
+ *     </EventBusProvider>
+ *   );
+ * }
+ * ```
+ */
+export function SelectionProvider({
+  children,
+  debug = false,
+  compareEntities = defaultCompareEntities,
+}: SelectionProviderProps) {
+  const eventBus = useEventBus();
+  const [selected, setSelectedState] = useState<unknown | null>(null);
+
+  /**
+   * Set the selected entity
+   */
+  const setSelected = useCallback(
+    (entity: unknown | null) => {
+      setSelectedState(entity);
+      if (debug) {
+        console.log('[SelectionProvider] Selection set:', entity);
+      }
+    },
+    [debug]
+  );
+
+  /**
+   * Clear the selection
+   */
+  const clearSelection = useCallback(() => {
+    setSelectedState(null);
+    if (debug) {
+      console.log('[SelectionProvider] Selection cleared');
+    }
+  }, [debug]);
+
+  /**
+   * Check if an entity is selected
+   */
+  const isSelected = useCallback(
+    (entity: unknown): boolean => {
+      return compareEntities(selected, entity);
+    },
+    [selected, compareEntities]
+  );
+
+  /**
+   * Listen to event bus for selection events
+   */
+  useEffect(() => {
+    // Handle selection events
+    const handleSelect = (event: KFlowEvent) => {
+      const row = event.payload?.row;
+      if (row) {
+        setSelected(row);
+        if (debug) {
+          console.log(`[SelectionProvider] ${event.type} received:`, row);
+        }
+      }
+    };
+
+    // Handle deselection events
+    const handleDeselect = (event: KFlowEvent) => {
+      clearSelection();
+      if (debug) {
+        console.log(`[SelectionProvider] ${event.type} received - clearing selection`);
+      }
+    };
+
+    // Subscribe to selection events
+    const unsubView = eventBus.on('UI:VIEW', handleSelect);
+    const unsubSelect = eventBus.on('UI:SELECT', handleSelect);
+
+    // Subscribe to deselection events
+    const unsubClose = eventBus.on('UI:CLOSE', handleDeselect);
+    const unsubDeselect = eventBus.on('UI:DESELECT', handleDeselect);
+    const unsubCancel = eventBus.on('UI:CANCEL', handleDeselect);
+
+    return () => {
+      unsubView();
+      unsubSelect();
+      unsubClose();
+      unsubDeselect();
+      unsubCancel();
+    };
+  }, [eventBus, setSelected, clearSelection, debug]);
+
+  const contextValue: SelectionContextType = {
+    selected,
+    setSelected,
+    clearSelection,
+    isSelected,
+  };
+
+  return (
+    <SelectionContext.Provider value={contextValue}>
+      {children}
+    </SelectionContext.Provider>
+  );
+}
+
+// ============================================================================
+// Hook
+// ============================================================================
+
+/**
+ * Hook to access selection state.
+ *
+ * @throws Error if used outside SelectionProvider
+ *
+ * @example
+ * ```tsx
+ * function OrderDetailDrawer() {
+ *   const { selected, clearSelection } = useSelection<Order>();
+ *
+ *   if (!selected) return null;
+ *
+ *   return (
+ *     <Drawer onClose={clearSelection}>
+ *       <OrderDetail order={selected} />
+ *     </Drawer>
+ *   );
+ * }
+ * ```
+ */
+export function useSelection<T = unknown>(): SelectionContextType<T> {
+  const context = useContext(SelectionContext);
+
+  if (!context) {
+    throw new Error('useSelection must be used within a SelectionProvider');
+  }
+
+  return context as SelectionContextType<T>;
+}
+
+/**
+ * Hook to access selection state with fallback for components
+ * that may be used outside SelectionProvider.
+ *
+ * Returns null if no SelectionProvider is found.
+ */
+export function useSelectionOptional<T = unknown>(): SelectionContextType<T> | null {
+  const context = useContext(SelectionContext);
+  return context as SelectionContextType<T> | null;
+}
+
+export { SelectionContext };

package/shells/typescript-shell/packages/client/src/providers/index.ts

@@ -0,0 +1,31 @@
+/**
+ * Providers barrel export
+ *
+ * Unified providers for Almadar applications.
+ * Use OrbitalProvider for most cases - it combines all required providers.
+ */
+
+// Main unified provider
+export { OrbitalProvider, type OrbitalProviderProps } from './OrbitalProvider';
+
+// Individual providers (for advanced use cases)
+export { EventBusProvider, EventBusContext } from './EventBusProvider';
+export { SelectionProvider, SelectionContext, useSelection, useSelectionOptional } from './SelectionProvider';
+export type { SelectionContextType } from './SelectionProvider';
+
+export {
+  FetchedDataProvider,
+  FetchedDataContext,
+  useFetchedDataContext,
+  useFetchedData,
+  useFetchedEntity,
+} from './FetchedDataProvider';
+export type {
+  FetchedDataProviderProps,
+  FetchedDataContextValue,
+  FetchedDataState,
+  EntityRecord,
+} from './FetchedDataProvider';
+
+// Note: EventBusContextType is exported from hooks/event-bus-types to avoid duplicate exports
+// Note: ThemeProvider and UISlotProvider are exported from context/ directory

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

@@ -0,0 +1,267 @@
+/**
+ * Client Effect Executor
+ *
+ * Executes client effects returned from the server.
+ * This is the core of the dual execution model - the server processes
+ * events and returns client effects, which this module executes.
+ *
+ * Used by both Builder preview and compiled shells.
+ *
+ * @packageDocumentation
+ */
+
+import type {
+  ClientEffect,
+  ClientEffectExecutorConfig,
+  PatternConfig,
+  NotifyOptions,
+} from './types';
+
+// ============================================================================
+// Effect Execution
+// ============================================================================
+
+/**
+ * Execute an array of client effects.
+ *
+ * Effects are executed sequentially in order.
+ * Errors in one effect don't prevent subsequent effects from executing.
+ *
+ * @param effects - Array of client effects to execute
+ * @param config - Configuration providing implementations for each effect type
+ *
+ * @example
+ * ```typescript
+ * executeClientEffects(
+ *   [
+ *     ['render-ui', 'main', { type: 'entity-table', entity: 'Task' }],
+ *     ['notify', 'Tasks loaded!', { type: 'success' }]
+ *   ],
+ *   {
+ *     renderToSlot: (slot, pattern) => slotManager.render(slot, pattern),
+ *     navigate: (path) => router.push(path),
+ *     notify: (message, opts) => toast.show(message, opts),
+ *     eventBus: { emit: (event, payload) => bus.emit(event, payload) }
+ *   }
+ * );
+ * ```
+ */
+export function executeClientEffects(
+  effects: ClientEffect[],
+  config: ClientEffectExecutorConfig
+): void {
+  if (!effects || effects.length === 0) {
+    return;
+  }
+
+  for (const effect of effects) {
+    try {
+      executeEffect(effect, config);
+    } catch (error) {
+      console.error(
+        `[ClientEffectExecutor] Error executing effect:`,
+        effect,
+        error
+      );
+    }
+  }
+
+  // Call onComplete callback if provided
+  config.onComplete?.();
+}
+
+/**
+ * Execute a single client effect.
+ */
+function executeEffect(
+  effect: ClientEffect,
+  config: ClientEffectExecutorConfig
+): void {
+  const [effectType, ...args] = effect;
+
+  switch (effectType) {
+    case 'render-ui': {
+      const [slot, patternConfig] = args as [string, PatternConfig | null];
+      executeRenderUI(slot, patternConfig, config);
+      break;
+    }
+
+    case 'navigate': {
+      const [path, params] = args as [string, Record<string, unknown>?];
+      executeNavigate(path, params, config);
+      break;
+    }
+
+    case 'notify': {
+      const [message, options] = args as [string, NotifyOptions?];
+      executeNotify(message, options, config);
+      break;
+    }
+
+    case 'emit': {
+      const [event, payload] = args as [string, unknown?];
+      executeEmit(event, payload, config);
+      break;
+    }
+
+    default:
+      console.warn(`[ClientEffectExecutor] Unknown effect type: ${effectType}`);
+  }
+}
+
+// ============================================================================
+// Individual Effect Handlers
+// ============================================================================
+
+/**
+ * Execute a render-ui effect.
+ *
+ * If patternConfig is null, the slot is cleared.
+ */
+function executeRenderUI(
+  slot: string,
+  patternConfig: PatternConfig | null,
+  config: ClientEffectExecutorConfig
+): void {
+  config.renderToSlot(slot, patternConfig);
+}
+
+/**
+ * Execute a navigate effect.
+ */
+function executeNavigate(
+  path: string,
+  params: Record<string, unknown> | undefined,
+  config: ClientEffectExecutorConfig
+): void {
+  config.navigate(path, params);
+}
+
+/**
+ * Execute a notify effect.
+ */
+function executeNotify(
+  message: string,
+  options: NotifyOptions | undefined,
+  config: ClientEffectExecutorConfig
+): void {
+  config.notify(message, options);
+}
+
+/**
+ * Execute an emit effect.
+ */
+function executeEmit(
+  event: string,
+  payload: unknown | undefined,
+  config: ClientEffectExecutorConfig
+): void {
+  config.eventBus.emit(event, payload);
+}
+
+// ============================================================================
+// Effect Parsing Utilities
+// ============================================================================
+
+/**
+ * Parse a raw effect array into a typed ClientEffect.
+ * Handles unknown effect formats gracefully.
+ */
+export function parseClientEffect(
+  raw: unknown[]
+): ClientEffect | null {
+  if (!Array.isArray(raw) || raw.length < 1) {
+    console.warn('[ClientEffectExecutor] Invalid effect format:', raw);
+    return null;
+  }
+
+  const [type, ...args] = raw;
+
+  if (typeof type !== 'string') {
+    console.warn('[ClientEffectExecutor] Effect type must be string:', raw);
+    return null;
+  }
+
+  switch (type) {
+    case 'render-ui':
+      return ['render-ui', args[0] as string, args[1] as PatternConfig | null];
+    case 'navigate':
+      return ['navigate', args[0] as string, args[1] as Record<string, unknown>];
+    case 'notify':
+      return ['notify', args[0] as string, args[1] as NotifyOptions];
+    case 'emit':
+      return ['emit', args[0] as string, args[1]];
+    default:
+      console.warn(`[ClientEffectExecutor] Unknown effect type: ${type}`);
+      return null;
+  }
+}
+
+/**
+ * Parse an array of raw effects into typed ClientEffects.
+ * Filters out invalid effects.
+ */
+export function parseClientEffects(
+  raw: unknown[] | undefined
+): ClientEffect[] {
+  if (!raw || !Array.isArray(raw)) {
+    return [];
+  }
+
+  return raw
+    .map((effect) => parseClientEffect(effect as unknown[]))
+    .filter((effect): effect is ClientEffect => effect !== null);
+}
+
+// ============================================================================
+// Effect Filtering
+// ============================================================================
+
+/**
+ * Filter effects by type.
+ */
+export function filterEffectsByType<T extends ClientEffect[0]>(
+  effects: ClientEffect[],
+  type: T
+): Extract<ClientEffect, [T, ...unknown[]]>[] {
+  return effects.filter(
+    (effect): effect is Extract<ClientEffect, [T, ...unknown[]]> =>
+      effect[0] === type
+  );
+}
+
+/**
+ * Get all render-ui effects.
+ */
+export function getRenderUIEffects(
+  effects: ClientEffect[]
+): Array<['render-ui', string, PatternConfig | null]> {
+  return filterEffectsByType(effects, 'render-ui');
+}
+
+/**
+ * Get all navigate effects.
+ */
+export function getNavigateEffects(
+  effects: ClientEffect[]
+): Array<['navigate', string, Record<string, unknown>?]> {
+  return filterEffectsByType(effects, 'navigate');
+}
+
+/**
+ * Get all notify effects.
+ */
+export function getNotifyEffects(
+  effects: ClientEffect[]
+): Array<['notify', string, NotifyOptions?]> {
+  return filterEffectsByType(effects, 'notify');
+}
+
+/**
+ * Get all emit effects.
+ */
+export function getEmitEffects(
+  effects: ClientEffect[]
+): Array<['emit', string, unknown?]> {
+  return filterEffectsByType(effects, 'emit');
+}