@but212/atom-effect-jquery 0.30.1 → 0.32.0

package/dist/types.d.ts

@@ -0,0 +1,476 @@
+import { AtomOptions as BaseAtomOptions, ComputedAtom, ComputedOptions, Dependency, EffectObject, MergedDependencyValue, ReadonlyAtom, WritableAtom } from '@but212/atom-effect';
+/** A function that performs cleanup tasks for a reactive effect or component. */
+export type EffectCleanup = () => void;
+/** Represents the unmounting phase of a component's lifecycle. */
+export interface ComponentLifecycle {
+    /** Cleanup task executed during the unmount phase. */
+    unmount: EffectCleanup;
+}
+/** The result of a reactive effect function, which may include cleanup logic. */
+export type EffectResult = undefined | EffectCleanup | ComponentLifecycle;
+/** A function used to determine equality between two reactive values. */
+export type EqualFn<T> = (a: T, b: T) => boolean;
+/**
+ * Configuration options for creating reactive atoms.
+ *
+ * @public
+ */
+export interface AtomOptions extends BaseAtomOptions {
+    /** Optional name for debugging and diagnostic purposes. */
+    name?: string;
+    /** Whether to trigger updates synchronously. Default is false (batched). */
+    sync?: boolean;
+}
+/**
+ * A value that can be a static literal, a reactive atom, or a getter function.
+ *
+ * Logic: Polymorphic Input
+ * Supports raw values for static initialization, reactive atoms for state-driven
+ * updates, or functional getters for deferred execution of complex logic.
+ *
+ * @public
+ */
+export type ReactiveValue<T> = T | ReadonlyAtom<T> | (() => T);
+/**
+ * A value that can be a static literal, a reactive atom, a promise, or a getter
+ * function that returns any of these.
+ *
+ * When to use:
+ * - CSS or Attribute bindings that require data from an asynchronous source.
+ * - Integration with fetch-based reactive atoms where values resolve over time.
+ *
+ * @public
+ */
+export type AsyncReactiveValue<T> = T | ReadonlyAtom<T | Promise<T>> | Promise<T> | (() => T | Promise<T>);
+/** Supported primitive types for attribute and property bindings. */
+export type PrimitiveValue = string | number | boolean | null | undefined;
+/** A CSS property value or a tuple containing a value and its unit (e.g., [10, 'px']). */
+export type CssValue = AsyncReactiveValue<string | number> | [source: AsyncReactiveValue<number>, unit: string];
+/** A mapping of CSS property names to their reactive values. */
+export type CssBindings = Record<string, CssValue>;
+/**
+ * Declaration of reactive bindings for a DOM element.
+ *
+ * Logic: Binding Strategy Map
+ * Maps reactive sources to specific DOM manipulation strategies (text, class,
+ * val, etc.). This declarative structure allows the engine to batch updates
+ * and optimize resource cleanup automatically.
+ *
+ * @public
+ */
+export interface BindingOptions<T = unknown> {
+    /** Binds the element's text content. Can include an optional formatter. */
+    text?: AsyncReactiveValue<unknown> | [source: AsyncReactiveValue<unknown>, formatter: (v: unknown) => string];
+    /** Binds the element's inner HTML. Use with caution for untrusted content. */
+    html?: AsyncReactiveValue<string>;
+    /** Toggles CSS classes based on reactive conditions. */
+    class?: Record<string, AsyncReactiveValue<boolean>>;
+    /** Binds CSS styles reactively. */
+    css?: CssBindings;
+    /** Binds HTML attributes reactively. */
+    attr?: Record<string, AsyncReactiveValue<PrimitiveValue>>;
+    /** Binds DOM properties reactively. */
+    prop?: Record<string, AsyncReactiveValue<unknown>>;
+    /** Toggles element visibility (`display: block/none`) based on a condition. */
+    show?: AsyncReactiveValue<boolean>;
+    /** Hides the element (`display: none`) when the condition is true. */
+    hide?: AsyncReactiveValue<boolean>;
+    /** Two-way binding for form input values. */
+    val?: WritableAtom<T> | [atom: WritableAtom<T>, options: ValOptions<T>];
+    /** Two-way binding for checkbox and radio checked states. */
+    checked?: WritableAtom<boolean>;
+    /** Orchestrates two-way bindings for an entire form element. */
+    form?: WritableAtom<T extends object ? T : unknown> | [
+        atom: WritableAtom<T extends object ? T : unknown>,
+        options: FormOptions<T extends object ? T : unknown>
+    ];
+    /** Registers event listeners with automatic lifecycle management. */
+    on?: Record<string, (e: JQuery.Event) => void>;
+}
+/** A writable atom that includes an explicit disposal mechanism. @internal */
+export interface DisposableWritableAtom<T> extends WritableAtom<T> {
+    /** Releases all reactive resources and observers associated with the atom. */
+    dispose(): void;
+}
+/** Supported key types for identifying items in a reactive list. */
+export type ListKey = string | number;
+/** Valid return types for a list item render function. */
+export type ListRenderResult = string | Element | DocumentFragment | JQuery;
+/** A function that extracts a unique identity key from a list item. */
+export type ListKeyFn<T> = (item: T, index: number) => ListKey;
+/**
+ * Configuration options for reactive list rendering.
+ *
+ * Optimization: DOM Reconciliation
+ * Uses unique keys for identity tracking to minimize DOM churn by reordering
+ * existing elements instead of re-rendering the entire list when data changes.
+ *
+ * @public
+ */
+export interface ListOptions<T> {
+    /** The property name or function used to extract unique keys. */
+    key: keyof T | ListKeyFn<T>;
+    /** Function to generate the DOM representation for an item. */
+    render: (item: T, index: number) => ListRenderResult;
+    /** Optional callback to apply bindings to the rendered element. */
+    bind?: ($el: JQuery, item: T, index: number) => void;
+    /** Optional callback triggered when an item's data is updated. */
+    update?: ($el: JQuery, item: T, index: number) => void;
+    /** Callback triggered when a new element is added to the list. */
+    onAdd?: ($el: JQuery) => void;
+    /** Callback triggered when an element is removed (can be used for transitions). */
+    onRemove?: ($el: JQuery) => Promise<void> | void;
+    /** Content to display when the list is empty. */
+    empty?: ListRenderResult;
+    /** Event handlers bound to individual list items. */
+    events?: Record<string, (item: T, index: number, e: JQuery.TriggeredEvent) => void>;
+    /** Optional function for custom item equality checks. */
+    isEqual?: (a: T, b: T) => boolean;
+}
+/** Options for customizing two-way value bindings. */
+export interface ValOptions<T> {
+    /** Time in milliseconds to delay atom synchronization after user input. */
+    debounce?: number;
+    /** The DOM event used to trigger synchronization (e.g., 'change'). */
+    event?: string;
+    /** Function to parse the DOM string value into the atom's type. */
+    parse?: (v: string) => T;
+    /** Function to format the atom's value for DOM display. */
+    format?: (v: T) => string;
+    /** Function for custom value equality checks. */
+    equal?: EqualFn<T>;
+}
+/** Options for orchestrating form-wide reactive synchronization. */
+export interface FormOptions<T> extends ValOptions<T> {
+    /** Function to transform field values based on their object path before synchronization. */
+    transform?: (path: string, value: unknown) => unknown;
+    /** Callback triggered whenever any field in the form changes. */
+    onChange?: (path: string, value: unknown) => void;
+    /** Reactive validation schema mapping paths to validators. */
+    validation?: Record<string, (val: unknown) => string | boolean>;
+}
+/** Configuration for reactive AJAX requests. */
+export interface FetchOptions<T> {
+    /** The value returned while the request is pending or if it fails. */
+    defaultValue: T;
+    /** Optional name for debugging and diagnostic logging. */
+    name?: string;
+    /** HTTP method to use for the request. */
+    method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD' | 'OPTIONS' | (string & {});
+    /** Custom HTTP headers to include in the request. */
+    headers?: Record<string, string>;
+    /** Function to transform the raw response before it is stored in the atom. */
+    transform?: (raw: unknown, xhr: JQuery.jqXHR) => T | Promise<T>;
+    /** Direct overrides for the underlying jQuery AJAX settings. */
+    ajaxOptions?: JQuery.AjaxSettings | (() => JQuery.AjaxSettings);
+    /** Callback triggered when the request fails. */
+    onError?: (err: unknown) => void;
+    /** Whether to trigger the initial request immediately upon creation. */
+    eager?: boolean;
+}
+/** An error object containing the source jqXHR for diagnostic purposes. */
+export interface FetchError extends Error {
+    /** The underlying jQuery XHR object that caused the error. */
+    jqXHR?: JQuery.jqXHR;
+}
+/** Definition for a mountable component that manages its own reactive lifecycle. */
+export type ComponentFn<P = Record<string, unknown>> = ($el: JQuery, props: P) => EffectResult;
+/** Lifecycle hooks for navigating between application routes. */
+export interface RouteLifecycle {
+    /**
+     * Hook triggered before entering a route.
+     * Returning false aborts the navigation.
+     */
+    onEnter?: (params: Record<string, string>, router: Router) => Record<string, string> | undefined | false;
+    /**
+     * Hook triggered before leaving the current route.
+     * Returning false prevents navigation away.
+     */
+    onLeave?: (router: Router) => boolean | undefined;
+    /** Optional document title for the route. */
+    title?: string;
+    /** Optional metadata tags for the route (e.g., description, keywords). */
+    meta?: Record<string, string>;
+}
+/** Definition of a specific application route and its rendering logic. */
+export interface RouteDefinition extends RouteLifecycle {
+    /** Selector for a template fragment to be cloned and rendered. */
+    template?: string;
+    /** Custom function to render the route content into the container. */
+    render?: (container: HTMLElement, route: string, params: Record<string, string>, onUnmount: (cleanupFn: () => void) => void, router: Router) => void;
+    /** Callback triggered after the route content has been mounted to the DOM. */
+    onMount?: ($content: JQuery, onUnmount: (cleanupFn: () => void) => void, router: Router) => void;
+}
+/** Global configuration for the reactive router. */
+export interface RouteConfig {
+    /** The root element or selector where route content will be injected. */
+    target: string | JQuery<HTMLElement> | HTMLElement;
+    /** The default path to navigate to if no route matches. */
+    default?: string;
+    /** Mapping of path patterns to route definitions. */
+    routes?: Record<string, RouteDefinition>;
+    /** Synchronization mode: 'hash' or HTML5 'history' API. */
+    mode?: 'hash' | 'history';
+    /** Base path for the application (useful for history mode). */
+    basePath?: string;
+    /** Path to navigate to when a requested route is not found. */
+    notFound?: string;
+    /** Whether to automatically intercept and route link clicks. */
+    autoBindLinks?: boolean;
+    /** CSS class applied to navigation elements matching the active route. */
+    activeClass?: string;
+    /** Callback triggered immediately before a navigation transition starts. */
+    beforeTransition?: (from: string, to: string) => void;
+    /** Callback triggered after a navigation transition has completed. */
+    afterTransition?: (from: string, to: string) => void;
+}
+/** Represents a structured navigation location. */
+export interface RouteLocation {
+    /** The normalized path part of the URL. */
+    path: string;
+    /** Key-value pairs of query string parameters. */
+    query: Record<string, string>;
+    /** Extracted parameters from dynamic segments (e.g., :id). */
+    params: Record<string, string>;
+}
+/** Interface for programmatically interacting with the application router. */
+export interface Router {
+    /** Reactive atom containing the current route name. */
+    currentRoute: ReadonlyAtom<string>;
+    /** Reactive atom containing the current query string parameters. */
+    queryParams: ReadonlyAtom<Record<string, string>>;
+    /** Reactive atom containing the extracted path parameters. */
+    params: ReadonlyAtom<Record<string, string>>;
+    /** Reactive atom providing a unified snapshot of the current location. */
+    location: ReadonlyAtom<RouteLocation>;
+    /** Programmatically navigates to the specified path or location object. */
+    navigate: (to: string | Partial<RouteLocation>) => void;
+    /** Shuts down the router and releases all observers. */
+    destroy: () => void;
+}
+/** Options for AJAX-based fragment navigation. */
+export interface AtomNavOptions {
+    /** The target container for injected content. */
+    target: string | JQuery<HTMLElement> | HTMLElement;
+    /** Optional sub-selector to extract from the loaded document. */
+    selector?: string;
+    /** Custom HTTP headers for navigation requests. */
+    headers?: Record<string, string>;
+    /** Hook triggered before a navigation request is initiated. */
+    onBeforeLoad?: (url: string) => boolean | undefined | Promise<boolean | undefined>;
+    /** Callback triggered after the content has been injected. */
+    onMount?: ($container: JQuery, url: string) => void;
+    /** Callback triggered before content is replaced. */
+    onUnmount?: ($container: JQuery, oldUrl: string) => void;
+    /** Callback for handling navigation errors. */
+    onError?: (err: unknown, url: string) => boolean | undefined;
+    /** Whether to reset scroll position to the top after navigation. */
+    scrollToTop?: boolean;
+    /** Whether to synchronize the document title with the loaded page. */
+    syncTitle?: boolean;
+    /** Optional window context for cross-origin navigation. */
+    window?: Window & typeof globalThis;
+}
+/** Interface for managing AJAX fragment navigation. */
+export interface AtomNav {
+    /** Reactive atom containing the currently loaded URL. */
+    currentUrl: ReadonlyAtom<string>;
+    /** Reactive atom indicating whether a navigation request is in progress. */
+    isPending: ReadonlyAtom<boolean>;
+    /** Reactive atom indicating whether the last navigation failed. */
+    hasError: ReadonlyAtom<boolean>;
+    /** Navigates to a specific URL and replaces the container content. */
+    navigate(url: string, options?: {
+        replace?: boolean;
+    }): Promise<void>;
+    /** Disposes of the navigation manager and observers. */
+    destroy: () => void;
+}
+/**
+ * Internal state flags for two-way bindings.
+ *
+ * Logic: Feedback Loop Protection
+ * Prevents recursive update loops between the DOM and reactive atoms
+ * during two-way data flow (e.g., IME composition or rapid input events).
+ *
+ * @internal
+ */
+export declare enum BindingFlags {
+    /** No active synchronization or interaction. */
+    None = 0,
+    /** The input element is currently focused by the user. */
+    Focused = 1,
+    /** The user is currently performing IME composition. */
+    Composing = 2,
+    /** Synchronization from DOM to Atom is currently active. */
+    SyncingToAtom = 4,
+    /** Synchronization from Atom to DOM is currently active. */
+    SyncingToDom = 8,
+    /** The binding is considered busy and will ignore external updates. */
+    Busy = 14
+}
+/**
+ * Options for customizing jQuery core method overrides.
+ *
+ * @public
+ */
+export interface PatchOptions {
+    /**
+     * Automatically wraps .on()/.one() callbacks in $.batch() for reactivity.
+     * @default true
+     */
+    events?: boolean;
+    /**
+     * Hooks .remove()/.empty()/.detach() for automatic resource cleanup.
+     * @default true
+     */
+    lifecycle?: boolean;
+}
+/**
+ * Global configuration settings for the library.
+ *
+ * @public
+ */
+export interface AEJConfig {
+    /**
+     * Configuration for jQuery prototype patches.
+     * Set to false to disable all automated overrides.
+     */
+    patch?: boolean | PatchOptions;
+    /**
+     * Configuration for the automated MutationObserver cleanup system.
+     * Set to false to manage reactive resource disposal manually.
+     */
+    autoCleanup?: boolean | {
+        root: Element | ShadowRoot | DocumentFragment;
+    };
+}
+/**
+ * A scoped version of the jQuery selector function.
+ *
+ * Logic: Scope Enforcement
+ * Restricts element selection to the component's internal DOM tree (ShadowRoot
+ * or host container) to ensure encapsulation and prevent cross-component leaks.
+ *
+ * @public
+ */
+export type JQueryScopedSelector = (selector: string | JQuery | HTMLElement, context?: Element | Document | JQuery | ShadowRoot | DocumentFragment) => JQuery;
+/**
+ * Composition-based controller for managing a component's reactive lifecycle.
+ *
+ * When to use:
+ * - To build Custom Elements that require reactive attribute and slot synchronization.
+ * - To manage complex component lifecycles with automated resource disposal.
+ * - To provide or inject reactive state across Shadow DOM boundaries.
+ *
+ * @public
+ */
+export interface AtomComponentController {
+    /** The raw host element of the component. */
+    readonly host: HTMLElement;
+    /** The active root node (ShadowRoot or Host container). */
+    readonly root: Node | null;
+    /**
+     * Scoped jQuery selector.
+     * Limited to selecting elements within the component's encapsulated DOM.
+     */
+    readonly $: JQueryScopedSelector;
+    /**
+     * Factory function that returns a reactive lens atom for a specific HTML attribute.
+     * Accessing a name returns a WritableAtom<string | null>.
+     */
+    readonly attrs: (name: string) => WritableAtom<string | null>;
+    /**
+     * Factory function that returns a reactive lens atom for a specific Shadow DOM slot.
+     * Provides ReadonlyAtom<Node[]> for each named slot (or 'default' for unnamed).
+     */
+    readonly slots: (name: string) => ReadonlyAtom<Node[]>;
+    /**
+     * Access to the component's internal state and accessibility properties via ElementInternals.
+     * Available only if the browser supports attachInternals().
+     */
+    readonly internals?: ElementInternals | undefined;
+    /** Registers a reactive provider on this element for dependency injection. */
+    provideAtom<T = unknown>(key: string | symbol, val: T): void;
+    /** Injects a reactive value provided by an ancestor element. */
+    injectAtom<T = unknown>(key: string | symbol): WritableAtom<T> | null;
+    /**
+     * Initializes the component's reactive lifecycle and observers.
+     *
+     * Logic: Hybrid Options
+     * Accepts a raw ShadowRoot for traditional usage or a configuration object
+     * for declarative hydration and automatic event dispatching.
+     *
+     * @param options - ShadowRoot or configuration object for hydration and event dispatching.
+     */
+    setup(options?: ShadowRoot | {
+        shadowRoot?: ShadowRoot;
+        /** Maps event names to atoms or getter functions for automatic dispatching. */
+        dispatch?: Record<string, ReactiveValue<unknown>>;
+        /** Maps data-bind keys to atoms for declarative DOM hydration. */
+        bind?: Record<string, ReadonlyAtom<unknown>>;
+        /**
+         * Constructable stylesheets to be shared across instances.
+         * Strings are automatically converted to shared CSSStyleSheet objects.
+         */
+        styles?: (string | CSSStyleSheet)[];
+        /**
+         * Reactive accessibility bindings via AriaMixin (ElementInternals).
+         * Maps ARIA properties (e.g., 'ariaExpanded') to atoms.
+         */
+        aria?: Record<string, ReadonlyAtom<unknown>>;
+        /**
+         * Reactive CSS Part bindings.
+         * Maps element selectors or data-aej-part keys to atoms for dynamic part names.
+         */
+        parts?: Record<string, ReadonlyAtom<string | string[] | Record<string, boolean>>>;
+        /**
+         * Reactive value for Form-Associated Custom Elements (FACE).
+         * Automatically synchronized with the native <form> via internals.setFormValue().
+         */
+        value?: ReadonlyAtom<unknown> | {
+            val: ReadonlyAtom<unknown>;
+            state?: ReadonlyAtom<unknown>;
+        };
+        /**
+         * Reactive validation logic for Form-Associated Custom Elements (FACE).
+         * Can be a validation message string, a ValidityStateFlags object, or an atom/function returning either.
+         */
+        validation?: ReadonlyAtom<ValidityStateFlags | string> | ((val: unknown) => ValidityStateFlags | string);
+    }): void;
+    /**
+     * Tears down all reactive bindings and observers.
+     * Disconnects observers immediately; actual cleanup is deferred to a microtask.
+     *
+     * Logic: Cleanup Mechanism
+     * Releases all listeners, observers, and effects created during setup() or
+     * through reactive property access (attrs/slots).
+     */
+    teardown(): void;
+}
+/**
+ * Represents an HTMLElement that has been enhanced with an AEJ controller.
+ *
+ * @public
+ */
+export type AtomComponentElement<T extends HTMLElement = HTMLElement> = T & {
+    readonly aej: AtomComponentController;
+};
+/**
+ * Declarative specification for Atom-Effect components.
+ * @internal
+ */
+export interface AtomComponentStatic {
+    aejStyles?: (string | CSSStyleSheet)[];
+    aejBind?: Record<string, ReadonlyAtom<unknown>>;
+    aejAria?: Record<string, ReadonlyAtom<unknown>>;
+    aejParts?: Record<string, ReadonlyAtom<string | string[] | Record<string, boolean>>>;
+    aejDispatch?: Record<string, ReactiveValue<unknown>>;
+    aejValue?: ReadonlyAtom<unknown> | {
+        val: ReadonlyAtom<unknown>;
+        state?: ReadonlyAtom<unknown>;
+    };
+    aejValidation?: ReadonlyAtom<ValidityStateFlags | string> | ((val: unknown) => ValidityStateFlags | string);
+}
+export type { ComputedAtom, ComputedOptions, Dependency, EffectObject, MergedDependencyValue, ReadonlyAtom, WritableAtom, };
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

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

