@nuraly/lumenui 0.2.1 → 0.2.2

package/dist/src/components/radio-group/controllers/ripple.controller.d.ts

@@ -0,0 +1,59 @@
+/**
+ * @license
+ * Copyright 2023 Nuraly, Laabidi Aymen
+ * SPDX-License-Identifier: MIT
+ */
+import { ReactiveControllerHost } from 'lit';
+import { RippleController } from '../interfaces/ripple-controller.interface.js';
+/**
+ * Controller that manages ripple effects for radio interactions
+ * Implements performance optimizations with debouncing and throttling
+ *
+ * @example
+ * ```typescript
+ * const controller = new RadioRippleController(hostElement);
+ * controller.addRippleEffect(clickEvent); // Throttled for performance
+ * ```
+ */
+export declare class RadioRippleController implements RippleController {
+    readonly host: ReactiveControllerHost;
+    private _rippleEnabled;
+    private boundClickHandler;
+    private activeRipples;
+    private ripplePool;
+    constructor(host: ReactiveControllerHost);
+    hostConnected(): void;
+    hostDisconnected(): void;
+    get rippleEnabled(): boolean;
+    set rippleEnabled(value: boolean);
+    private handleClick;
+    addRippleEffect(event: Event): void;
+    addRippleToElement(target: HTMLElement): void;
+    private addButtonRippleEffect;
+    private createRippleElement;
+    private parseDuration;
+    triggerRipple(optionValue?: string): void;
+    disableRipple(): void;
+    enableRipple(): void;
+    /**
+     * Clear all active ripple effects for performance
+     * Implements object pooling for memory efficiency
+     */
+    clearRipples(): void;
+    /**
+     * Get a ripple element from pool or create new one
+     * Improves performance by reusing DOM elements
+     */
+    private getRippleElement;
+    /**
+     * Add ripple effect to a specific element (interface method)
+     * @param element - The element to add ripple effect to
+     */
+    addRippleEffectToElement(element: HTMLElement): void;
+    /**
+     * Set whether ripple effects are enabled (interface method)
+     * @param enabled - True to enable ripple effects
+     */
+    setRippleEnabled(enabled: boolean): void;
+}
+//# sourceMappingURL=ripple.controller.d.ts.map

package/dist/src/components/radio-group/controllers/ripple.controller.js

