@almadar/cli 0.3.2 → 1.0.3

package/shells/typescript-shell/packages/client/src/hooks/useOrbitalMutations.ts

@@ -0,0 +1,234 @@
+/**
+ * useOrbitalMutations - Event-based entity mutations via almadar events route
+ *
+ * This hook provides entity mutations that go through the almadar events route
+ * instead of direct CRUD API calls. This ensures all mutations:
+ * 1. Go through trait state machines
+ * 2. Enforce guards
+ * 3. Execute all trait effects (including persist)
+ *
+ * This is the Phase 7 replacement for direct CRUD mutations.
+ *
+ * @example
+ * ```tsx
+ * const { createEntity, updateEntity, deleteEntity } = useOrbitalMutations('Task', 'TaskManager');
+ *
+ * // Create - sends ENTITY_CREATE event to orbital
+ * await createEntity({ title: 'New Task', status: 'pending' });
+ *
+ * // Update - sends ENTITY_UPDATE event to orbital
+ * await updateEntity(taskId, { status: 'completed' });
+ *
+ * // Delete - sends ENTITY_DELETE event to orbital
+ * await deleteEntity(taskId);
+ * ```
+ *
+ * @packageDocumentation
+ */
+
+import { useMutation, useQueryClient } from '@tanstack/react-query';
+import { apiClient } from '../lib/api-client';
+import { entityDataKeys } from './useEntityData';
+
+/**
+ * Standard events for entity mutations
+ * These are handled by orbitals with CRUD-capable traits
+ */
+export const ENTITY_EVENTS = {
+  CREATE: 'ENTITY_CREATE',
+  UPDATE: 'ENTITY_UPDATE',
+  DELETE: 'ENTITY_DELETE',
+} as const;
+
+export interface OrbitalEventPayload {
+  event: string;
+  payload?: Record<string, unknown>;
+  entityId?: string;
+}
+
+export interface OrbitalEventResponse {
+  success: boolean;
+  transitioned: boolean;
+  states: Record<string, string>;
+  emittedEvents: Array<{ event: string; payload?: unknown }>;
+  error?: string;
+}
+
+/**
+ * Send an event to an almadar via the events route
+ */
+async function sendOrbitalEvent(
+  orbitalName: string,
+  eventPayload: OrbitalEventPayload
+): Promise<OrbitalEventResponse> {
+  const response = await apiClient.post<OrbitalEventResponse>(
+    `/orbitals/${orbitalName}/events`,
+    eventPayload
+  );
+  return response;
+}
+
+/**
+ * Hook for event-based entity mutations via almadar events route
+ *
+ * @param entityName - The entity type name (for cache invalidation)
+ * @param orbitalName - The almadar to send events to
+ * @param options - Optional configuration
+ */
+export function useOrbitalMutations(
+  entityName: string,
+  orbitalName: string,
+  options?: {
+    /** Custom event names for create/update/delete */
+    events?: {
+      create?: string;
+      update?: string;
+      delete?: string;
+    };
+    /** Enable debug logging */
+    debug?: boolean;
+  }
+) {
+  const queryClient = useQueryClient();
+  const events = {
+    create: options?.events?.create || ENTITY_EVENTS.CREATE,
+    update: options?.events?.update || ENTITY_EVENTS.UPDATE,
+    delete: options?.events?.delete || ENTITY_EVENTS.DELETE,
+  };
+
+  const log = (message: string, data?: unknown) => {
+    if (options?.debug) {
+      console.log(`[useOrbitalMutations:${orbitalName}] ${message}`, data ?? '');
+    }
+  };
+
+  /**
+   * Create mutation - sends create event to orbital
+   */
+  const createMutation = useMutation({
+    mutationFn: async (data: Record<string, unknown>): Promise<OrbitalEventResponse> => {
+      log('Creating entity', data);
+      return sendOrbitalEvent(orbitalName, {
+        event: events.create,
+        payload: { data, entityType: entityName },
+      });
+    },
+    onSuccess: (response) => {
+      log('Create succeeded', response);
+      queryClient.invalidateQueries({ queryKey: entityDataKeys.list(entityName) });
+    },
+    onError: (error) => {
+      console.error(`[useOrbitalMutations] Create failed:`, error);
+    },
+  });
+
+  /**
+   * Update mutation - sends update event to orbital
+   */
+  const updateMutation = useMutation({
+    mutationFn: async ({
+      id,
+      data,
+    }: {
+      id: string;
+      data: Record<string, unknown>;
+    }): Promise<OrbitalEventResponse> => {
+      log(`Updating entity ${id}`, data);
+      return sendOrbitalEvent(orbitalName, {
+        event: events.update,
+        entityId: id,
+        payload: { data, entityType: entityName },
+      });
+    },
+    onSuccess: (response, variables) => {
+      log('Update succeeded', response);
+      queryClient.invalidateQueries({ queryKey: entityDataKeys.list(entityName) });
+      queryClient.invalidateQueries({
+        queryKey: entityDataKeys.detail(entityName, variables.id),
+      });
+    },
+    onError: (error) => {
+      console.error(`[useOrbitalMutations] Update failed:`, error);
+    },
+  });
+
+  /**
+   * Delete mutation - sends delete event to orbital
+   */
+  const deleteMutation = useMutation({
+    mutationFn: async (id: string): Promise<OrbitalEventResponse> => {
+      log(`Deleting entity ${id}`);
+      return sendOrbitalEvent(orbitalName, {
+        event: events.delete,
+        entityId: id,
+        payload: { entityType: entityName },
+      });
+    },
+    onSuccess: (response, id) => {
+      log('Delete succeeded', response);
+      queryClient.invalidateQueries({ queryKey: entityDataKeys.list(entityName) });
+      queryClient.removeQueries({ queryKey: entityDataKeys.detail(entityName, id) });
+    },
+    onError: (error) => {
+      console.error(`[useOrbitalMutations] Delete failed:`, error);
+    },
+  });
+
+  return {
+    // Async functions
+    createEntity: async (data: Record<string, unknown>) => {
+      return createMutation.mutateAsync(data);
+    },
+    updateEntity: async (id: string | undefined, data: Record<string, unknown>) => {
+      if (!id) {
+        console.warn('[useOrbitalMutations] Cannot update without ID');
+        return;
+      }
+      return updateMutation.mutateAsync({ id, data });
+    },
+    deleteEntity: async (id: string | undefined) => {
+      if (!id) {
+        console.warn('[useOrbitalMutations] Cannot delete without ID');
+        return;
+      }
+      return deleteMutation.mutateAsync(id);
+    },
+
+    // Mutation objects for fine-grained control
+    createMutation,
+    updateMutation,
+    deleteMutation,
+
+    // Aggregate states
+    isCreating: createMutation.isPending,
+    isUpdating: updateMutation.isPending,
+    isDeleting: deleteMutation.isPending,
+    isMutating: createMutation.isPending || updateMutation.isPending || deleteMutation.isPending,
+
+    // Errors
+    createError: createMutation.error,
+    updateError: updateMutation.error,
+    deleteError: deleteMutation.error,
+  };
+}
+
+/**
+ * Send a custom event to an orbital
+ * For non-CRUD operations that go through trait state machines
+ */
+export function useSendOrbitalEvent(orbitalName: string) {
+  const mutation = useMutation({
+    mutationFn: async (payload: OrbitalEventPayload): Promise<OrbitalEventResponse> => {
+      return sendOrbitalEvent(orbitalName, payload);
+    },
+  });
+
+  return {
+    sendEvent: async (event: string, payload?: Record<string, unknown>, entityId?: string) => {
+      return mutation.mutateAsync({ event, payload, entityId });
+    },
+    isPending: mutation.isPending,
+    error: mutation.error,
+    data: mutation.data,
+  };
+}

