@almadar/ui 2.14.0 → 2.15.1

package/dist/hooks/event-bus-types.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Event Bus Types
+ *
+ * Type definitions for the page event bus system.
+ *
+ * @packageDocumentation
+ */
+/**
+ * A KFlow event that can be emitted on the event bus.
+ */
+export interface KFlowEvent {
+    /** Event type identifier (e.g., 'TASK_COMPLETED', 'VALIDATION_SUCCESS') */
+    type: string;
+    /** Optional payload data */
+    payload?: Record<string, unknown>;
+    /** Timestamp when the event was emitted */
+    timestamp: number;
+    /** Source trait or component that emitted the event */
+    source?: string;
+}
+/**
+ * Event listener callback function.
+ */
+export type EventListener = (event: KFlowEvent) => void;
+/**
+ * Function to unsubscribe from events.
+ */
+export type Unsubscribe = () => void;
+/**
+ * Event bus context type.
+ */
+export interface EventBusContextType {
+    /**
+     * Emit an event to all listeners.
+     *
+     * @param type - Event type identifier
+     * @param payload - Optional payload data
+     */
+    emit: (type: string, payload?: Record<string, unknown>) => void;
+    /**
+     * Subscribe to an event type.
+     *
+     * @param type - Event type to listen for
+     * @param listener - Callback function
+     * @returns Unsubscribe function
+     */
+    on: (type: string, listener: EventListener) => Unsubscribe;
+    /**
+     * Subscribe to an event type, but only fire once.
+     *
+     * @param type - Event type to listen for
+     * @param listener - Callback function
+     * @returns Unsubscribe function
+     */
+    once: (type: string, listener: EventListener) => Unsubscribe;
+    /**
+     * Check if there are any listeners for an event type.
+     *
+     * @param type - Event type to check
+     * @returns True if there are listeners
+     */
+    hasListeners: (type: string) => boolean;
+    /**
+     * Subscribe to ALL events regardless of type.
+     * Useful for verification, debugging, and analytics.
+     *
+     * @param listener - Callback function invoked for every emitted event
+     * @returns Unsubscribe function
+     */
+    onAny?: (listener: EventListener) => Unsubscribe;
+}

