@almadar/ui 2.0.0 → 2.0.1

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

@@ -0,0 +1,84 @@
+/**
+ * Valid UI slot names
+ */
+export type UISlot = 'main' | 'sidebar' | 'modal' | 'drawer' | 'overlay' | 'center' | 'toast' | 'hud-top' | 'hud-bottom' | 'floating';
+/**
+ * Animation types for slot transitions
+ */
+export type SlotAnimation = 'fade' | 'slide' | 'scale' | 'none';
+/**
+ * Content rendered in a slot
+ */
+export interface SlotContent {
+    /** Unique ID for this content */
+    id: string;
+    /** Pattern/component type to render */
+    pattern: string;
+    /** Props to pass to the pattern component */
+    props: Record<string, unknown>;
+    /** Priority for conflict resolution (higher wins) */
+    priority: number;
+    /** Animation for showing/hiding */
+    animation?: SlotAnimation;
+    /** Auto-dismiss timestamp (for toasts) */
+    autoDismissAt?: number;
+    /** Callback when dismissed */
+    onDismiss?: () => void;
+    /** Source trait that rendered this content */
+    sourceTrait?: string;
+}
+/**
+ * Configuration for render_ui effect
+ */
+export interface RenderUIConfig {
+    /** Target slot */
+    target: UISlot;
+    /** Pattern/component to render */
+    pattern: string;
+    /** Props for the pattern */
+    props?: Record<string, unknown>;
+    /** Priority (default: 0) */
+    priority?: number;
+    /** Animation type */
+    animation?: SlotAnimation;
+    /** Auto-dismiss after ms (for toasts) */
+    autoDismissMs?: number;
+    /** Callback on dismiss */
+    onDismiss?: () => void;
+    /** Source trait name */
+    sourceTrait?: string;
+}
+/**
+ * Callback for slot changes
+ */
+export type SlotChangeCallback = (slot: UISlot, content: SlotContent | null) => void;
+/**
+ * UI Slot Manager interface
+ */
+export interface UISlotManager {
+    /** Current content for each slot */
+    slots: Record<UISlot, SlotContent | null>;
+    /** Render content to a slot */
+    render: (config: RenderUIConfig) => string;
+    /** Clear a specific slot */
+    clear: (slot: UISlot) => void;
+    /** Clear content by ID */
+    clearById: (id: string) => void;
+    /** Clear all slots */
+    clearAll: () => void;
+    /** Subscribe to slot changes */
+    subscribe: (callback: SlotChangeCallback) => () => void;
+    /** Check if a slot has content */
+    hasContent: (slot: UISlot) => boolean;
+    /** Get content for a slot */
+    getContent: (slot: UISlot) => SlotContent | null;
+}
+declare const DEFAULT_SLOTS: Record<UISlot, SlotContent | null>;
+/**
+ * Create a UI Slot Manager instance.
+ *
+ * This is the internal hook that creates the manager.
+ * Use `useUISlots()` from context in components.
+ */
+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 {};

package/dist/lib/entityDebug.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Entity Debug - Provides entity state snapshots for debugging
+ *
+ * @packageDocumentation
+ */
+export interface EntityState {
+    id: string;
+    type: string;
+    fields: Record<string, unknown>;
+    lastUpdated: number;
+}
+export interface RuntimeEntity {
+    id: string;
+    type: string;
+    data: Record<string, unknown>;
+}
+export interface PersistentEntityInfo {
+    loaded: boolean;
+    count: number;
+}
+export interface EntitySnapshot {
+    entities: EntityState[];
+    timestamp: number;
+    totalCount: number;
+    /** Singleton entities by name */
+    singletons: Record<string, unknown>;
+    /** Runtime entities (in-memory) */
+    runtime: RuntimeEntity[];
+    /** Persistent entities info by type */
+    persistent: Record<string, PersistentEntityInfo>;
+}
+type EntityProvider = () => EntityState[];
+export declare function setEntityProvider(provider: EntityProvider): void;
+export declare function clearEntityProvider(): void;
+export declare function getEntitySnapshot(): EntitySnapshot | null;
+export declare function getEntityById(id: string): EntityState | undefined;
+export declare function getEntitiesByType(type: string): EntityState[];
+export {};

