@almadar/ui 2.13.3 → 2.15.0

package/dist/renderer/useClientEffects.d.ts

@@ -0,0 +1,88 @@
+import type { ClientEffect, ClientEffectExecutorConfig } from './types';
+/**
+ * Options for the useClientEffects hook
+ */
+export interface UseClientEffectsOptions extends ClientEffectExecutorConfig {
+    /**
+     * Whether to execute effects. Defaults to true.
+     * Set to false to temporarily disable effect execution.
+     */
+    enabled?: boolean;
+    /**
+     * Debug mode - logs effect execution details.
+     */
+    debug?: boolean;
+}
+/**
+ * Result of useClientEffects hook
+ */
+export interface UseClientEffectsResult {
+    /**
+     * Number of effects executed in the last batch.
+     */
+    executedCount: number;
+    /**
+     * Whether effects are currently being executed.
+     */
+    executing: boolean;
+    /**
+     * Manually trigger effect execution.
+     * Useful for imperative control.
+     */
+    execute: (effects: ClientEffect[]) => void;
+}
+/**
+ * Execute client effects from server response.
+ *
+ * This hook automatically executes effects when they change,
+ * tracking which effects have been executed to prevent duplicates.
+ *
+ * @param effects - Array of client effects to execute (from server response)
+ * @param options - Configuration including effect implementations
+ * @returns Hook result with execution state and manual trigger
+ *
+ * @example
+ * ```typescript
+ * function useMyTrait() {
+ *   const [state, setState] = useState({ pendingEffects: [] });
+ *   const effectConfig = useClientEffectConfig();
+ *
+ *   useClientEffects(state.pendingEffects, {
+ *     ...effectConfig,
+ *     onComplete: () => setState(s => ({ ...s, pendingEffects: [] }))
+ *   });
+ *
+ *   // ...
+ * }
+ * ```
+ */
+export declare function useClientEffects(effects: ClientEffect[] | undefined, options: UseClientEffectsOptions): UseClientEffectsResult;
+declare const ClientEffectConfigContext: import("react").Context<ClientEffectExecutorConfig | null>;
+/**
+ * Provider for client effect configuration.
+ */
+export declare const ClientEffectConfigProvider: import("react").Provider<ClientEffectExecutorConfig | null>;
+/**
+ * Hook to get the client effect configuration from context.
+ *
+ * @throws Error if used outside of ClientEffectConfigProvider
+ *
+ * @example
+ * ```typescript
+ * function MyTraitHook() {
+ *   const effectConfig = useClientEffectConfig();
+ *
+ *   useClientEffects(pendingEffects, {
+ *     ...effectConfig,
+ *     onComplete: () => clearPendingEffects()
+ *   });
+ * }
+ * ```
+ */
+export declare function useClientEffectConfig(): ClientEffectExecutorConfig;
+/**
+ * Hook to get client effect configuration, returning null if not available.
+ * Use this for optional integration where effects may not be configured.
+ */
+export declare function useClientEffectConfigOptional(): ClientEffectExecutorConfig | null;
+export { ClientEffectConfigContext };

package/dist/runtime/EntitySchemaContext.d.ts

