@but212/atom-effect-jquery 0.30.1 → 0.32.0

package/dist/features/route/index.d.ts

@@ -0,0 +1,43 @@
+import { RouteConfig, Router } from '../../types';
+/**
+ * Initializes a reactive router for synchronizing URL state with DOM views.
+ *
+ * When to use:
+ * - Invoke during application bootstrap to define your routing manifest
+ *   and bind a target container for dynamic content rendering.
+ *
+ * Logic: Reactive Routing
+ * This manager orchestrates URL synchronization, path matching, and dynamic
+ * view rendering. It exposes reactive atoms (`currentRoute`, `params`)
+ * allowing the rest of your UI to respond automatically to navigation changes.
+ *
+ * Capabilities:
+ * - Multi-mode support: Modern 'history' (clean URLs) or 'hash' for legacy/static hosting.
+ * - Dynamic matching: High-performance parameter extraction for named segments.
+ * - Lifecycle guards: Navigation control via `onEnter` and `onLeave` hooks.
+ * - Accessibility: Built-in focus management for Screen Readers on route transitions.
+ *
+ * @param config - Configuration for routes, target containers, and lifecycle hooks.
+ * @returns A router interface for programmatic control and state monitoring.
+ *
+ * @example
+ * ```typescript
+ * const router = $.route({
+ *   target: '#app-root',
+ *   routes: {
+ *     '/': { template: '#home-tmpl' },
+ *     '/user/:id': {
+ *       onEnter: (params) => console.log('Entering user:', params.id),
+ *       render: (el, name, params) => {
+ *         $(el).text(`User Profile: ${params.id}`);
+ *       }
+ *     }
+ *   }
+ * });
+ *
+ * // Programmatic navigation
+ * router.navigate('/user/42');
+ * ```
+ */
+export declare function route(config: RouteConfig): Router;
+//# sourceMappingURL=index.d.ts.map

package/dist/features/route/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/features/route/index.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AAGnD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,wBAAgB,KAAK,CAAC,MAAM,EAAE,WAAW,GAAG,MAAM,CAEjD"}

package/dist/features/route/router.d.ts

@@ -0,0 +1,74 @@
+import { ReadonlyAtom } from '@but212/atom-effect';
+import { RouteConfig, RouteLocation, Router } from '../../types';
+/**
+ * Concrete implementation of the Router interface.
+ * Coordinates the transition from URL intent to rendered view.
+ */
+export declare class RouterImpl implements Router {
+    readonly location: ReadonlyAtom<RouteLocation>;
+    readonly currentRoute: ReadonlyAtom<string>;
+    readonly queryParams: ReadonlyAtom<Record<string, string>>;
+    readonly params: ReadonlyAtom<Record<string, string>>;
+    private readonly matcher;
+    private readonly config;
+    private readonly urlAdapter;
+    private readonly $target;
+    private readonly scanner;
+    private readonly renderer;
+    private readonly currentRouteAtom;
+    private readonly queryParamsAtom;
+    private readonly paramsAtom;
+    /**
+     * Logic: Internal State Management
+     * Tracks transient flags and metadata that are hidden from the public API
+     * to ensure stable transitions and prevent feedback loops.
+     */
+    private readonly stateAtom;
+    private readonly cleanups;
+    /**
+     * The public context object passed to route guards and lifecycle hooks.
+     * Defined as a separate object to maintain interface compatibility.
+     */
+    private readonly context;
+    constructor(config: RouteConfig);
+    /**
+     * Logic: Lifecycle Orchestration
+     * Establishes the reactive bridge between the URL adapter and the renderer.
+     */
+    private setupLifecycle;
+    private updateState;
+    /**
+     * Programmatically transitions the application to a new location.
+     *
+     * When to use:
+     * - Triggered by user clicks or script-driven navigation logic.
+     *
+     * Caution:
+     * - Navigation will be aborted if the current route's `onLeave` guard returns `false`.
+     *
+     * @example
+     * router.navigate('/user/123', { debug: 'true' });
+     */
+    navigate(to: string | Partial<RouteLocation>, query?: Record<string, string>): Promise<void>;
+    /**
+     * Logic: Browser State Synchronization
+     * Handles external URL changes (e.g., Back/Forward button) and ensures
+     * they are validated against route guards before adoption.
+     */
+    private handleBrowserSync;
+    /**
+     * Logic: Internal Rendering Dispatch
+     * Resolves the route definition and delegates DOM manipulation to the renderer.
+     */
+    private render;
+    /**
+     * Executes the unmount guard for the current route.
+     */
+    private canLeave;
+    /**
+     * Cleanup: Resource Disposal
+     * Terminates all reactive effects, unbinds global listeners, and releases DOM references.
+     */
+    destroy(): void;
+}
+//# sourceMappingURL=router.d.ts.map

