@almadar/ui 1.0.34 → 2.0.1

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/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/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/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/useTranslate.d.ts

@@ -0,0 +1,35 @@
+export type TranslateFunction = (key: string, params?: Record<string, string | number>) => string;
+export interface I18nContextValue {
+    /** Current locale code (e.g. 'en', 'ar', 'sl') */
+    locale: string;
+    /** Text direction for the current locale */
+    direction: 'ltr' | 'rtl';
+    /** Translate a key, with optional interpolation params */
+    t: TranslateFunction;
+}
+/**
+ * Provider component — wrap your app or Storybook decorator with this.
+ *
+ * ```tsx
+ * <I18nProvider value={{ locale: 'ar', direction: 'rtl', t: createTranslate(arMessages) }}>
+ *   <App />
+ * </I18nProvider>
+ * ```
+ */
+export declare const I18nProvider: import("react").Provider<I18nContextValue>;
+/**
+ * Hook to access the current locale and translate function.
+ * Safe to call without a provider — returns passthrough t().
+ */
+export declare function useTranslate(): I18nContextValue;
+/**
+ * Create a translate function from a flat messages object.
+ *
+ * ```ts
+ * const t = createTranslate({ 'common.save': 'Save', 'table.showing': 'Showing {{count}} of {{total}}' });
+ * t('common.save') // → 'Save'
+ * t('table.showing', { count: 5, total: 20 }) // → 'Showing 5 of 20'
+ * t('missing.key') // → 'missing.key' (fallback)
+ * ```
+ */
+export declare function createTranslate(messages: Record<string, string>): TranslateFunction;

package/dist/hooks/useUIEvents.d.ts

@@ -0,0 +1,35 @@
+import { useEventBus } from "./useEventBus";
+/**
+ * Hook to bridge UI events to state machine dispatch
+ *
+ * @param dispatch - The state machine dispatch function
+ * @param validEvents - Optional array of valid event names (filters which events to handle)
+ * @param eventBusInstance - Optional event bus instance (for testing, uses hook if not provided)
+ */
+export declare function useUIEvents<E extends string>(dispatch: (event: E, payload?: unknown) => void, validEvents?: readonly E[], eventBusInstance?: ReturnType<typeof useEventBus>): void;
+/**
+ * Hook for selected entity tracking
+ * Many list UIs need to track which item is selected.
+ *
+ * This hook uses SelectionProvider if available (preferred),
+ * otherwise falls back to listening to events directly.
+ *
+ * @example Using with SelectionProvider (recommended)
+ * ```tsx
+ * function MyPage() {
+ *   return (
+ *     <EventBusProvider>
+ *       <SelectionProvider>
+ *         <MyComponent />
+ *       </SelectionProvider>
+ *     </EventBusProvider>
+ *   );
+ * }
+ *
+ * function MyComponent() {
+ *   const [selected, setSelected] = useSelectedEntity<Order>();
+ *   // selected is automatically updated when UI:VIEW/UI:SELECT events fire
+ * }
+ * ```
+ */
+export declare function useSelectedEntity<T>(eventBusInstance?: ReturnType<typeof useEventBus>): [T | null, (entity: T | null) => void];

package/dist/{useUISlots-D0mttBSP.d.ts → hooks/useUISlots.d.ts}

@@ -1,15 +1,15 @@
 /**
  * Valid UI slot names
  */
-type UISlot = 'main' | 'sidebar' | 'modal' | 'drawer' | 'overlay' | 'center' | 'toast' | 'hud-top' | 'hud-bottom' | 'floating';
+export type UISlot = 'main' | 'sidebar' | 'modal' | 'drawer' | 'overlay' | 'center' | 'toast' | 'hud-top' | 'hud-bottom' | 'floating';
 /**
  * Animation types for slot transitions
  */
-type SlotAnimation = 'fade' | 'slide' | 'scale' | 'none';
+export type SlotAnimation = 'fade' | 'slide' | 'scale' | 'none';
 /**
  * Content rendered in a slot
  */
