@clusterenvision/ui-framework 1.0.0

package/dist/lib/dom.d.ts

@@ -0,0 +1,373 @@
+/**
+ * @fileoverview CE DOM Utilities
+ * @description Comprehensive DOM manipulation library for TypeScript projects
+ * @author ClusterEnvision
+ * @version 2.0.0
+ *
+ * Provides a jQuery-like chainable API with full type safety, optimized for
+ * modern browsers and production use. Includes performance optimizations,
+ * error handling, and extensive utility functions.
+ *
+ * @example
+ * ```typescript
+ * import { $, create, delegate } from '@app/lib/dom';
+ *
+ * // Select and manipulate
+ * $('.button').addClass('active').on('click', handler);
+ *
+ * // Create elements
+ * const btn = create('button', {
+ *   text: 'Click me',
+ *   className: 'btn primary',
+ *   on: { click: () => console.log('clicked') }
+ * });
+ *
+ * // Event delegation
+ * delegate('click', '.dynamic-btn', (e, target) => {
+ *   console.log('Delegated click', target);
+ * });
+ * ```
+ */
+/** Enable/disable debug mode */
+declare function setDebugMode(enabled: boolean): void;
+type ElementInput = string | HTMLElement | null | undefined;
+type ElementsInput = string | HTMLElement[] | NodeListOf<Element>;
+type EventHandler<T extends Event = Event> = (event: T) => void;
+type DelegateHandler = (event: Event, target: HTMLElement) => void;
+/**
+ * Options for creating elements
+ * @template K - HTML element tag name type
+ */
+interface CreateElementOptions {
+    /** CSS class name */
+    className?: string;
+    /** Array of CSS classes */
+    classes?: string[];
+    /** Element ID */
+    id?: string;
+    /** Text content */
+    text?: string;
+    /** HTML content */
+    html?: string;
+    /** HTML attributes */
+    attrs?: Record<string, string | number | boolean>;
+    /** Data attributes (without 'data-' prefix) */
+    data?: Record<string, string | number | boolean>;
+    /** Inline styles */
+    styles?: Record<string, string | number>;
+    /** Event listeners */
+    on?: Record<string, EventListener>;
+    /** Child elements or text nodes */
+    children?: (HTMLElement | string)[];
+}
+/**
+ * Chainable DOM element wrapper
+ * Provides jQuery-like API for DOM manipulation
+ */
+interface DOMElement {
+    /** The underlying HTMLElement */
+    readonly el: HTMLElement | null;
+    addClass(...classes: string[]): DOMElement;
+    removeClass(...classes: string[]): DOMElement;
+    toggleClass(className: string, force?: boolean): DOMElement;
+    hasClass(className: string): boolean;
+    attr(name: string): string | null;
+    attr(name: string, value: string | number | boolean): DOMElement;
+    removeAttr(name: string): DOMElement;
+    data(key: string): string | null;
+    data(key: string, value: string | number | boolean): DOMElement;
+    html(): string;
+    html(content: string): DOMElement;
+    text(): string;
+    text(content: string): DOMElement;
+    val(): string;
+    val(value: string): DOMElement;
+    on(event: string, handler: EventListener, options?: AddEventListenerOptions): DOMElement;
+    off(event: string, handler: EventListener): DOMElement;
+    once(event: string, handler: EventListener): DOMElement;
+    trigger(event: string, detail?: unknown): DOMElement;
+    append(content: string | HTMLElement | HTMLElement[]): DOMElement;
+    prepend(content: string | HTMLElement | HTMLElement[]): DOMElement;
+    before(content: string | HTMLElement): DOMElement;
+    after(content: string | HTMLElement): DOMElement;
+    remove(): void;
+    empty(): DOMElement;
+    replace(newContent: string | HTMLElement): void;
+    parent(): DOMElement;
+    children(): HTMLElement[];
+    siblings(): HTMLElement[];
+    find(selector: string): DOMElement;
+    findAll(selector: string): HTMLElement[];
+    closest(selector: string): DOMElement;
+    next(): DOMElement;
+    prev(): DOMElement;
+    css(property: string): string;
+    css(property: string, value: string | number): DOMElement;
+    css(properties: Record<string, string | number>): DOMElement;
+    show(): DOMElement;
+    hide(): DOMElement;
+    toggle(force?: boolean): DOMElement;
+    width(): number;
+    height(): number;
+    offset(): {
+        top: number;
+        left: number;
+    };
+    scrollTop(): number;
+    scrollTop(value: number): DOMElement;
+    isVisible(): boolean;
+    isHidden(): boolean;
+    exists(): boolean;
+    focus(): DOMElement;
+    blur(): DOMElement;
+}
+/**
+ * Select a single element (jQuery-like $)
+ *
+ * @param selector - CSS selector string or HTMLElement
+ * @returns DOMElement wrapper for chainable operations
+ *
+ * @example
+ * ```typescript
+ * // Select by CSS selector
+ * $('button').addClass('active').on('click', handler);
+ *
+ * // Wrap existing element
+ * const el = document.getElementById('app');
+ * $(el).css('color', 'red');
+ *
+ * // Null-safe
+ * $('.non-existent').addClass('foo'); // No error
+ * ```
+ */
+declare function $(selector: ElementInput): DOMElement;
+/**
+ * Select multiple elements
+ *
+ * @param selector - CSS selector string
+ * @returns Array of HTMLElements (not wrapped)
+ *
+ * @example
+ * ```typescript
+ * // Get all matching elements
+ * $$('.items').forEach(el => $(el).addClass('processed'));
+ *
+ * // Map and filter
+ * const visible = $$('.item').filter(el => $(el).isVisible());
+ * ```
+ */
+declare function $$(selector: string): HTMLElement[];
+/**
+ * Select by ID (faster than querySelector)
+ *
+ * @param id - Element ID (without # prefix)
+ * @returns DOMElement wrapper
+ *
+ * @example
+ * ```typescript
+ * $id('app').html('<h1>Hello</h1>');
+ * $id('sidebar').addClass('collapsed');
+ * ```
+ */
+declare function $id(id: string): DOMElement;
+/**
+ * Create a new element with comprehensive options
+ *
+ * @template K - HTML element tag name type
+ * @param tag - HTML tag name (e.g., 'div', 'button', 'input')
+ * @param options - Configuration options for the element
+ * @returns Created HTMLElement of the specified type
+ *
+ * @example
+ * ```typescript
+ * // Simple button
+ * const btn = create('button', {
+ *   className: 'btn btn-primary',
+ *   text: 'Click me'
+ * });
+ *
+ * // Complex form input
+ * const input = create('input', {
+ *   classes: ['form-control', 'input-lg'],
+ *   attrs: { type: 'email', placeholder: 'Enter email', required: true },
+ *   data: { validation: 'email', maxLength: '255' },
+ *   on: {
+ *     input: (e) => console.log('Input changed:', e.target.value),
+ *     blur: validateEmail
+ *   }
+ * });
+ *
+ * // Container with children
+ * const card = create('div', {
+ *   className: 'card',
+ *   children: [
+ *     create('h3', { text: 'Card Title' }),
+ *     create('p', { text: 'Card content goes here' }),
+ *     create('button', { text: 'Action', className: 'btn' })
+ *   ]
+ * });
+ * ```
+ */
+declare function create<K extends keyof HTMLElementTagNameMap>(tag: K, options?: CreateElementOptions): HTMLElementTagNameMap[K];
+/**
+ * Create a document fragment from HTML string
+ *
+ * @param html - HTML string to parse
+ * @returns DocumentFragment containing parsed elements
+ *
+ * @example
+ * ```typescript
+ * const frag = fragment(`
+ *   <div class="card">
+ *     <h3>Title</h3>
+ *     <p>Content</p>
+ *   </div>
+ * `);
+ * document.body.appendChild(frag);
+ * ```
+ */
+declare function fragment(html: string): DocumentFragment;
+/**
+ * Event delegation helper for dynamic elements
+ *
+ * Attaches a single event listener to a root element and handles events
+ * from matching child elements, even if they're added dynamically after
+ * the listener is attached.
+ *
+ * @param event - Event type (e.g., 'click', 'input', 'change')
+ * @param selector - CSS selector for target elements
+ * @param handler - Callback function receiving event and matched target
+ * @param root - Root element or document to attach listener to
+ * @returns Cleanup function to remove the delegated listener
+ *
+ * @example
+ * ```typescript
+ * // Handle clicks on dynamically added buttons
+ * const cleanup = delegate('click', '.btn-delete', (e, target) => {
+ *   const id = target.dataset.id;
+ *   deleteItem(id);
+ * });
+ *
+ * // With custom root
+ * delegate('click', '.item', handleClick, myContainer);
+ *
+ * // Clean up when done
+ * cleanup();
+ * ```
+ */
+declare function delegate(event: string, selector: string, handler: DelegateHandler, root?: HTMLElement | Document): () => void;
+/**
+ * Execute callback when DOM is ready
+ *
+ * Safely runs code when the DOM is fully loaded. If DOM is already ready,
+ * executes callback immediately.
+ *
+ * @param callback - Function to execute when DOM is ready
+ *
+ * @example
+ * ```typescript
+ * ready(() => {
+ *   console.log('DOM is ready!');
+ *   initApp();
+ *   setupEventListeners();
+ * });
+ *
+ * // Or with arrow function
+ * ready(() => $('#app').html('<h1>Loaded</h1>'));
+ * ```
+ */
+declare function ready(callback: () => void): void;
+/**
+ * Clone an element deeply
+ */
+declare function clone(element: HTMLElement, deep?: boolean): HTMLElement;
+/**
+ * Check if element matches selector
+ */
+declare function matches(element: HTMLElement, selector: string): boolean;
+declare function elementData<T = unknown>(element: HTMLElement, key: string, value?: T): T | undefined;
+/**
+ * Serialize form data to object
+ */
+declare function serializeForm(form: HTMLFormElement): Record<string, string>;
+/**
+ * Get all form values including nested objects
+ */
+type FormValue = FormDataEntryValue | FormDataEntryValue[];
+declare function getFormValues(form: HTMLFormElement): Record<string, FormValue>;
+/**
+ * Debounce function for performance
+ */
+declare function debounce<T extends (...args: unknown[]) => unknown>(func: T, wait: number): (...args: Parameters<T>) => void;
+/**
+ * Throttle function for performance
+ */
+declare function throttle<T extends (...args: unknown[]) => unknown>(func: T, limit: number): (...args: Parameters<T>) => void;
+/**
+ * Wait for an element to appear in DOM
+ */
+declare function waitForElement(selector: string, timeout?: number): Promise<HTMLElement>;
+/**
+ * Execute callback when element becomes visible (intersection observer)
+ */
+declare function onVisible(element: HTMLElement, callback: (entry: IntersectionObserverEntry) => void, options?: IntersectionObserverInit): () => void;
+/**
+ * Animate element with CSS transitions
+ */
+declare function animate(element: HTMLElement, properties: Record<string, string>, duration?: number, easing?: string): Promise<void>;
+/**
+ * Fade in element
+ */
+declare function fadeIn(element: HTMLElement, duration?: number): Promise<void>;
+/**
+ * Fade out element
+ */
+declare function fadeOut(element: HTMLElement, duration?: number): Promise<void>;
+/**
+ * Slide down (show) element
+ */
+declare function slideDown(element: HTMLElement, duration?: number): Promise<void>;
+/**
+ * Slide up (hide) element
+ */
+declare function slideUp(element: HTMLElement, duration?: number): Promise<void>;
+/**
+ * Complete DOM utilities API
+ *
+ * @example
+ * ```typescript
+ * // Named imports (recommended)
+ * import { $, create, delegate } from '@app/lib/dom';
+ *
+ * // Default import
+ * import DOM from '@app/lib/dom';
+ * DOM.$('.button').addClass('active');
+ * ```
+ */
+declare const DOMApi: {
+    version: string;
+    $: typeof $;
+    $$: typeof $$;
+    $id: typeof $id;
+    create: typeof create;
+    fragment: typeof fragment;
+    delegate: typeof delegate;
+    ready: typeof ready;
+    clone: typeof clone;
+    matches: typeof matches;
+    elementData: typeof elementData;
+    serializeForm: typeof serializeForm;
+    getFormValues: typeof getFormValues;
+    debounce: typeof debounce;
+    throttle: typeof throttle;
+    waitForElement: typeof waitForElement;
+    onVisible: typeof onVisible;
+    animate: typeof animate;
+    fadeIn: typeof fadeIn;
+    fadeOut: typeof fadeOut;
+    slideDown: typeof slideDown;
+    slideUp: typeof slideUp;
+    setDebugMode: typeof setDebugMode;
+};
+
+export { $, $$, $id, type CreateElementOptions, type DOMElement, type DelegateHandler, type ElementInput, type ElementsInput, type EventHandler, animate, clone, create, debounce, DOMApi as default, delegate, elementData, fadeIn, fadeOut, fragment, getFormValues, matches, onVisible, ready, serializeForm, setDebugMode, slideDown, slideUp, throttle, waitForElement };