package/dist/features/route/router.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"router.d.ts","sourceRoot":"","sources":["../../../src/features/route/router.ts"],"names":[],"mappings":"AAAA,OAAO,EAKL,KAAK,YAAY,EAElB,MAAM,qBAAqB,CAAC;AAM7B,OAAO,KAAK,EAAE,WAAW,EAAmB,aAAa,EAAE,MAAM,EAAgB,MAAM,SAAS,CAAC;AAqBjG;;;GAGG;AACH,qBAAa,UAAW,YAAW,MAAM;IACvC,SAAgB,QAAQ,EAAE,YAAY,CAAC,aAAa,CAAC,CAAC;IACtD,SAAgB,YAAY,EAAE,YAAY,CAAC,MAAM,CAAC,CAAC;IACnD,SAAgB,WAAW,EAAE,YAAY,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IAClE,SAAgB,MAAM,EAAE,YAAY,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IAE7D,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAe;IACvC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAsE;IAC7F,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAmC;IAC9D,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAsB;IAE9C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAe;IACvC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAgB;IAEzC,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAuB;IACxD,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAuC;IACvE,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAuC;IAElE;;;;OAIG;IACH,OAAO,CAAC,QAAQ,CAAC,SAAS,CAKvB;IAEH,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAgC;IAEzD;;;OAGG;IACH,OAAO,CAAC,QAAQ,CAAC,OAAO,CAWtB;gBAEU,MAAM,EAAE,WAAW;IA6E/B;;;OAGG;IACH,OAAO,CAAC,cAAc;IAiCtB,OAAO,CAAC,WAAW;IAanB;;;;;;;;;;;OAWG;IACU,QAAQ,CACnB,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC,EACnC,KAAK,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAM,GACjC,OAAO,CAAC,IAAI,CAAC;IA+ChB;;;;OAIG;IACH,OAAO,CAAC,iBAAiB;IA0CzB;;;OAGG;IACH,OAAO,CAAC,MAAM;IAqBd;;OAEG;IACH,OAAO,CAAC,QAAQ;IAMhB;;;OAGG;IACI,OAAO,IAAI,IAAI;CAQvB"}

package/dist/features/route/types.d.ts

