extended-dynamic-forms 0.2.0 → 0.3.0

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

@@ -0,0 +1,59 @@
+import { ChoiceWidgetConfig, PresentationMode } from './ChoiceWidget.types';
+export * from './ChoiceWidget.types';
+export { isStaticDataSource, isApiDataSource, supportsMultipleSelections, DEFAULT_CHOICE_CONFIG, DEFAULT_CACHE_CONFIG, DEFAULT_RESPONSE_MAPPER, } from './ChoiceWidget.types';
+export { DataSourceProvider, DEFAULT_RETRY_CONFIG, createSimpleHash, validateChoiceOptions, } from './providers/DataSourceProvider';
+export type { RetryConfig, DataSourceMetrics, DataSourceEventCallbacks, } from './providers/DataSourceProvider';
+export { StaticDataSource, createStaticDataSource, hasGroup, createGroupedOptions, } from './providers/StaticDataSource';
+export type { StaticDataSourceOptions } from './providers/StaticDataSource';
+export { ApiDataSource, createApiDataSource, COMMON_RESPONSE_MAPPERS, AUTH_HELPERS, } from './providers/ApiDataSource';
+export { WebSocketDataSource, createWebSocketDataSource, WebSocketConnectionState, WS_AUTH_HELPERS, WS_MESSAGE_HELPERS, } from './providers/WebSocketDataSource';
+export type { WebSocketDataSourceOptions, } from './providers/WebSocketDataSource';
+export { validateChoiceOption, getNestedValue, setNestedValue, extractArrayFromResponse, mapSimpleResponse, mapNestedResponse, createCustomMapper, mapResponse, ResponseMappingError, COMMON_MAPPERS, PAGINATED_MAPPERS, createActiveMapper, createMapperPipeline, filterEnabledOptions, sortByLabel, sortByValue, groupOptions, transformOptions, } from './utils/responseMappers';
+export { PresenterStrategy } from './presenters/PresenterStrategy';
+export { DropdownPresenter } from './presenters/DropdownPresenter';
+export { RadioPresenter } from './presenters/RadioPresenter';
+export { CheckboxPresenter } from './presenters/CheckboxPresenter';
+export { useDataSource, useDataSourceWithRetry, useMultipleDataSources, } from './hooks';
+export { useChoiceWidget, useChoiceWidgetWithErrorBoundary, useChoiceWidgetWithMetrics, } from './hooks/useChoiceWidget';
+export type { UseChoiceWidgetReturn } from './hooks/useChoiceWidget';
+export type { UseDataSourceReturn } from './hooks';
+export { ChoiceWidget, default as DefaultChoiceWidget } from './ChoiceWidget';
+/**
+ * Factory function to create a default ChoiceWidgetConfig
+ */
+export declare const createDefaultConfig: (overrides?: Partial<ChoiceWidgetConfig>) => ChoiceWidgetConfig;
+/**
+ * Presentation mode helper
+ * Determines the best presentation mode based on options count and schema
+ */
+export declare const suggestPresentationMode: (optionCount: number, isMultiSelect?: boolean, preferences?: {
+    preferRadio?: boolean;
+    preferDropdown?: boolean;
+}) => PresentationMode;
+/**
+ * Legacy compatibility helper
+ * Converts legacy enumOptions format to ChoiceWidgetConfig
+ */
+export declare const convertLegacyConfig: (enumOptions: Array<{
+    label: string;
+    value: unknown;
+}>, uiOptions?: Record<string, unknown>) => ChoiceWidgetConfig;
+/**
+ * Widget registration helper for RJSF
+ * Simplifies registering the Choice Widget with RJSF forms
+ */
+export declare const createChoiceWidgetRegistry: (customConfig?: Partial<ChoiceWidgetConfig>) => {
+    widgets: {
+        choice: import('react').FC<import('./ChoiceWidget.types').ChoiceWidgetProps>;
+        ChoiceWidget: import('react').FC<import('./ChoiceWidget.types').ChoiceWidgetProps>;
+        select: import('react').FC<import('./ChoiceWidget.types').ChoiceWidgetProps>;
+        radio: import('react').FC<import('./ChoiceWidget.types').ChoiceWidgetProps>;
+        checkboxes: import('react').FC<import('./ChoiceWidget.types').ChoiceWidgetProps>;
+    };
+    uiSchema: {
+        'ui:widget': string;
+        'ui:options': {
+            choiceConfig: ChoiceWidgetConfig;
+        };
+    };
+};

