extended-dynamic-forms 0.2.0 → 0.3.0

package/dist/widgets/choice/ChoiceWidget.types.d.ts

@@ -0,0 +1,496 @@
+import { WidgetProps } from '@rjsf/utils';
+
+/**
+ * Presentation modes for the Choice Widget
+ */
+export declare enum PresentationMode {
+    /** Dropdown/Select presentation */
+    DROPDOWN = "dropdown",
+    /** Radio button presentation */
+    RADIO = "radio",
+    /** Checkbox presentation (multi-select) */
+    CHECKBOX = "checkbox"
+}
+/**
+ * Loading states for async data operations
+ */
+export interface LoadingState {
+    /** Whether the widget is currently loading */
+    isLoading: boolean;
+    /** Loading message to display to users */
+    message?: string;
+    /** Progress percentage (0-100) for long operations */
+    progress?: number;
+}
+/**
+ * Error states for data operations
+ */
+export interface ErrorState {
+    /** Whether an error has occurred */
+    hasError: boolean;
+    /** Error message to display to users */
+    message: string;
+    /** Error code for programmatic handling */
+    code?: string | number;
+    /** Stack trace for debugging (development only) */
+    stack?: string;
+    /** Whether the error is recoverable */
+    recoverable?: boolean;
+    /** Timestamp when the error occurred */
+    timestamp?: number;
+}
+/**
+ * Represents a single choice option
+ */
+export interface ChoiceOption {
+    /** Display text for the option */
+    label: string;
+    /** Value to be stored when selected */
+    value: string | number | boolean;
+    /** Whether this option is disabled */
+    disabled?: boolean;
+    /** Additional metadata for the option */
+    metadata?: {
+        /** Optional description or help text */
+        description?: string;
+        /** CSS class names for styling */
+        className?: string;
+        /** Icon identifier for display */
+        icon?: string;
+        /** Group or category identifier for organizing options */
+        group?: string;
+        /** Display order for sorting */
+        order?: number;
+        /** Additional data attributes */
+        data?: Record<string, unknown>;
+        /** Accessibility attributes */
+        a11y?: {
+            /** ARIA label for screen readers */
+            ariaLabel?: string;
+            /** ARIA description */
+            ariaDescription?: string;
+            /** Whether this option has a popup */
+            ariaHasPopup?: boolean;
+        };
+        /** Internal properties for system use */
+        _index?: number;
+        _active?: boolean;
+        _originalData?: any;
+    };
+}
+/**
+ * Configuration for static data sources
+ */
+export interface StaticDataSourceConfig {
+    /** Type identifier for static data source */
+    type: 'static';
+    /** Array of choice options */
+    options: ChoiceOption[];
+}
+/**
+ * HTTP method types for API requests
+ */
+export type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH';
+/**
+ * Response mapper function to transform API data into ChoiceOption[]
+ */
+export type ResponseMapper = (data: unknown) => ChoiceOption[];
+/**
+ * Built-in response mapper configurations
+ */
+export interface ResponseMapperConfig {
+    /** Type of built-in mapper */
+    type: 'simple' | 'nested' | 'custom';
+    /** Configuration for simple mapper */
+    simple?: {
+        /** Path to the array in response (e.g., 'data.items') */
+        arrayPath?: string;
+        /** Field name for label (default: 'label') */
+        labelField?: string;
+        /** Field name for value (default: 'value') */
+        valueField?: string;
+        /** Field name for disabled state (default: 'disabled') */
+        disabledField?: string;
+    };
+    /** Configuration for nested mapper */
+    nested?: {
+        /** Path to the array in response */
+        arrayPath: string;
+        /** Nested paths for extracting data */
+        paths: {
+            label: string;
+            value: string;
+            disabled?: string;
+            description?: string;
+        };
+    };
+    /** Custom mapper function */
+    custom?: ResponseMapper;
+}
+/**
+ * Cache configuration for API responses
+ */
+export interface CacheConfig {
+    /** Cache duration in milliseconds (default: 300000 = 5 minutes) */
+    ttl?: number;
+    /** Cache key for storage (auto-generated if not provided) */
+    key?: string;
+    /** Whether to use browser storage for persistence */
+    persistent?: boolean;
+    /** Cache storage type */
+    storageType?: 'memory' | 'sessionStorage' | 'localStorage';
+}
+/**
+ * Configuration for API data sources
+ */
+export interface ApiDataSourceConfig {
+    /** Type identifier for API data source */
+    type: 'api';
+    /** API endpoint URL */
+    url: string;
+    /** HTTP method (default: 'GET') */
+    method?: HttpMethod;
+    /** Request headers */
+    headers?: Record<string, string>;
+    /** Request body for POST/PUT/PATCH */
+    body?: unknown;
+    /** Query parameters */
+    params?: Record<string, string | number | boolean>;
+    /** Response mapper configuration */
+    responseMapper: ResponseMapperConfig;
+    /** Cache configuration */
+    cache?: CacheConfig;
+    /** Request timeout in milliseconds (default: 30000) */
+    timeout?: number;
+    /** Number of retry attempts on failure (default: 0) */
+    retries?: number;
+    /** Authentication configuration */
+    auth?: {
+        /** Authentication type */
+        type: 'bearer' | 'basic' | 'apiKey';
+        /** Token or credentials */
+        credentials: string | {
+            username: string;
+            password: string;
+        };
+        /** Header name for API key auth */
+        headerName?: string;
+    };
+}
+/**
+ * WebSocket message types for real-time communication
+ */
+export type WebSocketMessageType = 'options-update' | 'options-add' | 'options-remove' | 'options-patch' | 'search-request' | 'search-response' | 'connection-ready' | 'error' | 'heartbeat';
+/**
+ * WebSocket message structure
+ */
+export interface WebSocketMessage<T = unknown> {
+    /** Message type identifier */
+    type: WebSocketMessageType;
+    /** Message payload */
+    data?: T;
+    /** Unique message ID for correlation */
+    messageId?: string;
+    /** Timestamp when message was created */
+    timestamp?: number;
+    /** Error details for error messages */
+    error?: {
+        code: string;
+        message: string;
+        details?: unknown;
+    };
+}
+/**
+ * Configuration for WebSocket data sources
+ */
+export interface WebSocketDataSourceConfig {
+    /** Type identifier for WebSocket data source */
+    type: 'websocket';
+    /** WebSocket server URL */
+    url: string;
+    /** WebSocket protocols */
+    protocols?: string | string[];
+    /** Authentication configuration */
+    auth?: {
+        /** Authentication type */
+        type: 'bearer' | 'query' | 'header';
+        /** Token or credentials */
+        credentials: string;
+        /** Parameter/header name for auth */
+        paramName?: string;
+    };
+    /** Connection configuration */
+    connection?: {
+        /** Connection timeout in milliseconds (default: 30000) */
+        connectTimeout?: number;
+        /** Auto-reconnect on connection loss (default: true) */
+        autoReconnect?: boolean;
+        /** Max reconnection attempts (default: 5) */
+        maxReconnectAttempts?: number;
+        /** Reconnection delay in milliseconds (default: 1000) */
+        reconnectDelay?: number;
+        /** Heartbeat interval in milliseconds (default: 30000) */
+        heartbeatInterval?: number;
+        /** Response timeout for requests in milliseconds (default: 10000) */
+        responseTimeout?: number;
+    };
+    /** Message handling configuration */
+    messageHandling?: {
+        /** Whether to request initial options on connect (default: true) */
+        requestInitialOptions?: boolean;
+        /** Initial message to send after connection */
+        initialMessage?: WebSocketMessage;
+        /** Whether to enable real-time search (default: false) */
+        enableRealtimeSearch?: boolean;
+        /** Search debounce delay in milliseconds (default: 300) */
+        searchDebounceMs?: number;
+    };
+    /** Response transformation */
+    responseMapper?: ResponseMapperConfig;
+    /** Cache configuration (for offline support) */
+    cache?: CacheConfig;
+}
+/**
+ * Union type for all data source configurations
+ */
+export type DataSourceConfig = StaticDataSourceConfig | ApiDataSourceConfig | WebSocketDataSourceConfig;
+/**
+ * Validation configuration for selected values
+ */
+export interface ValidationConfig {
+    /** Custom validation function */
+    validator?: (value: unknown, options: ChoiceOption[]) => string | null;
+    /** Whether to validate on change (default: true) */
+    validateOnChange?: boolean;
+    /** Whether to validate on blur (default: true) */
+    validateOnBlur?: boolean;
+    /** Custom error messages */
+    messages?: {
+        required?: string;
+        invalid?: string;
+        custom?: string;
+    };
+}
+/**
+ * Search and filtering configuration
+ */
+export interface SearchConfig {
+    /** Whether search is enabled */
+    enabled: boolean;
+    /** Search placeholder text */
+    placeholder?: string;
+    /** Minimum characters before search activates */
+    minLength?: number;
+    /** Search debounce delay in milliseconds */
+    debounceMs?: number;
+    /** Whether search is case-sensitive */
+    caseSensitive?: boolean;
+    /** Fields to search in */
+    searchFields?: ('label' | 'value' | 'description')[];
+    /** Custom search function */
+    customFilter?: (option: ChoiceOption, searchTerm: string) => boolean;
+}
+/**
+ * Accessibility configuration
+ */
+export interface AccessibilityConfig {
+    /** ARIA label for the widget */
+    ariaLabel?: string;
+    /** ARIA description */
+    ariaDescription?: string;
+    /** Whether to announce changes to screen readers */
+    announceChanges?: boolean;
+    /** Custom ARIA attributes */
+    ariaAttributes?: Record<string, string>;
+    /** Keyboard navigation configuration */
+    keyboard?: {
+        /** Whether to enable arrow key navigation */
+        arrowKeys?: boolean;
+        /** Whether to enable type-ahead search */
+        typeAhead?: boolean;
+        /** Whether to enable home/end keys */
+        homeEnd?: boolean;
+    };
+}
+/**
+ * Main configuration interface for the Choice Widget
+ */
+export interface ChoiceWidgetConfig {
+    /** Presentation mode for the widget */
+    presentationMode?: PresentationMode;
+    /** Data source configuration */
+    dataSource?: DataSourceConfig;
+    /** Whether multiple selections are allowed */
+    multiple?: boolean;
+    /** Whether to allow clearing the selection */
+    allowClear?: boolean;
+    /** Placeholder text when no option is selected */
+    placeholder?: string;
+    /** Whether the widget is disabled */
+    disabled?: boolean;
+    /** Whether the widget is read-only */
+    readonly?: boolean;
+    /** Maximum number of selections (for multiple mode) */
+    maxSelections?: number;
+    /** Minimum number of selections (for multiple mode) */
+    minSelections?: number;
+    /** Search and filtering configuration */
+    search?: SearchConfig;
+    /** Validation configuration */
+    validation?: ValidationConfig;
+    /** Accessibility configuration */
+    accessibility?: AccessibilityConfig;
+    /** Custom CSS class names */
+    className?: string;
+    /** Custom inline styles */
+    style?: React.CSSProperties;
+    /** Size variant for Ant Design components */
+    size?: 'small' | 'middle' | 'large';
+    /** Whether to show option counts in multi-select */
+    showOptionCount?: boolean;
+    /** Custom loading component */
+    loadingComponent?: React.ComponentType<LoadingState>;
+    /** Custom error component */
+    errorComponent?: React.ComponentType<ErrorState>;
+    /** Custom empty state component */
+    emptyComponent?: React.ComponentType<{
+        message?: string;
+    }>;
+}
+/**
+ * Internal state interface for the Choice Widget
+ */
+export interface ChoiceWidgetState {
+    /** Available options */
+    options: ChoiceOption[];
+    /** Currently selected values */
+    selectedValues: (string | number | boolean)[];
+    /** Loading state */
+    loading: LoadingState;
+    /** Error state */
+    error: ErrorState;
+    /** Search term */
+    searchTerm: string;
+    /** Filtered options based on search */
+    filteredOptions: ChoiceOption[];
+    /** Whether the dropdown/menu is open */
+    isOpen: boolean;
+    /** Focused option index for keyboard navigation */
+    focusedOptionIndex: number;
+}
+/**
+ * Event handlers for the Choice Widget
+ */
+export interface ChoiceWidgetEventHandlers {
+    /** Called when selection changes */
+    onSelectionChange?: (values: (string | number | boolean)[], options: ChoiceOption[]) => void;
+    /** Called when search term changes */
+    onSearchChange?: (searchTerm: string) => void;
+    /** Called when widget receives focus */
+    onFocus?: (event: React.FocusEvent) => void;
+    /** Called when widget loses focus */
+    onBlur?: (event: React.FocusEvent) => void;
+    /** Called when dropdown opens */
+    onOpen?: () => void;
+    /** Called when dropdown closes */
+    onClose?: () => void;
+    /** Called when data loading starts */
+    onLoadingStart?: () => void;
+    /** Called when data loading completes */
+    onLoadingComplete?: (options: ChoiceOption[]) => void;
+    /** Called when an error occurs */
+    onError?: (error: ErrorState) => void;
+    /** Called when error is cleared */
+    onErrorClear?: () => void;
+}
+/**
+ * Props interface for the Choice Widget component
+ * Extends RJSF WidgetProps and adds Choice Widget specific properties
+ */
+export interface ChoiceWidgetProps extends WidgetProps {
+    /** Choice Widget configuration from ui:options */
+    options: WidgetProps['options'] & {
+        /** Choice Widget specific configuration */
+        choiceConfig?: ChoiceWidgetConfig;
+        /** Legacy support for enum options */
+        enumOptions?: {
+            label: string;
+            value: unknown;
+        }[];
+    };
+    /** Event handlers */
+    eventHandlers?: ChoiceWidgetEventHandlers;
+    /** Current widget state (for controlled usage) */
+    state?: Partial<ChoiceWidgetState>;
+    /** State change handler (for controlled usage) */
+    onStateChange?: (state: Partial<ChoiceWidgetState>) => void;
+}
+/**
+ * Data provider interface for abstracting data sources
+ */
+export interface ChoiceDataProvider {
+    /** Fetch options from the data source */
+    fetchOptions(): Promise<ChoiceOption[]>;
+    /** Whether this provider supports caching */
+    supportsCaching: boolean;
+    /** Whether this provider supports real-time updates */
+    supportsRealTime: boolean;
+    /** Cleanup resources */
+    cleanup(): void;
+}
+/**
+ * Cache interface for storing fetched data
+ */
+export interface ChoiceCache {
+    /** Get cached data */
+    get(key: string): ChoiceOption[] | null;
+    /** Set cached data */
+    set(key: string, data: ChoiceOption[], ttl?: number): void;
+    /** Clear specific cache entry */
+    clear(key: string): void;
+    /** Clear all cache entries */
+    clearAll(): void;
+    /** Check if cache entry exists and is valid */
+    has(key: string): boolean;
+}
+/**
+ * Strategy interface for different presentation modes
+ */
+export interface PresentationStrategy {
+    /** Render the widget */
+    render(props: ChoiceWidgetProps, state: ChoiceWidgetState): React.ReactElement;
+    /** Handle selection change */
+    handleSelectionChange(value: unknown, props: ChoiceWidgetProps, state: ChoiceWidgetState): (string | number | boolean)[];
+    /** Get default props for this presentation mode */
+    getDefaultProps(): Partial<ChoiceWidgetConfig>;
+    /** Validate props for this presentation mode */
+    validateProps(config: ChoiceWidgetConfig): string[] | null;
+}
+/**
+ * Type guard to check if a data source is static
+ */
+export declare function isStaticDataSource(dataSource: DataSourceConfig): dataSource is StaticDataSourceConfig;
+/**
+ * Type guard to check if a data source is API-based
+ */
+export declare function isApiDataSource(dataSource: DataSourceConfig): dataSource is ApiDataSourceConfig;
+/**
+ * Type guard to check if a data source is WebSocket-based
+ */
+export declare function isWebSocketDataSource(dataSource: DataSourceConfig): dataSource is WebSocketDataSourceConfig;
+/**
+ * Type guard to check if widget supports multiple selections
+ */
+export declare function supportsMultipleSelections(mode: PresentationMode): boolean;
+/**
+ * Default configuration values
+ */
+export declare const DEFAULT_CHOICE_CONFIG: Partial<ChoiceWidgetConfig>;
+/**
+ * Default cache configuration
+ */
+export declare const DEFAULT_CACHE_CONFIG: CacheConfig;
+/**
+ * Default response mapper for simple API responses
+ */
+export declare const DEFAULT_RESPONSE_MAPPER: ResponseMapperConfig;

