@almadar/ui 2.0.1 → 2.0.2

package/dist/hooks/useEntityData.d.ts

@@ -1,155 +0,0 @@
-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

@@ -1,80 +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 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;
-};

package/dist/hooks/useEventBus.d.ts

@@ -1,96 +0,0 @@
-import type { KFlowEvent, EventListener, Unsubscribe, EventBusContextType } from './event-bus-types';
-export type { KFlowEvent, EventListener, Unsubscribe, EventBusContextType };
-declare global {
-    interface Window {
-        __kflowEventBus?: EventBusContextType | null;
-    }
-}
-/**
- * Global event bus reference for bridging between packages.
- *
- * Uses window-level global to enable cross-package communication.
- * This allows @almadar/ui components to emit events to the same bus
- * that the consuming app's trait state machine listens to.
- *
- * When the EventBusProvider mounts, it sets window.__kflowEventBus.
- * Components in any package can then use this shared event bus.
- *
- * SSR Safety: All window access is guarded by `typeof window !== 'undefined'`.
- * React Compiler Safety: The global bus reference is set once at provider mount
- * and is stable — no render-path side effects. In practice, the React context
- * path (priority 1) is used in real apps; the window global (priority 2) is
- * only reached when no EventBusProvider is in the tree (e.g., Storybook).
- */
-/**
- * Set the global event bus reference.
- * Called by EventBusProvider when it mounts.
- *
- * @param bus - The event bus context to set as global, or null to clear
- */
-export declare function setGlobalEventBus(bus: EventBusContextType | null): void;
-/**
- * Get the global event bus reference.
- *
- * @returns The global event bus if set, null otherwise
- */
-export declare function getGlobalEventBus(): EventBusContextType | null;
-/**
- * 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 declare function useEventBus(): EventBusContextType;
-/**
- * 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 declare function useEventListener(event: string, handler: EventListener): void;
-/**
- * Alias for useEventListener for backward compatibility
- */
-export declare const useEventSubscription: typeof 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 declare function useEmitEvent(): (type: string, payload?: Record<string, unknown>) => void;
-export default useEventBus;

package/dist/hooks/useExtensions.d.ts

@@ -1,32 +0,0 @@
-export interface Extension {
-    id: string;
-    name: string;
-    language?: string;
-    loaded: boolean;
-}
-export interface ExtensionEntry {
-    file: string;
-    language?: string;
-}
-export interface ExtensionManifest {
-    languages: Record<string, {
-        extensions: string[];
-        icon?: string;
-        color?: string;
-    }>;
-    extensions: ExtensionEntry[];
-}
-export interface UseExtensionsOptions {
-    appId: string;
-    loadOnMount?: boolean;
-}
-export interface UseExtensionsResult {
-    extensions: Extension[];
-    manifest: ExtensionManifest;
-    isLoading: boolean;
-    error: string | null;
-    loadExtension: (extensionId: string) => Promise<void>;
-    loadExtensions: () => Promise<void>;
-    getExtensionForFile: (filename: string) => Extension | null;
-}
-export declare function useExtensions(options: UseExtensionsOptions): UseExtensionsResult;

package/dist/hooks/useFileEditor.d.ts

@@ -1,32 +0,0 @@
-import type { UseExtensionsResult } from './useExtensions';
-import type { UseFileSystemResult } from './useFileSystem';
-import type { OrbitalSchema } from '@almadar/core';
-export interface OpenFile {
-    path: string;
-    content: string;
-    isDirty: boolean;
-    language?: string;
-}
-export interface UseFileEditorOptions {
-    extensions: UseExtensionsResult;
-    fileSystem: UseFileSystemResult;
-    onSchemaUpdate?: (schema: OrbitalSchema) => Promise<void>;
-}
-export interface FileEditResult {
-    success: boolean;
-    action?: 'updated_schema' | 'converted_extension' | 'saved_extension' | 'saved';
-    error?: string;
-}
-export interface UseFileEditorResult {
-    openFiles: OpenFile[];
-    activeFile: OpenFile | null;
-    isSaving: boolean;
-    openFile: (path: string) => Promise<void>;
-    closeFile: (path: string) => void;
-    setActiveFile: (path: string) => void;
-    updateFileContent: (path: string, content: string) => void;
-    handleFileEdit: (path: string, content: string) => Promise<FileEditResult>;
-    saveFile: (path: string) => Promise<void>;
-    saveAllFiles: () => Promise<void>;
-}
-export declare function useFileEditor(options: UseFileEditorOptions): UseFileEditorResult;