package/dist/widgets/choice/presenters/CheckboxPresenter.d.ts

@@ -0,0 +1,70 @@
+import { default as React } from 'react';
+import { PresenterStrategy } from './PresenterStrategy';
+import { ChoiceWidgetProps, ChoiceWidgetState, ChoiceWidgetConfig, PresentationMode } from '../ChoiceWidget.types';
+
+/**
+ * Checkbox presenter configuration
+ */
+export interface CheckboxPresenterConfig {
+    /** Enable/disable select all functionality */
+    showSelectAll?: boolean;
+    /** Label for select all checkbox */
+    selectAllLabel?: string;
+    /** Layout mode: 'vertical' | 'horizontal' | 'grid' */
+    layout?: 'vertical' | 'horizontal' | 'grid';
+    /** Number of columns for grid layout */
+    columns?: number;
+    /** Responsive column configuration */
+    responsive?: {
+        xs?: number;
+        sm?: number;
+        md?: number;
+        lg?: number;
+        xl?: number;
+        xxl?: number;
+    };
+    /** Space between checkboxes */
+    spacing?: number;
+    /** Enable bulk operations (select all, clear, invert) */
+    enableBulkOperations?: boolean;
+    /** Custom bulk operation labels */
+    bulkOperationLabels?: {
+        selectAll?: string;
+        clearAll?: string;
+        invertSelection?: string;
+    };
+}
+/**
+ * Checkbox-based presenter strategy for multi-select choice widgets
+ *
+ * Features:
+ * - Ant Design Checkbox.Group integration
+ * - "Select All" with indeterminate states
+ * - Grid layout support with responsive columns
+ * - Individual checkbox disabled states
+ * - Bulk selection operations
+ * - Comprehensive accessibility support
+ */
+export declare class CheckboxPresenter extends PresenterStrategy {
+    readonly presentationMode = PresentationMode.CHECKBOX;
+    /**
+     * Render the checkbox widget using CheckboxWidget component.
+     */
+    render(props: ChoiceWidgetProps, state: ChoiceWidgetState): React.ReactElement;
+    /**
+     * Handle selection change from Checkbox.Group component.
+     */
+    handleSelectionChange(value: unknown, _props: ChoiceWidgetProps, _state: ChoiceWidgetState): (string | number | boolean)[];
+    /**
+     * Get default configuration for checkbox presentation.
+     */
+    getDefaultProps(): Partial<ChoiceWidgetConfig>;
+    /**
+     * Validate checkbox-specific configuration.
+     */
+    validateProps(config: ChoiceWidgetConfig): string[] | null;
+    /**
+     * Get the appropriate ARIA role for checkbox presentation.
+     */
+    protected getAriaRole(): string;
+}

package/dist/widgets/choice/presenters/DropdownPresenter.d.ts

@@ -0,0 +1,37 @@
+import { default as React } from 'react';
+import { ChoiceWidgetProps, ChoiceWidgetState, ChoiceWidgetConfig, PresentationMode } from '../ChoiceWidget.types';
+import { PresenterStrategy } from './PresenterStrategy';
+
+/**
+ * Dropdown presenter implementation using Ant Design Select component.
+ * Provides a dropdown/select UI with support for single and multi-select modes,
+ * search functionality, virtual scrolling for large datasets, and full accessibility.
+ *
+ * @class DropdownPresenter
+ * @extends {PresenterStrategy}
+ */
+export declare class DropdownPresenter extends PresenterStrategy {
+    readonly presentationMode = PresentationMode.DROPDOWN;
+    /**
+     * Render the dropdown widget using Ant Design Select.
+     */
+    render(props: ChoiceWidgetProps, state: ChoiceWidgetState): React.ReactElement;
+    /**
+     * Handle selection change from Select component.
+     * Normalizes the value(s) for consistent handling.
+     */
+    handleSelectionChange(value: unknown, props: ChoiceWidgetProps, _state: ChoiceWidgetState): (string | number | boolean)[];
+    /**
+     * Get default configuration for dropdown presentation.
+     */
+    getDefaultProps(): Partial<ChoiceWidgetConfig>;
+    /**
+     * Validate dropdown-specific configuration.
+     */
+    validateProps(config: ChoiceWidgetConfig): string[] | null;
+    /**
+     * Get the ARIA role for dropdown presentation.
+     */
+    protected getAriaRole(): string;
+}
+export default DropdownPresenter;