@@ -0,0 +1,60 @@
+import { Option } from '@but212/atom-effect-utils';
+import { RouteDefinition } from '../../types';
+/**
+ * Represents the current parsed state of a URL.
+ *
+ * Logic: Data Contract
+ * Provides an immutable snapshot used to bridge the gap between browser-specific
+ * URL states and the router's internal reactive state.
+ */
+export type URLState = {
+    readonly path: string;
+    readonly query: Record<string, string>;
+    readonly url: string;
+};
+/**
+ * Interface for browser URL interaction.
+ *
+ * Logic: State Adaptation
+ * Abstracting History and Hash behavior behind this interface allows the router
+ * to remain agnostic of the underlying URL strategy.
+ */
+export interface UrlAdapter {
+    /** Retrieves the current path and query from the browser. */
+    readonly get: (base: string) => URLState;
+    /** Updates the browser URL and returns the new state. */
+    readonly commit: (fullPath: string, base: string) => URLState;
+    /** Rolls back the browser URL to a previous state (used when navigation is rejected). */
+    readonly revert: (previousUrl: string) => void;
+    /** Resolves an anchor element's destination relative to the base path. */
+    readonly resolveAnchor: (el: Element, base: string) => string;
+    /** Sets up a listener for browser navigation events (popstate or hashchange). */
+    readonly setupListener: (handler: () => void) => () => void;
+}
+/**
+ * Internal metadata for a compiled route pattern.
+ */
+export interface CompiledRoute {
+    readonly pattern: string;
+    readonly def: RouteDefinition;
+}
+/**
+ * Outcome of a route matching operation.
+ *
+ * Logic: Polymorphic Result
+ * Uses the `Option` type to represent a successful match with params or a miss.
+ */
+export type MatchResult = Option<{
+    readonly route: CompiledRoute;
+    readonly params: Record<string, string>;
+}>;
+/**
+ * A single entry in the route matcher containing both metadata and matching logic.
+ */
+export interface MatchEntry {
+    readonly pattern: string;
+    readonly def: RouteDefinition;
+    /** Executes the matching logic against a given path. */
+    readonly match: (path: string) => MatchResult;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/features/route/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/features/route/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,2BAA2B,CAAC;AACxD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAE/C;;;;;;GAMG;AACH,MAAM,MAAM,QAAQ,GAAG;IACrB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACvC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;CACtB,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,WAAW,UAAU;IACzB,6DAA6D;IAC7D,QAAQ,CAAC,GAAG,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,QAAQ,CAAC;IAEzC,yDAAyD;IACzD,QAAQ,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,KAAK,QAAQ,CAAC;IAE9D,yFAAyF;IACzF,QAAQ,CAAC,MAAM,EAAE,CAAC,WAAW,EAAE,MAAM,KAAK,IAAI,CAAC;IAE/C,0EAA0E;IAC1E,QAAQ,CAAC,aAAa,EAAE,CAAC,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,KAAK,MAAM,CAAC;IAE9D,iFAAiF;IACjF,QAAQ,CAAC,aAAa,EAAE,CAAC,OAAO,EAAE,MAAM,IAAI,KAAK,MAAM,IAAI,CAAC;CAC7D;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,GAAG,EAAE,eAAe,CAAC;CAC/B;AAED;;;;;GAKG;AACH,MAAM,MAAM,WAAW,GAAG,MAAM,CAAC;IAC/B,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC;IAC9B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACzC,CAAC,CAAC;AAEH;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,GAAG,EAAE,eAAe,CAAC;IAE9B,wDAAwD;IACxD,QAAQ,CAAC,KAAK,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,WAAW,CAAC;CAC/C"}

package/dist/features/route/view.d.ts

@@ -0,0 +1,116 @@
+import { ReadonlyAtom } from '@but212/atom-effect';
+import { SlotBuffer } from '@but212/atom-effect-utils';
+import { RouteConfig, RouteDefinition, Router } from '../../types';
+import { createAdapter, RouteMatcher } from './core';
+/**
+ * State container for a specific routing target.
+ */
+export interface RouteRenderer {
+    $target: JQuery<HTMLElement>;
+    config: Required<RouteConfig> & {
+        routes: Record<string, RouteDefinition>;
+    };
+    urlAdapter: ReturnType<typeof createAdapter>;
+    cleanups: SlotBuffer<() => void>;
+    previousPath: string;
+}
+/**
+ * Initializes a renderer state for a target element.
+ */
+export declare function createRouteRenderer($target: JQuery<HTMLElement>, config: Required<RouteConfig> & {
+    routes: Record<string, RouteDefinition>;
+}, urlAdapter: ReturnType<typeof createAdapter>): RouteRenderer;
+/**
+ * Orchestrates the transition between views within a target container.
+ *
+ * When to use:
+ * - Invoked by the router whenever a route match is confirmed.
+ *
+ * Logic: View Update Pipeline
+ * 1. Synchronizes document metadata (Title/Meta).
+ * 2. Clears the container and triggers previous view cleanups.
+ * 3. Renders the new content using the defined strategy.
+ * 4. Manages focus and scroll for Accessibility compliance.
+ *
+ * @example
+ * renderRoute(renderer, homeDef, '/home', {}, routerInstance);
+ */
+export declare function renderRoute(renderer: RouteRenderer, def: RouteDefinition, routeName: string, params: Record<string, string>, router: Router): void;
+/**
+ * Disposes of all resources and effects bound to the current route view.
+ */
+export declare function runRendererCleanups(renderer: RouteRenderer): void;
+/**
+ * State container for the navigation link tracker.
+ */
+export interface RouteScanner {
+    config: Required<RouteConfig> & {
+        routes: Record<string, RouteDefinition>;
+    };
+    matcher: RouteMatcher;
+    urlAdapter: ReturnType<typeof createAdapter>;
+    activeClass: string;
+    trackedLinks: Set<Element>;
+    pathCache: WeakMap<Element, string>;
+    activeStateCache: WeakMap<Element, boolean>;
+    linkObserver?: MutationObserver;
+}
+/**
+ * Creates a scanner that tracks elements to apply "active" CSS classes.
+ */
+export declare function createRouteScanner(config: Required<RouteConfig> & {
+    routes: Record<string, RouteDefinition>;
+}, matcher: RouteMatcher, urlAdapter: ReturnType<typeof createAdapter>, activeClass: string): RouteScanner;
+/**
+ * Initializes reactive tracking for navigation links across the entire document.
+ *
+ * When to use:
+ * - Call once during application bootstrap to enable automatic "active" link styling.
+ *
+ * Logic: Link Lifecycle Management
+ * 1. Uses MutationObserver to detect links injected via AJAX or templates.
+ * 2. Binds reactive effects to each link to toggle classes based on the current atom state.
+ * 3. Automatically cleans up effects when elements are removed from the DOM.
+ *
+ * @param scanner - The scanner state.
+ * @param currentRouteAtom - The reactive atom containing the current path.
+ *
+ * @example
+ * setupRouteScanner(scanner, router.current);
+ */
+export declare function setupRouteScanner(scanner: RouteScanner, currentRouteAtom: ReadonlyAtom<string>): {
+    scan: () => void;
+    resolvePath: (el: Element, stripQuery?: boolean) => string;
+};
+/**
+ * Scans the initial DOM for declarative route definitions.
+ *
+ * Logic: Declarative Route Manifest Discovery
+ * Extracts route definitions from `<template data-path="...">` tags.
+ * This allows defining the application structure directly in HTML.
+ *
+ * @returns A partial route manifest and the identified default path.
+ *
+ * @example
+ * // HTML: <template data-path="/home" data-default>...</template>
+ * const { routes, default: def } = discoverRoutes();
+ */
+export declare function discoverRoutes(): {
+    routes: Record<string, RouteDefinition>;
+    default: string | undefined;
+};
+/**
+ * Intercepts document-level clicks to implement "hijack" navigation.
+ *
+ * Logic: Global Click Interception
+ * Decides whether a click should be handled by the router based on:
+ * 1. Is it a valid navigation click (e.g., Left click without modifiers)?
+ * 2. Does the target match a known route or the 'notFound' handler?
+ * 3. Does the target represent a file download? (Heuristic: ignore dots in paths unless matched).
+ *
+ * @returns A cleanup function to unbind the global listener.
+ */
+export declare function setupRouteInterceptor(config: Required<RouteConfig> & {
+    routes: Record<string, RouteDefinition>;
+}, matcher: RouteMatcher, resolvePath: (el: Element) => string, navigate: (path: string) => Promise<void>): () => void;
+//# sourceMappingURL=view.d.ts.map

package/dist/features/route/view.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"view.d.ts","sourceRoot":"","sources":["../../../src/features/route/view.ts"],"names":[],"mappings":"AAAA,OAAO,EAAoB,KAAK,YAAY,EAAa,MAAM,qBAAqB,CAAC;AACrF,OAAO,EAAU,UAAU,EAAE,MAAM,2BAA2B,CAAC;AAe/D,OAAO,KAAK,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AAEpE,OAAO,EAAE,KAAK,aAAa,EAAmB,KAAK,YAAY,EAAE,MAAM,QAAQ,CAAC;AA8BhF;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,MAAM,CAAC,WAAW,CAAC,CAAC;IAC7B,MAAM,EAAE,QAAQ,CAAC,WAAW,CAAC,GAAG;QAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAA;KAAE,CAAC;IAC5E,UAAU,EAAE,UAAU,CAAC,OAAO,aAAa,CAAC,CAAC;IAC7C,QAAQ,EAAE,UAAU,CAAC,MAAM,IAAI,CAAC,CAAC;IACjC,YAAY,EAAE,MAAM,CAAC;CACtB;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,MAAM,CAAC,WAAW,CAAC,EAC5B,MAAM,EAAE,QAAQ,CAAC,WAAW,CAAC,GAAG;IAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAA;CAAE,EAC3E,UAAU,EAAE,UAAU,CAAC,OAAO,aAAa,CAAC,GAC3C,aAAa,CAEf;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,WAAW,CACzB,QAAQ,EAAE,aAAa,EACvB,GAAG,EAAE,eAAe,EACpB,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC9B,MAAM,EAAE,MAAM,QA4Df;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,aAAa,QAG1D;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,QAAQ,CAAC,WAAW,CAAC,GAAG;QAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAA;KAAE,CAAC;IAC5E,OAAO,EAAE,YAAY,CAAC;IACtB,UAAU,EAAE,UAAU,CAAC,OAAO,aAAa,CAAC,CAAC;IAC7C,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,GAAG,CAAC,OAAO,CAAC,CAAC;IAC3B,SAAS,EAAE,OAAO,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;IACpC,gBAAgB,EAAE,OAAO,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;IAC5C,YAAY,CAAC,EAAE,gBAAgB,CAAC;CACjC;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,QAAQ,CAAC,WAAW,CAAC,GAAG;IAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAA;CAAE,EAC3E,OAAO,EAAE,YAAY,EACrB,UAAU,EAAE,UAAU,CAAC,OAAO,aAAa,CAAC,EAC5C,WAAW,EAAE,MAAM,GAClB,YAAY,CAUd;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,YAAY,EAAE,gBAAgB,EAAE,YAAY,CAAC,MAAM,CAAC;;sBACpE,OAAO;EAoEjC;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,cAAc,IAAI;IAChC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;IACxC,OAAO,EAAE,MAAM,GAAG,SAAS,CAAC;CAC7B,CAoBA;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,QAAQ,CAAC,WAAW,CAAC,GAAG;IAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAA;CAAE,EAC3E,OAAO,EAAE,YAAY,EACrB,WAAW,EAAE,CAAC,EAAE,EAAE,OAAO,KAAK,MAAM,EACpC,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,GACxC,MAAM,IAAI,CAwBZ"}