package/dist/hooks/index.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Hooks barrel export
+ */
+export { useOrbitalHistory, type HistoryTimelineItem, type RevertResult, type ChangeSummary, type UseOrbitalHistoryOptions, type UseOrbitalHistoryResult, } from './useOrbitalHistory';
+export { useFileSystem, type FileSystemStatus, type FileSystemFile, type SelectedFile, type UseFileSystemResult, } from './useFileSystem';
+export { useExtensions, type Extension, type ExtensionManifest, type UseExtensionsOptions, type UseExtensionsResult, } from './useExtensions';
+export { useFileEditor, type OpenFile, type UseFileEditorOptions, type UseFileEditorResult, } from './useFileEditor';
+export { useCompile, type CompileStage, type CompileResult, type UseCompileResult, } from './useCompile';
+export { usePreview } from './usePreview';
+export { useAgentChat } from './useAgentChat';
+export { useValidation } from './useValidation';
+export { useDeepAgentGeneration } from './useDeepAgentGeneration';
+export { useEventBus, useEventListener, useEmitEvent } from './useEventBus';
+export type { KFlowEvent, EventListener, Unsubscribe, EventBusContextType } from './event-bus-types';
+export { useUISlotManager, DEFAULT_SLOTS, type UISlot, type SlotAnimation, type SlotContent, type RenderUIConfig, type SlotChangeCallback, type UISlotManager, } from './useUISlots';
+export { useUIEvents, useSelectedEntity } from './useUIEvents';
+export { useEntityList, useEntityDetail, useEntity, useEntityListSuspense, useEntitySuspense, entityDataKeys, EntityDataProvider, useEntityDataAdapter, type EntityDataAdapter, type EntityDataRecord, type UseEntityListOptions, type UseEntityListResult, type UseEntityDetailResult, } from './useEntityData';
+export { useQuerySingleton, parseQueryBinding, type QueryState, type QuerySingletonEntity, type QuerySingletonResult, type QuerySingletonState, } from './useQuerySingleton';
+export { useEntityMutations, useCreateEntity, useUpdateEntity, useDeleteEntity, type EntityMutationResult, type UseEntityMutationsOptions, } from './useEntityMutations';
+export { useOrbitalMutations, useSendOrbitalEvent, ENTITY_EVENTS, type OrbitalEventPayload, type OrbitalEventResponse, } from './useOrbitalMutations';
+export { useEntities, useEntity as useEntityById, useEntitiesByType, useSingletonEntity, usePlayer, usePhysics, useInput, spawnEntity, updateEntity, updateSingleton, removeEntity, clearEntities, getEntity, getByType, getAllEntities, getSingleton, type Entity, } from './useEntities';
+export { useTranslate, I18nProvider, createTranslate, type TranslateFunction, type I18nContextValue, } from './useTranslate';
+export { useResolvedEntity, type ResolvedEntity, } from './useResolvedEntity';
+export { useAuthContext, type AuthUser, type AuthContextValue, } from './useAuthContext';
+export { useSwipeGesture, type SwipeGestureOptions, type SwipeGestureResult, type SwipeHandlers, } from './useSwipeGesture';
+export { useLongPress, type LongPressOptions, type LongPressHandlers, } from './useLongPress';
+export { useDragReorder, type DragReorderResult, } from './useDragReorder';
+export { useInfiniteScroll, type InfiniteScrollOptions, type InfiniteScrollResult, } from './useInfiniteScroll';
+export { usePullToRefresh, type PullToRefreshOptions, type PullToRefreshResult, } from './usePullToRefresh';
+export { usePinchZoom, type PinchZoomOptions, type PinchZoomResult, } from './usePinchZoom';
+export { useGitHubStatus, useConnectGitHub, useDisconnectGitHub, useGitHubRepos, useGitHubRepo, useGitHubBranches, type GitHubStatus, type GitHubRepo, } from './useGitHub';

package/dist/hooks/useAgentChat.d.ts

@@ -0,0 +1,104 @@
+import type { DeepAgentInterrupt } from './useDeepAgentGeneration';
+export interface ChatMessage {
+    id: string;
+    role: 'user' | 'assistant' | 'system';
+    content: string;
+    timestamp: number;
+}
+export type AvatarRole = 'user' | 'assistant' | 'system';
+export type FileOperation = 'ls' | 'read_file' | 'write_file' | 'edit_file';
+export type Activity = {
+    type: 'message';
+    role: AvatarRole;
+    content: string;
+    timestamp: number;
+    isStreaming?: boolean;
+} | {
+    type: 'tool_call';
+    tool: string;
+    args: Record<string, unknown>;
+    timestamp: number;
+    isExecuting?: boolean;
+} | {
+    type: 'tool_result';
+    tool: string;
+    result: unknown;
+    success: boolean;
+    timestamp: number;
+} | {
+    type: 'file_operation';
+    operation: FileOperation;
+    path: string;
+    success?: boolean;
+    timestamp: number;
+} | {
+    type: 'schema_diff';
+    filePath: string;
+    hunks: DiffHunk[];
+    timestamp: number;
+} | {
+    type: 'error';
+    message: string;
+    code?: string;
+    timestamp: number;
+};
+export interface TodoActivity {
+    type: 'thinking' | 'tool_call' | 'tool_result' | 'code_change';
+    content: string;
+    timestamp: number;
+    tool?: string;
+    success?: boolean;
+    filePath?: string;
+    diff?: string;
+}
+export interface Todo {
+    id: string;
+    task: string;
+    status: 'pending' | 'in_progress' | 'completed';
+    latestActivity?: TodoActivity;
+    activityHistory?: TodoActivity[];
+}
+export interface DiffHunk {
+    oldStart: number;
+    oldLines: number;
+    newStart: number;
+    newLines: number;
+    lines: Array<{
+        type: 'add' | 'remove' | 'context';
+        content: string;
+    }>;
+}
+export interface SchemaDiff {
+    id: string;
+    filePath: string;
+    hunks: DiffHunk[];
+    timestamp: number;
+    addedLines: number;
+    removedLines: number;
+}
+export type AgentStatus = 'idle' | 'running' | 'complete' | 'error' | 'interrupted';
+export interface UseAgentChatOptions {
+    appId?: string;
+    onComplete?: (schema?: unknown) => void;
+    onSchemaChange?: (diff?: unknown) => void;
+    onError?: (error: Error | string) => void;
+}
+export interface UseAgentChatResult {
+    messages: ChatMessage[];
+    status: AgentStatus;
+    activities: Activity[];
+    todos: Todo[];
+    schemaDiffs: SchemaDiff[];
+    isLoading: boolean;
+    error: string | null;
+    threadId: string | null;
+    interrupt: DeepAgentInterrupt | null;
+    sendMessage: (content: string) => Promise<void>;
+    startGeneration: (skill: string | string[], prompt: string, options?: Record<string, unknown>) => Promise<void>;
+    continueConversation: (message: string | string[]) => Promise<void>;
+    resumeWithDecision: (decisions: unknown[]) => Promise<void>;
+    cancel: () => void;
+    clearMessages: () => void;
+    clearHistory: () => void;
+}
+export declare function useAgentChat(options?: UseAgentChatOptions): UseAgentChatResult;