@@ -0,0 +1,208 @@
+/**
+ * @license
+ * Copyright 2023 Nuraly, Laabidi Aymen
+ * SPDX-License-Identifier: MIT
+ */
+import { throttle } from '@nuralyui/common/utils';
+/**
+ * Controller that manages ripple effects for radio interactions
+ * Implements performance optimizations with debouncing and throttling
+ *
+ * @example
+ * ```typescript
+ * const controller = new RadioRippleController(hostElement);
+ * controller.addRippleEffect(clickEvent); // Throttled for performance
+ * ```
+ */
+export class RadioRippleController {
+    constructor(host) {
+        this._rippleEnabled = true;
+        this.activeRipples = new Set();
+        this.ripplePool = []; // Object pooling for performance
+        this.host = host;
+        this.boundClickHandler = this.handleClick.bind(this);
+        host.addController(this);
+        // Create throttled version of addRippleEffect for performance (60fps)
+        const originalAddRippleEffect = this.addRippleEffect.bind(this);
+        this.addRippleEffect = throttle(originalAddRippleEffect, 16);
+    }
+    hostConnected() {
+        this.host.addEventListener('click', this.boundClickHandler);
+    }
+    hostDisconnected() {
+        this.host.removeEventListener('click', this.boundClickHandler);
+    }
+    // Getters and setters
+    get rippleEnabled() {
+        return this._rippleEnabled;
+    }
+    set rippleEnabled(value) {
+        this._rippleEnabled = value;
+    }
+    // Event handler
+    handleClick(event) {
+        if (!this._rippleEnabled)
+            return;
+        const target = event.target;
+        // Handle ripple for radio inputs
+        if (target && target.matches('input[type="radio"]')) {
+            this.addRippleToElement(target);
+        }
+        // Handle ripple for button-style radios (if needed)
+        if (target && target.matches('nr-button[role="radio"]')) {
+            this.addButtonRippleEffect(target);
+        }
+    }
+    // Public method for event-based ripple
+    addRippleEffect(event) {
+        const target = event.target;
+        if (target) {
+            this.addRippleToElement(target);
+        }
+    }
+    // Add ripple effect to radio input element  
+    addRippleToElement(target) {
+        // Remove any existing ripple animation
+        target.style.animation = 'none';
+        // Force reflow to ensure animation is cleared
+        target.getAnimations();
+        // Add ripple animation using CSS custom properties
+        const duration = getComputedStyle(target).getPropertyValue('--nuraly-radio-ripple-duration') ||
+            getComputedStyle(target).getPropertyValue('--nuraly-radio-local-ripple-duration') ||
+            '300ms';
+        target.style.animation = `radioRipple ${duration} ease-out`;
+        // Clean up animation after completion
+        const animationDuration = this.parseDuration(duration);
+        setTimeout(() => {
+            target.style.animation = '';
+        }, animationDuration);
+    }
+    // Add ripple effect to button-style radio
+    addButtonRippleEffect(target) {
+        // For button-style radios, we can trigger the button's own ripple effect
+        // or create a custom one
+        const rippleElement = this.createRippleElement(target);
+        if (rippleElement) {
+            target.appendChild(rippleElement);
+            // Remove ripple element after animation
+            setTimeout(() => {
+                if (rippleElement.parentNode) {
+                    rippleElement.parentNode.removeChild(rippleElement);
+                }
+            }, 600);
+        }
+    }
+    // Create ripple element for manual ripple effects (uses object pooling)
+    createRippleElement(container) {
+        const ripple = this.getRippleElement(container);
+        ripple.style.animation = 'radioRippleSpread 600ms ease-out';
+        return ripple;
+    }
+    // Parse CSS duration string to milliseconds
+    parseDuration(duration) {
+        const match = duration.match(/^([\d.]+)(s|ms)$/);
+        if (!match)
+            return 300;
+        const value = Number.parseFloat(match[1]);
+        const unit = match[2];
+        return unit === 's' ? value * 1000 : value;
+    }
+    // Programmatic ripple trigger
+    triggerRipple(optionValue) {
+        if (!this._rippleEnabled)
+            return;
+        const host = this.host;
+        const shadowRoot = host.shadowRoot;
+        if (!shadowRoot)
+            return;
+        let target = null;
+        if (optionValue) {
+            // Find specific radio input by value
+            target = shadowRoot.querySelector(`input[type="radio"][value="${optionValue}"]`);
+        }
+        else {
+            // Find selected radio input
+            target = shadowRoot.querySelector('input[type="radio"]:checked');
+        }
+        if (target) {
+            this.addRippleToElement(target);
+        }
+    }
+    // Disable ripple effects
+    disableRipple() {
+        this._rippleEnabled = false;
+    }
+    // Enable ripple effects
+    enableRipple() {
+        this._rippleEnabled = true;
+    }
+    /**
+     * Clear all active ripple effects for performance
+     * Implements object pooling for memory efficiency
+     */
+    clearRipples() {
+        // Clear all active ripples and return elements to pool
+        this.activeRipples.forEach(ripple => {
+            if (ripple.parentNode) {
+                ripple.parentNode.removeChild(ripple);
+            }
+            // Return to pool for reuse
+            if (this.ripplePool.length < 10) { // Limit pool size
+                ripple.style.animation = '';
+                ripple.style.transform = 'scale(0)';
+                this.ripplePool.push(ripple);
+            }
+        });
+        this.activeRipples.clear();
+        // Clear any CSS animations on radio inputs
+        const host = this.host;
+        const shadowRoot = host.shadowRoot;
+        if (shadowRoot) {
+            const radioInputs = shadowRoot.querySelectorAll('input[type="radio"]');
+            radioInputs.forEach((input) => {
+                input.style.animation = '';
+            });
+        }
+    }
+    /**
+     * Get a ripple element from pool or create new one
+     * Improves performance by reusing DOM elements
+     */
+    getRippleElement(container) {
+        let ripple = this.ripplePool.pop();
+        if (!ripple) {
+            ripple = document.createElement('span');
+            ripple.className = 'radio-ripple';
+            ripple.style.position = 'absolute';
+            ripple.style.borderRadius = '50%';
+            ripple.style.background = 'currentColor';
+            ripple.style.opacity = '0.1';
+            ripple.style.pointerEvents = 'none';
+        }
+        // Calculate ripple size and position
+        const rect = container.getBoundingClientRect();
+        const size = Math.max(rect.width, rect.height);
+        ripple.style.width = `${size}px`;
+        ripple.style.height = `${size}px`;
+        ripple.style.left = `${-size / 2}px`;
+        ripple.style.top = `${-size / 2}px`;
+        ripple.style.transform = 'scale(0)';
+        this.activeRipples.add(ripple);
+        return ripple;
+    }
+    /**
+     * Add ripple effect to a specific element (interface method)
+     * @param element - The element to add ripple effect to
+     */
+    addRippleEffectToElement(element) {
+        this.addRippleToElement(element);
+    }
+    /**
+     * Set whether ripple effects are enabled (interface method)
+     * @param enabled - True to enable ripple effects
+     */
+    setRippleEnabled(enabled) {
+        this._rippleEnabled = enabled;
+    }
+}
+//# sourceMappingURL=ripple.controller.js.map