package/dist/features/web-component/index.d.ts

@@ -0,0 +1,33 @@
+import { AtomComponentController, WritableAtom } from '../../types';
+/**
+ * Orchestrates AEJ features for a specific DOM element.
+ *
+ * Usage:
+ * ```ts
+ * const ctrl = useAtomComponent(el);
+ * ctrl.setup({
+ *   bind: { '.title': { text: titleAtom } }
+ * });
+ * ```
+ */
+export declare function useAtomComponent(element: HTMLElement): AtomComponentController;
+/**
+ * Registers a value or atom to be provided to all descendant elements.
+ *
+ * Side-effect: Synchronizes the value to a CSS variable `--aej-[key]`
+ * on the host element for hybrid styling (CSS-in-JS lite).
+ *
+ * @example
+ * provideAtom(el, 'theme', $.atom('dark'));
+ */
+export declare function provideAtom(element: HTMLElement | JQuery | string, key: string | symbol, val: unknown): void;
+/**
+ * Injects a provided value or atom from an ancestor.
+ * Returns a proxy atom that tracks the provider's location in the DOM.
+ *
+ * @example
+ * const theme = injectAtom(el, 'theme');
+ * $.effect(() => console.log(theme.value));
+ */
+export declare function injectAtom<T = unknown>(element: HTMLElement | JQuery | string, key: string | symbol): WritableAtom<T> | null;
+//# sourceMappingURL=index.d.ts.map

