@almadar/cli 0.3.2 → 0.3.3

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

@@ -0,0 +1,288 @@
+/**
+ * useEntityData Hook
+ *
+ * Provides data fetching utilities for entity lists.
+ * This is a stub implementation for the design system that returns mock data.
+ * In a real application, this would connect to a backend API.
+ *
+ * @packageDocumentation
+ */
+
+import { useState, useEffect } from "react";
+
+/**
+ * Query key factory for entity data queries.
+ * Used with React Query for cache invalidation.
+ */
+export const entityDataKeys = {
+  all: ['entities'] as const,
+  lists: () => [...entityDataKeys.all, 'list'] as const,
+  list: (entity: string, filters?: Record<string, unknown>) =>
+    [...entityDataKeys.lists(), entity, filters] as const,
+  details: () => [...entityDataKeys.all, 'detail'] as const,
+  detail: (entity: string, id: string) =>
+    [...entityDataKeys.details(), entity, id] as const,
+};
+
+/**
+ * Generic entity data record type
+ */
+export type EntityDataRecord = Record<string, unknown>;
+
+export interface UseEntityListOptions {
+  /** Skip fetching */
+  skip?: boolean;
+}
+
+export interface UseEntityListResult<T = Record<string, unknown>> {
+  /** Fetched data */
+  data: T[];
+  /** Loading state */
+  isLoading: boolean;
+  /** Error state */
+  error: Error | null;
+  /** Refetch function */
+  refetch: () => void;
+}
+
+/**
+ * Hook for fetching entity list data
+ *
+ * @param entity - Entity name to fetch
+ * @param options - Fetch options
+ * @returns Entity list data and loading states
+ *
+ * @example
+ * ```tsx
+ * const { data, isLoading, error } = useEntityList('tasks');
+ * ```
+ */
+export function useEntityList<T = Record<string, unknown>>(
+  entity: string | undefined,
+  options: UseEntityListOptions = {},
+): UseEntityListResult<T> {
+  const { skip = false } = options;
+  const [data, setData] = useState<T[]>([]);
+  const [isLoading, setIsLoading] = useState(!skip && !!entity);
+  const [error, setError] = useState<Error | null>(null);
+
+  const refetch = () => {
+    if (!entity || skip) return;
+    setIsLoading(true);
+    setError(null);
+    // In a real implementation, this would fetch from an API
+    // For the design system, we just simulate a short delay
+    setTimeout(() => {
+      setData([]);
+      setIsLoading(false);
+    }, 100);
+  };
+
+  useEffect(() => {
+    if (skip || !entity) {
+      setIsLoading(false);
+      return;
+    }
+
+    refetch();
+  }, [entity, skip]);
+
+  return { data, isLoading, error, refetch };
+}
+
+/**
+ * Hook for fetching a single entity by ID
+ *
+ * @param entity - Entity name
+ * @param id - Entity ID
+ * @returns Single entity data and loading states
+ */
+export function useEntity<T = Record<string, unknown>>(
+  entity: string | undefined,
+  id: string | undefined,
+): { data: T | null; isLoading: boolean; error: Error | null } {
+  const [data, setData] = useState<T | null>(null);
+  const [isLoading, setIsLoading] = useState(!!entity && !!id);
+  const [error, setError] = useState<Error | null>(null);
+
+  useEffect(() => {
+    if (!entity || !id) {
+      setIsLoading(false);
+      return;
+    }
+
+    setIsLoading(true);
+    // Simulate API call
+    setTimeout(() => {
+      setData(null);
+      setIsLoading(false);
+    }, 100);
+  }, [entity, id]);
+
+  return { data, isLoading, error };
+}
+
+/**
+ * Result type for useEntityDetail hook
+ */
+export interface UseEntityDetailResult<T = Record<string, unknown>> {
+  /** Fetched entity data */
+  data: T | null;
+  /** Loading state */
+  isLoading: boolean;
+  /** Error state */
+  error: Error | null;
+  /** Refetch function */
+  refetch: () => void;
+}
+
+/**
+ * Hook for fetching entity detail by ID (alias for useEntity with refetch)
+ *
+ * @param entity - Entity name
+ * @param id - Entity ID
+ * @returns Entity detail data and loading states
+ *
+ * @example
+ * ```tsx
+ * const { data, isLoading, error, refetch } = useEntityDetail('tasks', taskId);
+ * ```
+ */
+export function useEntityDetail<T = Record<string, unknown>>(
+  entity: string | undefined,
+  id: string | undefined,
+): UseEntityDetailResult<T> {
+  const [data, setData] = useState<T | null>(null);
+  const [isLoading, setIsLoading] = useState(!!entity && !!id);
+  const [error, setError] = useState<Error | null>(null);
+
+  const refetch = () => {
+    if (!entity || !id) return;
+    setIsLoading(true);
+    setError(null);
+    // In a real implementation, this would fetch from an API
+    // For the design system, we just simulate a short delay
+    setTimeout(() => {
+      setData(null);
+      setIsLoading(false);
+    }, 100);
+  };
+
+  useEffect(() => {
+    if (!entity || !id) {
+      setIsLoading(false);
+      return;
+    }
+
+    refetch();
+  }, [entity, id]);
+
+  return { data, isLoading, error, refetch };
+}
+
+/**
+ * Pagination parameters for paginated queries
+ */
+export interface PaginationParams {
+  /** Current page (1-indexed) */
+  page: number;
+  /** Items per page */
+  pageSize: number;
+  /** Search query */
+  search?: string;
+  /** Sort field */
+  sortBy?: string;
+  /** Sort direction */
+  sortDirection?: "asc" | "desc";
+  /** Filters */
+  filters?: Record<string, unknown>;
+}
+
+export interface UsePaginatedEntityListResult<T = Record<string, unknown>> {
+  /** Fetched data */
+  data: T[];
+  /** Loading state */
+  isLoading: boolean;
+  /** Error state */
+  error: Error | null;
+  /** Total item count */
+  totalCount: number;
+  /** Total pages */
+  totalPages: number;
+  /** Has next page */
+  hasNextPage: boolean;
+  /** Has previous page */
+  hasPreviousPage: boolean;
+  /** Refetch function */
+  refetch: () => void;
+}
+
+/**
+ * Hook for fetching paginated entity list data
+ *
+ * @param entity - Entity name to fetch
+ * @param params - Pagination parameters
+ * @param options - Fetch options
+ * @returns Paginated entity list data and loading states
+ *
+ * @example
+ * ```tsx
+ * const { data, isLoading, totalPages } = usePaginatedEntityList('tasks', { page: 1, pageSize: 10 });
+ * ```
+ */
+export function usePaginatedEntityList<T = Record<string, unknown>>(
+  entity: string | undefined,
+  params: PaginationParams,
+  options: UseEntityListOptions = {},
+): UsePaginatedEntityListResult<T> {
+  const { skip = false } = options;
+  const [data, setData] = useState<T[]>([]);
+  const [isLoading, setIsLoading] = useState(!skip && !!entity);
+  const [error, setError] = useState<Error | null>(null);
+  const [totalCount, setTotalCount] = useState(0);
+
+  const refetch = () => {
+    if (!entity || skip) return;
+    setIsLoading(true);
+    setError(null);
+    // In a real implementation, this would fetch from an API with pagination
+    // For the design system, we just simulate a short delay
+    setTimeout(() => {
+      setData([]);
+      setTotalCount(0);
+      setIsLoading(false);
+    }, 100);
+  };
+
+  useEffect(() => {
+    if (skip || !entity) {
+      setIsLoading(false);
+      return;
+    }
+
+    refetch();
+  }, [
+    entity,
+    params.page,
+    params.pageSize,
+    params.search,
+    params.sortBy,
+    params.sortDirection,
+    skip,
+  ]);
+
+  const totalPages = Math.ceil(totalCount / params.pageSize) || 1;
+
+  return {
+    data,
+    isLoading,
+    error,
+    totalCount,
+    totalPages,
+    hasNextPage: params.page < totalPages,
+    hasPreviousPage: params.page > 1,
+    refetch,
+  };
+}
+
+export default useEntityList;

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