package/dist/src/components/radio-group/controllers/validation.controller.d.ts

@@ -0,0 +1,73 @@
+/**
+ * @license
+ * Copyright 2023 Nuraly, Laabidi Aymen
+ * SPDX-License-Identifier: MIT
+ */
+import { ReactiveControllerHost } from 'lit';
+import { BaseValidationController } from '@nuralyui/common/controllers';
+import { ValidationController } from '../interfaces/validation-controller.interface.js';
+/**
+ * Host interface for radio group validation
+ */
+interface RadioGroupValidationHost extends ReactiveControllerHost {
+    required: boolean;
+    value: string;
+    name: string;
+    requestUpdate(): void;
+    dispatchEvent(event: Event): boolean;
+}
+/**
+ * Controller that manages validation logic and form integration for radio groups
+ * Implements HTML5 form validation patterns with custom validation support
+ *
+ * Features:
+ * - Required field validation
+ * - Custom validation message support
+ * - Form integration with native validation API
+ * - Real-time validation state tracking
+ *
+ * @example
+ * ```typescript
+ * const controller = new RadioValidationController(hostElement);
+ * const isValid = controller.validate(); // Validate current state
+ * console.log(controller.validationMessage); // Get validation error
+ * ```
+ */
+export declare class RadioValidationController extends BaseValidationController<RadioGroupValidationHost> implements ValidationController {
+    /**
+     * Validates the current radio group state
+     * Checks required field constraints and custom validation rules
+     *
+     * @returns True if validation passes, false otherwise
+     * @fires invalid - When validation fails (for form integration)
+     */
+    validate(): boolean;
+    /**
+     * Set a custom validation message
+     */
+    setCustomValidity(message: string): void;
+    /**
+     * Get form data for form submission
+     */
+    getFormData(): {
+        [key: string]: string;
+    };
+    /**
+     * Report validation state (similar to native form elements)
+     */
+    reportValidity(): boolean;
+    /**
+     * Form reset handler
+     */
+    reset(): void;
+    /**
+     * Get FormData object for native form submission
+     */
+    getFormDataObject(): FormData | null;
+    /**
+     * Validate on value change
+     */
+    validateOnChange(): void;
+}
+export {};
+//# sourceMappingURL=validation.controller.d.ts.map

package/dist/src/components/radio-group/controllers/validation.controller.js

@@ -0,0 +1,108 @@
+/**
+ * @license
+ * Copyright 2023 Nuraly, Laabidi Aymen
+ * SPDX-License-Identifier: MIT
+ */
+import { BaseValidationController } from '@nuralyui/common/controllers';
+/**
+ * Controller that manages validation logic and form integration for radio groups
+ * Implements HTML5 form validation patterns with custom validation support
+ *
+ * Features:
+ * - Required field validation
+ * - Custom validation message support
+ * - Form integration with native validation API
+ * - Real-time validation state tracking
+ *
+ * @example
+ * ```typescript
+ * const controller = new RadioValidationController(hostElement);
+ * const isValid = controller.validate(); // Validate current state
+ * console.log(controller.validationMessage); // Get validation error
+ * ```
+ */
+export class RadioValidationController extends BaseValidationController {
+    /**
+     * Validates the current radio group state
+     * Checks required field constraints and custom validation rules
+     *
+     * @returns True if validation passes, false otherwise
+     * @fires invalid - When validation fails (for form integration)
+     */
+    validate() {
+        const isRequired = this.host.required;
+        const selectedValue = this.host.value;
+        if (isRequired && !selectedValue) {
+            this._isValid = false;
+            this._validationMessage = 'Please select an option';
+            this.requestUpdate();
+            return false;
+        }
+        this._isValid = true;
+        this._validationMessage = '';
+        this.requestUpdate();
+        return true;
+    }
+    /**
+     * Set a custom validation message
+     */
+    setCustomValidity(message) {
+        this._isValid = !message;
+        this._validationMessage = message;
+        this.requestUpdate();
+    }
+    /**
+     * Get form data for form submission
+     */
+    getFormData() {
+        const name = this.host.name;
+        const value = this.host.value;
+        return name ? { [name]: value } : {};
+    }
+    /**
+     * Report validation state (similar to native form elements)
+     */
+    reportValidity() {
+        const isValid = this.validate();
+        if (!isValid) {
+            // Dispatch invalid event
+            const invalidEvent = new CustomEvent('invalid', {
+                detail: {
+                    message: this._validationMessage
+                },
+                bubbles: true,
+                composed: true
+            });
+            this._host.dispatchEvent(invalidEvent);
+        }
+        return isValid;
+    }
+    /**
+     * Form reset handler
+     */
+    reset() {
+        this.clearValidation();
+    }
+    /**
+     * Get FormData object for native form submission
+     */
+    getFormDataObject() {
+        const name = this.host.name;
+        const value = this.host.value;
+        if (!name || !value)
+            return null;
+        const formData = new FormData();
+        formData.append(name, value);
+        return formData;
+    }
+    /**
+     * Validate on value change
+     */
+    validateOnChange() {
+        // Auto-validate when value changes if validation was previously invalid
+        if (!this._isValid) {
+            this.validate();
+        }
+    }
+}
+//# sourceMappingURL=validation.controller.js.map