package/dist/widgets/choice/examples/ChoiceWidget.example.d.ts

@@ -0,0 +1,7 @@
+import { default as React } from 'react';
+
+/**
+ * Main Examples Container
+ */
+declare const ChoiceWidgetExamples: React.FC;
+export default ChoiceWidgetExamples;

package/dist/widgets/choice/hooks/__tests__/useChoiceWidget.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/widgets/choice/hooks/__tests__/useDataSource.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/widgets/choice/hooks/examples/useChoiceWidget.example.d.ts

@@ -0,0 +1,18 @@
+import { default as React } from 'react';
+
+/**
+ * Example: Basic Choice Widget Hook Usage
+ */
+export declare const BasicChoiceWidgetExample: React.FC;
+/**
+ * Example: Choice Widget with Error Boundary
+ */
+export declare const ErrorBoundaryChoiceWidgetExample: React.FC;
+/**
+ * Example: Choice Widget with Performance Metrics
+ */
+export declare const PerformanceChoiceWidgetExample: React.FC;
+/**
+ * Example: Advanced Choice Widget Configuration
+ */
+export declare const AdvancedChoiceWidgetExample: React.FC;

package/dist/widgets/choice/hooks/examples/useDataSourceExample.d.ts

@@ -0,0 +1,22 @@
+import { default as React } from 'react';
+
+/**
+ * Example demonstrating basic useDataSource usage
+ */
+export declare const BasicDataSourceExample: React.FC;
+/**
+ * Example demonstrating API data source with dynamic configuration
+ */
+export declare const ApiDataSourceExample: React.FC;
+/**
+ * Example demonstrating retry functionality
+ */
+export declare const RetryDataSourceExample: React.FC;
+/**
+ * Example demonstrating WebSocket real-time updates
+ */
+export declare const WebSocketDataSourceExample: React.FC;
+/**
+ * Example demonstrating presentation mode switching
+ */
+export declare const PresentationModeSwitchExample: React.FC;

