@sekiui/elements 0.0.55 → 0.0.57

package/dist/collection/utils/a11y.js

@@ -0,0 +1,291 @@
+/**
+ * Accessibility Utilities
+ * Provides helpers for ARIA attributes, keyboard navigation, and accessibility features
+ */
+/**
+ * Generate a unique ID for ARIA relationships
+ * @param prefix - Optional prefix for the ID
+ * @param suffix - Optional suffix for the ID
+ */
+export function generateAriaId(prefix = 'aria', suffix) {
+    const timestamp = Date.now().toString(36);
+    const random = Math.random().toString(36).substr(2, 9);
+    const finalSuffix = suffix ? `-${suffix}` : '';
+    return `${prefix}-${timestamp}-${random}${finalSuffix}`;
+}
+/**
+ * Set ARIA attributes on an element
+ * @param element - The element to set attributes on
+ * @param attributes - Object with attribute names and values
+ */
+export function setAriaAttributes(element, attributes) {
+    Object.entries(attributes).forEach(([key, value]) => {
+        if (value === null || value === false) {
+            element.removeAttribute(`aria-${key}`);
+        }
+        else if (value === true) {
+            element.setAttribute(`aria-${key}`, 'true');
+        }
+        else {
+            element.setAttribute(`aria-${key}`, String(value));
+        }
+    });
+}
+/**
+ * Add accessible label to an element
+ * @param element - The element to label
+ * @param label - The label text or element ID
+ * @param useAriaLabel - If true, uses aria-label; if false, uses aria-labelledby
+ */
+export function addAriaLabel(element, label, useAriaLabel = true) {
+    if (useAriaLabel) {
+        element.setAttribute('aria-label', label);
+    }
+    else {
+        element.setAttribute('aria-labelledby', label);
+    }
+}
+/**
+ * Add accessible description to an element
+ * @param element - The element to describe
+ * @param description - The description text or element ID
+ * @param useAriaDescription - If true, uses aria-description; if false, uses aria-describedby
+ */
+export function addAriaDescription(element, description, useAriaDescription = false) {
+    if (useAriaDescription) {
+        element.setAttribute('aria-description', description);
+    }
+    else {
+        element.setAttribute('aria-describedby', description);
+    }
+}
+/**
+ * Set ARIA live region announcement
+ * @param element - The element to make a live region
+ * @param message - The message to announce
+ * @param politeness - 'polite' (default), 'assertive', or 'off'
+ * @param atomic - Whether to announce the entire region
+ */
+export function announceAriaLive(element, message, politeness = 'polite', atomic = false) {
+    element.setAttribute('aria-live', politeness);
+    if (atomic) {
+        element.setAttribute('aria-atomic', 'true');
+    }
+    element.textContent = message;
+}
+/**
+ * Mark an element as disabled with ARIA attributes
+ * @param element - The element to mark as disabled
+ * @param disabled - Whether the element is disabled
+ */
+export function setAriaDisabled(element, disabled) {
+    if (disabled) {
+        element.setAttribute('aria-disabled', 'true');
+        element.style.pointerEvents = 'none';
+        element.style.opacity = '0.5';
+    }
+    else {
+        element.removeAttribute('aria-disabled');
+        element.style.pointerEvents = '';
+        element.style.opacity = '';
+    }
+}
+/**
+ * Mark an element as expanded/collapsed (for collapsible sections)
+ * @param element - The element to mark
+ * @param expanded - Whether the element is expanded
+ * @param targetId - ID of the element being controlled (optional)
+ */
+export function setAriaExpanded(element, expanded, targetId) {
+    element.setAttribute('aria-expanded', expanded ? 'true' : 'false');
+    if (targetId) {
+        element.setAttribute('aria-controls', targetId);
+    }
+}
+/**
+ * Mark an element as selected
+ * @param element - The element to mark
+ * @param selected - Whether the element is selected
+ */
+export function setAriaSelected(element, selected) {
+    element.setAttribute('aria-selected', selected ? 'true' : 'false');
+}
+/**
+ * Mark an element as checked (for checkboxes and radio buttons)
+ * @param element - The element to mark
+ * @param checked - The checked state ('true', 'false', or 'mixed')
+ */
+export function setAriaChecked(element, checked) {
+    element.setAttribute('aria-checked', checked);
+}
+/**
+ * Set the current value of an element (for sliders, spinbuttons, etc.)
+ * @param element - The element
+ * @param current - Current value
+ * @param min - Minimum value
+ * @param max - Maximum value
+ * @param text - Optional text description of the value
+ */
+export function setAriaValueNow(element, current, min, max, text) {
+    element.setAttribute('aria-valuenow', String(current));
+    if (min !== undefined)
+        element.setAttribute('aria-valuemin', String(min));
+    if (max !== undefined)
+        element.setAttribute('aria-valuemax', String(max));
+    if (text !== undefined)
+        element.setAttribute('aria-valuetext', text);
+}
+/**
+ * Mark an element as having a popup (for menus, popovers, etc.)
+ * @param element - The element with the popup trigger
+ * @param type - Type of popup: 'menu', 'listbox', 'tree', 'grid', 'dialog'
+ * @param popupId - ID of the popup element
+ */
+export function setAriaPopup(element, type = 'menu', popupId) {
+    element.setAttribute('aria-haspopup', type);
+    if (popupId) {
+        element.setAttribute('aria-owns', popupId);
+    }
+}
+/**
+ * Set role for an element
+ * @param element - The element
+ * @param role - The role (button, menu, menuitem, etc.)
+ */
+export function setRole(element, role) {
+    element.setAttribute('role', role);
+}
+/**
+ * Get the accessible name of an element
+ * Follows ARIA naming convention: aria-labelledby > aria-label > title > textContent
+ */
+export function getAccessibleName(element) {
+    // Check aria-labelledby
+    const labelledby = element.getAttribute('aria-labelledby');
+    if (labelledby) {
+        const labelElement = document.getElementById(labelledby);
+        if (labelElement)
+            return labelElement.textContent || '';
+    }
+    // Check aria-label
+    const ariaLabel = element.getAttribute('aria-label');
+    if (ariaLabel)
+        return ariaLabel;
+    // Check title
+    const title = element.getAttribute('title');
+    if (title)
+        return title;
+    // Fall back to textContent
+    return element.textContent || '';
+}
+/**
+ * Create a skip link for keyboard navigation
+ * @param text - Link text
+ * @param targetId - ID of element to skip to
+ */
+export function createSkipLink(text, targetId) {
+    const link = document.createElement('a');
+    link.href = `#${targetId}`;
+    link.textContent = text;
+    link.className = 'sr-only'; // Visually hidden but accessible to screen readers
+    link.style.position = 'absolute';
+    link.style.top = '-9999px';
+    link.style.left = '-9999px';
+    // Show on focus
+    link.addEventListener('focus', () => {
+        link.style.top = '0';
+        link.style.left = '0';
+    });
+    // Hide on blur
+    link.addEventListener('blur', () => {
+        link.style.top = '-9999px';
+        link.style.left = '-9999px';
+    });
+    return link;
+}
+/**
+ * Check if element should be hidden from screen readers
+ */
+export function isAriaHidden(element) {
+    return element.getAttribute('aria-hidden') === 'true';
+}
+/**
+ * Hide element from screen readers but keep visually visible
+ */
+export function setAriaHidden(element, hidden) {
+    if (hidden) {
+        element.setAttribute('aria-hidden', 'true');
+    }
+    else {
+        element.removeAttribute('aria-hidden');
+    }
+}
+/**
+ * Announce a message to screen readers immediately (without ARIA live regions)
+ * @param message - The message to announce
+ * @param politeness - 'polite' (default) or 'assertive'
+ */
+export function announceToScreenReader(message, politeness = 'polite') {
+    if (typeof document === 'undefined')
+        return;
+    const announcement = document.createElement('div');
+    announcement.setAttribute('aria-live', politeness);
+    announcement.setAttribute('aria-atomic', 'true');
+    announcement.className = 'sr-only';
+    announcement.style.position = 'absolute';
+    announcement.style.left = '-9999px';
+    announcement.style.top = '-9999px';
+    announcement.textContent = message;
+    document.body.appendChild(announcement);
+    // Remove after announcement is made
+    setTimeout(() => {
+        announcement.remove();
+    }, 1000);
+}
+/**
+ * Set proper heading hierarchy
+ * @param element - The heading element
+ * @param level - Heading level (1-6)
+ */
+export function setHeadingLevel(element, level) {
+    const tag = `h${level}`;
+    if (element.tagName.toLowerCase() !== tag) {
+        // If element is not correct tag, set role as fallback
+        element.setAttribute('role', tag);
+    }
+}
+/**
+ * Enable keyboard navigation for a custom component
+ * @param element - The element that should handle keyboard
+ * @param keys - Map of key to handler function
+ */
+export function enableKeyboardNavigation(element, keys) {
+    const handleKeyDown = (event) => {
+        const handler = keys[event.key.toLowerCase()];
+        if (handler) {
+            event.preventDefault();
+            handler(event);
+        }
+    };
+    element.addEventListener('keydown', handleKeyDown);
+    // Return cleanup function
+    return () => {
+        element.removeEventListener('keydown', handleKeyDown);
+    };
+}
+/**
+ * Check if element has accessible focus styling
+ */
+export function hasAccessibleFocus(element) {
+    const styles = window.getComputedStyle(element);
+    return !!(styles.outline || styles.boxShadow || styles.border);
+}
+/**
+ * Ensure focus visible styling (for focus-visible pseudo-class)
+ */
+export function ensureFocusVisible(element) {
+    if (!hasAccessibleFocus(element)) {
+        element.style.outline = '2px solid #4A90E2';
+        element.style.outlineOffset = '2px';
+    }
+}

