npm - ladrillosjs - Versions diffs - 2.0.0-beta.5.1 → 2.0.0-beta.7 - Mend

ladrillosjs 2.0.0-beta.5.1 → 2.0.0-beta.7

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (48) hide show

package/LICENSE +21 -0
package/README.md +134 -46
package/dist/core/builtins/lazyElement.d.ts +35 -0
package/dist/core/cache/expressionCache.d.ts +15 -0
package/dist/core/component/bindingParser.d.ts +2 -0
package/dist/core/component/cache.d.ts +22 -0
package/dist/core/component/extract.d.ts +2 -0
package/dist/core/component/loader.d.ts +10 -0
package/dist/core/component/webcomponent.d.ts +29 -0
package/dist/core/configure.d.ts +28 -0
package/dist/core/css/cssParser/cssParser.d.ts +3 -0
package/dist/core/diff/listDiff.d.ts +99 -0
package/dist/core/directives/directiveProcessor.d.ts +58 -0
package/dist/core/events/eventBus.d.ts +136 -0
package/dist/core/helpers/frameworkHelpers.d.ts +38 -0
package/dist/core/html/htmlparser.d.ts +19 -0
package/dist/core/js/moduleExecutor.d.ts +118 -0
package/dist/core/js/reactivity.d.ts +52 -0
package/dist/core/js/scriptParser.d.ts +52 -0
package/dist/core/ladrillos.d.ts +68 -0
package/dist/core/lazy/index.d.ts +6 -0
package/dist/core/lazy/lazyLoader.d.ts +22 -0
package/dist/core/lazy/lazyStrategies.d.ts +73 -0
package/dist/core/scheduler/batchScheduler.d.ts +97 -0
package/dist/core.d.ts +15 -0
package/dist/core.js +2 -0
package/dist/core.js.map +1 -0
package/dist/events.d.ts +20 -0
package/dist/events.js +1 -0
package/dist/index.d.ts +11 -9
package/dist/index.js +2 -1
package/dist/index.js.map +1 -0
package/dist/lazy.d.ts +17 -0
package/dist/lazy.js +1 -0
package/dist/shared-7u414ZMv.js +3 -0
package/dist/shared-7u414ZMv.js.map +1 -0
package/dist/shared-BA0RyagV.js +2 -0
package/dist/shared-BA0RyagV.js.map +1 -0
package/dist/shared-D-P0qKQY.js +2 -0
package/dist/shared-D-P0qKQY.js.map +1 -0
package/dist/types/index.d.ts +171 -0
package/dist/utils/devWarnings.d.ts +133 -0
package/dist/utils/directives.d.ts +149 -0
package/dist/utils/jsevents.d.ts +4 -0
package/dist/utils/keyModifiers.d.ts +106 -0
package/dist/utils/regex.d.ts +5 -0
package/dist/utils/sandbox.d.ts +25 -0
package/package.json +62 -14

package/LICENSE ADDED Viewed

@@ -0,0 +1,21 @@
+MIT License
+Copyright (c) 2025 Daniel Rubio
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md CHANGED Viewed

@@ -44,7 +44,10 @@
 ### 1. Add the Script
 ```html
-<script src="https://cdn.jsdelivr.net/npm/ladrillosjs/dist/ladrillosjs.umd.js"></script>
+<script type="module">
+  import ladrillosjs from "https://cdn.jsdelivr.net/npm/ladrillosjs@2/dist/index.js";
+  window.ladrillosjs = ladrillosjs;
+</script>
 ```
 ### 2. Create a Component
@@ -89,9 +92,9 @@ Save this as `counter.html`:
 <!DOCTYPE html>
 <html>
   <head>
-    <script src="https://cdn.jsdelivr.net/npm/ladrillosjs/dist/ladrillosjs.umd.js"></script>
     <script type="module">
-      ladrillosjs.registerComponent("my-counter", "./counter.html");
+      import { registerComponent } from "https://cdn.jsdelivr.net/npm/ladrillosjs@2/dist/index.js";
+      registerComponent("my-counter", "./counter.html");
     </script>
   </head>
   <body>