@@ -0,0 +1,40 @@
+/**
+ * EntitySchemaContext
+ *
+ * Minimal context providing entity schema definitions (field metadata).
+ * This is NOT a data store - data comes from FetchedDataContext via server.
+ *
+ * Replaces EntityStore's schema functionality without the mock data generation.
+ *
+ * @packageDocumentation
+ */
+import React from 'react';
+import type { ResolvedEntity } from '@almadar/core';
+export interface EntitySchemaContextValue {
+    /** Entity definitions (schema metadata only) */
+    entities: Map<string, ResolvedEntity>;
+}
+export interface EntitySchemaProviderProps {
+    /** Entity definitions from resolved schema */
+    entities: ResolvedEntity[];
+    /** Children */
+    children: React.ReactNode;
+}
+/**
+ * Provides entity schema definitions to the component tree.
+ *
+ * This is a lightweight provider that only holds schema metadata (field definitions).
+ * Actual entity data comes from FetchedDataContext via server responses.
+ */
+export declare function EntitySchemaProvider({ entities, children, }: EntitySchemaProviderProps): React.ReactElement;
+/**
+ * Access entity schema definitions.
+ * Use this for field metadata (form building, filter enrichment).
+ * For actual data, use useFetchedDataContext.
+ */
+export declare function useEntitySchema(): EntitySchemaContextValue;
+/**
+ * Get a specific entity's schema definition.
+ */
+export declare function useEntityDefinition(entityName: string): ResolvedEntity | undefined;
+export default EntitySchemaProvider;

package/dist/runtime/TraitProvider.d.ts

@@ -0,0 +1,52 @@
+/**
+ * TraitProvider Component
+ *
+ * Provides trait state machines to child components via React context.
+ *
+ * @packageDocumentation
+ */
+import React from 'react';
+import type { ResolvedTrait, ResolvedTraitBinding, ResolvedEntity } from './types';
+export interface TraitInstance {
+    /** Trait name */
+    name: string;
+    /** Current state */
+    currentState: string;
+    /** Available events (can be triggered) */
+    availableEvents: string[];
+    /** Dispatch an event to the state machine */
+    dispatch: (eventKey: string, payload?: Record<string, unknown>) => void;
+    /** Check if an event can be dispatched */
+    canDispatch: (eventKey: string) => boolean;
+    /** Get the full trait definition */
+    trait: ResolvedTrait;
+}
+export interface TraitContextValue {
+    /** All trait instances on this page */
+    traits: Map<string, TraitInstance>;
+    /** Get a trait instance by name */
+    getTrait: (name: string) => TraitInstance | undefined;
+    /** Dispatch an event to a specific trait */
+    dispatchToTrait: (traitName: string, eventKey: string, payload?: Record<string, unknown>) => void;
+    /** Check if an event can be dispatched to a trait */
+    canDispatch: (traitName: string, eventKey: string) => boolean;
+}
+export declare const TraitContext: React.Context<TraitContextValue | null>;
+export interface TraitProviderProps {
+    /** Trait bindings for this page */
+    traits: ResolvedTraitBinding[];
+    /** Entity map for context */
+    entities: Map<string, ResolvedEntity>;
+    /** Children to render */
+    children: React.ReactNode;
+}
+export declare function TraitProvider({ traits: traitBindings, children, }: TraitProviderProps): React.ReactElement;
+/**
+ * Access the trait context from within the TraitProvider.
+ */
+export declare function useTraitContext(): TraitContextValue;
+/**
+ * Access a specific trait instance.
+ */
+export declare function useTrait(traitName: string): TraitInstance | undefined;
+export default TraitProvider;

package/dist/runtime/createClientEffectHandlers.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Client Effect Handlers Factory
+ *
+ * Creates the standard effect handler set for client-side trait execution.
+ *
+ * @packageDocumentation
+ */
+import type { EffectHandlers } from '@almadar/runtime';
+export interface ClientEventBus {
+    emit: (type: string, payload?: Record<string, unknown>) => void;
+}
+export interface SlotSetter {
+    addPattern: (slot: string, pattern: unknown, props?: Record<string, unknown>) => void;
+    clearSlot: (slot: string) => void;
+}
+export interface CreateClientEffectHandlersOptions {
+    eventBus: ClientEventBus;
+    slotSetter: SlotSetter;
+    navigate?: (path: string, params?: Record<string, unknown>) => void;
+    notify?: (message: string, type: 'success' | 'error' | 'warning' | 'info') => void;
+    enrichPattern?: (pattern: unknown) => unknown;
+}
+export declare function createClientEffectHandlers(options: CreateClientEffectHandlersOptions): EffectHandlers;