package/dist/hooks/useAuthContext.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Auth Context Hook Stub
+ *
+ * Provides a placeholder auth context for the design system.
+ * Applications should provide their own AuthContext provider
+ * that implements this interface.
+ */
+export interface AuthUser {
+    uid: string;
+    email: string | null;
+    displayName: string | null;
+    photoURL: string | null;
+}
+export interface AuthContextValue {
+    user: AuthUser | null;
+    loading: boolean;
+    signIn?: () => Promise<void>;
+    signOut?: () => Promise<void>;
+}
+/**
+ * Stub hook that returns empty auth context.
+ * Applications should wrap their app with an AuthProvider
+ * that supplies real auth state.
+ */
+export declare function useAuthContext(): AuthContextValue;

package/dist/hooks/useCompile.d.ts

@@ -0,0 +1,22 @@
+export interface SchemaLike {
+    name: string;
+    version?: string;
+    [key: string]: unknown;
+}
+export type CompileStage = 'idle' | 'compiling' | 'done' | 'error';
+export interface CompileResult {
+    success: boolean;
+    files?: Array<{
+        path: string;
+        content: string;
+    }>;
+    errors?: string[];
+}
+export interface UseCompileResult {
+    isCompiling: boolean;
+    stage: CompileStage;
+    lastResult: CompileResult | null;
+    error: string | null;
+    compileSchema: (schema: SchemaLike) => Promise<CompileResult | null>;
+}
+export declare function useCompile(): UseCompileResult;

package/dist/hooks/useDeepAgentGeneration.d.ts

@@ -0,0 +1,46 @@
+import type { OrbitalSchema } from '@almadar/core';
+export interface DeepAgentActionRequest {
+    id: string;
+    type: string;
+    tool: string;
+    args: Record<string, unknown>;
+    description?: string;
+    allowedDecisions: ('approve' | 'edit' | 'reject')[];
+    status: 'pending' | 'approved' | 'rejected' | 'edited';
+}
+export interface DeepAgentInterrupt {
+    id: string;
+    type: 'tool_calls' | 'confirmation' | 'error';
+    message?: string;
+    actionRequests: DeepAgentActionRequest[];
+    timestamp: number;
+    threadId?: string;
+}
+export interface GenerationRequest {
+    id: string;
+    prompt: string;
+    status: 'pending' | 'running' | 'completed' | 'failed';
+    result?: OrbitalSchema;
+    error?: string;
+}
+export interface GenerationProgress {
+    stage: string;
+    percent: number;
+    message: string;
+}
+export interface UseDeepAgentGenerationResult {
+    requests: GenerationRequest[];
+    currentRequest: GenerationRequest | null;
+    isGenerating: boolean;
+    isLoading: boolean;
+    isComplete: boolean;
+    progress: GenerationProgress;
+    error: string | null;
+    interrupt: DeepAgentInterrupt | null;
+    generate: (prompt: string) => Promise<OrbitalSchema | null>;
+    startGeneration: (skill: string, prompt: string, options?: Record<string, unknown>) => Promise<void>;
+    cancelGeneration: () => void;
+    clearRequests: () => void;
+    submitInterruptDecisions: (decisions: unknown[]) => void;
+}
+export declare function useDeepAgentGeneration(): UseDeepAgentGenerationResult;