@@ -108,20 +111,27 @@ That's it! Your reactive component is ready. 🎉
 ### CDN (No Build Step)
+LadrillosJS v2 is distributed as native ES modules. Import directly from a CDN:
 ```html
-<!-- Global (UMD) -->
-<script src="https://cdn.jsdelivr.net/npm/ladrillosjs/dist/ladrillosjs.umd.js"></script>
+<!-- ES Module (recommended) -->
 <script type="module">
-  ladrillosjs.registerComponent("my-component", "./component.html");
+  import {
+    registerComponent,
+    registerComponents,
+  } from "https://cdn.jsdelivr.net/npm/ladrillosjs@2/dist/index.js";
+  registerComponent("my-component", "./component.html");
 </script>
-<!-- ES Module -->
+<!-- Also available on unpkg -->
 <script type="module">
-  import { registerComponent } from "https://cdn.jsdelivr.net/npm/ladrillosjs/dist/ladrillosjs.es.js";
-  registerComponent("my-component", "./component.html");
+  import { registerComponent } from "https://unpkg.com/ladrillosjs@2/dist/index.js";
 </script>
 ```
+> **Note:** LadrillosJS v2 is ESM-only. Legacy UMD/IIFE global builds are not published to npm.
 ### NPM (With Build Tools)
 ```bash
@@ -141,6 +151,22 @@ await registerComponents([
 ]);
 ```
+### Granular Imports (Tree-Shaking)
+```javascript
+// Full API
+import { registerComponent, $emit, $listen } from "ladrillosjs";
+// Core only (no lazy loading, no event bus)
+import { registerComponent } from "ladrillosjs/core";
+// Lazy loading strategies only
+import { lazyOnVisible, lazyOnIdle } from "ladrillosjs/lazy";
+// Event bus only
+import { $emit, $listen } from "ladrillosjs/events";
+```
 ---
 ## 📖 Core Concepts
@@ -203,16 +229,16 @@ Use `$bind` to sync form inputs with state:
 ---
-## 🧩 Directives
+## 🧩 Built-in Elements & Directives
 ### Conditional Rendering
-Use `$if`, `$else-if`, and `$else` to conditionally render elements:
+Use `<if>`, `<else-if>`, and `<else>` to conditionally render elements:
 ```html
-<div $if="{status === 'loading'}">Loading...</div>
-<div $else-if="{status === 'error'}">Something went wrong!</div>
-<div $else>Content loaded successfully!</div>
+<if condition="status === 'loading'">Loading...</if>
+<else-if condition="status === 'error'">Something went wrong!</else-if>
+<else>Content loaded successfully!</else>
 <script>
   let status = "loading";
@@ -221,10 +247,10 @@ Use `$if`, `$else-if`, and `$else` to conditionally render elements:
 ### Show/Hide (CSS Toggle)
-Use `$show` to toggle visibility without removing from DOM (uses `display: none`):
+Use `<show>` to toggle visibility without removing from DOM (uses `display: none`):
 ```html
-<div $show="{isVisible}">I can be shown or hidden</div>
+<show condition="isVisible">I can be shown or hidden</show>
 <button onclick="isVisible = !isVisible">Toggle</button>