package/dist/hooks/useFileSystem.d.ts

@@ -1,40 +0,0 @@
-export interface FileNode {
-    path: string;
-    name: string;
-    type: 'file' | 'directory';
-    children?: FileNode[];
-}
-export type FileSystemStatus = 'idle' | 'booting' | 'ready' | 'running' | 'error';
-export interface FileSystemFile {
-    path: string;
-    content: string;
-}
-export interface SelectedFile {
-    path: string;
-    content: string;
-    language?: string;
-    isDirty?: boolean;
-}
-export interface UseFileSystemResult {
-    status: FileSystemStatus;
-    error: string | null;
-    isLoading: boolean;
-    files: FileNode[];
-    selectedFile: SelectedFile | null;
-    selectedPath: string | null;
-    previewUrl: string | null;
-    boot: () => Promise<void>;
-    mountFiles: (files: FileSystemFile[] | Record<string, unknown>) => Promise<void>;
-    readFile: (path: string) => Promise<string>;
-    writeFile: (path: string, content: string) => Promise<void>;
-    selectFile: (path: string) => Promise<void>;
-    updateContent: (pathOrContent: string, content?: string) => void;
-    updateSelectedContent: (content: string) => void;
-    refreshTree: () => Promise<void>;
-    runCommand: (command: string) => Promise<{
-        exitCode: number;
-        output: string;
-    }>;
-    startDevServer: () => Promise<void>;
-}
-export declare function useFileSystem(): UseFileSystemResult;

package/dist/hooks/useGitHub.d.ts

@@ -1,58 +0,0 @@
-/**
- * GitHub connection status
- */
-export interface GitHubStatus {
-    connected: boolean;
-    username?: string;
-    avatarUrl?: string;
-    scopes?: string[];
-    connectedAt?: number;
-    lastUsedAt?: number;
-}
-/**
- * GitHub repository
- */
-export interface GitHubRepo {
-    id: number;
-    name: string;
-    fullName: string;
-    owner: string;
-    isPrivate: boolean;
-    description: string | null;
-    defaultBranch: string;
-    url: string;
-}
-/**
- * Hook to get GitHub connection status
- */
-export declare function useGitHubStatus(): import("@tanstack/react-query").UseQueryResult<GitHubStatus, Error>;
-/**
- * Hook to connect GitHub (initiate OAuth flow)
- */
-export declare function useConnectGitHub(): {
-    connectGitHub: () => void;
-};
-/**
- * Hook to disconnect GitHub
- */
-export declare function useDisconnectGitHub(): import("@tanstack/react-query").UseMutationResult<unknown, Error, void, unknown>;
-/**
- * Hook to list GitHub repositories
- */
-export declare function useGitHubRepos(page?: number, perPage?: number): import("@tanstack/react-query").UseQueryResult<{
-    repos: GitHubRepo[];
-    page: number;
-    perPage: number;
-}, Error>;
-/**
- * Hook to get repository details
- */
-export declare function useGitHubRepo(owner: string, repo: string, enabled?: boolean): import("@tanstack/react-query").UseQueryResult<{
-    repo: GitHubRepo;
-}, Error>;
-/**
- * Hook to list repository branches
- */
-export declare function useGitHubBranches(owner: string, repo: string, enabled?: boolean): import("@tanstack/react-query").UseQueryResult<{
-    branches: string[];
-}, Error>;

package/dist/hooks/useOrbitalHistory.d.ts

@@ -1,39 +0,0 @@
-import type { OrbitalSchema } from '@almadar/core';
-export interface ChangeSummary {
-    added: number;
-    modified: number;
-    removed: number;
-}
-export interface HistoryTimelineItem {
-    id: string;
-    type: 'changeset' | 'snapshot';
-    version: number;
-    timestamp: number;
-    description: string;
-    source?: string;
-    summary?: ChangeSummary;
-    reason?: string;
-}
-export interface RevertResult {
-    success: boolean;
-    error?: string;
-    restoredSchema?: OrbitalSchema;
-}
-export interface UseOrbitalHistoryOptions {
-    appId: string | null;
-    /** Firebase auth token for authenticated API requests */
-    authToken?: string | null;
-    /** User ID for x-user-id header (required for Firestore path) */
-    userId?: string | null;
-    onHistoryChange?: (timeline: HistoryTimelineItem[]) => void;
-    onRevertSuccess?: (restoredSchema: OrbitalSchema) => void;
-}
-export interface UseOrbitalHistoryResult {
-    timeline: HistoryTimelineItem[];
-    currentVersion: number;
-    isLoading: boolean;
-    error: string | null;
-    revertToSnapshot: (snapshotId: string) => Promise<RevertResult>;
-    refresh: () => Promise<void>;
-}
-export declare function useOrbitalHistory(options: UseOrbitalHistoryOptions): UseOrbitalHistoryResult;

