@fluixi/dom 1.0.0-alpha.53

package/dist/lib/dom/utils.d.ts

@@ -0,0 +1,411 @@
+/**
+ * @fileoverview DOM utilities for Fluixi
+ * @module @fluixi/core/dom
+ *
+ * This module provides utilities for DOM manipulation and queries.
+ */
+/**
+ * Convert camelCase to kebab-case for attribute names
+ */
+export declare function toAttributeName(key: string): string;
+/**
+ * Check if key is an event handler
+ */
+export declare function isEventHandler(key: string): boolean;
+/**
+ * Get Lit event name from key
+ */
+export declare function getLitEventName(key: string): string;
+/**
+ * Check if attribute should be set as property
+ */
+export declare function shouldSetAsProperty(element: string, key: string): boolean;
+/**
+ * Self-closing HTML tags
+ */
+export declare const VOID_ELEMENTS: Set<string>;
+/**
+ * SVG namespace elements
+ */
+export declare const SVG_ELEMENTS: Set<string>;
+export declare const SVG_NAMESPACE = "http://www.w3.org/2000/svg";
+/**
+ * Returns true for custom elements (tag name contains a hyphen per the Web
+ * Components spec — e.g. `adf-accounts-selector`).
+ */
+export declare function isCustomElement(element: Element): boolean;
+/**
+ * Set a prop on an element, choosing between DOM property assignment and
+ * setAttribute based on:
+ *   - Custom elements always receive complex values (object/array) as DOM
+ *     properties so that Lit components get the rich value, not a serialised
+ *     string.
+ *   - Primitives (string/number/boolean) and standard HTML elements go through
+ *     the normal setAttribute path.
+ */
+export declare function applyElementProp(element: Element, name: string, value: any, isSVG?: boolean): void;
+export declare const JSX_PROPERTIES: Set<string>;
+/**
+ * Queries a single element with type safety
+ *
+ * @template T - Element type
+ * @param {string} selector - CSS selector
+ * @param {Element | Document} root - Root element (default: document)
+ * @returns {T | null} Found element or null
+ *
+ * @example
+ * ```typescript
+ * import { query } from '@fluixi/core/dom';
+ *
+ * const button = query<HTMLButtonElement>('#my-button');
+ * button?.click();
+ * ```
+ */
+export declare function query<T extends Element = Element>(selector: string, root?: Element | Document): T | null;
+/**
+ * Queries all matching elements with type safety
+ *
+ * @template T - Element type
+ * @param {string} selector - CSS selector
+ * @param {Element | Document} root - Root element (default: document)
+ * @returns {T[]} Array of matching elements
+ *
+ * @example
+ * ```typescript
+ * import { queryAll } from '@fluixi/core/dom';
+ *
+ * const buttons = queryAll<HTMLButtonElement>('button');
+ * buttons.forEach(btn => btn.disabled = true);
+ * ```
+ */
+export declare function queryAll<T extends Element = Element>(selector: string, root?: Element | Document): T[];
+/**
+ * Queries the closest matching ancestor element
+ *
+ * @template T - Element type
+ * @param {Element} element - Starting element
+ * @param {string} selector - CSS selector
+ * @returns {T | null} Closest matching ancestor or null
+ *
+ * @example
+ * ```typescript
+ * import { closest } from '@fluixi/core/dom';
+ *
+ * const form = closest<HTMLFormElement>(button, 'form');
+ * form?.submit();
+ * ```
+ */
+export declare function closest<T extends Element = Element>(element: Element, selector: string): T | null;
+/**
+ * Adds one or more classes to an element
+ *
+ * @param {Element} element - Target element
+ * @param {...string} classes - Classes to add
+ *
+ * @example
+ * ```typescript
+ * import { addClass } from '@fluixi/core/dom';
+ *
+ * addClass(element, 'active', 'visible');
+ * ```
+ */
+export declare function addClass(element: Element, ...classes: string[]): void;
+/**
+ * Removes one or more classes from an element
+ *
+ * @param {Element} element - Target element
+ * @param {...string} classes - Classes to remove
+ *
+ * @example
+ * ```typescript
+ * import { removeClass } from '@fluixi/core/dom';
+ *
+ * removeClass(element, 'active', 'visible');
+ * ```
+ */
+export declare function removeClass(element: Element, ...classes: string[]): void;
+/**
+ * Toggles one or more classes on an element
+ *
+ * @param {Element} element - Target element
+ * @param {...string} classes - Classes to toggle
+ *
+ * @example
+ * ```typescript
+ * import { toggleClass } from '@fluixi/core/dom';
+ *
+ * toggleClass(element, 'active');
+ * ```
+ */
+export declare function toggleClass(element: Element, ...classes: string[]): void;
+/**
+ * Checks if element has a class
+ *
+ * @param {Element} element - Target element
+ * @param {string} className - Class name to check
+ * @returns {boolean} True if element has the class
+ *
+ * @example
+ * ```typescript
+ * import { hasClass } from '@fluixi/core/dom';
+ *
+ * if (hasClass(element, 'active')) {
+ *   console.log('Element is active');
+ * }
+ * ```
+ */
+export declare function hasClass(element: Element, className: string): boolean;
+/**
+ * Sets an attribute on an element
+ *
+ * @param {Element} element - Target element
+ * @param {string} name - Attribute name
+ * @param {string | number | boolean} value - Attribute value
+ *
+ * @example
+ * ```typescript
+ * import { setAttribute } from '@fluixi/core/dom';
+ *
+ * setAttribute(input, 'disabled', true);
+ * setAttribute(div, 'data-id', '123');
+ * ```
+ */
+export declare function setAttribute(element: Element, name: string, value: unknown, isSVG?: boolean): void;
+/**
+ * Gets an attribute from an element
+ *
+ * @param {Element} element - Target element
+ * @param {string} name - Attribute name
+ * @returns {string | null} Attribute value or null
+ *
+ * @example
+ * ```typescript
+ * import { getAttribute } from '@fluixi/core/dom';
+ *
+ * const id = getAttribute(div, 'data-id');
+ * ```
+ */
+export declare function getAttribute(element: Element, name: string): string | null;
+/**
+ * Removes an attribute from an element
+ *
+ * @param {Element} element - Target element
+ * @param {string} name - Attribute name
+ *
+ * @example
+ * ```typescript
+ * import { removeAttribute } from '@fluixi/core/dom';
+ *
+ * removeAttribute(input, 'disabled');
+ * ```
+ */
+export declare function removeAttribute(element: Element, name: string): void;
+/**
+ * Sets multiple styles on an element
+ *
+ * @param {HTMLElement} element - Target element
+ * @param {Partial<CSSStyleDeclaration>} styles - Styles object
+ *
+ * @example
+ * ```typescript
+ * import { setStyles } from '@fluixi/core/dom';
+ *
+ * setStyles(div, {
+ *   backgroundColor: 'red',
+ *   padding: '10px',
+ *   display: 'flex'
+ * });
+ * ```
+ */
+export declare function setStyles(element: any, styles: Partial<CSSStyleDeclaration>): void;
+/**
+ * Gets computed style of an element
+ *
+ * @param {Element} element - Target element
+ * @param {string} property - CSS property name
+ * @returns {string} Computed style value
+ *
+ * @example
+ * ```typescript
+ * import { getStyle } from '@fluixi/core/dom';
+ *
+ * const color = getStyle(div, 'backgroundColor');
+ * ```
+ */
+export declare function getStyle(element: Element, property: string): string;
+/**
+ * Creates an element with attributes and children
+ *
+ * @template K - Element tag name
+ * @param {K} tagName - HTML tag name
+ * @param {Record<string, any>} attributes - Element attributes
+ * @param {...(Node | string)} children - Child nodes or text
+ * @returns {HTMLElementTagNameMap[K]} Created element
+ *
+ * @example
+ * ```typescript
+ * import { createElement } from '@fluixi/core/dom';
+ *
+ * const button = createElement('button',
+ *   { class: 'btn', disabled: true },
+ *   'Click me'
+ * );
+ * ```
+ */
+export declare function createElement<K extends keyof HTMLElementTagNameMap>(tagName: K, attributes?: Record<string, any>, ...children: (Node | string)[]): HTMLElementTagNameMap[K];
+/**
+ * Removes all children from an element
+ *
+ * @param {Element} element - Target element
+ *
+ * @example
+ * ```typescript
+ * import { removeChildren } from '@fluixi/core/dom';
+ *
+ * removeChildren(container);
+ * ```
+ */
+export declare function removeChildren(element: Element): void;
+/**
+ * Appends multiple children to an element
+ *
+ * @param {Element} parent - Parent element
+ * @param {...(Node | string)} children - Children to append
+ *
+ * @example
+ * ```typescript
+ * import { appendChildren } from '@fluixi/core/dom';
+ *
+ * appendChildren(container,
+ *   createElement('div', {}, 'Child 1'),
+ *   'Text node',
+ *   createElement('span', {}, 'Child 2')
+ * );
+ * ```
+ */
+export declare function appendChildren(parent: Element, ...children: (Node | string)[]): void;
+/**
+ * Checks if element is visible in the viewport
+ *
+ * @param {Element} element - Target element
+ * @returns {boolean} True if element is visible
+ *
+ * @example
+ * ```typescript
+ * import { isVisible } from '@fluixi/core/dom';
+ *
+ * if (isVisible(element)) {
+ *   console.log('Element is in viewport');
+ * }
+ * ```
+ */
+export declare function isVisible(element: Element): boolean;
+/**
+ * Scrolls element into view smoothly
+ *
+ * @param {Element} element - Target element
+ * @param {ScrollIntoViewOptions} options - Scroll options
+ *
+ * @example
+ * ```typescript
+ * import { scrollIntoView } from '@fluixi/core/dom';
+ *
+ * scrollIntoView(element, { behavior: 'smooth', block: 'center' });
+ * ```
+ */
+export declare function scrollIntoView(element: Element, options?: ScrollIntoViewOptions): void;
+/**
+ * Gets element's offset relative to document
+ *
+ * @param {Element} element - Target element
+ * @returns {{ top: number; left: number }} Offset coordinates
+ *
+ * @example
+ * ```typescript
+ * import { getOffset } from '@fluixi/core/dom';
+ *
+ * const { top, left } = getOffset(element);
+ * ```
+ */
+export declare function getOffset(element: Element): {
+    top: number;
+    left: number;
+};
+/**
+ * Delegates event handling to a parent element
+ *
+ * @template K - Event type
+ * @param {Element} parent - Parent element
+ * @param {K} eventName - Event name
+ * @param {string} selector - Child selector
+ * @param {(event: Event, target: Element) => void} handler - Event handler
+ * @returns {() => void} Cleanup function
+ *
+ * @example
+ * ```typescript
+ * import { delegate } from '@fluixi/core/dom';
+ *
+ * const cleanup = delegate(list, 'click', '.item', (event, target) => {
+ *   console.log('Clicked item:', target);
+ * });
+ * ```
+ */
+export declare function delegate<K extends keyof HTMLElementEventMap>(parent: Element, eventName: K, selector: string, handler: (event: HTMLElementEventMap[K], target: Element) => void): () => void;
+/**
+ * Waits for an element to appear in the DOM
+ *
+ * @param {string} selector - CSS selector
+ * @param {number} timeout - Timeout in milliseconds (default: 5000)
+ * @returns {Promise<Element>} Promise that resolves with the element
+ *
+ * @example
+ * ```typescript
+ * import { waitForElement } from '@fluixi/core/dom';
+ *
+ * const element = await waitForElement('#dynamic-content');
+ * ```
+ */
+export declare function waitForElement(selector: string, timeout?: number): Promise<Element>;
+/**
+ * Observes element intersection with viewport
+ *
+ * @param {Element} element - Target element
+ * @param {(isIntersecting: boolean) => void} callback - Callback function
+ * @param {IntersectionObserverInit} options - Observer options
+ * @returns {() => void} Cleanup function
+ *
+ * @example
+ * ```typescript
+ * import { observeIntersection } from '@fluixi/core/dom';
+ *
+ * const cleanup = observeIntersection(element, (isIntersecting) => {
+ *   console.log('Element visible:', isIntersecting);
+ * });
+ * ```
+ */
+export declare function observeIntersection(element: Element, callback: (isIntersecting: boolean) => void, options?: IntersectionObserverInit): () => void;
+/**
+ * Observes element size changes
+ *
+ * @param {Element} element - Target element
+ * @param {(entry: ResizeObserverEntry) => void} callback - Callback function
+ * @returns {() => void} Cleanup function
+ *
+ * @example
+ * ```typescript
+ * import { observeResize } from '@fluixi/core/dom';
+ *
+ * const cleanup = observeResize(element, (entry) => {
+ *   console.log('New size:', entry.contentRect.width, entry.contentRect.height);
+ * });
+ * ```
+ */
+export declare function observeResize(element: Element, callback: (entry: ResizeObserverEntry) => void): () => void;
+export declare function isReactElement(value: any): boolean;
+export declare function isLitTemplateResult(value: any): boolean;
+export declare function isTemplateFactory(value: any): boolean;
+export declare function isJSXTemplate(value: any): boolean;
+export declare function isDOMNode(value: any): value is Node;
+export declare function registerGlobal(key: string, value: any, _Key?: string): void;
+export declare function getGlobal(key: string, value?: any, _Key?: string): any;
+//# sourceMappingURL=utils.d.ts.map

package/dist/lib/dom/utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../../src/lib/dom/utils.ts"],"names":[],"mappings":"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"}