-interface SlotContent {
+export interface SlotContent {
     /** Unique ID for this content */
     id: string;
     /** Pattern/component type to render */
@@ -30,7 +30,7 @@ interface SlotContent {
 /**
  * Configuration for render_ui effect
  */
-interface RenderUIConfig {
+export interface RenderUIConfig {
     /** Target slot */
     target: UISlot;
     /** Pattern/component to render */
@@ -51,11 +51,11 @@ interface RenderUIConfig {
 /**
  * Callback for slot changes
  */
-type SlotChangeCallback = (slot: UISlot, content: SlotContent | null) => void;
+export type SlotChangeCallback = (slot: UISlot, content: SlotContent | null) => void;
 /**
  * UI Slot Manager interface
  */
-interface UISlotManager {
+export interface UISlotManager {
     /** Current content for each slot */
     slots: Record<UISlot, SlotContent | null>;
     /** Render content to a slot */
@@ -80,6 +80,5 @@ declare const DEFAULT_SLOTS: Record<UISlot, SlotContent | null>;
  * This is the internal hook that creates the manager.
  * Use `useUISlots()` from context in components.
  */
-declare function useUISlotManager(): UISlotManager;
-
-export { DEFAULT_SLOTS as D, type RenderUIConfig as R, type SlotContent as S, type UISlotManager as U, type UISlot as a, type SlotAnimation as b, type SlotChangeCallback as c, useUISlotManager as u };
+export declare function useUISlotManager(): UISlotManager;
+export { DEFAULT_SLOTS };

package/dist/hooks/useValidation.d.ts

@@ -0,0 +1,46 @@
+export interface LLMErrorContext {
+    rawValuePreview?: string;
+    expectedType?: string;
+    actualType?: string;
+    source?: {
+        agent: 'requirements' | 'builder' | 'view-planner';
+        operation: string;
+        promptHash?: string;
+    };
+    tokenUsage?: {
+        prompt: number;
+        completion: number;
+    };
+}
+export interface ValidationError {
+    code: string;
+    message: string;
+    path?: string;
+    severity: 'error' | 'warning';
+    suggestion?: string;
+    validValues?: string[];
+    expectedShape?: string;
+    fixGuidance?: string;
+    llmContext?: LLMErrorContext;
+}
+export interface ValidationResult {
+    valid: boolean;
+    errors: ValidationError[];
+    warnings: ValidationError[];
+}
+export type ValidationStage = 'idle' | 'validating' | 'fixing' | 'complete';
+export interface UseValidationResult {
+    result: ValidationResult | null;
+    isValidating: boolean;
+    error: string | null;
+    stage: ValidationStage;
+    isFixing: boolean;
+    progressMessage: string | null;
+    errors: ValidationError[];
+    warnings: ValidationError[];
+    isValid: boolean;
+    validate: (appId: string) => Promise<ValidationResult>;
+    clearResult: () => void;
+    reset: () => void;
+}
+export declare function useValidation(): UseValidationResult;

package/dist/lib/api-client.d.ts

@@ -0,0 +1,42 @@
+/**
+ * API Client - HTTP client for backend API calls
+ *
+ * Provides typed methods for making API requests.
+ * All requests go through the backend server, NOT directly to Firestore.
+ *
+ * @packageDocumentation
+ */
+/**
+ * API Error class for handling HTTP errors
+ */
+export declare class ApiError extends Error {
+    status: number;
+    statusText: string;
+    constructor(status: number, statusText: string, message?: string);
+}
+/**
+ * API client with typed methods
+ */
+export declare const apiClient: {
+    /**
+     * GET request
+     */
+    get<T>(endpoint: string): Promise<T>;
+    /**
+     * POST request
+     */
+    post<T>(endpoint: string, data?: unknown): Promise<T>;
+    /**
+     * PUT request
+     */
+    put<T>(endpoint: string, data?: unknown): Promise<T>;
+    /**
+     * PATCH request
+     */
+    patch<T>(endpoint: string, data?: unknown): Promise<T>;
+    /**
+     * DELETE request
+     */
+    delete<T = void>(endpoint: string): Promise<T>;
+};
+export default apiClient;

package/dist/lib/cn.d.ts

@@ -0,0 +1,6 @@
+import { type ClassValue } from 'clsx';
+/**
+ * Utility function to merge Tailwind CSS classes
+ * Combines clsx for conditional classes with tailwind-merge to handle conflicts
+ */
+export declare function cn(...inputs: ClassValue[]): string;

package/dist/lib/debug.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Debug utilities for development
+ */
+export declare function isDebugEnabled(): boolean;
+export declare function debug(...args: unknown[]): void;
+export declare function debugGroup(label: string): void;
+export declare function debugGroupEnd(): void;
+export declare function debugWarn(...args: unknown[]): void;
+export declare function debugError(...args: unknown[]): void;
+export declare function debugTable(data: unknown): void;
+export declare function debugTime(label: string): void;
+export declare function debugTimeEnd(label: string): void;
+/**
+ * Debug input events (keyboard, mouse, touch)
+ * @param inputType - Type of input (e.g., 'keydown', 'keyup', 'mouse')
+ * @param data - Input data to log
+ */
+export declare function debugInput(inputType: string, data: unknown): void;
+/**
+ * Debug collision events between entities
+ * @param entityA - First entity in collision
+ * @param entityB - Second entity in collision
+ * @param details - Additional collision details
+ */
+export declare function debugCollision(entityA: {
+    id?: string;
+    type?: string;
+}, entityB: {
+    id?: string;
+    type?: string;
+}, details?: unknown): void;
+/**
+ * Debug physics updates (position, velocity)
+ * @param entityId - Entity identifier
+ * @param physics - Physics data to log
+ */
+export declare function debugPhysics(entityId: string, physics: unknown): void;
+/**
+ * Debug game state changes
+ * @param stateName - Name of the state that changed
+ * @param value - New state value
+ */
+export declare function debugGameState(stateName: string, value: unknown): void;

package/dist/lib/debugRegistry.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Debug Registry - Central event log for debugging
+ *
+ * @packageDocumentation
+ */
+export type DebugEventType = 'state-change' | 'event-fired' | 'effect-executed' | 'guard-evaluated' | 'error' | 'warning' | 'info';
+export interface DebugEvent {
+    id: string;
+    type: DebugEventType;
+    source: string;
+    message: string;
+    data?: Record<string, unknown>;
+    timestamp: number;
+}
+type ChangeListener = () => void;
+export declare function logDebugEvent(type: DebugEventType, source: string, message: string, data?: Record<string, unknown>): void;
+export declare function logStateChange(source: string, from: string, to: string, event?: string): void;
+export declare function logEventFired(source: string, eventName: string, payload?: unknown): void;
+export declare function logEffectExecuted(source: string, effectType: string, details?: unknown): void;
+export declare function logError(source: string, message: string, error?: unknown): void;
+export declare function logWarning(source: string, message: string, data?: Record<string, unknown>): void;
+export declare function logInfo(source: string, message: string, data?: Record<string, unknown>): void;
+export declare function getDebugEvents(): DebugEvent[];
+export declare function getRecentEvents(count: number): DebugEvent[];
+export declare function getEventsByType(type: DebugEventType): DebugEvent[];
+export declare function getEventsBySource(source: string): DebugEvent[];
+export declare function subscribeToDebugEvents(listener: ChangeListener): () => void;
+export declare function clearDebugEvents(): void;
+export {};

package/dist/lib/debugUtils.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Debug Utilities - Functions for toggling and checking debug mode
+ *
+ * @packageDocumentation
+ */
+type DebugToggleListener = (enabled: boolean) => void;
+/**
+ * Check if debug mode is enabled
+ */
+export declare function isDebugEnabled(): boolean;
+/**
+ * Enable or disable debug mode
+ */
+export declare function setDebugEnabled(enabled: boolean): void;
+/**
+ * Toggle debug mode
+ */
+export declare function toggleDebug(): boolean;
+/**
+ * Subscribe to debug mode changes
+ */
+export declare function onDebugToggle(listener: DebugToggleListener): () => void;
+/**
+ * Initialize debug mode from keyboard shortcut (Ctrl+Shift+D)
+ */
+export declare function initDebugShortcut(): () => void;
+export {};