package/dist/src/components/radio-group/interfaces/base-controller.interface.d.ts

@@ -0,0 +1,75 @@
+/**
+ * @license
+ * Copyright 2023 Nuraly, Laabidi Aymen
+ * SPDX-License-Identifier: MIT
+ */
+import { ReactiveController } from 'lit';
+/**
+ * Base interface that all radio controllers must implement
+ * Extends Lit's ReactiveController with common functionality
+ */
+export interface RadioBaseController extends ReactiveController {
+    /**
+     * Called when the host element is connected to the DOM
+     * Used for setting up event listeners, observers, etc.
+     */
+    hostConnected(): void;
+    /**
+     * Called when the host element is disconnected from the DOM
+     * Used for cleanup of event listeners, observers, etc.
+     */
+    hostDisconnected(): void;
+}
+/**
+ * Error handling interface for controllers
+ */
+export interface ErrorHandler {
+    /**
+     * Handle errors that occur within the controller
+     * @param operation - The operation that failed
+     * @param error - The error that occurred
+     */
+    handleError(operation: string, error: Error): void;
+}
+/**
+ * Interface representing the radio component host element that extends ReactiveControllerHost
+ */
+export interface RadioHost {
+    /**
+     * The radio button options
+     */
+    options: any[];
+    /**
+     * The currently selected value
+     */
+    value: string;
+    /**
+     * The default value to select initially
+     */
+    defaultValue: string;
+    /**
+     * The name attribute for form submission
+     */
+    name: string;
+    /**
+     * Whether the radio group is required
+     */
+    required: boolean;
+    /**
+     * Whether the radio group is disabled
+     */
+    disabled: boolean;
+    /**
+     * Request an update of the component
+     */
+    requestUpdate(): void;
+    /**
+     * Dispatch an event from the component
+     */
+    dispatchEvent(event: Event): boolean;
+    /**
+     * Add a reactive controller to the host
+     */
+    addController(controller: ReactiveController): void;
+}
+//# sourceMappingURL=base-controller.interface.d.ts.map

package/dist/src/components/radio-group/interfaces/base-controller.interface.js

@@ -0,0 +1,7 @@
+/**
+ * @license
+ * Copyright 2023 Nuraly, Laabidi Aymen
+ * SPDX-License-Identifier: MIT
+ */
+export {};
+//# sourceMappingURL=base-controller.interface.js.map

package/dist/src/components/radio-group/interfaces/focus-controller.interface.d.ts

@@ -0,0 +1,40 @@
+/**
+ * @license
+ * Copyright 2023 Nuraly, Laabidi Aymen
+ * SPDX-License-Identifier: MIT
+ */
+import { RadioBaseController } from './base-controller.interface.js';
+/**
+ * Interface for controllers that handle keyboard navigation
+ */
+export interface KeyboardController extends RadioBaseController {
+    /**
+     * Handle keyboard events for radio group navigation
+     * @param event - The keyboard event to handle
+     */
+    handleKeyDown(event: KeyboardEvent): void;
+}
+/**
+ * Interface for controllers that handle focus management
+ */
+export interface FocusController extends RadioBaseController {
+    /**
+     * Set focus to a specific option by index
+     * @param index - The index of the option to focus
+     */
+    setFocusedOption(index: number): void;
+    /**
+     * Focus the radio group (usually the selected or first option)
+     */
+    focus(): void;
+    /**
+     * Remove focus from the radio group
+     */
+    blur(): void;
+    /**
+     * Get the currently focused option index
+     * @returns The focused option index or -1 if none focused
+     */
+    getFocusedIndex(): number;
+}
+//# sourceMappingURL=focus-controller.interface.d.ts.map

