npm - ladrillosjs - Versions diffs - 2.0.0-beta.5.1 → 2.0.0-rc.1 - Mend

ladrillosjs 2.0.0-beta.5.1 → 2.0.0-rc.1

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 (50) hide show

package/LICENSE +21 -0
package/README.md +77 -12
package/dist/core/cache/expressionCache.d.ts +80 -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 +83 -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 +13 -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 +48 -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/reactivity/dependencyTracker.d.ts +120 -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 +2 -0
package/dist/events.js.map +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 +2 -0
package/dist/lazy.js.map +1 -0
package/dist/shared-CqJzci1Q.js +2 -0
package/dist/shared-CqJzci1Q.js.map +1 -0
package/dist/shared-DGGk2qBc.js +2 -0
package/dist/shared-DGGk2qBc.js.map +1 -0
package/dist/shared-DKFppTJL.js +2 -0
package/dist/shared-DKFppTJL.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 +60 -12

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
@@ -406,11 +432,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 +468,7 @@ registerComponent("my-nav", "./nav.html", false);
 registerComponent("my-footer", "./footer.html", true, lazyOnVisible());
 ```
-### registerComponents
+### `registerComponents`
 Register multiple components with parallel fetching:
@@ -448,6 +482,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                         |
@@ -531,7 +596,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/cache/expressionCache.d.ts ADDED Viewed

@@ -0,0 +1,80 @@
+/**
+ * Expression Cache
+ *
+ * Caches compiled expression evaluators to avoid repeated Function() construction.
+ *
+ * Creating functions via new Function() is expensive:
+ * - Parsing the function body
+ * - JIT compilation
+ * - Memory allocation
+ *
+ * By caching the compiled functions, we only pay this cost once per unique expression.
+ */
+type ExpressionEvaluator = (context: Record<string, unknown>) => unknown;
+/**
+ * Gets or creates a cached expression evaluator.
+ *
+ * @param expression - The expression to compile (e.g., "count + 1")
+ * @param contextKeys - Variable names available in scope
+ * @returns A function that evaluates the expression against a context
+ *
+ * @example
+ * const evaluate = getCachedEvaluator("count * 2", ["count"]);
+ * const result = evaluate({ count: 5 }); // 10
+ */
+export declare function getCachedEvaluator(expression: string, contextKeys: string[]): ExpressionEvaluator;
+/**
+ * Clears all expression caches.
+ * Useful for testing or when context shape changes dramatically.
+ */
+export declare function clearExpressionCache(): void;
+/**
+ * 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;
+/**
+ * Cached check if an expression depends on a variable.
+ *
+ * @param expression - The expression to check
+ * @param variableName - The variable to look for
+ * @returns true if the expression references the variable
+ */
+export declare function expressionDependsOnCached(expression: string, variableName: string): boolean;
+/**
+ * Gets or creates a cached path array from a dot-notation string.
+ *
+ * @param pathString - The dot-notation path (e.g., "person.address.city")
+ * @returns Array of path segments
+ *
+ * @example
+ * getCachedPath("person.name") // ["person", "name"]
+ */
+export declare function getCachedPath(pathString: string): readonly string[];
+/**
+ * Resolves a value from an object using a cached path.
+ *
+ * @param obj - The object to read from
+ * @param pathString - Dot-notation path
+ * @returns The value at the path, or undefined
+ *
+ * @example
+ * getByPath({ person: { name: "John" } }, "person.name") // "John"
+ */
+export declare function getByPath(obj: Record<string, unknown>, pathString: string): unknown;
+/**
+ * Sets a value on an object using a cached path.
+ *
+ * @param obj - The object to write to
+ * @param pathString - Dot-notation path
+ * @param value - The value to set
+ *
+ * @example
+ * const obj = { person: { name: "John" } };
+ * setByPath(obj, "person.name", "Jane");
+ * // obj.person.name === "Jane"
+ */
+export declare function setByPath(obj: Record<string, unknown>, pathString: string, value: unknown): void;
+export {};

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,83 @@
+/**
+ * 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[];
+/**
+ * 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, 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;

package/dist/core/events/eventBus.d.ts ADDED Viewed

@@ -0,0 +1,136 @@
+/**
+ * LadrillosJS Global Event Bus
+ *
+ * Provides cross-component communication without prop drilling.
+ *
+ * Usage:
+ * - $emit("event-name", data) - Emit an event to all listeners
+ * - $listen("event-name", callback) - Listen for events from any component
+ *
+ * @example
+ * ```html
+ * <!-- Component A: Emitting events -->
+ * <script>
+ *   const login = () => {
+ *     $emit("user-logged-in", { userId: 123, username: "john" });
+ *   };
+ * </script>
+ *
+ * <!-- Component B: Listening for events -->
+ * <script>
+ *   let isLoggedIn = false;
+ *   let username = "";
+ *
+ *   $listen("user-logged-in", (user) => {
+ *     isLoggedIn = true;
+ *     username = user.username;
+ *   });
+ * </script>
+ * ```
+ */
+/**
+ * Event listener callback function type
+ */
+export type EventListener<T = unknown> = (data: T) => void;
+/**
+ * Public alias for EventListener (for external API)
+ */
+export type EventCallback<T = unknown> = EventListener<T>;
+/**
+ * Internal listener registration with metadata for cleanup
+ */
+interface ListenerRegistration {
+    callback: EventListener;
+    componentId?: string;
+}
+/**
+ * Unsubscribe function returned by $listen
+ */
+export type Unsubscribe = () => void;
+/**
+ * Global event bus interface for type safety
+ */
+interface GlobalEventBus {
+    listeners: Map<string, Set<ListenerRegistration>>;
+    componentListeners: Map<string, Set<{
+        event: string;
+        registration: ListenerRegistration;
+    }>>;
+}
+/**
+ * Extend globalThis to include our event bus
+ */
+declare global {
+    var __ladrillosEventBus: GlobalEventBus | undefined;
+}
+/**
+ * Emit an event to all registered listeners.
+ *
+ * @param eventName - The name of the event to emit
+ * @param data - Optional data to pass to listeners
+ *
+ * @example
+ * ```js
+ * $emit("user-logged-in", { userId: 123, username: "john" });
+ * $emit("show-modal");
+ * $emit("item-added", { id: 1, name: "Product" });
+ * ```
+ */
+export declare function $emit<T = unknown>(eventName: string, data?: T): void;
+/**
+ * Listen for events from any component.
+ *
+ * @param eventName - The name of the event to listen for
+ * @param callback - Function to call when the event is emitted
+ * @param componentId - Optional component ID for automatic cleanup
+ * @returns Unsubscribe function to remove the listener
+ *
+ * @example
+ * ```js
+ * // Basic usage
+ * $listen("user-logged-in", (user) => {
+ *   console.log(`Welcome, ${user.username}!`);
+ *   isLoggedIn = true;
+ * });
+ *
+ * // With unsubscribe
+ * const unsubscribe = $listen("notifications", handleNotification);
+ * // Later: unsubscribe();
+ * ```
+ */
+export declare function $listen<T = unknown>(eventName: string, callback: EventListener<T>, componentId?: string): Unsubscribe;
+/**
+ * Remove all listeners registered by a specific component.
+ * Called automatically when a component is disconnected from the DOM.
+ *
+ * @param componentId - The component's unique ID
+ */
+export declare function cleanupComponentListeners(componentId: string): void;
+/**
+ * Remove all event listeners (useful for testing)
+ */
+export declare function clearAllListeners(): void;
+/**
+ * Get the count of listeners for an event (useful for debugging)
+ */
+export declare function getListenerCount(eventName: string): number;
+/**
+ * Check if an event has any listeners
+ */
+export declare function hasListeners(eventName: string): boolean;
+/**
+ * Creates event bus helpers bound to a specific component.
+ * This enables automatic cleanup when the component is disconnected.
+ *
+ * @param componentId - The unique ID of the component
+ * @returns Object containing bound $emit and $listen functions
+ */
+export declare function createEventBusHelpers(componentId: string): {
+    $emit: <T = unknown>(eventName: string, data?: T) => void;
+    $listen: <T = unknown>(eventName: string, callback: EventListener<T>) => Unsubscribe;
+};
+/**
+ * Names of event bus helpers (for Function parameter lists)
+ */
+export declare const eventBusHelperNames: string[];
+export {};

package/dist/core/helpers/frameworkHelpers.d.ts ADDED Viewed

@@ -0,0 +1,38 @@
+import { ComponentConfig, RegisterComponentsResult } from '../ladrillos';
+import { LazyStrategy } from '../lazy';
+/**
+ * Wraps a Map in a Proxy to allow cleaner dot notation access.
+ * Supports both $refs.inputEl and $refs.get("inputEl") syntax.
+ *
+ * @example
+ * const $refs = createRefsProxy(new Map());
+ * $refs.set("input", document.querySelector("input"));
+ * $refs.input.focus();  // Works!
+ * $refs.get("input").focus();  // Also works!
+ */
+export declare function createRefsProxy<T extends HTMLElement = HTMLElement>(map: Map<string, T>): Map<string, T> & Record<string, T>;
+/**
+ * Creates framework helpers bound to a specific component's base URL.
+ * This ensures relative paths like "./buttons.html" resolve correctly
+ * relative to the component that calls registerComponent.
+ *
+ * @param componentUrl - The absolute URL of the component (e.g., "http://localhost/header/header.html")
+ * @returns Object containing bound helper functions
+ */
+export declare function createFrameworkHelpers(componentUrl: string): {
+    registerComponent: (name: string, path: string, useShadowDOM?: boolean, lazy?: boolean | LazyStrategy) => Promise<void>;
+    registerComponents: (configs: ComponentConfig[] | Record<string, string | Omit<ComponentConfig, "name">>) => Promise<RegisterComponentsResult>;
+    $use: (path: string, useShadowDOM?: boolean, lazy?: boolean | LazyStrategy) => Promise<void>;
+};
+/**
+ * Names of all framework helpers (for Function parameter lists)
+ */
+export declare const frameworkHelperNames: string[];
+/**
+ * Default helpers for entry point usage (resolve relative to page URL).
+ * Inside components, use createFrameworkHelpers(componentUrl) instead.
+ */
+export declare function getFrameworkHelperValues(): ((...args: any[]) => any)[];
+export declare const registerComponent: (name: string, path: string, useShadowDOM?: boolean, lazy?: boolean | LazyStrategy) => Promise<void>;
+export declare const registerComponents: (configs: ComponentConfig[] | Record<string, string | Omit<ComponentConfig, "name">>) => Promise<RegisterComponentsResult>;
+export declare const $use: (path: string, useShadowDOM?: boolean, lazy?: boolean | LazyStrategy) => Promise<void>;