package/dist/lib/dom.js

@@ -0,0 +1,3 @@
+export { $, $$, $id, animate, clone, create, debounce, dom_default as default, delegate, elementData, fadeIn, fadeOut, fragment, getFormValues, matches, onVisible, ready, serializeForm, setDebugMode, slideDown, slideUp, throttle, waitForElement } from '../chunk-22HQL2Y4.js';
+//# sourceMappingURL=dom.js.map
+//# sourceMappingURL=dom.js.map

package/dist/lib/dom.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"dom.js"}

package/dist/lib/icons.cjs

@@ -0,0 +1,20 @@
+'use strict';
+
+var chunkR6XQUMWT_cjs = require('../chunk-R6XQUMWT.cjs');
+
+
+
+Object.defineProperty(exports, "ICONS", {
+  enumerable: true,
+  get: function () { return chunkR6XQUMWT_cjs.ICONS; }
+});
+Object.defineProperty(exports, "icon", {
+  enumerable: true,
+  get: function () { return chunkR6XQUMWT_cjs.icon; }
+});
+Object.defineProperty(exports, "iconHtml", {
+  enumerable: true,
+  get: function () { return chunkR6XQUMWT_cjs.iconHtml; }
+});
+//# sourceMappingURL=icons.cjs.map
+//# sourceMappingURL=icons.cjs.map