package/dist/lib/getNestedValue.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Get Nested Value Utility
+ *
+ * Safely retrieves nested values from objects using dot-notation paths.
+ * Used by display components to support relation field access like "company.name".
+ *
+ * @packageDocumentation
+ */
+/**
+ * Get a nested value from an object using dot-notation path.
+ *
+ * @param obj - The object to traverse
+ * @param path - Dot-notation path (e.g., "company.name", "address.city")
+ * @returns The value at the path, or undefined if not found
+ *
+ * @example
+ * const data = { company: { name: "Acme Corp", address: { city: "NYC" } } };
+ * getNestedValue(data, "company.name");         // => "Acme Corp"
+ * getNestedValue(data, "company.address.city"); // => "NYC"
+ * getNestedValue(data, "company.missing");      // => undefined
+ */
+export declare function getNestedValue(obj: Record<string, unknown> | null | undefined, path: string): unknown;
+/**
+ * Format a nested field path as a human-readable label.
+ *
+ * @param path - Dot-notation path (e.g., "company.name")
+ * @returns Formatted label (e.g., "Company Name")
+ *
+ * @example
+ * formatFieldLabel("company.name");    // => "Company Name"
+ * formatFieldLabel("address.zipCode"); // => "Address Zip Code"
+ */
+export declare function formatNestedFieldLabel(path: string): string;

package/dist/lib/guardRegistry.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Guard Registry - Tracks guard evaluations for debugging
+ *
+ * @packageDocumentation
+ */
+export interface GuardContext {
+    traitName?: string;
+    type?: "transition" | "tick";
+    transitionFrom?: string;
+    transitionTo?: string;
+    tickName?: string;
+    [key: string]: unknown;
+}
+export interface GuardEvaluation {
+    id: string;
+    traitName: string;
+    guardName: string;
+    expression: string;
+    result: boolean;
+    context: GuardContext;
+    timestamp: number;
+    /** Input values used in guard evaluation */
+    inputs: Record<string, unknown>;
+}
+type ChangeListener = () => void;
+export declare function recordGuardEvaluation(evaluation: Omit<GuardEvaluation, "id" | "timestamp">): void;
+export declare function getGuardHistory(): GuardEvaluation[];
+export declare function getRecentGuardEvaluations(count: number): GuardEvaluation[];
+export declare function getGuardEvaluationsForTrait(traitName: string): GuardEvaluation[];
+export declare function subscribeToGuardChanges(listener: ChangeListener): () => void;
+export declare function clearGuardHistory(): void;
+export {};

package/dist/lib/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Lib - Utility functions and registries
+ *
+ * Core utilities for the Almadar UI library.
+ */
+export { cn } from './cn';
+export * from './api-client';
+export * from './debug';
+export { setDebugEnabled, toggleDebug, onDebugToggle, initDebugShortcut, } from './debugUtils';
+export * from './entityDebug';
+export * from './debugRegistry';
+export * from './guardRegistry';
+export * from './tickRegistry';
+export * from './traitRegistry';
+export * from './verificationRegistry';
+export * from './getNestedValue';
+export * from './visualizer';
+export * from './parseContentSegments';

package/dist/lib/jazari/svg-paths.d.ts

@@ -0,0 +1,61 @@
+/**
+ * SVG path generators for the Al-Jazari state machine visualization.
+ * Pure TypeScript — zero React/DOM dependencies.
+ *
+ * Generates paths for gear teeth, arabesque borders, pipe shapes, and lock icons.
+ */
+/**
+ * Generate an SVG path for gear teeth around a circle.
+ *
+ * @param cx - Center X
+ * @param cy - Center Y
+ * @param innerRadius - Inner radius (base circle)
+ * @param outerRadius - Outer radius (tip of teeth)
+ * @param numTeeth - Number of teeth around the gear
+ * @returns SVG path d attribute string
+ */
+export declare function gearTeethPath(cx: number, cy: number, innerRadius: number, outerRadius: number, numTeeth: number): string;
+/**
+ * Generate an SVG path for a small gear-shaped lock icon.
+ *
+ * @param cx - Center X
+ * @param cy - Center Y
+ * @param size - Overall size of the lock icon
+ * @returns SVG path d attribute for the lock body + shackle
+ */
+export declare function lockIconPath(cx: number, cy: number, size: number): string;
+/**
+ * Generate a simple brain-like icon path.
+ *
+ * @param cx - Center X
+ * @param cy - Center Y
+ * @param size - Overall size
+ * @returns SVG path d attribute
+ */
+export declare function brainIconPath(cx: number, cy: number, size: number): string;
+/**
+ * Generate a simple pipe/tube icon path.
+ *
+ * @param cx - Center X
+ * @param cy - Center Y
+ * @param size - Overall size
+ * @returns SVG path d attribute
+ */
+export declare function pipeIconPath(cx: number, cy: number, size: number): string;
+/**
+ * Generate a single 8-pointed star path for the arabesque border pattern.
+ *
+ * @param cx - Center X
+ * @param cy - Center Y
+ * @param outerR - Outer radius (star tips)
+ * @param innerR - Inner radius (star valleys)
+ * @returns SVG path d attribute
+ */
+export declare function eightPointedStarPath(cx: number, cy: number, outerR: number, innerR: number): string;
+/**
+ * Generate a simple arrowhead path for transition arm endpoints.
+ *
+ * @param size - Arrow size
+ * @returns SVG path d attribute
+ */
+export declare function arrowheadPath(size: number): string;