package/dist/features/web-component/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/features/web-component/index.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EACV,uBAAuB,EAKvB,YAAY,EACb,MAAM,SAAS,CAAC;AAsRjB;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,WAAW,GAAG,uBAAuB,CAuM9E;AAED;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CACzB,OAAO,EAAE,WAAW,GAAG,MAAM,GAAG,MAAM,EACtC,GAAG,EAAE,MAAM,GAAG,MAAM,EACpB,GAAG,EAAE,OAAO,GACX,IAAI,CA2CN;AAED;;;;;;;GAOG;AACH,wBAAgB,UAAU,CAAC,CAAC,GAAG,OAAO,EACpC,OAAO,EAAE,WAAW,GAAG,MAAM,GAAG,MAAM,EACtC,GAAG,EAAE,MAAM,GAAG,MAAM,GACnB,YAAY,CAAC,CAAC,CAAC,GAAG,IAAI,CAyBxB"}

package/dist/features/web-component/setup.d.ts

@@ -0,0 +1,77 @@
+import { SlotBuffer } from '@but212/atom-effect-utils';
+import { EffectObject, ReactiveValue, ReadonlyAtom } from '../../types';
+/**
+ * Collection of decomposed activation logic for setup components.
+ * Separates concerns for different reactive integrations to maintain maintainability.
+ * @internal
+ */
+export declare const SetupFeatures: {
+    /**
+     * Synchronizes atom values to custom events dispatched from the host.
+     *
+     * Logic:
+     * - If the source is a function returning an object, it is used as the event `detail`.
+     * - Otherwise, the value is wrapped in `{ value: val }` for a predictable API.
+     */
+    dispatch(el: HTMLElement, mappings: Record<string, ReactiveValue<unknown>>, effects: SlotBuffer<EffectObject>): void;
+    /**
+     * Applies constructable stylesheets to a ShadowRoot or Document.
+     * Note: This appends to existing sheets rather than replacing them.
+     */
+    styles(root: ShadowRoot | Document, sheets: CSSStyleSheet[]): CSSStyleSheet[];
+    /**
+     * Synchronizes atoms to AriaMixin properties via ElementInternals.
+     * Useful for high-level accessibility state (e.g. `aria-pressed`, `aria-valuenow`).
+     */
+    aria(internals: ElementInternals, aria: Record<string, ReadonlyAtom<unknown>>, effects: SlotBuffer<EffectObject>): void;
+    /**
+     * Performs declarative hydration of text content based on data-aej-bind attributes.
+     *
+     * Constraint: Uses `HYDRATION_MARKER` to ensure a node is only bound once,
+     * even if multiple hydration passes occur.
+     */
+    hydrate(root: ParentNode, bindings: Record<string, ReadonlyAtom<unknown>>, effects: SlotBuffer<EffectObject>, hydratedNodes: Set<Element>): void;
+    /**
+     * Synchronizes atoms to CSS Parts (`part` attribute) based on data-aej-part.
+     *
+     * Input Support:
+     * - String: "part1 part2"
+     * - Array: ["part1", "part2"]
+     * - Object: { part1: true, part2: false }
+     */
+    parts(root: ParentNode, parts: Record<string, ReadonlyAtom<unknown>>, effects: SlotBuffer<EffectObject>): void;
+    /**
+     * Shared DOM observer for detecting dynamically added elements matching a selector.
+     * This is the engine behind "late-binding" hydration for dynamically inserted nodes.
+     */
+    observe(root: ParentNode, selector: string, apply: (n: Element) => void, effects: SlotBuffer<EffectObject>): void;
+    /**
+     * Integrates reactive state with Form-Associated Custom Element (FACE) internals.
+     *
+     * This handles both the value state (via `setFormValue`) and the validity state
+     * (via `setValidity`), making the component behave like a native input.
+     */
+    form(el: HTMLElement, internals: ElementInternals, value: ReadonlyAtom<unknown> | {
+        val: ReadonlyAtom<unknown>;
+        state?: ReadonlyAtom<unknown>;
+    } | undefined, validation: ReadonlyAtom<ValidityStateFlags | string> | ((val: unknown) => ValidityStateFlags | string) | undefined, effects: SlotBuffer<EffectObject>): void;
+    /**
+     * Initializes attribute tracking.
+     *
+     * Optimisation: If `observedAttributes` is defined on the class,
+     * we only watch those specific attributes to reduce MutationObserver overhead.
+     */
+    attributes(host: HTMLElement): {
+        atom: ReadonlyAtom<Record<string, string | null>>;
+        observer: MutationObserver;
+    };
+    /**
+     * Initializes reactive slot tracking.
+     * Tracks `assignedNodes` for every slot in the ShadowRoot.
+     */
+    slots(root: ShadowRoot | null): {
+        atom: ReadonlyAtom<Record<string, Node[]>>;
+        listener: (e: Event) => void;
+    };
+};
+//# sourceMappingURL=setup.d.ts.map