package/dist/lib/icons.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"icons.cjs"}

package/dist/lib/icons.d.cts

@@ -0,0 +1,64 @@
+/**
+ * Icon utilities for the CE E-Commerce application
+ *
+ * This module provides helper functions for working with icons using the <ce-icon> web component.
+ *
+ * @example
+ * ```typescript
+ * // Create an icon element
+ * const cartIcon = icon('cart-2', { size: '24px', title: 'Shopping cart' });
+ * element.appendChild(cartIcon);
+ *
+ * // Get icon HTML string for innerHTML
+ * const menuHtml = iconHtml('menu-3', { size: '20px', title: 'Menu' });
+ * ```
+ */
+interface IconOptions {
+    /** Size of the icon (CSS length: px, rem, em, %) */
+    size?: string;
+    /** Accessible label for the icon */
+    title?: string;
+    /** CSS class names to add to the icon element */
+    className?: string;
+}
+/**
+ * Create a <ce-icon> element programmatically
+ *
+ * @param name - Icon name from Nucleo set (e.g., 'cart-2', 'menu-3', 'user')
+ * @param options - Icon configuration options
+ * @returns HTMLElement - The ce-icon custom element
+ */
+declare function icon(name: string, options?: IconOptions): HTMLElement;
+/**
+ * Get icon HTML string for use with innerHTML
+ *
+ * @param name - Icon name from Nucleo set
+ * @param options - Icon configuration options
+ * @returns string - HTML string of the ce-icon element
+ */
+declare function iconHtml(name: string, options?: IconOptions): string;
+/**
+ * Common icon names used in the application
+ */
+declare const ICONS: {
+    readonly menu: "menu-3";
+    readonly close: "xmark";
+    readonly cart: "cart-2";
+    readonly star: "star";
+    readonly heart: "heart";
+    readonly user: "user";
+    readonly settings: "settings";
+    readonly logout: "logout";
+    readonly search: "search";
+    readonly filter: "filter";
+    readonly sort: "sort";
+    readonly edit: "edit";
+    readonly delete: "trash";
+    readonly add: "plus";
+    readonly check: "check";
+    readonly warning: "triangle-warning";
+    readonly error: "xmark";
+    readonly info: "info-circle";
+};
+
+export { ICONS, type IconOptions, icon, iconHtml };

