@almadar/ui 2.14.0 → 2.15.0

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' | 'hud-left' | 'hud-right' | '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/index.d.ts

@@ -0,0 +1,5 @@
+export { computeJazariLayout } from './layout.js';
+export type { LayoutState, LayoutTransition, LayoutInput } from './layout.js';
+export { gearTeethPath, lockIconPath, brainIconPath, pipeIconPath, eightPointedStarPath, arrowheadPath, } from './svg-paths.js';
+export type { JazariLayout, JazariGearLayout, JazariArmLayout, JazariGuardInfo, JazariEffectInfo, } from './types.js';
+export { JAZARI_COLORS } from './types.js';

package/dist/lib/jazari/layout.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Layout algorithm for the Al-Jazari state machine visualization.
+ * Pure TypeScript — zero React/DOM dependencies.
+ *
+ * 1. BFS from initial state to order states by graph distance.
+ * 2. Horizontal distribution of gears along the golden axis.
+ * 3. Transition arm routing: forward arcs above, backward arcs below, self-loops above.
+ * 4. Guard icons at 30% along arm, effect icons at 70%.
+ */
+import type { JazariLayout } from './types.js';
+export interface LayoutState {
+    name: string;
+    isInitial?: boolean;
+    isTerminal?: boolean;
+    isFinal?: boolean;
+}
+export interface LayoutTransition {
+    from: string;
+    to: string;
+    event: string;
+    guard?: unknown;
+    effects?: unknown[];
+}
+export interface LayoutInput {
+    states: LayoutState[];
+    transitions: LayoutTransition[];
+    entityFields?: string[];
+    direction?: 'ltr' | 'rtl';
+}
+export declare function computeJazariLayout(input: LayoutInput): JazariLayout;

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;

package/dist/lib/jazari/types.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Shared types for the Al-Jazari state machine visualization.
+ * Pure TypeScript — zero React/DOM dependencies.
+ */
+/** Layout for a single gear (state node) */
+export interface JazariGearLayout {
+    /** State name */
+    name: string;
+    /** Center X coordinate */
+    cx: number;
+    /** Center Y coordinate */
+    cy: number;
+    /** Gear outer radius */
+    radius: number;
+    /** Whether this is the initial state */
+    isInitial: boolean;
+    /** Whether this is a terminal state */
+    isTerminal: boolean;
+}
+/** Guard info attached to an arm */
+export interface JazariGuardInfo {
+    /** Position X along the arm (30% point) */
+    x: number;
+    /** Position Y along the arm (30% point) */
+    y: number;
+    /** Whether this is an AI guard (call-service) vs deterministic */
+    isAI: boolean;
+}
+/** Effect info attached to an arm */
+export interface JazariEffectInfo {
+    /** Position X along the arm (70% point) */
+    x: number;
+    /** Position Y along the arm (70% point) */
+    y: number;
+    /** Number of effects */
+    count: number;
+    /** Effect labels for tooltip display */
+    names: string[];
+}
+/** Layout for a single transition arm */
+export interface JazariArmLayout {
+    /** Source state name */
+    from: string;
+    /** Target state name */
+    to: string;
+    /** Event name label */
+    event: string;
+    /** SVG path d attribute for the arm curve */
+    path: string;
+    /** Label position X (midpoint of arm) */
+    labelX: number;
+    /** Label position Y (midpoint of arm) */
+    labelY: number;
+    /** Guard info if transition has guards */
+    guard: JazariGuardInfo | null;
+    /** Effect info if transition has effects */
+    effect: JazariEffectInfo | null;
+    /** Whether this is a self-loop */
+    isSelfLoop: boolean;
+}
+/** Complete layout result for an entire state machine diagram */
+export interface JazariLayout {
+    /** Total SVG width */
+    width: number;
+    /** Total SVG height */
+    height: number;
+    /** All gear positions */
+    gears: JazariGearLayout[];
+    /** All transition arm paths */
+    arms: JazariArmLayout[];
+    /** Golden axis Y position */
+    axisY: number;
+    /** Golden axis start X */
+    axisStartX: number;
+    /** Golden axis end X */
+    axisEndX: number;
+    /** Entity field labels to display on the axis */
+    entityFields: string[];
+    /** Text direction */
+    direction: 'ltr' | 'rtl';
+}
+/** Al-Jazari color palette constants */
+export declare const JAZARI_COLORS: {
+    readonly brass: "#B87333";
+    readonly gold: "#C8A951";
+    readonly sky: "#0EA5E9";
+    readonly crimson: "#DC2626";
+    readonly lapis: "#1E40AF";
+    readonly ivory: "#FFFBEB";
+    readonly darkBg: "#1a1a2e";
+};