package/dist/hooks/useDragReorder.d.ts

@@ -0,0 +1,26 @@
+import type React from 'react';
+export interface DragReorderResult<T> {
+    /** The reordered items array */
+    items: T[];
+    /** Index of the item currently being dragged (-1 if not dragging) */
+    dragIndex: number;
+    /** Index of the drop target (-1 if not over any target) */
+    dragOverIndex: number;
+    /** Whether a drag is in progress */
+    isDragging: boolean;
+    /** Props to spread on the drag handle element for a given index */
+    getDragHandleProps: (index: number) => {
+        onPointerDown: (e: React.PointerEvent) => void;
+        style: React.CSSProperties;
+        'aria-grabbed': boolean;
+        role: string;
+    };
+    /** Props to spread on each list item for a given index */
+    getItemProps: (index: number) => {
+        onPointerMove: (e: React.PointerEvent) => void;
+        onPointerUp: () => void;
+        'aria-dropeffect': string;
+        style: React.CSSProperties;
+    };
+}
+export declare function useDragReorder<T>(initialItems: T[], onReorder: (fromIndex: number, toIndex: number, item: T) => void): DragReorderResult<T>;

package/dist/hooks/useEntities.d.ts

@@ -0,0 +1,52 @@
+import { getEntity, getByType, getAllEntities, getSingleton, spawnEntity, updateEntity, updateSingleton, removeEntity, clearEntities } from '../stores/entityStore';
+import type { Entity } from '../stores/entityStore';
+export type { Entity };
+/**
+ * Hook to access all entities
+ */
+export declare function useEntities(): {
+    entities: Map<string, Entity>;
+    getEntity: typeof getEntity;
+    getByType: typeof getByType;
+    getAllEntities: typeof getAllEntities;
+    getSingleton: typeof getSingleton;
+    spawnEntity: typeof spawnEntity;
+    updateEntity: typeof updateEntity;
+    updateSingleton: typeof updateSingleton;
+    removeEntity: typeof removeEntity;
+    clearEntities: typeof clearEntities;
+};
+/**
+ * Hook to access a specific entity by ID
+ */
+export declare function useEntity(id: string): Entity | undefined;
+/**
+ * Hook to access entities of a specific type
+ */
+export declare function useEntitiesByType(type: string): Entity[];
+/**
+ * Hook to access a singleton entity by type
+ */
+export declare function useSingletonEntity<T extends Entity = Entity>(type: string): T | undefined;
+/**
+ * Hook for Player entity (convenience)
+ */
+export declare function usePlayer(): {
+    player: Entity | undefined;
+    updatePlayer: (updates: Partial<Entity>) => void;
+};
+/**
+ * Hook for Physics entity (convenience)
+ */
+export declare function usePhysics(): {
+    physics: Entity | undefined;
+    updatePhysics: (updates: Partial<Entity>) => void;
+};
+/**
+ * Hook for Input entity (convenience)
+ */
+export declare function useInput(): {
+    input: Entity | undefined;
+    updateInput: (updates: Partial<Entity>) => void;
+};
+export { spawnEntity, updateEntity, updateSingleton, removeEntity, clearEntities, getEntity, getByType, getAllEntities, getSingleton, };