@@ -0,0 +1,258 @@
+/**
+ * useEntityMutations - Entity CRUD mutation hooks
+ *
+ * Provides create, update, and delete mutations for entities.
+ * Used by trait hooks for persist_data effects.
+ *
+ * @deprecated For new code, prefer useOrbitalMutations which sends mutations
+ * through the almadar events route. This ensures all mutations go through
+ * trait state machines and enforce guards/effects.
+ *
+ * Migration:
+ * ```tsx
+ * // Old (deprecated):
+ * const { createEntity } = useEntityMutations('Task');
+ *
+ * // New (recommended):
+ * const { createEntity } = useOrbitalMutations('Task', 'TaskManager');
+ * ```
+ *
+ * @see useOrbitalMutations
+ */
+
+import { useMutation, useQueryClient } from '@tanstack/react-query';
+import { apiClient } from '../lib/api-client';
+import { entityDataKeys } from './useEntityData';
+import { ENTITY_EVENTS, type OrbitalEventResponse } from './useOrbitalMutations';
+
+/**
+ * Convert entity name to API collection path
+ * Uses the KFlow convention: {entity-name}-list
+ * e.g., "Customer" -> "customer-list", "InventoryItem" -> "inventory-item-list"
+ */
+function entityToCollection(entityName: string): string {
+  return entityName
+    .replace(/([a-z])([A-Z])/g, '$1-$2') // camelCase to kebab-case
+    .toLowerCase() + '-list'; // KFlow API convention
+}
+
+export interface EntityMutationResult {
+  id: string;
+  [key: string]: unknown;
+}
+
+/**
+ * Hook for creating entities
+ */
+export function useCreateEntity(entityName: string) {
+  const queryClient = useQueryClient();
+  const collection = entityToCollection(entityName);
+
+  return useMutation({
+    mutationFn: async (data: Record<string, unknown>) => {
+      console.log(`[useCreateEntity] Creating ${entityName}:`, data);
+      const response = await apiClient.post<{ data: EntityMutationResult }>(
+        `/${collection}`,
+        data
+      );
+      return response.data;
+    },
+    onSuccess: () => {
+      // Invalidate list queries to refetch
+      queryClient.invalidateQueries({ queryKey: entityDataKeys.list(entityName) });
+    },
+    onError: (error) => {
+      console.error(`[useCreateEntity] Failed to create ${entityName}:`, error);
+    },
+  });
+}
+
+/**
+ * Hook for updating entities
+ */
+export function useUpdateEntity(entityName: string) {
+  const queryClient = useQueryClient();
+  const collection = entityToCollection(entityName);
+
+  return useMutation({
+    mutationFn: async ({ id, data }: { id: string; data: Record<string, unknown> }) => {
+      console.log(`[useUpdateEntity] Updating ${entityName} ${id}:`, data);
+      const response = await apiClient.patch<{ data: EntityMutationResult }>(
+        `/${collection}/${id}`,
+        data
+      );
+      return response.data;
+    },
+    onSuccess: (_, variables) => {
+      // Invalidate both list and detail queries
+      queryClient.invalidateQueries({ queryKey: entityDataKeys.list(entityName) });
+      queryClient.invalidateQueries({ queryKey: entityDataKeys.detail(entityName, variables.id) });
+    },
+    onError: (error) => {
+      console.error(`[useUpdateEntity] Failed to update ${entityName}:`, error);
+    },
+  });
+}
+
+/**
+ * Hook for deleting entities
+ */
+export function useDeleteEntity(entityName: string) {
+  const queryClient = useQueryClient();
+  const collection = entityToCollection(entityName);
+
+  return useMutation({
+    mutationFn: async (id: string) => {
+      console.log(`[useDeleteEntity] Deleting ${entityName} ${id}`);
+      await apiClient.delete(`/${collection}/${id}`);
+      return { id };
+    },
+    onSuccess: (_, id) => {
+      // Invalidate list and remove detail from cache
+      queryClient.invalidateQueries({ queryKey: entityDataKeys.list(entityName) });
+      queryClient.removeQueries({ queryKey: entityDataKeys.detail(entityName, id) });
+    },
+    onError: (error) => {
+      console.error(`[useDeleteEntity] Failed to delete ${entityName}:`, error);
+    },
+  });
+}
+
+export interface UseEntityMutationsOptions {
+  /**
+   * If provided, mutations go through almadar events route instead of direct CRUD.
+   * This is the recommended approach for Phase 7+ compliance.
+   */
+  orbitalName?: string;
+  /**
+   * Custom event names when using orbital-based mutations
+   */
+  events?: {
+    create?: string;
+    update?: string;
+    delete?: string;
+  };
+}
+
+/**
+ * Send mutation event to almadar events route
+ */
+async function sendOrbitalMutation(
+  orbitalName: string,
+  event: string,
+  entityId: string | undefined,
+  payload: Record<string, unknown>
+): Promise<OrbitalEventResponse> {
+  const response = await apiClient.post<OrbitalEventResponse>(
+    `/orbitals/${orbitalName}/events`,
+    { event, entityId, payload }
+  );
+  return response;
+}
+
+/**
+ * Combined hook that provides all entity mutations
+ * Used by trait hooks for persist_data effects
+ *
+ * @param entityName - The entity type name
+ * @param options - Optional configuration including orbital-based mutations
+ *
+ * @deprecated For new code, prefer useOrbitalMutations directly
+ */
+export function useEntityMutations(entityName: string, options?: UseEntityMutationsOptions) {
+  const queryClient = useQueryClient();
+
+  // If orbitalName provided, use almadar events route
+  const useOrbitalRoute = !!options?.orbitalName;
+  const events = {
+    create: options?.events?.create || ENTITY_EVENTS.CREATE,
+    update: options?.events?.update || ENTITY_EVENTS.UPDATE,
+    delete: options?.events?.delete || ENTITY_EVENTS.DELETE,
+  };
+
+  // Legacy direct CRUD mutations
+  const createMutation = useCreateEntity(entityName);
+  const updateMutation = useUpdateEntity(entityName);
+  const deleteMutation = useDeleteEntity(entityName);
+
+  // Almadar-based mutations
+  const orbitalCreateMutation = useMutation({
+    mutationFn: async (data: Record<string, unknown>) => {
+      return sendOrbitalMutation(options!.orbitalName!, events.create, undefined, {
+        data,
+        entityType: entityName,
+      });
+    },
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: entityDataKeys.list(entityName) });
+    },
+  });
+
+  const orbitalUpdateMutation = useMutation({
+    mutationFn: async ({ id, data }: { id: string; data: Record<string, unknown> }) => {
+      return sendOrbitalMutation(options!.orbitalName!, events.update, id, {
+        data,
+        entityType: entityName,
+      });
+    },
+    onSuccess: (_, variables) => {
+      queryClient.invalidateQueries({ queryKey: entityDataKeys.list(entityName) });
+      queryClient.invalidateQueries({
+        queryKey: entityDataKeys.detail(entityName, variables.id),
+      });
+    },
+  });
+
+  const orbitalDeleteMutation = useMutation({
+    mutationFn: async (id: string) => {
+      return sendOrbitalMutation(options!.orbitalName!, events.delete, id, {
+        entityType: entityName,
+      });
+    },
+    onSuccess: (_, id) => {
+      queryClient.invalidateQueries({ queryKey: entityDataKeys.list(entityName) });
+      queryClient.removeQueries({ queryKey: entityDataKeys.detail(entityName, id) });
+    },
+  });
+
+  // Select which mutations to use based on options
+  const activeMutations = {
+    create: useOrbitalRoute ? orbitalCreateMutation : createMutation,
+    update: useOrbitalRoute ? orbitalUpdateMutation : updateMutation,
+    delete: useOrbitalRoute ? orbitalDeleteMutation : deleteMutation,
+  };
+
+  return {
+    // Async functions that can be called directly
+    // Accepts either (data) or (entityName, data) for compiler compatibility
+    createEntity: async (entityOrData: string | Record<string, unknown>, data?: Record<string, unknown>) => {
+      const actualData = typeof entityOrData === 'string' ? data : entityOrData;
+      if (!actualData) {
+        console.warn('[useEntityMutations] Cannot create entity without data');
+        return;
+      }
+      return activeMutations.create.mutateAsync(actualData as Record<string, unknown>);
+    },
+    updateEntity: async (id: string | undefined, data: Record<string, unknown>) => {
+      if (!id) {
+        console.warn('[useEntityMutations] Cannot update entity without ID');
+        return;
+      }
+      return activeMutations.update.mutateAsync({ id, data });
+    },
+    deleteEntity: async (id: string | undefined) => {
+      if (!id) {
+        console.warn('[useEntityMutations] Cannot delete entity without ID');
+        return;
+      }
+      return activeMutations.delete.mutateAsync(id);
+    },
+    // Mutation states for UI feedback
+    isCreating: activeMutations.create.isPending,
+    isUpdating: activeMutations.update.isPending,
+    isDeleting: activeMutations.delete.isPending,
+    createError: activeMutations.create.error,
+    updateError: activeMutations.update.error,
+    deleteError: activeMutations.delete.error,
+  };
+}

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

