@almadar/ui 2.14.0 → 2.15.0

package/dist/hooks/useEventBus.d.ts

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

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

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

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

@@ -0,0 +1,58 @@
+/**
+ * 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/useInfiniteScroll.d.ts

@@ -0,0 +1,13 @@
+export interface InfiniteScrollOptions {
+    /** Root margin for IntersectionObserver (default: "200px") */
+    rootMargin?: string;
+    /** Whether more items are available to load */
+    hasMore?: boolean;
+    /** Whether a load is currently in progress */
+    isLoading?: boolean;
+}
+export interface InfiniteScrollResult {
+    /** Ref to attach to the sentinel element */
+    sentinelRef: React.RefCallback<HTMLElement>;
+}
+export declare function useInfiniteScroll(onLoadMore: () => void, options?: InfiniteScrollOptions): InfiniteScrollResult;

package/dist/hooks/useLongPress.d.ts

@@ -0,0 +1,16 @@
+import type React from 'react';
+export interface LongPressOptions {
+    /** Hold duration in ms before triggering (default: 500) */
+    duration?: number;
+    /** Movement tolerance in px before canceling (default: 10) */
+    moveThreshold?: number;
+}
+export interface LongPressHandlers {
+    onPointerDown: (e: React.PointerEvent) => void;
+    onPointerMove: (e: React.PointerEvent) => void;
+    onPointerUp: () => void;
+    onPointerCancel: () => void;
+    /** Whether the long press is currently active (held down, timer running) */
+    isPressed: boolean;
+}
+export declare function useLongPress(onLongPress: () => void, options?: LongPressOptions): LongPressHandlers;

package/dist/hooks/useOrbitalHistory.d.ts

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

@@ -0,0 +1,95 @@
+/**
+ * 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/usePinchZoom.d.ts

@@ -0,0 +1,22 @@
+import type React from 'react';
+export interface PinchZoomResult {
+    /** Current zoom scale (1 = no zoom) */
+    scale: number;
+    /** Whether a pinch gesture is active */
+    isPinching: boolean;
+    /** Props to spread on the zoomable container */
+    gestureProps: {
+        onTouchStart: (e: React.TouchEvent) => void;
+        onTouchMove: (e: React.TouchEvent) => void;
+        onTouchEnd: () => void;
+    };
+    /** Reset zoom to 1 */
+    resetZoom: () => void;
+}
+export interface PinchZoomOptions {
+    /** Minimum zoom scale (default: 0.5) */
+    minScale?: number;
+    /** Maximum zoom scale (default: 4) */
+    maxScale?: number;
+}
+export declare function usePinchZoom(options?: PinchZoomOptions): PinchZoomResult;

package/dist/hooks/usePreview.d.ts

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

package/dist/hooks/usePullToRefresh.d.ts

@@ -0,0 +1,25 @@
+import type React from 'react';
+export interface PullToRefreshOptions {
+    /** Distance in px to pull before triggering refresh (default: 60) */
+    threshold?: number;
+    /** Maximum pull distance in px (default: 120) */
+    maxPull?: number;
+}
+export interface PullToRefreshResult {
+    /** Current pull distance in px */
+    pullDistance: number;
+    /** Whether the user is actively pulling */
+    isPulling: boolean;
+    /** Whether a refresh was triggered and is in progress */
+    isRefreshing: boolean;
+    /** Props to spread on the scrollable container */
+    containerProps: {
+        onTouchStart: (e: React.TouchEvent) => void;
+        onTouchMove: (e: React.TouchEvent) => void;
+        onTouchEnd: () => void;
+        style: React.CSSProperties;
+    };
+    /** Call this when the refresh operation completes */
+    endRefresh: () => void;
+}
+export declare function usePullToRefresh(onRefresh: () => void, options?: PullToRefreshOptions): PullToRefreshResult;

package/dist/hooks/useQuerySingleton.d.ts

@@ -0,0 +1,78 @@
+/**
+ * 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;
+}
+/**
+ * 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 declare function useQuerySingleton(query?: string): QuerySingletonState | null;
+/**
+ * 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 declare function parseQueryBinding(binding: string): {
+    query: string;
+    field?: string;
+};
+export default useQuerySingleton;

package/dist/hooks/useResolvedEntity.d.ts

@@ -0,0 +1,32 @@
+export interface ResolvedEntity<T> {
+    /** Resolved data array */
+    data: T[];
+    /** True when data was provided directly via props (not fetched) */
+    isLocal: boolean;
+    /** Loading state — always false for local data */
+    isLoading: boolean;
+    /** Error state — always null for local data */
+    error: Error | null;
+}
+/**
+ * Resolves entity data from either a direct `data` prop or an `entity` string.
+ *
+ * When `data` is provided, it is used directly (isLocal: true).
+ * When only `entity` (string) is provided, data is fetched via useEntityList.
+ * Direct `data` always takes precedence over auto-fetch.
+ *
+ * @param entity - Entity name string for auto-fetch, or undefined
+ * @param data - Direct data array from trait render-ui, or undefined
+ * @returns Normalized { data, isLocal, isLoading, error }
+ *
+ * @example
+ * ```tsx
+ * function MyOrganism({ entity, data, isLoading, error }: MyProps) {
+ *   const resolved = useResolvedEntity<Item>(entity, data);
+ *   // resolved.data is always T[] regardless of source
+ *   // resolved.isLocal tells you if data came from props
+ * }
+ * ```
+ */
+export declare function useResolvedEntity<T = Record<string, unknown>>(entity: string | undefined, data: readonly T[] | T[] | undefined): ResolvedEntity<T>;
+export default useResolvedEntity;

package/dist/hooks/useSwipeGesture.d.ts

@@ -0,0 +1,26 @@
+export interface SwipeGestureOptions {
+    /** Minimum distance in px to trigger a swipe (default: 50) */
+    threshold?: number;
+    /** Minimum velocity in px/ms to qualify (default: 0.3) */
+    velocityThreshold?: number;
+    /** Prevent default touch behavior during swipe (default: false) */
+    preventDefault?: boolean;
+}
+export interface SwipeGestureResult {
+    onSwipeLeft?: () => void;
+    onSwipeRight?: () => void;
+    onSwipeUp?: () => void;
+    onSwipeDown?: () => void;
+}
+export interface SwipeHandlers {
+    onPointerDown: (e: React.PointerEvent) => void;
+    onPointerMove: (e: React.PointerEvent) => void;
+    onPointerUp: (e: React.PointerEvent) => void;
+    onPointerCancel: (e: React.PointerEvent) => void;
+    /** Current horizontal offset during swipe (for animation) */
+    offsetX: number;
+    /** Whether a swipe gesture is in progress */
+    isSwiping: boolean;
+}
+import type React from 'react';
+export declare function useSwipeGesture(callbacks: SwipeGestureResult, options?: SwipeGestureOptions): SwipeHandlers;