package/dist/features/web-component/setup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"setup.d.ts","sourceRoot":"","sources":["../../../src/features/web-component/setup.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AAI5D,OAAO,KAAK,EAAE,YAAY,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAIzE;;;;GAIG;AACH,eAAO,MAAM,aAAa;IACxB;;;;;;OAMG;iBAEG,WAAW,YACL,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,OAAO,CAAC,CAAC,WACvC,UAAU,CAAC,YAAY,CAAC;IAkBnC;;;OAGG;iBACU,UAAU,GAAG,QAAQ,UAAU,aAAa,EAAE;IAK3D;;;OAGG;oBAEU,gBAAgB,QACrB,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,OAAO,CAAC,CAAC,WAClC,UAAU,CAAC,YAAY,CAAC;IAenC;;;;;OAKG;kBAEK,UAAU,YACN,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,OAAO,CAAC,CAAC,WACtC,UAAU,CAAC,YAAY,CAAC,iBAClB,GAAG,CAAC,OAAO,CAAC;IA6B7B;;;;;;;OAOG;gBAEK,UAAU,SACT,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,OAAO,CAAC,CAAC,WACnC,UAAU,CAAC,YAAY,CAAC;IAmCnC;;;OAGG;kBAEK,UAAU,YACN,MAAM,SACT,CAAC,CAAC,EAAE,OAAO,KAAK,IAAI,WAClB,UAAU,CAAC,YAAY,CAAC;IA+BnC;;;;;OAKG;aAEG,WAAW,aACJ,gBAAgB,SAEvB,YAAY,CAAC,OAAO,CAAC,GACrB;QAAE,GAAG,EAAE,YAAY,CAAC,OAAO,CAAC,CAAC;QAAC,KAAK,CAAC,EAAE,YAAY,CAAC,OAAO,CAAC,CAAA;KAAE,GAC7D,SAAS,cAET,YAAY,CAAC,kBAAkB,GAAG,MAAM,CAAC,GACzC,CAAC,CAAC,GAAG,EAAE,OAAO,KAAK,kBAAkB,GAAG,MAAM,CAAC,GAC/C,SAAS,WACJ,UAAU,CAAC,YAAY,CAAC;IAgDnC;;;;;OAKG;qBACc,WAAW,GAAG;QAC7B,IAAI,EAAE,YAAY,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC,CAAC,CAAC;QAClD,QAAQ,EAAE,gBAAgB,CAAC;KAC5B;IAuCD;;;OAGG;gBACS,UAAU,GAAG,IAAI,GAAG;QAC9B,IAAI,EAAE,YAAY,CAAC,MAAM,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC;QAC3C,QAAQ,EAAE,CAAC,CAAC,EAAE,KAAK,KAAK,IAAI,CAAC;KAC9B;CA6BF,CAAC"}