package/dist/hooks/useOrbitalMutations.d.ts

@@ -1,95 +0,0 @@
-/**
- * useOrbitalMutations - Event-based entity mutations via orbital events route
- *
- * This hook provides entity mutations that go through the orbital 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
- */
-/**
- * Standard events for entity mutations
- * These are handled by orbitals with CRUD-capable traits
- */
-export declare const ENTITY_EVENTS: {
-    readonly CREATE: "ENTITY_CREATE";
-    readonly UPDATE: "ENTITY_UPDATE";
-    readonly DELETE: "ENTITY_DELETE";
-};
-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;
-}
-/**
- * Hook for event-based entity mutations via orbital events route
- *
- * @param entityName - The entity type name (for cache invalidation)
- * @param orbitalName - The orbital to send events to
- * @param options - Optional configuration
- */
-export declare 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;
-}): {
-    createEntity: (data: Record<string, unknown>) => Promise<OrbitalEventResponse>;
-    updateEntity: (id: string | undefined, data: Record<string, unknown>) => Promise<OrbitalEventResponse | undefined>;
-    deleteEntity: (id: string | undefined) => Promise<OrbitalEventResponse | undefined>;
-    createMutation: import("@tanstack/react-query").UseMutationResult<OrbitalEventResponse, Error, Record<string, unknown>, unknown>;
-    updateMutation: import("@tanstack/react-query").UseMutationResult<OrbitalEventResponse, Error, {
-        id: string;
-        data: Record<string, unknown>;
-    }, unknown>;
-    deleteMutation: import("@tanstack/react-query").UseMutationResult<OrbitalEventResponse, Error, string, unknown>;
-    isCreating: boolean;
-    isUpdating: boolean;
-    isDeleting: boolean;
-    isMutating: boolean;
-    createError: Error | null;
-    updateError: Error | null;
-    deleteError: Error | null;
-};
-/**
- * Send a custom event to an orbital
- * For non-CRUD operations that go through trait state machines
- */
-export declare function useSendOrbitalEvent(orbitalName: string): {
-    sendEvent: (event: string, payload?: Record<string, unknown>, entityId?: string) => Promise<OrbitalEventResponse>;
-    isPending: boolean;
-    error: Error | null;
-    data: OrbitalEventResponse | undefined;
-};

package/dist/hooks/usePreview.d.ts

@@ -1,57 +0,0 @@
-import type { OrbitalSchema } from '@almadar/core';
-export interface PreviewApp {
-    id: string;
-    name: string;
-    status: 'loading' | 'ready' | 'error';
-    schema?: OrbitalSchema;
-    graphView: {
-        version: string;
-    };
-}
-export interface Notification {
-    id: string;
-    type: 'info' | 'warning' | 'error' | 'success';
-    title: string;
-    message: string;
-    timestamp: number;
-    read?: boolean;
-    actionLabel?: string;
-    onAction?: () => void;
-    autoDismiss?: boolean;
-    dismissAfter?: number;
-}
-export interface NotificationsState {
-    notifications: Notification[];
-    isPanelOpen: boolean;
-    closePanel: () => void;
-    dismissNotification: (id: string) => void;
-    markAsRead: (id: string) => void;
-    clearAll: () => void;
-}
-export interface ErrorToast {
-    message: string;
-}
-export interface UsePreviewResult {
-    previewUrl: string | null;
-    isLoading: boolean;
-    error: string | null;
-    loadError: string | null;
-    app: PreviewApp | null;
-    isFullscreen: boolean;
-    isExecutingEvent: boolean;
-    errorToast: ErrorToast | null;
-    currentStateName: string | null;
-    notifications: NotificationsState;
-    startPreview: () => Promise<void>;
-    stopPreview: () => Promise<void>;
-    refresh: () => Promise<void>;
-    handleRefresh: () => Promise<void>;
-    handleReset: () => Promise<void>;
-    toggleFullscreen: () => void;
-    setErrorToast: (toast: ErrorToast | null) => void;
-    dismissErrorToast: () => void;
-}
-export interface UsePreviewOptions {
-    appId?: string;
-}
-export declare function usePreview(options?: UsePreviewOptions): UsePreviewResult;