package/dist/utils/debug.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Provides visual instrumentation and diagnostic logging for the reactive system.
+ *
+ * When to use:
+ * - To debug reactive updates and DOM mutations in real-time.
+ * - To inspect error causes and stack traces within binding hooks.
+ *
+ * Logic: Runtime Control
+ * The `debug.enabled` flag can be toggled at runtime (e.g., via the browser console)
+ * to activate or deactivate visual instrumentation without requiring a page reload.
+ *
+ * @example
+ * ```typescript
+ * // Enable visual highlights for DOM updates
+ * $.debug.enabled = true;
+ * ```
+ */
+export declare const debug: {
+    /** Global toggle for the debug system. */
+    enabled: boolean;
+    /** Logs a warning message with the standardized library prefix. */
+    warn: (prefix: string, message: string, ...rest: unknown[]) => void;
+    /** Logs an error with the standardized library prefix and the associated cause. */
+    error: (prefix: string, message: string, cause: unknown) => void;
+    /**
+     * Logs a DOM mutation and triggers a visual highlight on the target element.
+     *
+     * Logic: Mutation Tracking
+     * When enabled, this method logs the property change and its new value to
+     * the console, followed by a "flash" effect on the element to assist in
+     * identifying the source of the mutation.
+     *
+     * @param prefix - The logging prefix.
+     * @param target - The DOM element or JQuery collection that was updated.
+     * @param type - The type of mutation (e.g., 'text', 'html', 'attr').
+     * @param value - The new value applied to the target.
+     */
+    domUpdated(prefix: string, target: Element | JQuery, type: string, value: unknown): void;
+};
+//# sourceMappingURL=debug.d.ts.map