package/shells/typescript-shell/packages/client/src/hooks/useQuerySingleton.ts

@@ -0,0 +1,179 @@
+/**
+ * useQuerySingleton Hook
+ *
+ * Provides query state management for search/filter components.
+ * This is a stub implementation for the design system.
+ * In a real application, this would connect to the almadar query singleton.
+ *
+ * @packageDocumentation
+ */
+
+import { useState, useCallback, useMemo } from 'react';
+
+/**
+ * Query state for filters and search
+ */
+export interface QueryState {
+  search?: string;
+  filters?: Record<string, unknown>;
+  sortField?: string;
+  sortDirection?: 'asc' | 'desc';
+}
+
+/**
+ * Query singleton entity reference
+ */
+export interface QuerySingletonEntity {
+  name: string;
+  fields: Record<string, unknown>;
+}
+
+/**
+ * Query singleton result type
+ */
+export interface QuerySingletonResult {
+  state: QueryState;
+  setState: (state: Partial<QueryState>) => void;
+  reset: () => void;
+}
+
+export interface QuerySingletonState {
+  /** Current search term */
+  search: string;
+  /** Set search term */
+  setSearch: (value: string) => void;
+  /** Current filters */
+  filters: Record<string, unknown>;
+  /** Set a filter value */
+  setFilter: (key: string, value: unknown) => void;
+  /** Clear all filters */
+  clearFilters: () => void;
+  /** Current sort field */
+  sortField?: string;
+  /** Current sort direction */
+  sortDirection?: 'asc' | 'desc';
+  /** Set sort */
+  setSort: (field: string, direction: 'asc' | 'desc') => void;
+}
+
+// In-memory store for query singletons (keyed by query name)
+const queryStores = new Map<string, {
+  search: string;
+  filters: Record<string, unknown>;
+  sortField?: string;
+  sortDirection?: 'asc' | 'desc';
+  listeners: Set<() => void>;
+}>();
+
+function getOrCreateStore(query: string) {
+  if (!queryStores.has(query)) {
+    queryStores.set(query, {
+      search: '',
+      filters: {},
+      sortField: undefined,
+      sortDirection: undefined,
+      listeners: new Set(),
+    });
+  }
+  return queryStores.get(query)!;
+}
+
+/**
+ * Hook for accessing a query singleton by name
+ *
+ * @param query - Query singleton name (e.g., "@TaskQuery")
+ * @returns Query singleton state or null if no query provided
+ *
+ * @example
+ * ```tsx
+ * const queryState = useQuerySingleton('@TaskQuery');
+ *
+ * // Use search state
+ * queryState?.search
+ * queryState?.setSearch('new search term')
+ * ```
+ */
+export function useQuerySingleton(query?: string): QuerySingletonState | null {
+  const [, forceUpdate] = useState({});
+
+  // Return null if no query provided
+  if (!query) {
+    return null;
+  }
+
+  const store = useMemo(() => getOrCreateStore(query), [query]);
+
+  // Subscribe to updates
+  useMemo(() => {
+    const listener = () => forceUpdate({});
+    store.listeners.add(listener);
+    return () => {
+      store.listeners.delete(listener);
+    };
+  }, [store]);
+
+  const notifyListeners = useCallback(() => {
+    store.listeners.forEach((listener) => listener());
+  }, [store]);
+
+  const setSearch = useCallback((value: string) => {
+    store.search = value;
+    notifyListeners();
+  }, [store, notifyListeners]);
+
+  const setFilter = useCallback((key: string, value: unknown) => {
+    store.filters = { ...store.filters, [key]: value };
+    notifyListeners();
+  }, [store, notifyListeners]);
+
+  const clearFilters = useCallback(() => {
+    store.filters = {};
+    store.search = '';
+    notifyListeners();
+  }, [store, notifyListeners]);
+
+  const setSort = useCallback((field: string, direction: 'asc' | 'desc') => {
+    store.sortField = field;
+    store.sortDirection = direction;
+    notifyListeners();
+  }, [store, notifyListeners]);
+
+  return {
+    search: store.search,
+    setSearch,
+    filters: store.filters,
+    setFilter,
+    clearFilters,
+    sortField: store.sortField,
+    sortDirection: store.sortDirection,
+    setSort,
+  };
+}
+
+/**
+ * Parse a query binding string to extract the query singleton name
+ *
+ * @param binding - Binding string like "@TaskQuery.search" or "@TaskQuery"
+ * @returns Object with query name and optional field path
+ *
+ * @example
+ * ```tsx
+ * parseQueryBinding('@TaskQuery.search')
+ * // { query: 'TaskQuery', field: 'search' }
+ *
+ * parseQueryBinding('@TaskQuery')
+ * // { query: 'TaskQuery', field: undefined }
+ * ```
+ */
+export function parseQueryBinding(binding: string): { query: string; field?: string } {
+  // Remove @ prefix if present
+  const cleaned = binding.startsWith('@') ? binding.slice(1) : binding;
+  const parts = cleaned.split('.');
+
+  return {
+    query: parts[0],
+    field: parts.length > 1 ? parts.slice(1).join('.') : undefined,
+  };
+}
+
+export default useQuerySingleton;