package/dist/widgets/choice/hooks/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * @module hooks
+ * @description React hooks for the Choice Widget
+ */
+export { useDataSource, useDataSourceWithRetry, useMultipleDataSources, type UseDataSourceReturn, } from './useDataSource';
+export { useChoiceWidget, useChoiceWidgetWithErrorBoundary, useChoiceWidgetWithMetrics, type UseChoiceWidgetReturn, } from './useChoiceWidget';

package/dist/widgets/choice/hooks/useChoiceWidget.d.ts

@@ -0,0 +1,65 @@
+import { default as React } from 'react';
+import { ChoiceWidgetProps, ChoiceWidgetState, ChoiceOption } from '../ChoiceWidget.types';
+import { PresenterStrategy } from '../presenters/PresenterStrategy';
+import { DataSourceMetrics } from '../providers/DataSourceProvider';
+
+/**
+ * Interface for the hook return value
+ */
+export interface UseChoiceWidgetReturn {
+    options: ChoiceOption[];
+    presenter: PresenterStrategy;
+    state: ChoiceWidgetState;
+    setState: (updates: Partial<ChoiceWidgetState>) => void;
+    value: unknown;
+    handleChange: (newValue: unknown) => void;
+    eventHandlers: {
+        onFocus: (event: React.FocusEvent) => void;
+        onBlur: (event: React.FocusEvent) => void;
+        onChange: (value: unknown) => void;
+        onSearch: (searchTerm: string) => void;
+    };
+    isMultiSelect: boolean;
+    isLoading: boolean;
+    hasError: boolean;
+    metrics: DataSourceMetrics;
+}
+/**
+ * Core business logic hook for Choice Widget
+ *
+ * This hook orchestrates all Choice Widget functionality including:
+ * - Data source management via useDataSource
+ * - Presenter strategy selection and coordination
+ * - Value transformation between widget and RJSF formats
+ * - Event system integration via FormEventHub
+ * - Schema-based behavior detection
+ * - Performance optimization with memoization
+ *
+ * @param props - RJSF-compatible widget props
+ * @returns Complete widget state and handlers
+ */
+export declare function useChoiceWidget(props: ChoiceWidgetProps): UseChoiceWidgetReturn;
+/**
+ * Hook for using Choice Widget with custom error handling
+ * Note: This hook catches runtime errors but not hook call errors.
+ * Hook call errors should be handled at the component level with Error Boundaries.
+ */
+export declare function useChoiceWidgetWithErrorBoundary(props: ChoiceWidgetProps, onError?: (error: Error) => void): UseChoiceWidgetReturn | {
+    error: Error;
+};
+/**
+ * Hook for using Choice Widget with performance monitoring
+ */
+export declare function useChoiceWidgetWithMetrics(props: ChoiceWidgetProps, onMetricsUpdate?: (metrics: DataSourceMetrics) => void): UseChoiceWidgetReturn & {
+    performanceMetrics: PerformanceMetrics;
+};
+/**
+ * Performance metrics interface
+ */
+interface PerformanceMetrics {
+    initialLoadTime: number;
+    renderCount: number;
+    averageRenderTime: number;
+    lastRenderTime: number;
+}
+export {};