package/dist/widgets/choice/presenters/PresenterStrategy.d.ts

@@ -0,0 +1,230 @@
+import { default as React } from 'react';
+import { ChoiceWidgetProps, ChoiceWidgetState, ChoiceWidgetConfig, ChoiceOption, AccessibilityConfig, ErrorState, LoadingState, PresentationMode } from '../ChoiceWidget.types';
+
+/**
+ * Abstract base class for Choice Widget presentation strategies.
+ * Implements the Strategy Pattern to support different presentation modes
+ * (dropdown, radio, checkbox) while maintaining consistent behavior,
+ * accessibility standards, and event handling.
+ *
+ * @abstract
+ * @class PresenterStrategy
+ */
+export declare abstract class PresenterStrategy {
+    /**
+     * The presentation mode this strategy implements
+     */
+    abstract readonly presentationMode: PresentationMode;
+    /**
+     * Render the widget UI according to the specific presentation strategy.
+     * Must integrate with FormEventHub and maintain accessibility standards.
+     *
+     * @param props - The widget props including RJSF props and custom configuration
+     * @param state - The current widget state including options and selection
+     * @returns React element representing the widget
+     */
+    abstract render(props: ChoiceWidgetProps, state: ChoiceWidgetState): React.ReactElement;
+    /**
+     * Handle selection change events and transform values appropriately.
+     * Must support both single and multi-select scenarios.
+     *
+     * @param value - The new value(s) from the UI component
+     * @param props - The widget props
+     * @param state - The current widget state
+     * @returns Array of selected values (normalized)
+     */
+    abstract handleSelectionChange(value: unknown, props: ChoiceWidgetProps, state: ChoiceWidgetState): (string | number | boolean)[];
+    /**
+     * Get default configuration specific to this presentation mode.
+     *
+     * @returns Partial configuration with mode-specific defaults
+     */
+    abstract getDefaultProps(): Partial<ChoiceWidgetConfig>;
+    /**
+     * Validate configuration for this specific presentation mode.
+     *
+     * @param config - The widget configuration to validate
+     * @returns Array of validation error messages, or null if valid
+     */
+    abstract validateProps(config: ChoiceWidgetConfig): string[] | null;
+    /**
+     * Generate accessibility properties for the widget.
+     * Ensures WCAG 2.1 AA compliance.
+     *
+     * @param props - The widget props
+     * @param state - The current widget state
+     * @param config - Accessibility configuration
+     * @returns Object containing ARIA attributes
+     */
+    getAccessibilityProps(props: ChoiceWidgetProps, state: ChoiceWidgetState, config?: AccessibilityConfig): Record<string, string | boolean | number>;
+    /**
+     * Get the appropriate ARIA role for this presentation mode.
+     *
+     * @returns The ARIA role string
+     */
+    protected abstract getAriaRole(): string;
+    /**
+     * Handle keyboard navigation events.
+     * Supports arrow keys, home/end, and type-ahead functionality.
+     *
+     * @param event - The keyboard event
+     * @param props - The widget props
+     * @param state - The current widget state
+     * @param callbacks - Callback functions for state updates
+     */
+    handleKeyboardNavigation(event: React.KeyboardEvent, props: ChoiceWidgetProps, state: ChoiceWidgetState, callbacks: {
+        setFocusedIndex: (index: number) => void;
+        selectOption: (option: ChoiceOption) => void;
+        toggleDropdown?: (open: boolean) => void;
+    }): void;
+    /**
+     * Handle type-ahead search functionality.
+     *
+     * @param char - The typed character
+     * @param state - The current widget state
+     * @param callbacks - Callback functions
+     */
+    private handleTypeAhead;
+    /**
+     * Generate props for the loading state display.
+     *
+     * @param loading - The loading state
+     * @param LoadingComponent - Optional custom loading component
+     * @returns Props for the loading display
+     */
+    getLoadingProps(loading: LoadingState, LoadingComponent?: React.ComponentType<LoadingState>): {
+        component: React.ComponentType<LoadingState>;
+        props: LoadingState;
+    };
+    /**
+     * Generate props for the error state display.
+     *
+     * @param error - The error state
+     * @param ErrorComponent - Optional custom error component
+     * @param fieldId - The field ID for accessibility
+     * @returns Props for the error display
+     */
+    getErrorProps(error: ErrorState, ErrorComponent?: React.ComponentType<ErrorState>, fieldId?: string): {
+        component: React.ComponentType<ErrorState>;
+        props: ErrorState & {
+            id?: string;
+        };
+    };
+    /**
+     * Generate props for the empty state display.
+     *
+     * @param message - Optional message for empty state
+     * @param EmptyComponent - Optional custom empty component
+     * @returns Props for the empty display
+     */
+    getEmptyProps(message?: string, EmptyComponent?: React.ComponentType<{
+        message?: string;
+    }>): {
+        component: React.ComponentType<{
+            message?: string;
+        }>;
+        props: {
+            message?: string;
+        };
+    };
+    /**
+     * Transform and normalize values between widget and form data.
+     * Handles both single and multi-select scenarios.
+     *
+     * @param value - The value to transform
+     * @param multiple - Whether multiple selections are allowed
+     * @returns Normalized value(s)
+     */
+    normalizeValue(value: unknown, multiple: boolean): (string | number | boolean)[];
+    /**
+     * Transform normalized values back to widget format.
+     *
+     * @param values - The normalized values
+     * @param multiple - Whether multiple selections are allowed
+     * @returns Value in widget format
+     */
+    denormalizeValue(values: (string | number | boolean)[], multiple: boolean): unknown;
+    /**
+     * Apply theme and custom styling to the widget.
+     * Integrates with Ant Design v5 theming system.
+     *
+     * @param config - Widget configuration
+     * @param additionalClasses - Additional CSS classes
+     * @returns Combined className string
+     */
+    getThemeClasses(config: ChoiceWidgetConfig, additionalClasses?: string): string;
+    /**
+     * Get style object with theme integration.
+     *
+     * @param config - Widget configuration
+     * @param additionalStyles - Additional styles
+     * @returns Combined style object
+     */
+    getThemeStyles(config: ChoiceWidgetConfig, additionalStyles?: React.CSSProperties): React.CSSProperties;
+    /**
+     * Default loading component implementation.
+     */
+    protected DefaultLoadingComponent: React.FC<LoadingState>;
+    /**
+     * Default error component implementation.
+     */
+    protected DefaultErrorComponent: React.FC<ErrorState & {
+        id?: string;
+    }>;
+    /**
+     * Default empty component implementation.
+     */
+    protected DefaultEmptyComponent: React.FC<{
+        message?: string;
+    }>;
+    /**
+     * Create event handlers integrated with FormEventHub.
+     * This method helps concrete strategies integrate with the central event system.
+     *
+     * @param fieldId - The field identifier
+     * @param schema - The field schema
+     * @param formData - The current form data
+     * @param fieldPath - The field path in the form
+     * @returns Object with event handler methods
+     */
+    protected createEventHandlers(fieldId: string, schema?: any, formData?: any, fieldPath?: string[]): {
+        fieldId: string;
+        schema: any;
+        formData: any;
+        fieldPath: string[] | undefined;
+        _hookRequired: true;
+    };
+    /**
+     * Validate option selection against configured rules.
+     *
+     * @param values - Selected values
+     * @param options - Available options
+     * @param config - Widget configuration
+     * @returns Validation error message or null if valid
+     */
+    validateSelection(values: (string | number | boolean)[], options: ChoiceOption[], config: ChoiceWidgetConfig): string | null;
+    /**
+     * Get size mapping for Ant Design components.
+     *
+     * @param size - The size configuration
+     * @returns Ant Design size value
+     */
+    protected getAntdSize(size?: 'small' | 'middle' | 'large'): 'small' | 'middle' | 'large';
+    /**
+     * Check if a value is selected.
+     *
+     * @param value - The value to check
+     * @param selectedValues - Currently selected values
+     * @returns Whether the value is selected
+     */
+    protected isSelected(value: string | number | boolean, selectedValues: (string | number | boolean)[]): boolean;
+    /**
+     * Filter options based on search configuration.
+     *
+     * @param options - All available options
+     * @param searchTerm - The search term
+     * @param searchConfig - Search configuration
+     * @returns Filtered options
+     */
+    protected filterOptions(options: ChoiceOption[], searchTerm: string, searchConfig?: ChoiceWidgetConfig['search']): ChoiceOption[];
+}