package/dist/features/web-component/state.d.ts

@@ -0,0 +1,47 @@
+import { Option, SlotBuffer } from '@but212/atom-effect-utils';
+import { CLEANUP_MARKER } from '../../core/symbols';
+import { EffectObject, WritableAtom } from '../../types';
+/**
+ * Centralizes all component-specific reactive state and resource tracking.
+ * Consolidates lifecycle resources into a single class instance to simplify teardown.
+ * @internal
+ */
+export declare class ComponentState {
+    host: HTMLElement;
+    /** The root node (host or shadowRoot) where bindings and styles are applied. */
+    root: Option<Node & {
+        [CLEANUP_MARKER]?: boolean;
+    }>;
+    /** Guards against double-initialization of the same host element. */
+    isInitialized: boolean;
+    /**
+     * A buffer for all reactive effects created during setup.
+     * Disposed as a single unit in `dispose()`.
+     */
+    effects: SlotBuffer<EffectObject>;
+    /** Set of nodes that have been processed by the hydration engine. */
+    hydratedNodes: Set<Element>;
+    /** The root atom containing the full snapshot of attributes. */
+    attributeAtom: WritableAtom<Record<string, string | null>> | null;
+    /** The observer that keeps `attributeAtom` in sync with the DOM. */
+    attributeObserver: MutationObserver | null;
+    /** Memoized lenses into `attributeAtom` to avoid redundant atom creation. */
+    attributeLenses: Map<string, WritableAtom<string | null>>;
+    /** The root atom containing the current mapping of assigned nodes per slot. */
+    slotsAtom: WritableAtom<Record<string, Node[]>> | null;
+    /** Memoized lenses into `slotsAtom`. */
+    slotLenses: Map<string, WritableAtom<Node[]>>;
+    /** Tracks listeners to allow precise removal during teardown. */
+    slotListeners: Map<string, (e: Event) => void>;
+    /** References to constructable stylesheets that must be removed from the root. */
+    appliedStyles: CSSStyleSheet[];
+    constructor(host: HTMLElement);
+    /**
+     * Deterministically releases all reactive resources and observers.
+     *
+     * Warning: Failure to call this on unmount will lead to memory leaks
+     * as the MutationObservers and effects will remain active.
+     */
+    dispose(): void;
+}
+//# sourceMappingURL=state.d.ts.map

