@almadar/cli 1.0.5 → 1.0.7

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

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

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

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