package/dist/utils/debug.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"debug.d.ts","sourceRoot":"","sources":["../../src/utils/debug.ts"],"names":[],"mappings":"AA0EA;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,KAAK;IAChB,0CAA0C;;IAG1C,mEAAmE;mBACpD,MAAM,WAAW,MAAM,WAAW,OAAO,EAAE;IAG1D,mFAAmF;oBACnE,MAAM,WAAW,MAAM,SAAS,OAAO;IAGvD;;;;;;;;;;;;OAYG;uBACgB,MAAM,UAAU,OAAO,GAAG,MAAM,QAAQ,MAAM,SAAS,OAAO;CAUlF,CAAC"}

package/dist/utils/index.d.ts

@@ -0,0 +1,51 @@
+import { RouteDefinition } from '../types';
+/**
+ * Determines if a value is a Promise or a thenable object.
+ *
+ * Logic: Duck-Typing
+ * Uses a standard thenable check to identify asynchronous objects across
+ * different implementation libraries.
+ *
+ * @internal
+ */
+export declare const isPromise: <T>(v: unknown) => v is Promise<T>;
+/**
+ * Generates a concise, human-readable CSS selector for a DOM element.
+ *
+ * Logic: Element Signature
+ * Prioritizes tag names, IDs, and class lists to create a reference string
+ * for debugging and diagnostic logging.
+ *
+ * Caution: SVG Compatibility
+ * SVG elements use `SVGAnimatedString` for the `className` property. This
+ * method detects and unpacks `baseVal` to ensure consistent selector
+ * generation across HTML and SVG namespaces.
+ *
+ * @internal
+ */
+export declare function getSelector(el: Element): string;
+/**
+ * Determines if a route is defined by a template selector.
+ * @internal
+ */
+export declare const isTemplateRoute: (r: RouteDefinition) => boolean;
+/**
+ * Determines if a route is defined by a custom render function.
+ * @internal
+ */
+export declare const isRenderRoute: (r: RouteDefinition) => boolean;
+/**
+ * Recursively flattens an object into a FormData instance.
+ *
+ * Logic: Nested Naming
+ * Converts nested structures into bracket-notation strings (e.g., 'user[profile][name]')
+ * to ensure compatibility with standard form parsers in most backend frameworks.
+ *
+ * @param fd - The FormData instance to populate.
+ * @param prefix - The name prefix for the current path.
+ * @param obj - The value to flatten.
+ *
+ * @internal
+ */
+export declare function flattenToFormData(fd: FormData, prefix: string, obj: unknown): void;
+//# sourceMappingURL=index.d.ts.map