package/dist/src/components/radio-group/interfaces/focus-controller.interface.js

@@ -0,0 +1,7 @@
+/**
+ * @license
+ * Copyright 2023 Nuraly, Laabidi Aymen
+ * SPDX-License-Identifier: MIT
+ */
+export {};
+//# sourceMappingURL=focus-controller.interface.js.map

package/dist/src/components/radio-group/interfaces/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * @license
+ * Copyright 2023 Nuraly, Laabidi Aymen
+ * SPDX-License-Identifier: MIT
+ */
+export { RadioBaseController, ErrorHandler, RadioHost } from './base-controller.interface.js';
+export { SelectionController } from './selection-controller.interface.js';
+export { KeyboardController, FocusController } from './focus-controller.interface.js';
+export { ValidationController } from './validation-controller.interface.js';
+export { RippleController } from './ripple-controller.interface.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/src/components/radio-group/interfaces/index.js

@@ -0,0 +1,7 @@
+/**
+ * @license
+ * Copyright 2023 Nuraly, Laabidi Aymen
+ * SPDX-License-Identifier: MIT
+ */
+export {};
+//# sourceMappingURL=index.js.map

package/dist/src/components/radio-group/interfaces/ripple-controller.interface.d.ts

@@ -0,0 +1,31 @@
+/**
+ * @license
+ * Copyright 2023 Nuraly, Laabidi Aymen
+ * SPDX-License-Identifier: MIT
+ */
+import { RadioBaseController } from './base-controller.interface.js';
+/**
+ * Interface for controllers that handle visual effects like ripples
+ */
+export interface RippleController extends RadioBaseController {
+    /**
+     * Add a ripple effect at the event location
+     * @param event - The event that triggered the ripple (click, touch, etc.)
+     */
+    addRippleEffect(event: Event): void;
+    /**
+     * Add a ripple effect at a specific element
+     * @param element - The element to add ripple effect to
+     */
+    addRippleEffectToElement(element: HTMLElement): void;
+    /**
+     * Clear all active ripple effects
+     */
+    clearRipples(): void;
+    /**
+     * Set whether ripple effects are enabled
+     * @param enabled - True to enable ripple effects
+     */
+    setRippleEnabled(enabled: boolean): void;
+}
+//# sourceMappingURL=ripple-controller.interface.d.ts.map

package/dist/src/components/radio-group/interfaces/ripple-controller.interface.js

@@ -0,0 +1,7 @@
+/**
+ * @license
+ * Copyright 2023 Nuraly, Laabidi Aymen
+ * SPDX-License-Identifier: MIT
+ */
+export {};
+//# sourceMappingURL=ripple-controller.interface.js.map

package/dist/src/components/radio-group/interfaces/selection-controller.interface.d.ts

@@ -0,0 +1,45 @@
+/**
+ * @license
+ * Copyright 2023 Nuraly, Laabidi Aymen
+ * SPDX-License-Identifier: MIT
+ */
+import { RadioBaseController } from './base-controller.interface.js';
+import { RadioButtonOption } from '../radio-group.types.js';
+/**
+ * Interface for controllers that handle radio button selection logic
+ */
+export interface SelectionController extends RadioBaseController {
+    /**
+     * Select a radio option programmatically
+     * @param option - The option to select
+     * @throws {Error} When option is disabled or invalid
+     */
+    selectOption(option: RadioButtonOption): void;
+    /**
+     * Get the currently selected option
+     * @returns The selected option or undefined if none selected
+     */
+    getSelectedOption(): RadioButtonOption | undefined;
+    /**
+     * Check if a specific option is currently selected
+     * @param option - The option to check
+     * @returns True if the option is selected
+     */
+    isOptionSelected(option: RadioButtonOption): boolean;
+    /**
+     * Check if a specific option is disabled
+     * @param option - The option to check
+     * @returns True if the option is disabled
+     */
+    isOptionDisabled(option: RadioButtonOption): boolean;
+    /**
+     * Get the current selected value as a string
+     * @returns The selected value or empty string
+     */
+    getSelectedValue(): string;
+    /**
+     * Reset the selection to no option selected
+     */
+    reset(): void;
+}
+//# sourceMappingURL=selection-controller.interface.d.ts.map