package/dist/hooks/useEntityData.d.ts

@@ -0,0 +1,155 @@
+import type { ReactNode } from "react";
+import React from "react";
+export interface EntityDataAdapter {
+    /** Get all records for an entity */
+    getData: (entity: string) => Record<string, unknown>[];
+    /** Get a single record by entity name and ID */
+    getById: (entity: string, id: string) => Record<string, unknown> | undefined;
+    /** Whether data is currently loading */
+    isLoading: boolean;
+    /** Current error */
+    error: string | null;
+}
+/**
+ * Provider that bridges a host app's data source to useEntityList/useEntity hooks.
+ *
+ * @example
+ * ```tsx
+ * // In builder runtime
+ * const fetchedData = useFetchedData();
+ * const adapter = {
+ *   getData: fetchedData.getData,
+ *   getById: fetchedData.getById,
+ *   isLoading: fetchedData.loading,
+ *   error: fetchedData.error,
+ * };
+ * <EntityDataProvider adapter={adapter}>
+ *   {children}
+ * </EntityDataProvider>
+ * ```
+ */
+export declare function EntityDataProvider({ adapter, children, }: {
+    adapter: EntityDataAdapter;
+    children: ReactNode;
+}): React.FunctionComponentElement<React.ProviderProps<EntityDataAdapter | null>>;
+/**
+ * Access the entity data adapter (null if no provider).
+ */
+export declare function useEntityDataAdapter(): EntityDataAdapter | null;
+export declare const entityDataKeys: {
+    all: readonly ["entities"];
+    lists: () => readonly ["entities", "list"];
+    list: (entity: string, filters?: Record<string, unknown>) => readonly ["entities", "list", string, Record<string, unknown> | undefined];
+    details: () => readonly ["entities", "detail"];
+    detail: (entity: string, id: string) => readonly ["entities", "detail", string, string];
+};
+export type EntityDataRecord = Record<string, unknown>;
+export interface UseEntityListOptions {
+    /** Skip fetching */
+    skip?: boolean;
+}
+export interface UseEntityListResult<T = Record<string, unknown>> {
+    data: T[];
+    isLoading: boolean;
+    error: Error | null;
+    refetch: () => void;
+}
+export interface UseEntityDetailResult<T = Record<string, unknown>> {
+    data: T | null;
+    isLoading: boolean;
+    error: Error | null;
+    refetch: () => void;
+}
+export interface PaginationParams {
+    page: number;
+    pageSize: number;
+    search?: string;
+    sortBy?: string;
+    sortDirection?: "asc" | "desc";
+    filters?: Record<string, unknown>;
+}
+export interface UsePaginatedEntityListResult<T = Record<string, unknown>> {
+    data: T[];
+    isLoading: boolean;
+    error: Error | null;
+    totalCount: number;
+    totalPages: number;
+    hasNextPage: boolean;
+    hasPreviousPage: boolean;
+    refetch: () => void;
+}
+/**
+ * Hook for fetching entity list data.
+ * Uses EntityDataContext if available, otherwise falls back to stub.
+ */
+export declare function useEntityList<T = Record<string, unknown>>(entity: string | undefined, options?: UseEntityListOptions): UseEntityListResult<T>;
+/**
+ * Hook for fetching a single entity by ID.
+ * Uses EntityDataContext if available, otherwise falls back to stub.
+ */
+export declare function useEntity<T = Record<string, unknown>>(entity: string | undefined, id: string | undefined): {
+    data: T | null;
+    isLoading: boolean;
+    error: Error | null;
+};
+/**
+ * Hook for fetching entity detail by ID (alias for useEntity with refetch).
+ * Uses EntityDataContext if available, otherwise falls back to stub.
+ */
+export declare function useEntityDetail<T = Record<string, unknown>>(entity: string | undefined, id: string | undefined): UseEntityDetailResult<T>;
+/**
+ * Hook for fetching paginated entity list data.
+ * Uses EntityDataContext if available (client-side pagination), otherwise falls back to stub.
+ */
+export declare function usePaginatedEntityList<T = Record<string, unknown>>(entity: string | undefined, params: PaginationParams, options?: UseEntityListOptions): UsePaginatedEntityListResult<T>;
+/**
+ * Suspense-compatible hook for fetching entity list data.
+ *
+ * Instead of returning `isLoading`/`error`, this hook **suspends** (throws a Promise)
+ * when data is not ready. Use inside a `<Suspense>` boundary.
+ *
+ * Falls back to the adapter when available; otherwise suspends briefly for stub data.
+ *
+ * @example
+ * ```tsx
+ * <Suspense fallback={<Skeleton variant="table" />}>
+ *   <ErrorBoundary>
+ *     <TaskList entity="Task" />
+ *   </ErrorBoundary>
+ * </Suspense>
+ *
+ * function TaskList({ entity }: { entity: string }) {
+ *   const { data } = useEntityListSuspense<Task>(entity);
+ *   // No loading check needed — Suspense handles it
+ *   return <DataTable data={data} ... />;
+ * }
+ * ```
+ */
+export declare function useEntityListSuspense<T = Record<string, unknown>>(entity: string): {
+    data: T[];
+    refetch: () => void;
+};
+/**
+ * Suspense-compatible hook for fetching a single entity by ID.
+ *
+ * Suspends when data is not ready. Use inside a `<Suspense>` boundary.
+ *
+ * @example
+ * ```tsx
+ * <Suspense fallback={<Skeleton variant="form" />}>
+ *   <ErrorBoundary>
+ *     <TaskDetail entity="Task" id={taskId} />
+ *   </ErrorBoundary>
+ * </Suspense>
+ *
+ * function TaskDetail({ entity, id }: { entity: string; id: string }) {
+ *   const { data } = useEntitySuspense<Task>(entity, id);
+ *   return <DetailPanel data={data} ... />;
+ * }
+ * ```
+ */
+export declare function useEntitySuspense<T = Record<string, unknown>>(entity: string, id: string): {
+    data: T | null;
+    refetch: () => void;
+};
+export default useEntityList;