package/dist/features/web-component/state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"state.d.ts","sourceRoot":"","sources":["../../../src/features/web-component/state.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AAE/D,OAAO,EAAE,cAAc,EAAoB,MAAM,gBAAgB,CAAC;AAClE,OAAO,KAAK,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAG1D;;;;GAIG;AACH,qBAAa,cAAc;IAiCN,IAAI,EAAE,WAAW;IAhCpC,gFAAgF;IAChF,IAAI,EAAE,MAAM,CAAC,IAAI,GAAG;QAAE,CAAC,cAAc,CAAC,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC,CAAe;IAElE,qEAAqE;IACrE,aAAa,UAAS;IAEtB;;;OAGG;IACH,OAAO,2BAAkC;IAEzC,qEAAqE;IACrE,aAAa,eAAsB;IAEnC,gEAAgE;IAChE,aAAa,EAAE,YAAY,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC,CAAC,GAAG,IAAI,CAAQ;IACzE,oEAAoE;IACpE,iBAAiB,EAAE,gBAAgB,GAAG,IAAI,CAAQ;IAClD,6EAA6E;IAC7E,eAAe,2CAAkD;IAEjE,+EAA+E;IAC/E,SAAS,EAAE,YAAY,CAAC,MAAM,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,GAAG,IAAI,CAAQ;IAC9D,wCAAwC;IACxC,UAAU,oCAA2C;IACrD,iEAAiE;IACjE,aAAa,kBAAuB,KAAK,KAAK,IAAI,EAAI;IAEtD,kFAAkF;IAClF,aAAa,EAAE,aAAa,EAAE,CAAM;gBAEjB,IAAI,EAAE,WAAW;IAEpC;;;;;OAKG;IACH,OAAO;CAqDR"}

package/dist/features/web-component/utils.d.ts

@@ -0,0 +1,13 @@
+import { ReactiveValue } from '../../types';
+/**
+ * Resolves the active ShadowRoot for component-local operations.
+ * @internal
+ */
+export declare const resolveShadowRoot: (element: HTMLElement, root: Node | ShadowRoot | null | undefined) => ShadowRoot | null;
+/**
+ * Resolves a reactive source into its current value.
+ * Supports static values, atoms, and getter functions.
+ * @internal
+ */
+export declare const resolveValue: <T>(source: ReactiveValue<T>) => T;
+//# sourceMappingURL=utils.d.ts.map

package/dist/features/web-component/utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../../src/features/web-component/utils.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAE7C;;;GAGG;AACH,eAAO,MAAM,iBAAiB,GAC5B,SAAS,WAAW,EACpB,MAAM,IAAI,GAAG,UAAU,GAAG,IAAI,GAAG,SAAS,KACzC,UAAU,GAAG,IAKJ,CAAC;AAEb;;;;GAIG;AACH,eAAO,MAAM,YAAY,GAAI,CAAC,EAAE,QAAQ,aAAa,CAAC,CAAC,CAAC,KAAG,CAI1D,CAAC"}