package/dist/widgets/choice/hooks/useDataSource.d.ts

@@ -0,0 +1,69 @@
+import { DataSourceConfig, ChoiceOption, LoadingState, ErrorState } from '../ChoiceWidget.types';
+import { DataSourceEventCallbacks, DataSourceMetrics } from '../providers/DataSourceProvider';
+
+/**
+ * Hook return type for useDataSource
+ */
+export interface UseDataSourceReturn {
+    /** Available choice options */
+    options: ChoiceOption[];
+    /** Loading state information */
+    loading: LoadingState;
+    /** Error state information */
+    error: ErrorState;
+    /** Refetch data from the source (bypasses cache) */
+    refetch: () => Promise<void>;
+    /** Refresh data (uses cache if available) */
+    refresh: () => Promise<void>;
+    /** Update the data source configuration */
+    updateConfig: (config: DataSourceConfig) => void;
+    /** Performance metrics for monitoring */
+    metrics: DataSourceMetrics;
+    /** Whether the cached data is stale */
+    isStale: boolean;
+}
+/**
+ * Custom React hook for managing data source lifecycle
+ *
+ * Features:
+ * - Manages loading, success, and error states
+ * - Handles provider switching and configuration changes
+ * - Implements caching coordination with providers
+ * - Provides refetch and refresh capabilities
+ * - Prevents race conditions with request cancellation
+ * - Includes performance monitoring
+ * - Ensures proper cleanup on unmount
+ *
+ * @param config - Data source configuration
+ * @param eventCallbacks - Optional event callbacks for monitoring
+ * @returns Data source state and control functions
+ *
+ * @example
+ * ```tsx
+ * const { options, loading, error, refetch } = useDataSource({
+ *   type: 'api',
+ *   url: '/api/options',
+ *   responseMapper: { type: 'simple' }
+ * });
+ * ```
+ */
+export declare function useDataSource(config: DataSourceConfig, eventCallbacks?: DataSourceEventCallbacks): UseDataSourceReturn;
+/**
+ * Helper hook for managing data source with automatic error retry
+ *
+ * @param config - Data source configuration
+ * @param options - Hook options
+ * @returns Data source state with automatic retry
+ */
+export declare function useDataSourceWithRetry(config: DataSourceConfig, options?: {
+    maxRetries?: number;
+    retryDelayMs?: number;
+    onRetry?: (attempt: number, error: Error) => void;
+}): UseDataSourceReturn;
+/**
+ * Helper hook for managing multiple data sources
+ *
+ * @param configs - Array of data source configurations
+ * @returns Array of data source states
+ */
+export declare function useMultipleDataSources(configs: DataSourceConfig[]): UseDataSourceReturn[];