package/dist/hooks/useEntityMutations.d.ts

@@ -0,0 +1,80 @@
+/**
+ * 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 orbital 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 { type OrbitalEventResponse } from './useOrbitalMutations';
+export interface EntityMutationResult {
+    id: string;
+    [key: string]: unknown;
+}
+/**
+ * Hook for creating entities
+ */
+export declare function useCreateEntity(entityName: string): import("@tanstack/react-query").UseMutationResult<EntityMutationResult, Error, Record<string, unknown>, unknown>;
+/**
+ * Hook for updating entities
+ */
+export declare function useUpdateEntity(entityName: string): import("@tanstack/react-query").UseMutationResult<EntityMutationResult, Error, {
+    id: string;
+    data: Record<string, unknown>;
+}, unknown>;
+/**
+ * Hook for deleting entities
+ */
+export declare function useDeleteEntity(entityName: string): import("@tanstack/react-query").UseMutationResult<{
+    id: string;
+}, Error, string, unknown>;
+export interface UseEntityMutationsOptions {
+    /**
+     * If provided, mutations go through orbital 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;
+    };
+}
+/**
+ * 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 declare function useEntityMutations(entityName: string, options?: UseEntityMutationsOptions): {
+    createEntity: (entityOrData: string | Record<string, unknown>, data?: Record<string, unknown>) => Promise<OrbitalEventResponse | EntityMutationResult | undefined>;
+    updateEntity: (id: string | undefined, data: Record<string, unknown>) => Promise<OrbitalEventResponse | EntityMutationResult | undefined>;
+    deleteEntity: (id: string | undefined) => Promise<OrbitalEventResponse | {
+        id: string;
+    } | undefined>;
+    isCreating: boolean;
+    isUpdating: boolean;
+    isDeleting: boolean;
+    createError: Error | null;
+    updateError: Error | null;
+    deleteError: Error | null;
+};