@@ -233,27 +259,33 @@ Use `$show` to toggle visibility without removing from DOM (uses `display: none`
 </script>
 ```
-> **`$show` vs `$if`:** `$show` toggles CSS display (element stays in DOM), `$if` adds/removes from DOM entirely.
+> **`<show>` vs `<if>`:** `<show>` toggles CSS display (children stay in DOM), `<if>` adds/removes children entirely.
 ### List Rendering
-Use `$for` to render lists with optional index and key:
+Use `<for>` to render lists with optional index and key:
 ```html
 <!-- Simple list -->
 <ul>
-  <li $for="fruit in fruits">🍎 {fruit}</li>
+  <for each="fruit in fruits">
+    <li>🍎 {fruit}</li>
+  </for>
 </ul>
 <!-- With index -->
-<div $for="(item, index) in items">#{index + 1}: {item}</div>
+<for each="(item, index) in items">
+  <div>#{index + 1}: {item}</div>
+</for>
 <!-- Object array with key -->
-<div $for="user in users" $key="user.id">
-  <span>{user.avatar}</span>
-  <span>{user.name}</span>
-  <span>{user.role}</span>
-</div>
+<for each="user in users" key="user.id">
+  <div>
+    <span>{user.avatar}</span>
+    <span>{user.name}</span>
+    <span>{user.role}</span>
+  </div>
+</for>
 <script>
   let fruits = ["Apple", "Banana", "Cherry"];
@@ -265,19 +297,34 @@ Use `$for` to render lists with optional index and key:
 </script>
 ```
-### Directives Cheat Sheet
+### Lazy Loading
-| Directive        | Purpose               | Example                                          |
-| ---------------- | --------------------- | ------------------------------------------------ |
-| `$if`            | Conditional render    | `<div $if="{isLoggedIn}">Welcome!</div>`         |
-| `$else-if`       | Chained condition     | `<div $else-if="{isGuest}">Hello Guest</div>`    |
-| `$else`          | Fallback              | `<div $else>Please log in</div>`                 |
-| `$show`          | CSS visibility toggle | `<div $show="{isOpen}">Menu</div>`               |
-| `$for`           | Loop rendering        | `<li $for="item in items">{item}</li>`           |
-| `$for` (indexed) | Loop with index       | `<li $for="(item, i) in items">{i}: {item}</li>` |
-| `$bind`          | Two-way binding       | `<input $bind="email" />`                        |
-| `$key`           | List optimization     | `<div $for="user in users" $key="user.id">`      |
-| `$ref`           | Element reference     | `<input $ref="inputEl" />`                       |
+Use `<lazy>` to defer rendering until a trigger fires (viewport, idle, delay, interaction, media):
+```html
+<lazy margin="100px">
+  <heavy-chart></heavy-chart>
+</lazy>
+<lazy interaction="click,focus">
+  <support-chat></support-chat>
+</lazy>
+```
+### Cheat Sheet
+| Element / Directive | Purpose                  | Example                                                |
+| ------------------- | ------------------------ | ------------------------------------------------------ |
+| `<if>`              | Conditional render       | `<if condition="isLoggedIn">Welcome!</if>`             |
+| `<else-if>`         | Chained condition        | `<else-if condition="isGuest">Hello Guest</else-if>`   |
+| `<else>`            | Fallback                 | `<else>Please log in</else>`                           |
+| `<show>`            | CSS visibility toggle    | `<show condition="isOpen">Menu</show>`                 |
+| `<for>`             | Loop rendering           | `<for each="item in items"><li>{item}</li></for>`      |
+| `<for>` (indexed)   | Loop with index          | `<for each="(item, i) in items">…</for>`               |
+| `<for key="…">`     | List optimization        | `<for each="u in users" key="u.id">…</for>`            |
+| `<lazy>`            | Defer rendering          | `<lazy idle><analytics-pixel /></lazy>`                |
+| `$bind`             | Two-way binding          | `<input $bind="email" />`                              |
+| `$ref`              | Element reference        | `<input $ref="inputEl" />`                             |
 ---
@@ -406,11 +453,19 @@ await registerComponents([
 | `lazyOnMedia`       | Mobile/desktop specific components           |
 | `lazyOnDelay`       | Chat widgets, notifications                  |
+### Eager Override
+Force a lazy component to load immediately by adding the `eager` attribute:
+```html
+<lazy-footer eager></lazy-footer>
+```
 ---
 ## 📋 API Reference
-### registerComponent
+### `registerComponent`
 ```javascript
 registerComponent(name, path, useShadowDOM?, lazy?)
@@ -434,7 +489,7 @@ registerComponent("my-nav", "./nav.html", false);
 registerComponent("my-footer", "./footer.html", true, lazyOnVisible());
 ```
-### registerComponents
+### `registerComponents`
 Register multiple components with parallel fetching:
@@ -448,6 +503,37 @@ const result = await registerComponents([
 // Returns: { success: [...], failed: [...], skipped: [...] }
 ```
+### `$use`
+Infer the component tag name from the file path:
+```javascript
+await $use("./components/user-card.html"); // Registers as <user-card>
+```
+### `loadLazyComponent`
+Force a lazy component to load immediately from JavaScript:
+```javascript
+import { loadLazyComponent } from "ladrillosjs";
+await loadLazyComponent("my-lazy-footer");
+```
+### `configure`
+Configure framework-level options (optional):
+```javascript
+import { configure } from "ladrillosjs";
+configure({
+  cacheSize: 50, // Component LRU cache size (default: 25)
+  onError: (err) => telemetry.capture(err), // Custom error handler
+});
+```
 ### Event Bus
 | Function                   | Description                         |
@@ -503,14 +589,16 @@ A complete CRUD example combining all directives:
   </form>
   <ul>
-    <li $for="todo in todos" $key="todo.id">
-      <input type="checkbox" onclick="toggleTodo({todo.id})" />
-      <span class="{todo.completed ? 'done' : ''}">{todo.text}</span>
-      <button onclick="removeTodo({todo.id})">🗑️</button>
-    </li>
+    <for each="todo in todos" key="todo.id">
+      <li>
+        <input type="checkbox" onclick="toggleTodo({todo.id})" />
+        <span class="{todo.completed ? 'done' : ''}">{todo.text}</span>
+        <button onclick="removeTodo({todo.id})">🗑️</button>
+      </li>
+    </for>
   </ul>
-  <p $if="{todos.length === 0}">No todos yet!</p>
+  <if condition="todos.length === 0"><p>No todos yet!</p></if>
 </div>
 <script>
@@ -531,7 +619,7 @@ A complete CRUD example combining all directives:
   function toggleTodo(id) {
     todos = todos.map((t) =>
-      t.id === id ? { ...t, completed: !t.completed } : t
+      t.id === id ? { ...t, completed: !t.completed } : t,
     );
   }

package/dist/core/builtins/lazyElement.d.ts ADDED Viewed

@@ -0,0 +1,35 @@
+import { LazyStrategy } from '../lazy/lazyStrategies';
+/**
+ * Pick a LazyStrategy from the attributes on a <lazy> element.
+ * Returns `null` for `eager` (= load immediately, no observation needed).
+ */
+export declare function resolveLazyStrategy(el: Element): LazyStrategy | null;
+/**
+ * Process a single <lazy> element. Removes it from the DOM and replaces it
+ * with a comment placeholder + (optional) placeholder content. Schedules the
+ * actual content to swap in when the chosen strategy fires.
+ */
+export declare function processLazyElement(lazyEl: Element): void;
+/**
+ * Find and process all top-level <lazy> elements in `host`. <lazy> elements
+ * inside <for> templates are skipped; they get processed when the loop
+ * renders each iteration via processLazyElement on the cloned content.
+ *
+ * Accepts a connected host OR a detached DocumentFragment — the latter is
+ * used by `loadTemplate` to preprocess <lazy> before any custom-element
+ * children get a chance to fire connectedCallback (and drain their light
+ * DOM into __originalChildren). Without this preprocessing, lazy's
+ * detach-then-reattach cycle would re-run children's connectedCallback with
+ * an empty innerHTML, breaking components that read $host.__originalHTML.
+ */
+export declare function scanLazyElements(host: HTMLElement | ShadowRoot | DocumentFragment): void;
+/**
+ * Returns all detached DocumentFragments held by pending `<lazy>` placeholders
+ * inside `host`. Used by binding/event-handler/directive scanners to wire up
+ * the children of `<lazy>` elements while they are still detached from the
+ * document. Wiring done on these fragments survives the later move into the
+ * host tree when the lazy strategy fires.
+ *
+ * Returns an empty array for hosts that contain no pending lazy fragments.
+ */
+export declare function getPendingLazyContent(host: HTMLElement | ShadowRoot | DocumentFragment): DocumentFragment[];

package/dist/core/cache/expressionCache.d.ts ADDED Viewed

@@ -0,0 +1,15 @@
+/**
+ * Variable Regex Cache
+ *
+ * Building a `RegExp` is comparatively expensive, and the reactivity layer
+ * checks the same variable names against many binding expressions when working
+ * out which bindings depend on which state keys. Caching the compiled regex per
+ * variable name avoids recreating it on every check.
+ */
+/**
+ * Gets or creates a cached regex for variable boundary matching.
+ *
+ * @param variableName - The variable name to match
+ * @returns A regex that matches the variable as a whole word
+ */
+export declare function getCachedVariableRegex(variableName: string): RegExp;

package/dist/core/component/bindingParser.d.ts ADDED Viewed

	@@ -0,0 +1,2 @@
1	+ import { BindingDescriptor } from '../../types';
2	+ export declare function analyzeBinding(raw: string): BindingDescriptor["bindings"][number];

package/dist/core/component/cache.d.ts ADDED Viewed

@@ -0,0 +1,22 @@
+/**
+ * Set the maximum number of component sources retained in the LRU cache.
+ * When the new size is smaller than the current cache, the least-recently
+ * used entries are evicted until the limit is satisfied.
+ */
+export declare const setCacheSize: (size: number) => void;
+/**
+ * LRU Cache: Gets cached content and marks it as recently used
+ * Moves the accessed item to the end of the Map (most recently used position)
+ * This ensures frequently accessed components stay in cache longer
+ * @param path - The file path to retrieve from cache
+ * @returns The cached content or undefined if not found
+ */
+export declare const getCachedComponentSource: (path: string) => string | undefined;
+/**
+ * LRU Cache: Stores content with automatic eviction of least recently used items
+ * Maintains cache size limit by removing oldest items when full
+ * Updates existing items without affecting cache size
+ * @param path - The file path to cache
+ * @param content - The content to store
+ */
+export declare const setCachedComponentSource: (path: string, content: string) => void;

package/dist/core/component/extract.d.ts ADDED Viewed

	@@ -0,0 +1,2 @@
1	+ import { LadrillosComponent } from '../../types';
2	+ export declare function parseComponent(source: string, name: string, componentUrl?: string): Promise<LadrillosComponent>;

package/dist/core/component/loader.d.ts ADDED Viewed

@@ -0,0 +1,10 @@
+/**
+ * Result of fetching a component source
+ */
+export interface FetchComponentResult {
+    /** The HTML source content */
+    source: string;
+    /** The actual resolved path (may differ from input for folder-as-component) */
+    resolvedPath: string;
+}
+export declare function fetchComponentSource(path: string): Promise<FetchComponentResult | undefined>;

package/dist/core/component/webcomponent.d.ts ADDED Viewed

@@ -0,0 +1,29 @@
+import { LadrillosComponent } from '../../types';
+/**
+ * Creates a Web Component class from a Ladrillos component definition.
+ *
+ * This function creates the class but does NOT register it with customElements.
+ * Use createWebComponent() if you want to both create and register.
+ *
+ * Follows the Web Components specification:
+ * - Proper lifecycle callbacks (connectedCallback, disconnectedCallback, etc.)
+ * - Observed attributes with attributeChangedCallback
+ * - Shadow DOM encapsulation (optional)
+ * - Reactive state that syncs with the DOM
+ *
+ * - Attributes from HTML OVERRIDE script variable defaults
+ * - Script variables serve as DEFAULT values when no attribute is provided
+ *
+ * Example:
+ *   <my-counter count="5"></my-counter>  <!-- count = 5, not the default -->
+ *   <my-counter></my-counter>            <!-- count = 0 (script default) -->
+ */
+export declare function createWebComponentClass(component: LadrillosComponent, useShadowDOM: boolean): typeof HTMLElement;
+/**
+ * Creates and registers a Web Component from a Ladrillos component.
+ *
+ * This is the main entry point that:
+ * 1. Creates the component class
+ * 2. Registers it with customElements.define
+ */
+export declare function createWebComponent(component: LadrillosComponent, useShadowDOM: boolean): void;

package/dist/core/configure.d.ts ADDED Viewed

@@ -0,0 +1,28 @@
+import { LadrillosErrorHandler } from '../utils/devWarnings';
+/**
+ * Options accepted by `configure()`.
+ */
+export interface LadrillosConfig {
+    /**
+     * Maximum number of component source files retained in the LRU cache.
+     * Defaults to 25. Must be a positive integer.
+     */
+    cacheSize?: number;
+    /**
+     * Custom error handler. Called in addition to the framework's built-in
+     * console logging so embedders can route framework errors to telemetry.
+     *
+     * @example
+     * configure({
+     *   onError: (err) => telemetry.capture(err),
+     * });
+     */
+    onError?: LadrillosErrorHandler | null;
+}
+/**
+ * Configure framework-level options.
+ *
+ * Safe to call at any time; subsequent calls override prior values. Pass
+ * `onError: null` to clear a previously registered handler.
+ */
+export declare function configure(config: LadrillosConfig): void;

package/dist/core/css/cssParser/cssParser.d.ts ADDED Viewed

@@ -0,0 +1,3 @@
+type StyleTarget = HTMLElement | ShadowRoot;
+export declare const loadStyles: (target: StyleTarget, cssText: string | undefined, useShadowDOM: boolean) => void;
+export {};

package/dist/core/diff/listDiff.d.ts ADDED Viewed

@@ -0,0 +1,99 @@
+/**
+ * Keyed List Diffing Algorithm
+ *
+ * Uses a simplified LIS (Longest Increasing Subsequence) approach
+ * for optimal DOM operations.
+ *
+ * Benefits:
+ * - Minimizes DOM operations (moves instead of recreate)
+ * - Preserves element state (focus, scroll, animations)
+ * - O(n) best case, O(n log n) worst case
+ *
+ * Usage with $for:
+ *   $for="item in items track by item.id"
+ *                          ^^^^^^^^^^^^^^
+ *                          Key expression for efficient diffing
+ */
+export interface DiffOperation {
+    type: "insert" | "remove" | "move" | "update";
+    /** Index in the old array (for remove/move/update) */
+    oldIndex?: number;
+    /** Index in the new array (for insert/move/update) */
+    newIndex?: number;
+    /** The item data */
+    item?: unknown;
+    /** Key for keyed operations */
+    key?: unknown;
+}
+/**
+ * Computes the minimal set of DOM operations to transform oldItems into newItems.
+ * Uses keys for identity matching - items with the same key are considered the same.
+ *
+ * @param oldItems - Previous array items
+ * @param newItems - New array items
+ * @param getKey - Function to extract a unique key from an item
+ * @returns Array of operations to perform
+ *
+ * @example
+ * const ops = diffKeyed(
+ *   [{ id: 1, name: 'A' }, { id: 2, name: 'B' }],
+ *   [{ id: 2, name: 'B' }, { id: 1, name: 'A' }, { id: 3, name: 'C' }],
+ *   item => item.id
+ * );
+ * // ops = [
+ * //   { type: 'move', oldIndex: 1, newIndex: 0, key: 2 },
+ * //   { type: 'move', oldIndex: 0, newIndex: 1, key: 1 },
+ * //   { type: 'insert', newIndex: 2, key: 3, item: { id: 3, name: 'C' } }
+ * // ]
+ */
+export declare function diffKeyed<T>(oldItems: T[], newItems: T[], getKey: (item: T, index: number) => unknown): DiffOperation[];
+/**
+ * Simpler diff for non-keyed lists.
+ * Less efficient but works when items don't have stable identity.
+ *
+ * @param oldLength - Previous array length
+ * @param newLength - New array length
+ * @param newItems - New array items
+ * @returns Array of operations
+ */
+export declare function diffUnkeyed<T>(oldLength: number, newLength: number, newItems: T[]): DiffOperation[];
+/**
+ * Computes the set of positions that form the longest increasing subsequence
+ * of `source`, ignoring entries whose value is < 0 (used to mark brand-new
+ * items that must always be (re)inserted).
+ *
+ * The loop renderer uses this to decide which reused elements are already in
+ * correct relative DOM order and can therefore stay put — only the remaining
+ * elements need to be moved. This turns an in-order content update into zero
+ * DOM moves and minimizes moves for partial reorders.
+ *
+ * Runs in O(n log n) using patience sorting with predecessor links.
+ *
+ * @param source - For each new position, the element's previous index, or -1 if new
+ * @returns Set of new-position indices that should NOT be moved
+ */
+export declare function getStableIndices(source: number[]): Set<number>;
+/**
+ * Creates a key getter function from a key expression.
+ *
+ * @param keyExpr - Key expression (e.g., "item.id" or just "id" if item is scope)
+ * @param itemName - The loop variable name (e.g., "item")
+ * @returns A function that extracts the key from an item
+ *
+ * @example
+ * const getKey = createKeyGetter("item.id", "item");
+ * getKey({ id: 123, name: "foo" }) // 123
+ */
+export declare function createKeyGetter<T>(keyExpr: string | undefined, itemName: string): (item: T, index: number) => unknown;
+/**
+ * Applies diff operations to a list of DOM elements.
+ * This is the main integration point with the loop renderer.
+ *
+ * @param container - Parent element containing the list
+ * @param elements - Current rendered elements
+ * @param operations - Diff operations to apply
+ * @param createFn - Function to create a new element for an item
+ * @param updateFn - Function to update an existing element
+ * @returns The new array of elements
+ */
+export declare function applyDiffOperations<T>(container: Element | ShadowRoot, elements: Element[], operations: DiffOperation[], createFn: (item: T, index: number) => Element, updateFn: (element: Element, item: T, index: number) => void): Element[];

package/dist/core/directives/directiveProcessor.d.ts ADDED Viewed

@@ -0,0 +1,58 @@
+import { ConditionalDescriptor, LoopDescriptor, TwoWayBindingDescriptor } from '../../types';
+export type RefMap = Map<string, HTMLElement>;
+export type DirectiveContext = {
+    loops: LoopDescriptor[];
+    conditionals: ConditionalDescriptor[][];
+    twoWayBindings: TwoWayBindingDescriptor[];
+    refs: RefMap;
+    showElements: ShowDescriptor[];
+};
+/**
+ * Registry for two-way bindings.
+ * Maps state keys to the elements bound to them.
+ */
+export type TwoWayBindingRegistry = Map<string, Array<{
+    element: HTMLElement;
+    path: string[];
+    isContentEditable?: boolean;
+}>>;
+export type ShowDescriptor = {
+    element: HTMLElement;
+    expression: string;
+    originalDisplay: string;
+};
+/**
+ * Scans the template for all directives and returns descriptors for each.
+ * This should be called after the template HTML is injected into the DOM.
+ */
+export declare function scanDirectives(host: HTMLElement | ShadowRoot): DirectiveContext;
+/**
+ * Scans the template for all directives and returns descriptors for each.
+ * This version accepts an existing refs Map to populate (used when refs
+ * need to be available before scripts run).
+ */
+export declare function scanDirectivesWithRefs(host: HTMLElement | ShadowRoot, existingRefs: RefMap): DirectiveContext;
+/**
+ * Scans for $ref directives only and populates the refs Map.
+ * This can be called early (before scripts run) to make refs available.
+ */
+export declare function scanRefsOnly(host: HTMLElement | ShadowRoot | DocumentFragment, refs: RefMap): void;
+/**
+ * Renders all loops with the current state.
+ */
+export declare function renderLoops(loops: LoopDescriptor[], state: Record<string, unknown>, evaluateExpression: (expr: string, context: Record<string, unknown>) => unknown): void;
+/**
+ * Updates all conditionals with the current state.
+ */
+export declare function updateConditionals(conditionals: ConditionalDescriptor[][], state: Record<string, unknown>, evaluateExpression: (expr: string, context: Record<string, unknown>) => unknown): void;
+/**
+ * Updates all $show elements with the current state.
+ */
+export declare function updateShowElements(showElements: ShowDescriptor[], state: Record<string, unknown>, evaluateExpression: (expr: string, context: Record<string, unknown>) => unknown): void;
+/**
+ * Sets up two-way bindings and returns a registry for state→input sync.
+ *
+ * Returns a function that should be called when state changes to update
+ * all bound input elements with the new state values.
+ */
+export declare function setupTwoWayBindings(bindings: TwoWayBindingDescriptor[], state: Record<string, unknown>, evaluateExpression: (expr: string, context: Record<string, unknown>) => unknown): (changedKey?: string) => void;