package/dist/lib/icons.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Icon utilities for the CE E-Commerce application
+ *
+ * This module provides helper functions for working with icons using the <ce-icon> web component.
+ *
+ * @example
+ * ```typescript
+ * // Create an icon element
+ * const cartIcon = icon('cart-2', { size: '24px', title: 'Shopping cart' });
+ * element.appendChild(cartIcon);
+ *
+ * // Get icon HTML string for innerHTML
+ * const menuHtml = iconHtml('menu-3', { size: '20px', title: 'Menu' });
+ * ```
+ */
+interface IconOptions {
+    /** Size of the icon (CSS length: px, rem, em, %) */
+    size?: string;
+    /** Accessible label for the icon */
+    title?: string;
+    /** CSS class names to add to the icon element */
+    className?: string;
+}
+/**
+ * Create a <ce-icon> element programmatically
+ *
+ * @param name - Icon name from Nucleo set (e.g., 'cart-2', 'menu-3', 'user')
+ * @param options - Icon configuration options
+ * @returns HTMLElement - The ce-icon custom element
+ */
+declare function icon(name: string, options?: IconOptions): HTMLElement;
+/**
+ * Get icon HTML string for use with innerHTML
+ *
+ * @param name - Icon name from Nucleo set
+ * @param options - Icon configuration options
+ * @returns string - HTML string of the ce-icon element
+ */
+declare function iconHtml(name: string, options?: IconOptions): string;
+/**
+ * Common icon names used in the application
+ */
+declare const ICONS: {
+    readonly menu: "menu-3";
+    readonly close: "xmark";
+    readonly cart: "cart-2";
+    readonly star: "star";
+    readonly heart: "heart";
+    readonly user: "user";
+    readonly settings: "settings";
+    readonly logout: "logout";
+    readonly search: "search";
+    readonly filter: "filter";
+    readonly sort: "sort";
+    readonly edit: "edit";
+    readonly delete: "trash";
+    readonly add: "plus";
+    readonly check: "check";
+    readonly warning: "triangle-warning";
+    readonly error: "xmark";
+    readonly info: "info-circle";
+};
+
+export { ICONS, type IconOptions, icon, iconHtml };

package/dist/lib/icons.js

@@ -0,0 +1,3 @@
+export { ICONS, icon, iconHtml } from '../chunk-7SCIB5HP.js';
+//# sourceMappingURL=icons.js.map
+//# sourceMappingURL=icons.js.map

package/dist/lib/icons.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"icons.js"}