package/shells/typescript-shell/packages/client/src/hooks/useUIEvents.ts

@@ -0,0 +1,228 @@
+/**
+ * useUIEvents - UI Event to State Machine Bridge
+ *
+ * Listens for UI events from the event bus and dispatches
+ * corresponding state machine events.
+ *
+ * Components emit events like `UI:VIEW`, `UI:SAVE`, `UI:CANCEL`
+ * This hook translates them to state machine dispatch calls.
+ */
+
+import { useEffect, useState, useMemo, useContext } from "react";
+import { useEventBus, type KFlowEvent } from "./useEventBus";
+import { SelectionContext } from "../providers/SelectionProvider";
+
+/**
+ * Map of UI events to state machine events.
+ * UI events are prefixed with "UI:" and the suffix is the event name.
+ */
+const UI_EVENT_MAP: Record<string, string> = {
+  // Form/CRUD events
+  "UI:SAVE": "SAVE",
+  "UI:CANCEL": "CANCEL",
+  "UI:CLOSE": "CLOSE",
+  "UI:VIEW": "VIEW",
+  "UI:EDIT": "EDIT",
+  "UI:DELETE": "DELETE",
+  "UI:CREATE": "CREATE",
+  "UI:SELECT": "SELECT",
+  "UI:DESELECT": "DESELECT",
+  "UI:SUBMIT": "SAVE",
+  "UI:UPDATE_STATUS": "UPDATE_STATUS",
+  "UI:SEARCH": "SEARCH",
+  "UI:CLEAR_SEARCH": "CLEAR_SEARCH",
+  "UI:ADD": "CREATE",
+  // Game events (for closed circuit with GameMenu, GamePauseOverlay, GameOverScreen)
+  "UI:PAUSE": "PAUSE",
+  "UI:RESUME": "RESUME",
+  "UI:RESTART": "RESTART",
+  "UI:GAME_OVER": "GAME_OVER",
+  "UI:START": "START",
+  "UI:QUIT": "QUIT",
+  "UI:INIT": "INIT",
+};
+
+/**
+ * Hook to bridge UI events to state machine dispatch
+ *
+ * @param dispatch - The state machine dispatch function
+ * @param validEvents - Optional array of valid event names (filters which events to handle)
+ * @param eventBusInstance - Optional event bus instance (for testing, uses hook if not provided)
+ */
+export function useUIEvents<E extends string>(
+  dispatch: (event: E, payload?: unknown) => void,
+  validEvents?: readonly E[],
+  eventBusInstance?: ReturnType<typeof useEventBus>,
+): void {
+  const defaultEventBus = useEventBus();
+  const eventBus = eventBusInstance ?? defaultEventBus;
+
+  // Stabilize validEvents to prevent re-subscriptions when array reference changes
+  // but contents are the same. This is critical because generated trait hooks
+  // pass inline arrays which create new references on every render.
+  const validEventsKey = validEvents
+    ? validEvents.slice().sort().join(",")
+    : "";
+  const stableValidEvents = useMemo(
+    () => validEvents,
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [validEventsKey],
+  );
+
+  useEffect(() => {
+    // Create handlers for all UI events
+    const unsubscribes: Array<() => void> = [];
+
+    // Listen for all UI events
+    Object.entries(UI_EVENT_MAP).forEach(([uiEvent, smEvent]) => {
+      const handler = (event: KFlowEvent) => {
+        // Only dispatch if the event is valid for this state machine
+        if (!stableValidEvents || stableValidEvents.includes(smEvent as E)) {
+          dispatch(smEvent as E, event.payload);
+        }
+      };
+
+      const unsubscribe = eventBus.on(uiEvent, handler);
+      unsubscribes.push(unsubscribe);
+    });
+
+    // Also listen for generic UI events that aren't in the map
+    const genericHandler = (event: KFlowEvent) => {
+      const eventName = event.payload?.event as string | undefined;
+      if (eventName) {
+        const smEvent = eventName as E;
+        if (!stableValidEvents || stableValidEvents.includes(smEvent)) {
+          dispatch(smEvent, event.payload);
+        }
+      }
+    };
+    const genericUnsubscribe = eventBus.on("UI:DISPATCH", genericHandler);
+    unsubscribes.push(genericUnsubscribe);
+
+    // Listen for custom UI events not in the static map
+    // Components emit events with UI: prefix (e.g., UI:OPEN_MODAL)
+    // We need to listen for both the prefixed and non-prefixed versions
+    if (stableValidEvents) {
+      stableValidEvents.forEach((smEvent) => {
+        // Skip events already handled by UI_EVENT_MAP
+        const uiPrefixedEvent = `UI:${smEvent}`;
+        const alreadyMapped =
+          Object.keys(UI_EVENT_MAP).includes(uiPrefixedEvent);
+        if (!alreadyMapped) {
+          const directHandler = (event: KFlowEvent) => {
+            dispatch(smEvent, event.payload);
+          };
+          // Listen for UI:EVENT (what components emit)
+          const unsubscribePrefixed = eventBus.on(
+            uiPrefixedEvent,
+            directHandler,
+          );
+          unsubscribes.push(unsubscribePrefixed);
+          // Also listen for EVENT directly (for internal trait events)
+          const unsubscribeDirect = eventBus.on(smEvent, directHandler);
+          unsubscribes.push(unsubscribeDirect);
+        }
+      });
+    }
+
+    return () => {
+      unsubscribes.forEach((unsub) => unsub());
+    };
+  }, [eventBus, dispatch, stableValidEvents]);
+}
+
+/**
+ * Hook for selected entity tracking
+ * Many list UIs need to track which item is selected.
+ *
+ * This hook uses SelectionProvider if available (preferred),
+ * otherwise falls back to listening to events directly.
+ *
+ * @example Using with SelectionProvider (recommended)
+ * ```tsx
+ * function MyPage() {
+ *   return (
+ *     <EventBusProvider>
+ *       <SelectionProvider>
+ *         <MyComponent />
+ *       </SelectionProvider>
+ *     </EventBusProvider>
+ *   );
+ * }
+ *
+ * function MyComponent() {
+ *   const [selected, setSelected] = useSelectedEntity<Order>();
+ *   // selected is automatically updated when UI:VIEW/UI:SELECT events fire
+ * }
+ * ```
+ */
+export function useSelectedEntity<T>(
+  eventBusInstance?: ReturnType<typeof useEventBus>,
+): [T | null, (entity: T | null) => void] {
+  const defaultEventBus = useEventBus();
+  const eventBus = eventBusInstance ?? defaultEventBus;
+
+  // Try to use SelectionProvider context first (preferred - survives component mount/unmount)
+  // Import dynamically to avoid circular dependency
+  const selectionContext = useSelectionContext<T>();
+
+  // Local state for fallback mode (when SelectionProvider is not available)
+  const [localSelected, setLocalSelected] = useState<T | null>(null);
+
+  // Track if we're using context mode
+  const usingContext = selectionContext !== null;
+
+  // Listen for selection events (fallback mode only - when no SelectionProvider)
+  useEffect(() => {
+    // Skip event listening if we have a SelectionProvider (it handles events itself)
+    if (usingContext) return;
+
+    const handleSelect = (event: KFlowEvent) => {
+      const row = event.payload?.row as T | undefined;
+      if (row) {
+        setLocalSelected(row);
+      }
+    };
+
+    const handleDeselect = () => {
+      setLocalSelected(null);
+    };
+
+    const unsubSelect = eventBus.on("UI:SELECT", handleSelect);
+    const unsubView = eventBus.on("UI:VIEW", handleSelect);
+    const unsubDeselect = eventBus.on("UI:DESELECT", handleDeselect);
+    const unsubClose = eventBus.on("UI:CLOSE", handleDeselect);
+    const unsubCancel = eventBus.on("UI:CANCEL", handleDeselect);
+
+    return () => {
+      unsubSelect();
+      unsubView();
+      unsubDeselect();
+      unsubClose();
+      unsubCancel();
+    };
+  }, [eventBus, usingContext]);
+
+  // Return context values if available, otherwise local state
+  if (selectionContext) {
+    return [selectionContext.selected, selectionContext.setSelected];
+  }
+
+  return [localSelected, setLocalSelected];
+}
+
+/**
+ * Internal hook to safely access SelectionContext without throwing.
+ * Returns null if SelectionProvider is not in the tree.
+ */
+function useSelectionContext<T>(): {
+  selected: T | null;
+  setSelected: (entity: T | null) => void;
+} | null {
+  // useContext returns null if the context is not available (no provider in tree)
+  const context = useContext(SelectionContext);
+  return context as {
+    selected: T | null;
+    setSelected: (entity: T | null) => void;
+  } | null;
+}