@almadar/cli 1.0.5 → 1.0.7

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

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

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

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