package/dist/collection/utils/common.js

@@ -0,0 +1,286 @@
+/**
+ * Common Utilities
+ * Shared utility functions used across the component library
+ */
+/* eslint-disable no-undef, @typescript-eslint/no-explicit-any */
+let idCounter = 0;
+/**
+ * Generate a unique ID with optional prefix
+ * @param prefix - Optional prefix for the ID (default: 'id')
+ */
+export function generateUniqueId(prefix = 'id') {
+    return `${prefix}-${++idCounter}-${Math.random().toString(36).substr(2, 9)}`;
+}
+/**
+ * Reset ID counter (useful for testing)
+ */
+export function resetIdCounter() {
+    idCounter = 0;
+}
+/**
+ * Debounce a function
+ * @param fn - Function to debounce
+ * @param delay - Delay in milliseconds
+ */
+export function debounce(fn, delay) {
+    let timeoutId = null;
+    return (...args) => {
+        if (timeoutId)
+            clearTimeout(timeoutId);
+        timeoutId = setTimeout(() => fn(...args), delay);
+    };
+}
+/**
+ * Throttle a function
+ * @param fn - Function to throttle
+ * @param delay - Delay in milliseconds
+ */
+export function throttle(fn, delay) {
+    let lastCall = 0;
+    let timeoutId = null;
+    return (...args) => {
+        const now = Date.now();
+        if (now - lastCall >= delay) {
+            lastCall = now;
+            fn(...args);
+        }
+        else {
+            if (timeoutId)
+                clearTimeout(timeoutId);
+            timeoutId = setTimeout(() => {
+                lastCall = Date.now();
+                fn(...args);
+            }, delay - (now - lastCall));
+        }
+    };
+}
+/**
+ * Add a class to an element
+ * @param element - The element
+ * @param className - Class name to add
+ */
+export function addClass(element, className) {
+    element.classList.add(className);
+}
+/**
+ * Remove a class from an element
+ * @param element - The element
+ * @param className - Class name to remove
+ */
+export function removeClass(element, className) {
+    element.classList.remove(className);
+}
+/**
+ * Toggle a class on an element
+ * @param element - The element
+ * @param className - Class name to toggle
+ * @param force - Optional force add/remove
+ */
+export function toggleClass(element, className, force) {
+    element.classList.toggle(className, force);
+}
+/**
+ * Check if element has a class
+ * @param element - The element
+ * @param className - Class name to check
+ */
+export function hasClass(element, className) {
+    return element.classList.contains(className);
+}
+/**
+ * Get all data attributes from an element as an object
+ */
+export function getDataAttributes(element) {
+    const data = {};
+    Array.from(element.attributes).forEach((attr) => {
+        if (attr.name.startsWith('data-')) {
+            const key = attr.name.slice(5); // Remove 'data-' prefix
+            data[key] = attr.value;
+        }
+    });
+    return data;
+}
+/**
+ * Set a data attribute on an element
+ * @param element - The element
+ * @param key - Data attribute name (without 'data-' prefix)
+ * @param value - The value to set
+ */
+export function setDataAttribute(element, key, value) {
+    if (value === null) {
+        element.removeAttribute(`data-${key}`);
+    }
+    else {
+        element.setAttribute(`data-${key}`, value);
+    }
+}
+/**
+ * Get the value of a data attribute
+ * @param element - The element
+ * @param key - Data attribute name (without 'data-' prefix)
+ */
+export function getDataAttribute(element, key) {
+    return element.getAttribute(`data-${key}`) || undefined;
+}
+/**
+ * Dispatch a custom event from an element
+ * @param element - The element to dispatch from
+ * @param eventName - Name of the custom event
+ * @param detail - Optional detail object to include in the event
+ */
+export function dispatchCustomEvent(element, eventName, detail) {
+    const event = new CustomEvent(eventName, {
+        detail,
+        bubbles: true,
+        cancelable: true,
+        composed: true,
+    });
+    element.dispatchEvent(event);
+}
+/**
+ * Listen for a custom event
+ * @param element - The element to listen on
+ * @param eventName - Name of the custom event
+ * @param handler - Callback function
+ * @returns Cleanup function to remove listener
+ */
+export function onCustomEvent(element, eventName, handler) {
+    const listener = (event) => {
+        handler(event.detail);
+    };
+    element.addEventListener(eventName, listener);
+    return () => {
+        element.removeEventListener(eventName, listener);
+    };
+}
+/**
+ * Get the offset position of an element relative to the viewport
+ */
+export function getElementOffset(element) {
+    const rect = element.getBoundingClientRect();
+    return {
+        top: rect.top + window.scrollY,
+        left: rect.left + window.scrollX,
+    };
+}
+/**
+ * Check if an element is in the viewport
+ */
+export function isElementInViewport(element) {
+    const rect = element.getBoundingClientRect();
+    return rect.top < window.innerHeight && rect.bottom > 0 && rect.left < window.innerWidth && rect.right > 0;
+}
+/**
+ * Scroll element into view
+ * @param element - The element to scroll into view
+ * @param options - Scroll behavior options
+ */
+export function scrollIntoView(element, options = {}) {
+    element.scrollIntoView(Object.assign({ behavior: 'smooth', block: 'nearest', inline: 'nearest' }, options));
+}
+/**
+ * Get computed style value
+ */
+export function getComputedValue(element, property) {
+    return window.getComputedStyle(element).getPropertyValue(property);
+}
+/**
+ * Wait for a specific time
+ * @param ms - Time in milliseconds
+ */
+export function wait(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+ * Wait for an element to appear in the DOM
+ * @param selector - CSS selector to wait for
+ * @param timeout - Timeout in milliseconds (default: 5000)
+ */
+export function waitForElement(selector, timeout = 5000) {
+    return new Promise((resolve, reject) => {
+        const element = document.querySelector(selector);
+        if (element) {
+            resolve(element);
+            return;
+        }
+        const observer = new MutationObserver(() => {
+            const el = document.querySelector(selector);
+            if (el) {
+                observer.disconnect();
+                resolve(el);
+            }
+        });
+        observer.observe(document.body, { childList: true, subtree: true });
+        setTimeout(() => {
+            observer.disconnect();
+            reject(new Error(`Element "${selector}" not found within ${timeout}ms`));
+        }, timeout);
+    });
+}
+/**
+ * Clone an object deeply
+ */
+export function deepClone(obj) {
+    if (obj === null || typeof obj !== 'object')
+        return obj;
+    if (obj instanceof Date)
+        return new Date(obj.getTime());
+    if (obj instanceof Array)
+        return obj.map((item) => deepClone(item));
+    if (obj instanceof Object) {
+        const cloned = {};
+        Object.keys(obj).forEach((key) => {
+            cloned[key] = deepClone(obj[key]);
+        });
+        return cloned;
+    }
+    return obj;
+}
+/**
+ * Merge objects
+ */
+export function mergeObjects(target, ...sources) {
+    return sources.reduce((result, source) => (Object.assign(Object.assign({}, result), source)), target);
+}
+/**
+ * Get the prefixed CSS property name (for vendor prefixes)
+ */
+export function getPrefixedProperty(property) {
+    const element = document.createElement('div');
+    const style = element.style;
+    if (property in style)
+        return property;
+    if (`webkit${property[0].toUpperCase()}${property.slice(1)}` in style)
+        return `webkit${property[0].toUpperCase()}${property.slice(1)}`;
+    if (`moz${property[0].toUpperCase()}${property.slice(1)}` in style)
+        return `moz${property[0].toUpperCase()}${property.slice(1)}`;
+    if (`ms${property[0].toUpperCase()}${property.slice(1)}` in style)
+        return `ms${property[0].toUpperCase()}${property.slice(1)}`;
+    return property;
+}
+/**
+ * Check if browser supports a CSS feature
+ */
+export function supportsCSSFeature(property, value) {
+    const element = document.createElement('div');
+    element.style.setProperty(property, value);
+    return element.style.getPropertyValue(property) !== '';
+}
+/**
+ * Request animation frame with promise
+ */
+export function requestAnimationFramePromise() {
+    return new Promise((resolve) => requestAnimationFrame(resolve));
+}
+/**
+ * Convert camelCase to kebab-case
+ */
+export function camelToKebab(str) {
+    return str.replace(/[A-Z]/g, (letter) => `-${letter.toLowerCase()}`);
+}
+/**
+ * Convert kebab-case to camelCase
+ */
+export function kebabToCamel(str) {
+    return str.replace(/-./g, (x) => x[1].toUpperCase());
+}