package/dist/utils/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAE/C;;;;;;;;GAQG;AACH,eAAO,MAAM,SAAS,GAAI,CAAC,EAAE,GAAG,OAAO,KAAG,CAAC,IAAI,OAAO,CAAC,CAAC,CAGN,CAAC;AAEnD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,WAAW,CAAC,EAAE,EAAE,OAAO,GAAG,MAAM,CAyB/C;AAED;;;GAGG;AACH,eAAO,MAAM,eAAe,GAAI,GAAG,eAAe,KAAG,OACkB,CAAC;AAExE;;;GAGG;AACH,eAAO,MAAM,aAAa,GAAI,GAAG,eAAe,KAAG,OACoB,CAAC;AAExE;;;;;;;;;;;;GAYG;AACH,wBAAgB,iBAAiB,CAAC,EAAE,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,OAAO,GAAG,IAAI,CASlF"}

package/dist/utils/sanitize.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Configuration for the HTML sanitization engine.
+ */
+export interface SanitizationPolicy {
+    /** List of attribute names whose values should be validated as URIs. */
+    readonly urlAttributes: string[];
+    /** List of element local names that should be neutralized or stripped. */
+    readonly blacklistedTags: string[];
+}
+/**
+ * The standard sanitization policy used by the library.
+ *
+ * Logic: Strict Isolation
+ * Targets executable elements (script, iframe), metadata (base, meta),
+ * and layout-breaking tags (body, title).
+ */
+export declare const DEFAULT_POLICY: SanitizationPolicy;
+/**
+ * Sanitizes an HTML string based on a security policy.
+ *
+ * When to use:
+ * - Before injecting untrusted HTML content into the DOM via `atomHtml` or jQuery methods.
+ * - To filter potentially malicious attributes, event handlers, and active scripts.
+ *
+ * @param html The raw HTML string to be sanitized.
+ * @param policy Custom sanitization policy. Defaults to `DEFAULT_POLICY`.
+ *
+ * @returns A safe HTML string with dangerous elements neutralized and attributes scrubbed.
+ *
+ * @example
+ * const safeHtml = sanitizeHtml('<img src=x onerror=alert(1)>');
+ * // Returns: '<img src="x" data-unsafe-attr="onerror">'
+ */
+export declare function sanitizeHtml(html: string | null | undefined, policy?: SanitizationPolicy): string;
+/**
+ * Validates if a specific attribute/value pair is considered dangerous under the policy.
+ *
+ * @param attr The attribute name to check.
+ * @param val The value to validate.
+ * @param policy The policy defining URL-carrying attributes.
+ *
+ * @returns True if the value contains a dangerous protocol or is a restricted sink.
+ */
+export declare const isDangerousUrl: (attr: string, val: string, policy?: SanitizationPolicy) => boolean;
+/**
+ * Validates if a CSS value contains dangerous patterns.
+ *
+ * @param val The CSS property value to check.
+ * @returns True if dangerous patterns (e.g., expression, javascript) are detected.
+ */
+export declare const isDangerousCssValue: (val: string) => boolean;
+//# sourceMappingURL=sanitize.d.ts.map

package/dist/utils/sanitize.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sanitize.d.ts","sourceRoot":"","sources":["../../src/utils/sanitize.ts"],"names":[],"mappings":"AAEA;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,wEAAwE;IACxE,QAAQ,CAAC,aAAa,EAAE,MAAM,EAAE,CAAC;IACjC,0EAA0E;IAC1E,QAAQ,CAAC,eAAe,EAAE,MAAM,EAAE,CAAC;CACpC;AAED;;;;;;GAMG;AACH,eAAO,MAAM,cAAc,EAAE,kBAwC5B,CAAC;AAsXF;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,YAAY,CAC1B,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EAC/B,MAAM,GAAE,kBAAmC,GAC1C,MAAM,CAGR;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,cAAc,GACzB,MAAM,MAAM,EACZ,KAAK,MAAM,EACX,SAAQ,kBAAmC,KAC1C,OAGF,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,GAAI,KAAK,MAAM,KAAG,OAAoC,CAAC"}