@@ -0,0 +1,166 @@
+/**
+ * useEventBus Hook
+ *
+ * Provides event bus utilities for component communication.
+ * This connects to the EventBusProvider for real applications
+ * or provides a simple in-memory bus for design system / Storybook.
+ *
+ * @packageDocumentation
+ */
+
+import { useCallback, useEffect, useRef, useContext } from 'react';
+import { EventBusContext } from '../providers/EventBusProvider';
+import type { KFlowEvent, EventListener, Unsubscribe, EventBusContextType } from './event-bus-types';
+
+// Re-export types for convenience
+export type { KFlowEvent, EventListener, Unsubscribe, EventBusContextType };
+
+// ============================================================================
+// Fallback Event Bus (for use outside EventBusProvider)
+// ============================================================================
+
+const fallbackListeners = new Map<string, Set<EventListener>>();
+
+const fallbackEventBus: EventBusContextType = {
+  emit: (type: string, payload?: Record<string, unknown>) => {
+    const event: KFlowEvent = {
+      type,
+      payload,
+      timestamp: Date.now(),
+    };
+    const handlers = fallbackListeners.get(type);
+    if (handlers) {
+      handlers.forEach((handler) => {
+        try {
+          handler(event);
+        } catch (error) {
+          console.error(`[EventBus] Error in listener for '${type}':`, error);
+        }
+      });
+    }
+  },
+  on: (type: string, listener: EventListener): Unsubscribe => {
+    if (!fallbackListeners.has(type)) {
+      fallbackListeners.set(type, new Set());
+    }
+    fallbackListeners.get(type)!.add(listener);
+    return () => {
+      const handlers = fallbackListeners.get(type);
+      if (handlers) {
+        handlers.delete(listener);
+        if (handlers.size === 0) {
+          fallbackListeners.delete(type);
+        }
+      }
+    };
+  },
+  once: (type: string, listener: EventListener): Unsubscribe => {
+    const wrappedListener: EventListener = (event) => {
+      fallbackListeners.get(type)?.delete(wrappedListener);
+      listener(event);
+    };
+    return fallbackEventBus.on(type, wrappedListener);
+  },
+  hasListeners: (type: string): boolean => {
+    const handlers = fallbackListeners.get(type);
+    return handlers !== undefined && handlers.size > 0;
+  },
+};
+
+// ============================================================================
+// Main Hook
+// ============================================================================
+
+/**
+ * Hook for accessing the event bus.
+ *
+ * Uses EventBusProvider context if available, otherwise falls back to
+ * a simple in-memory event bus (for design system / Storybook).
+ *
+ * @returns Event bus instance with emit, on, once, and hasListeners methods
+ *
+ * @example
+ * ```tsx
+ * const eventBus = useEventBus();
+ *
+ * // Emit an event
+ * eventBus.emit('UI:CLICK', { id: '123' });
+ *
+ * // Subscribe to an event
+ * useEffect(() => {
+ *   return eventBus.on('UI:CLICK', (event) => {
+ *     console.log('Clicked:', event.payload);
+ *   });
+ * }, []);
+ * ```
+ */
+export function useEventBus(): EventBusContextType {
+  const context = useContext(EventBusContext);
+  return context ?? fallbackEventBus;
+}
+
+// ============================================================================
+// Convenience Hooks
+// ============================================================================
+
+/**
+ * Hook for subscribing to a specific event.
+ * Automatically cleans up subscription on unmount.
+ *
+ * @param event - Event name to subscribe to
+ * @param handler - Event handler function
+ *
+ * @example
+ * ```tsx
+ * useEventListener('UI:CLICK', (event) => {
+ *   console.log('Clicked:', event.payload);
+ * });
+ * ```
+ */
+export function useEventListener(
+  event: string,
+  handler: EventListener
+): void {
+  const eventBus = useEventBus();
+  const handlerRef = useRef(handler);
+  handlerRef.current = handler;
+
+  useEffect(() => {
+    const wrappedHandler: EventListener = (evt) => {
+      handlerRef.current(evt);
+    };
+    return eventBus.on(event, wrappedHandler);
+  }, [event, eventBus]);
+}
+
+/**
+ * Alias for useEventListener for backward compatibility
+ */
+export const useEventSubscription = useEventListener;
+
+/**
+ * Hook for emitting events.
+ * Returns a memoized emit function.
+ *
+ * @returns Function to emit events
+ *
+ * @example
+ * ```tsx
+ * const emit = useEmitEvent();
+ *
+ * const handleClick = () => {
+ *   emit('UI:CLICK', { id: '123' });
+ * };
+ * ```
+ */
+export function useEmitEvent(): (type: string, payload?: Record<string, unknown>) => void {
+  const eventBus = useEventBus();
+  return useCallback(
+    (type: string, payload?: Record<string, unknown>) => {
+      eventBus.emit(type, payload);
+    },
+    [eventBus]
+  );
+}
+
+export default useEventBus;