package/dist/widgets/choice/presenters/RadioPresenter.d.ts

@@ -0,0 +1,39 @@
+import { default as React } from 'react';
+import { ChoiceWidgetProps, ChoiceWidgetState, ChoiceWidgetConfig, PresentationMode } from '../ChoiceWidget.types';
+import { PresenterStrategy } from './PresenterStrategy';
+
+/**
+ * Radio presenter implementation using Ant Design Radio.Group component.
+ * Provides a radio button UI with support for single selection only,
+ * vertical and horizontal layouts, custom option rendering, and full accessibility.
+ *
+ * Radio groups are inherently single-select, making them ideal for mutually exclusive choices.
+ *
+ * @class RadioPresenter
+ * @extends {PresenterStrategy}
+ */
+export declare class RadioPresenter extends PresenterStrategy {
+    readonly presentationMode = PresentationMode.RADIO;
+    /**
+     * Render the radio widget using Ant Design Radio.Group.
+     */
+    render(props: ChoiceWidgetProps, state: ChoiceWidgetState): React.ReactElement;
+    /**
+     * Handle selection change from Radio.Group component.
+     * Radio groups only support single selection.
+     */
+    handleSelectionChange(value: unknown): (string | number | boolean)[];
+    /**
+     * Get default configuration for radio presentation.
+     */
+    getDefaultProps(): Partial<ChoiceWidgetConfig>;
+    /**
+     * Validate radio-specific configuration.
+     */
+    validateProps(config: ChoiceWidgetConfig): string[] | null;
+    /**
+     * Get the ARIA role for radio presentation.
+     */
+    protected getAriaRole(): string;
+}
+export default RadioPresenter;

package/dist/widgets/choice/presenters/examples/RadioPresenterExample.d.ts

@@ -0,0 +1,7 @@
+import { default as React } from 'react';
+
+/**
+ * Example demonstrating RadioPresenter usage with various configurations
+ */
+export declare const RadioPresenterExample: React.FC;
+export default RadioPresenterExample;

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

@@ -0,0 +1,20 @@
+import { PresentationMode } from '../ChoiceWidget.types';
+import { PresenterStrategy } from './PresenterStrategy';
+/**
+ * Choice Widget Presenter Strategy Exports
+ *
+ * This module implements the Strategy Pattern for different presentation modes
+ * of the Choice Widget (dropdown, radio, checkbox).
+ */
+export { PresenterStrategy } from './PresenterStrategy';
+export { DropdownPresenter } from './DropdownPresenter';
+export { RadioPresenter } from './RadioPresenter';
+export { CheckboxPresenter } from './CheckboxPresenter';
+/**
+ * Presenter factory function to create the appropriate presenter
+ * based on the presentation mode.
+ *
+ * @param mode - The presentation mode
+ * @returns The appropriate presenter instance
+ */
+export declare function createPresenter(mode: PresentationMode): PresenterStrategy;