dalila 1.9.8 → 1.9.9

package/README.md

@@ -60,6 +60,8 @@ bind(document.getElementById('app')!, ctx);
 
 - [Template Binding](./docs/runtime/bind.md) — `bind()`, `mount()`, `configure()`, transitions, portal, text interpolation, events
 - [Components](./docs/runtime/component.md) — `defineComponent`, typed props/emits/refs, slots
+- [Lazy Loading](./docs/runtime/lazy.md) — `createLazyComponent`, `d-lazy`, `createSuspense` wrapper, code splitting
+- [Error Boundary](./docs/runtime/boundary.md) — `createErrorBoundary`, `createErrorBoundaryState`, `withErrorBoundary`, `d-boundary`
 - [FOUC Prevention](./docs/runtime/fouc-prevention.md) — Automatic token hiding
 
 ### Routing

package/dist/runtime/bind.js

@@ -10,6 +10,8 @@ import { effect, createScope, withScope, isInDevMode, signal, computeVirtualRang
 import { WRAPPED_HANDLER } from '../form/form.js';
 import { linkScopeToDom, withDevtoolsDomTarget } from '../core/devtools.js';
 import { isComponent, normalizePropDef, coercePropValue, kebabToCamel, camelToKebab } from './component.js';
+import { observeLazyElement, getLazyComponent } from './lazy.js';
+import { bindBoundary } from './boundary.js';
 // ============================================================================
 // Utilities
 // ============================================================================
@@ -1355,6 +1357,161 @@ function bindPortal(root, ctx, cleanups) {
     }
 }
 // ============================================================================
+// d-lazy Directive
+// ============================================================================
+/**
+ * Bind all [d-lazy] directives within root.
+ * Loads a lazy component when it enters the viewport.
+ */
+function bindLazy(root, ctx, cleanups, refs, events) {
+    const elements = qsaIncludingRoot(root, '[d-lazy]');
+    for (const el of elements) {
+        const lazyComponentName = normalizeBinding(el.getAttribute('d-lazy'));
+        if (!lazyComponentName)
+            continue;
+        const lazyResult = getLazyComponent(lazyComponentName);
+        if (!lazyResult) {
+            warn(`d-lazy: component "${lazyComponentName}" not found. Use createLazyComponent() to create it.`);
+            continue;
+        }
+        const { state } = lazyResult;
+        const htmlEl = el;
+        // Get loading and error templates from attributes
+        const loadingTemplate = el.getAttribute('d-lazy-loading') ?? state.loadingTemplate ?? '';
+        const errorTemplate = el.getAttribute('d-lazy-error') ?? state.errorTemplate ?? '';
+        // Remove the d-lazy attribute to prevent reprocessing
+        el.removeAttribute('d-lazy');
+        el.removeAttribute('d-lazy-loading');
+        el.removeAttribute('d-lazy-error');
+        // Track the current rendered node (starts as the original placeholder element)
+        let currentNode = htmlEl;
+        let componentMounted = false;
+        let componentDispose = null;
+        let componentEl = null;
+        let hasIntersected = false;
+        const refName = normalizeBinding(htmlEl.getAttribute('d-ref'));
+        const syncRef = (node) => {
+            if (!refName)
+                return;
+            if (node instanceof Element) {
+                refs.set(refName, node);
+            }
+        };
+        const replaceCurrentNode = (nextNode) => {
+            const parent = currentNode.parentNode;
+            if (!parent)
+                return;
+            parent.replaceChild(nextNode, currentNode);
+            currentNode = nextNode;
+            syncRef(nextNode);
+        };
+        const unmountComponent = () => {
+            if (componentDispose) {
+                componentDispose();
+                componentDispose = null;
+            }
+            componentMounted = false;
+            componentEl = null;
+        };
+        // Function to render the loaded component
+        const renderComponent = () => {
+            const comp = state.component();
+            if (!comp)
+                return;
+            // Create component element
+            const compDef = comp.definition;
+            const compEl = document.createElement(compDef.tag);
+            // Copy attributes from placeholder to component
+            for (const attr of Array.from(htmlEl.attributes)) {
+                if (!attr.name.startsWith('d-')) {
+                    compEl.setAttribute(attr.name, attr.value);
+                }
+            }
+            if (componentMounted && componentEl === compEl)
+                return;
+            replaceCurrentNode(compEl);
+            componentEl = compEl;
+            // Bind the component
+            const parentCtx = Object.create(ctx);
+            const parent = compEl.parentNode;
+            const nextSibling = compEl.nextSibling;
+            componentDispose = bind(compEl, parentCtx, {
+                components: { [compDef.tag]: comp },
+                events,
+                _skipLifecycle: true,
+            });
+            // bind() may replace the component host node; keep currentNode/ref pointing to the connected node.
+            if (!compEl.isConnected && parent) {
+                const renderedNode = nextSibling ? nextSibling.previousSibling : parent.lastChild;
+                if (renderedNode instanceof Node) {
+                    currentNode = renderedNode;
+                    syncRef(renderedNode);
+                }
+            }
+            componentMounted = true;
+        };
+        // Function to show loading state
+        const showLoading = () => {
+            if (loadingTemplate) {
+                if (componentMounted) {
+                    unmountComponent();
+                }
+                const loadingEl = document.createElement('div');
+                loadingEl.innerHTML = loadingTemplate;
+                replaceCurrentNode(loadingEl);
+            }
+        };
+        // Function to show error state
+        const showError = (err) => {
+            if (componentMounted) {
+                unmountComponent();
+            }
+            if (errorTemplate) {
+                const errorEl = document.createElement('div');
+                errorEl.innerHTML = errorTemplate;
+                replaceCurrentNode(errorEl);
+            }
+            else {
+                warn(`d-lazy: failed to load "${lazyComponentName}": ${err.message}`);
+            }
+        };
+        const syncFromState = () => {
+            // Always read reactive state so this effect stays subscribed even before visibility.
+            const loading = state.loading();
+            const error = state.error();
+            const comp = state.component();
+            if (!hasIntersected)
+                return;
+            if (error) {
+                showError(error);
+                return;
+            }
+            if (loading && !comp) {
+                showLoading();
+                return;
+            }
+            if (comp && !componentMounted) {
+                renderComponent();
+            }
+        };
+        // React to loading state changes
+        bindEffect(htmlEl, () => {
+            syncFromState();
+        });
+        // Observe element for viewport visibility
+        const cleanupObserver = observeLazyElement(htmlEl, () => {
+            hasIntersected = true;
+            syncFromState();
+            state.load();
+        }, 0 // Trigger when element enters viewport
+        );
+        cleanups.push(() => {
+            cleanupObserver();
+            unmountComponent();
+        });
+    }
+}
+// ============================================================================
 // d-when Directive
 // ============================================================================
 /**
@@ -3927,11 +4084,14 @@ export function bind(root, ctx, options = {}) {
         bindVirtualEach(root, ctx, cleanups);
         // 4. d-each — must run early: removes templates before TreeWalker visits them
         bindEach(root, ctx, cleanups);
-        // 5. Components — must run after d-each but before d-ref / text interpolation
+        // 5. d-boundary — must run before child directive/component passes
+        // to avoid binding boundary children twice (original + cloned subtree).
+        bindBoundary(root, ctx, cleanups);
+        // 6. Components — must run after d-each but before d-ref / text interpolation
         bindComponents(root, ctx, events, cleanups, onMountError);
-        // 6. d-ref — collect element references (after d-each removes templates)
+        // 7. d-ref — collect element references (after d-each removes templates)
         bindRef(root, refs);
-        // 6.5. d-text — safe textContent binding (before text interpolation)
+        // 7.5. d-text — safe textContent binding (before text interpolation)
         bindText(root, ctx, cleanups);
         // 7. Text interpolation (template plan cache + lazy parser fallback)
         bindTextInterpolation(root, ctx, rawTextSelectors, templatePlanCacheConfig, benchSession);
@@ -3955,6 +4115,8 @@ export function bind(root, ctx, options = {}) {
         bindError(root, ctx, cleanups);
         bindFormError(root, ctx, cleanups);
         // 17. d-portal — move already-bound elements to external targets
+        // d-lazy directive - loads component when it enters viewport
+        bindLazy(root, ctx, cleanups, refs, events);
         bindPortal(root, ctx, cleanups);
         // 18. d-if — must run last: elements are fully bound before conditional removal
         bindIf(root, ctx, cleanups, transitionRegistry);

package/dist/runtime/boundary.d.ts

@@ -0,0 +1,104 @@
+/**
+ * Dalila Error Boundary
+ *
+ * Provides error boundary component that captures errors in children
+ * and displays a fallback template.
+ *
+ * @module dalila/runtime/boundary
+ */
+import { signal, Signal } from '../core/index.js';
+import type { Component } from './component.js';
+import type { BindContext, DisposeFunction } from './bind.js';
+export interface ErrorBoundaryOptions {
+    /** Template to show when an error occurs */
+    fallback: string;
+    /** Callback when error is caught */
+    onError?: (error: Error) => void;
+    /** Callback when error is reset */
+    onReset?: () => void;
+}
+export interface ErrorBoundaryState {
+    /** The error that was caught */
+    error: ReturnType<typeof signal<Error | null>>;
+    /** Function to reset the error and retry */
+    reset: () => void;
+    /** Whether there's an error */
+    hasError: () => boolean;
+}
+export type ErrorBoundaryResult = {
+    /** The error boundary component */
+    component: Component;
+    /** Access to error boundary state */
+    state: ErrorBoundaryState;
+};
+/**
+ * Creates an error boundary component that catches errors in its children.
+ *
+ * @param options - Configuration for the error boundary
+ * @returns Component with error boundary functionality
+ *
+ * @example
+ * ```ts
+ * const ErrorBoundary = createErrorBoundary({
+ *   fallback: '<div class="error">Something went wrong</div>',
+ *   onError: (err) => console.error(err),
+ * });
+ *
+ * // Use as component
+ * <error-boundary>
+ *   <MyComponent />
+ * </error-boundary>
+ * ```
+ */
+export declare function createErrorBoundary(options: ErrorBoundaryOptions): Component;
+/**
+ * Bind d-boundary directive - wraps children with error handling
+ * This is typically used inside a component that provides error state
+ */
+export declare function bindBoundary(root: Element, ctx: BindContext, cleanups: DisposeFunction[]): void;
+/**
+ * Wraps a function with error boundary logic
+ *
+ * @param fn - Function that might throw
+ * @param errorSignal - Signal to store the error
+ * @returns Result of the function or undefined if error
+ *
+ * @example
+ * ```ts
+ * const result = withErrorBoundary(
+ *   () => riskyOperation(),
+ *   errorSignal
+ * );
+ * ```
+ */
+export declare function withErrorBoundary<T>(fn: () => T, errorSignal: Signal<Error | null>): T | undefined;
+/**
+ * Creates error boundary state for use in component setup
+ *
+ * @param options - Configuration options
+ * @returns Error boundary state and methods
+ *
+ * @example
+ * ```ts
+ * const MyComponent = defineComponent({
+ *   tag: 'my-component',
+ *   setup(props, ctx) {
+ *     const { error, reset, hasError } = createErrorBoundaryState({
+ *       onError: (err) => logError(err),
+ *     });
+ *
+ *     const handleClick = () => {
+ *       withErrorBoundary(() => {
+ *         // risky operation
+ *       }, error);
+ *     };
+ *
+ *     return { error, handleClick };
+ *   }
+ * });
+ * ```
+ */
+export declare function createErrorBoundaryState(options?: {
+    onError?: (error: Error) => void;
+    onReset?: () => void;
+}): ErrorBoundaryState;

package/dist/runtime/boundary.js

@@ -0,0 +1,304 @@
+/**
+ * Dalila Error Boundary
+ *
+ * Provides error boundary component that captures errors in children
+ * and displays a fallback template.
+ *
+ * @module dalila/runtime/boundary
+ */
+import { effect, signal } from '../core/index.js';
+import { bind } from './bind.js';
+import { defineComponent } from './component.js';
+// ============================================================================
+// Error Boundary Component
+// ============================================================================
+/**
+ * Creates an error boundary component that catches errors in its children.
+ *
+ * @param options - Configuration for the error boundary
+ * @returns Component with error boundary functionality
+ *
+ * @example
+ * ```ts
+ * const ErrorBoundary = createErrorBoundary({
+ *   fallback: '<div class="error">Something went wrong</div>',
+ *   onError: (err) => console.error(err),
+ * });
+ *
+ * // Use as component
+ * <error-boundary>
+ *   <MyComponent />
+ * </error-boundary>
+ * ```
+ */
+export function createErrorBoundary(options) {
+    const { fallback: fallbackTemplate = '<div>Error occurred</div>', onError, onReset, } = options;
+    // Create signal for tracking error state
+    const errorSignal = signal(null);
+    const hasError = () => {
+        return errorSignal() !== null;
+    };
+    const reset = () => {
+        errorSignal.set(null);
+        onReset?.();
+    };
+    const escapedFallback = escapeAttribute(fallbackTemplate);
+    // Create the error boundary component
+    const tag = `error-boundary-${Date.now()}-${Math.random().toString(36).slice(2, 9)}`;
+    const boundaryComponent = defineComponent({
+        tag,
+        template: `<div d-boundary="${escapedFallback}" d-boundary-error="$$boundaryError" d-boundary-reset="$$boundaryReset"><slot></slot></div>`,
+        props: {},
+        setup: () => {
+            if (onError) {
+                effect(() => {
+                    const error = errorSignal();
+                    if (error)
+                        onError(error);
+                });
+            }
+            // Return error state and reset function
+            return {
+                $$boundaryError: errorSignal,
+                $$boundaryReset: reset,
+                $$boundaryHasError: hasError,
+            };
+        }
+    });
+    // Return component with state
+    const result = {
+        component: boundaryComponent,
+        state: {
+            error: errorSignal,
+            reset,
+            hasError,
+        }
+    };
+    return boundaryComponent;
+}
+// ============================================================================
+// d-boundary Directive (for use within existing bind context)
+// ============================================================================
+/**
+ * Bind d-boundary directive - wraps children with error handling
+ * This is typically used inside a component that provides error state
+ */
+export function bindBoundary(root, ctx, cleanups) {
+    const elements = qsaIncludingRoot(root, '[d-boundary]');
+    const boundary = root.closest('[data-dalila-internal-bound]');
+    const consumedNested = new WeakSet();
+    for (const el of elements) {
+        if (consumedNested.has(el))
+            continue;
+        // Skip stale nodes from the initial snapshot.
+        if (!root.contains(el))
+            continue;
+        if (el.closest('[data-dalila-internal-bound]') !== boundary)
+            continue;
+        for (const nested of Array.from(el.querySelectorAll('[d-boundary]'))) {
+            consumedNested.add(nested);
+        }
+        const fallbackTemplate = el.getAttribute('d-boundary')?.trim() || '<div>Error occurred</div>';
+        const errorBindingName = normalizeBinding(el.getAttribute('d-boundary-error'));
+        const resetBindingName = normalizeBinding(el.getAttribute('d-boundary-reset'));
+        // Get error and reset from context
+        const errorSignal = errorBindingName ? ctx[errorBindingName] : null;
+        const resetFn = resetBindingName ? ctx[resetBindingName] : null;
+        // Remove d-boundary attributes to prevent reprocessing
+        el.removeAttribute('d-boundary');
+        el.removeAttribute('d-boundary-error');
+        el.removeAttribute('d-boundary-reset');
+        const templateChildren = Array.from(el.childNodes).map((child) => child.cloneNode(true));
+        const host = el;
+        // Preserve host node and render boundary content inside it.
+        while (host.firstChild) {
+            host.removeChild(host.firstChild);
+        }
+        let mountedNode = null;
+        let mountedDispose = null;
+        const unmountCurrent = () => {
+            if (mountedDispose) {
+                mountedDispose();
+                mountedDispose = null;
+            }
+            if (mountedNode && mountedNode.parentNode) {
+                mountedNode.parentNode.removeChild(mountedNode);
+            }
+            mountedNode = null;
+        };
+        const mountChildren = () => {
+            unmountCurrent();
+            const childCtx = Object.create(ctx);
+            if (errorSignal)
+                childCtx.error = errorSignal;
+            if (resetFn)
+                childCtx.reset = resetFn;
+            const container = document.createElement('div');
+            container.setAttribute('data-boundary-children', '');
+            container.setAttribute('data-dalila-internal-bound', '');
+            for (const child of templateChildren) {
+                container.appendChild(child.cloneNode(true));
+            }
+            host.appendChild(container);
+            mountedDispose = bind(container, childCtx, {
+                _skipLifecycle: true,
+            });
+            mountedNode = container;
+        };
+        const mountError = (error) => {
+            unmountCurrent();
+            const errorCtx = Object.create(ctx);
+            if (errorSignal)
+                errorCtx.error = errorSignal;
+            if (resetFn)
+                errorCtx.reset = resetFn;
+            const errorDisplay = document.createElement('div');
+            errorDisplay.setAttribute('data-boundary-error', '');
+            errorDisplay.setAttribute('data-dalila-internal-bound', '');
+            errorDisplay.innerHTML = fallbackTemplate;
+            const errorMsg = errorDisplay.querySelector('[data-error-message]');
+            if (errorMsg) {
+                errorMsg.textContent = error.message;
+            }
+            host.appendChild(errorDisplay);
+            mountedDispose = bind(errorDisplay, errorCtx, {
+                _skipLifecycle: true,
+            });
+            mountedNode = errorDisplay;
+        };
+        if (errorSignal) {
+            const getCurrentError = () => (typeof errorSignal === 'function' ? errorSignal() : null);
+            let lastError = getCurrentError();
+            if (lastError) {
+                mountError(lastError);
+            }
+            else {
+                mountChildren();
+            }
+            const disposeEffect = effect(() => {
+                const error = getCurrentError();
+                if (error === lastError)
+                    return;
+                lastError = error;
+                if (error) {
+                    mountError(error);
+                }
+                else {
+                    mountChildren();
+                }
+            });
+            cleanups.push(disposeEffect);
+        }
+        else {
+            mountChildren();
+        }
+        cleanups.push(() => {
+            unmountCurrent();
+        });
+    }
+}
+// Helper to find elements including root
+function qsaIncludingRoot(root, selector) {
+    const out = [];
+    if (root.matches(selector))
+        out.push(root);
+    out.push(...Array.from(root.querySelectorAll(selector)));
+    return out;
+}
+// Helper to normalize binding
+function normalizeBinding(raw) {
+    if (!raw)
+        return null;
+    const trimmed = raw.trim();
+    if (!trimmed)
+        return null;
+    return trimmed;
+}
+function escapeAttribute(value) {
+    return value
+        .replace(/&/g, '&amp;')
+        .replace(/"/g, '&quot;')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;');
+}
+// ============================================================================
+// withErrorBoundary Helper
+// ============================================================================
+/**
+ * Wraps a function with error boundary logic
+ *
+ * @param fn - Function that might throw
+ * @param errorSignal - Signal to store the error
+ * @returns Result of the function or undefined if error
+ *
+ * @example
+ * ```ts
+ * const result = withErrorBoundary(
+ *   () => riskyOperation(),
+ *   errorSignal
+ * );
+ * ```
+ */
+export function withErrorBoundary(fn, errorSignal) {
+    try {
+        return fn();
+    }
+    catch (error) {
+        errorSignal.set(error instanceof Error ? error : new Error(String(error)));
+        return undefined;
+    }
+}
+// ============================================================================
+// createErrorBoundaryState (for use in setup)
+// ============================================================================
+/**
+ * Creates error boundary state for use in component setup
+ *
+ * @param options - Configuration options
+ * @returns Error boundary state and methods
+ *
+ * @example
+ * ```ts
+ * const MyComponent = defineComponent({
+ *   tag: 'my-component',
+ *   setup(props, ctx) {
+ *     const { error, reset, hasError } = createErrorBoundaryState({
+ *       onError: (err) => logError(err),
+ *     });
+ *
+ *     const handleClick = () => {
+ *       withErrorBoundary(() => {
+ *         // risky operation
+ *       }, error);
+ *     };
+ *
+ *     return { error, handleClick };
+ *   }
+ * });
+ * ```
+ */
+export function createErrorBoundaryState(options) {
+    const errorSignal = signal(null);
+    const hasError = () => {
+        return errorSignal() !== null;
+    };
+    const reset = () => {
+        errorSignal.set(null);
+        options?.onReset?.();
+    };
+    // Set up error handler
+    const handleError = options?.onError;
+    if (handleError) {
+        effect(() => {
+            const error = errorSignal();
+            if (error) {
+                handleError(error);
+            }
+        });
+    }
+    return {
+        error: errorSignal,
+        reset,
+        hasError,
+    };
+}

package/dist/runtime/index.d.ts

@@ -12,3 +12,7 @@ export { fromHtml } from './fromHtml.js';
 export type { FromHtmlOptions } from './fromHtml.js';
 export { defineComponent } from './component.js';
 export type { Component, ComponentDefinition, PropsSchema, PropSignals, SetupContext, TypedPropSignals, TypedSetupContext, EmitsSchema, RefsSchema, TypedEmit, TypedRef, } from './component.js';
+export { createLazyComponent, createSuspense, getLazyComponent, preloadLazyComponent, isLazyComponentLoaded, getLazyComponentState, observeLazyElement, } from './lazy.js';
+export type { LazyComponentOptions, LazyComponentState, LazyComponentLoader, LazyComponentResult, } from './lazy.js';
+export { createErrorBoundary, bindBoundary, withErrorBoundary, createErrorBoundaryState, } from './boundary.js';
+export type { ErrorBoundaryOptions, ErrorBoundaryState, ErrorBoundaryResult, } from './boundary.js';

package/dist/runtime/index.js

@@ -9,3 +9,5 @@
 export { bind, autoBind, mount, configure, createPortalTarget, getVirtualListController, scrollToVirtualIndex } from './bind.js';
 export { fromHtml } from './fromHtml.js';
 export { defineComponent } from './component.js';
+export { createLazyComponent, createSuspense, getLazyComponent, preloadLazyComponent, isLazyComponentLoaded, getLazyComponentState, observeLazyElement, } from './lazy.js';
+export { createErrorBoundary, bindBoundary, withErrorBoundary, createErrorBoundaryState, } from './boundary.js';

package/dist/runtime/lazy.d.ts

@@ -0,0 +1,109 @@
+/**
+ * Dalila Lazy Components
+ *
+ * Provides lazy loading for components with:
+ * - createLazyComponent: Create a component that loads on demand
+ * - d-lazy directive: Load component when it enters viewport
+ * - d-suspense: Show fallback while component is loading
+ *
+ * @module dalila/runtime/lazy
+ */
+import { signal } from '../core/index.js';
+import type { Component } from './component.js';
+export interface LazyComponentOptions {
+    /** Loading fallback template */
+    loading?: string;
+    /** Error template to show on failure */
+    error?: string;
+    /** Delay before showing loading state (ms) */
+    loadingDelay?: number;
+}
+export interface LazyComponentState {
+    /** Whether the component is currently loading */
+    loading: ReturnType<typeof signal<boolean>>;
+    /** Whether the component has failed to load */
+    error: ReturnType<typeof signal<Error | null>>;
+    /** The loaded component (if successful) */
+    component: ReturnType<typeof signal<Component | null>>;
+    /** Function to trigger loading */
+    load: () => void;
+    /** Function to retry after error */
+    retry: () => void;
+    /** Whether the component has been loaded */
+    loaded: ReturnType<typeof signal<boolean>>;
+    /** Default loading template (used by d-lazy when attribute is omitted) */
+    loadingTemplate: string;
+    /** Default error template (used by d-lazy when attribute is omitted) */
+    errorTemplate: string;
+}
+export type LazyComponentLoader = () => Promise<{
+    default: Component;
+} | Component>;
+export interface LazyComponentResult {
+    /** The lazy component definition */
+    component: Component;
+    /** Access to lazy loading state */
+    state: LazyComponentState;
+}
+/**
+ * Get a lazy component by its tag name
+ */
+export declare function getLazyComponent(tag: string): LazyComponentResult | undefined;
+/**
+ * Creates a lazy-loaded component that defers loading until needed.
+ *
+ * @param loader - Function that returns a promise resolving to the component
+ * @param options - Configuration options for the lazy component
+ * @returns Component definition with loading state
+ *
+ * @example
+ * ```ts
+ * const LazyModal = createLazyComponent(() => import('./Modal.svelte'));
+ *
+ * // With custom loading template
+ * const LazyModal = createLazyComponent(
+ *   () => import('./Modal.svelte'),
+ *   { loading: '<div>Loading...</div>' }
+ * );
+ * ```
+ */
+export declare function createLazyComponent(loader: LazyComponentLoader, options?: LazyComponentOptions): Component;
+/**
+ * Creates a suspense component that shows loading/ error states
+ * while child components are loading.
+ *
+ * @param options - Configuration for suspense behavior
+ * @returns Component that wraps children with suspense behavior
+ *
+ * @example
+ * ```html
+ * <d-suspense>
+ *   <d-placeholder>Loading...</d-placeholder>
+ *   <my-heavy-component></my-heavy-component>
+ * </d-suspense>
+ * ```
+ */
+export declare function createSuspense(options?: {
+    /** Template to show while loading */
+    loading?: string;
+    /** Template to show on error */
+    error?: string;
+    /** Delay before showing loading state */
+    loadingDelay?: number;
+}): Component;
+/**
+ * Preload a lazy component
+ */
+export declare function preloadLazyComponent(tag: string): void;
+/**
+ * Check if a lazy component is loaded
+ */
+export declare function isLazyComponentLoaded(tag: string): boolean;
+/**
+ * Get lazy component loading state
+ */
+export declare function getLazyComponentState(tag: string): LazyComponentState | undefined;
+/**
+ * Observe an element for lazy loading when it enters viewport
+ */
+export declare function observeLazyElement(el: Element, loadCallback: () => void, threshold?: number): () => void;

package/dist/runtime/lazy.js

@@ -0,0 +1,254 @@
+/**
+ * Dalila Lazy Components
+ *
+ * Provides lazy loading for components with:
+ * - createLazyComponent: Create a component that loads on demand
+ * - d-lazy directive: Load component when it enters viewport
+ * - d-suspense: Show fallback while component is loading
+ *
+ * @module dalila/runtime/lazy
+ */
+import { signal } from '../core/index.js';
+import { defineComponent, isComponent } from './component.js';
+// ============================================================================
+// Lazy Component Registry
+// ============================================================================
+/**
+ * Global registry for lazy-loaded components
+ */
+const lazyComponentRegistry = new Map();
+/**
+ * Get a lazy component by its tag name
+ */
+export function getLazyComponent(tag) {
+    return lazyComponentRegistry.get(tag);
+}
+// ============================================================================
+// createLazyComponent
+// ============================================================================
+/**
+ * Creates a lazy-loaded component that defers loading until needed.
+ *
+ * @param loader - Function that returns a promise resolving to the component
+ * @param options - Configuration options for the lazy component
+ * @returns Component definition with loading state
+ *
+ * @example
+ * ```ts
+ * const LazyModal = createLazyComponent(() => import('./Modal.svelte'));
+ *
+ * // With custom loading template
+ * const LazyModal = createLazyComponent(
+ *   () => import('./Modal.svelte'),
+ *   { loading: '<div>Loading...</div>' }
+ * );
+ * ```
+ */
+export function createLazyComponent(loader, options = {}) {
+    const { loadingDelay = 0, loading = '', error = '' } = options;
+    // Create signals for tracking load state
+    const loadingSignal = signal(false);
+    const errorSignal = signal(null);
+    const componentSignal = signal(null);
+    const loadedSignal = signal(false);
+    let loadingTimeout = null;
+    let loadInFlight = false;
+    const load = () => {
+        if (loadedSignal() || loadInFlight)
+            return;
+        loadInFlight = true;
+        // Handle loading delay
+        if (loadingDelay > 0) {
+            loadingTimeout = setTimeout(() => {
+                loadingSignal.set(true);
+            }, loadingDelay);
+        }
+        else {
+            loadingSignal.set(true);
+        }
+        errorSignal.set(null);
+        Promise.resolve()
+            .then(() => loader())
+            .then((module) => {
+            // Clear timeout if still pending
+            if (loadingTimeout) {
+                clearTimeout(loadingTimeout);
+                loadingTimeout = null;
+            }
+            const loadedComp = isComponent(module)
+                ? module
+                : ('default' in module ? module.default : null);
+            if (!loadedComp) {
+                throw new Error('Lazy component: failed to load component from module');
+            }
+            componentSignal.set(loadedComp);
+            loadingSignal.set(false);
+            loadedSignal.set(true);
+            loadInFlight = false;
+        })
+            .catch((err) => {
+            if (loadingTimeout) {
+                clearTimeout(loadingTimeout);
+                loadingTimeout = null;
+            }
+            errorSignal.set(err instanceof Error ? err : new Error(String(err)));
+            loadingSignal.set(false);
+            loadInFlight = false;
+        });
+    };
+    const retry = () => {
+        errorSignal.set(null);
+        load();
+    };
+    // Create the wrapper component
+    const tag = `lazy-${Date.now()}-${Math.random().toString(36).slice(2, 9)}`;
+    const wrapperComponent = defineComponent({
+        tag,
+        template: '', // Required: empty template for lazy wrapper
+        props: {},
+        setup: () => {
+            // Auto-load when component is mounted
+            // The actual loading is triggered by the d-lazy directive or manually
+            return {
+                $$lazyLoading: loadingSignal,
+                $$lazyError: errorSignal,
+                $$lazyComponent: componentSignal,
+                $$lazyLoad: load,
+                $$lazyRetry: retry,
+                $$lazyLoaded: loadedSignal,
+            };
+        }
+    });
+    // Register in global registry for lookup by d-lazy directive
+    const result = {
+        component: wrapperComponent,
+        state: {
+            loading: loadingSignal,
+            error: errorSignal,
+            component: componentSignal,
+            load,
+            retry,
+            loaded: loadedSignal,
+            loadingTemplate: loading,
+            errorTemplate: error,
+        }
+    };
+    lazyComponentRegistry.set(tag, result);
+    return wrapperComponent;
+}
+// ============================================================================
+// d-suspense Component
+// ============================================================================
+/**
+ * Creates a suspense component that shows loading/ error states
+ * while child components are loading.
+ *
+ * @param options - Configuration for suspense behavior
+ * @returns Component that wraps children with suspense behavior
+ *
+ * @example
+ * ```html
+ * <d-suspense>
+ *   <d-placeholder>Loading...</d-placeholder>
+ *   <my-heavy-component></my-heavy-component>
+ * </d-suspense>
+ * ```
+ */
+export function createSuspense(options = {}) {
+    const suspenseTag = `d-suspense-${Date.now()}-${Math.random().toString(36).slice(2, 9)}`;
+    return defineComponent({
+        tag: suspenseTag,
+        props: {},
+        // Keep children rendered; loading/error orchestration can be layered on top.
+        template: `<div data-suspense=""><slot></slot></div>`,
+        setup: () => {
+            // Reserved for future suspense orchestration (loading/error/loadingDelay).
+            void options;
+            return {};
+        }
+    });
+}
+// ============================================================================
+// Lazy Loading Utilities
+// ============================================================================
+/**
+ * Preload a lazy component
+ */
+export function preloadLazyComponent(tag) {
+    const lazyResult = lazyComponentRegistry.get(tag);
+    if (lazyResult) {
+        lazyResult.state.load();
+    }
+}
+/**
+ * Check if a lazy component is loaded
+ */
+export function isLazyComponentLoaded(tag) {
+    const lazyResult = lazyComponentRegistry.get(tag);
+    return lazyResult?.state.loaded() ?? false;
+}
+/**
+ * Get lazy component loading state
+ */
+export function getLazyComponentState(tag) {
+    return lazyComponentRegistry.get(tag)?.state;
+}
+// ============================================================================
+// Intersection Observer for d-lazy
+// ============================================================================
+const lazyObserverElements = new WeakMap();
+const lazyObservers = new Map();
+function getLazyIntersectionObserver(threshold = 0) {
+    const currentCtor = globalThis.IntersectionObserver;
+    const cached = lazyObservers.get(threshold);
+    if (cached && cached.ctor === currentCtor) {
+        return cached.observer;
+    }
+    const observer = new IntersectionObserver((entries) => {
+        for (const entry of entries) {
+            if (entry.isIntersecting) {
+                const data = lazyObserverElements.get(entry.target);
+                if (data?.callback) {
+                    data.callback();
+                }
+                // Stop observing after triggering
+                observer?.unobserve(entry.target);
+            }
+        }
+    }, {
+        root: null, // viewport
+        rootMargin: '0px',
+        threshold,
+    });
+    lazyObservers.set(threshold, { observer, ctor: currentCtor });
+    return observer;
+}
+/**
+ * Observe an element for lazy loading when it enters viewport
+ */
+export function observeLazyElement(el, loadCallback, threshold = 0) {
+    if (typeof globalThis.IntersectionObserver !== 'function') {
+        // Graceful fallback for environments without IntersectionObserver.
+        // Load only if still connected after the current bind pass.
+        // This avoids eager loading elements removed by directives like d-if.
+        let canceled = false;
+        queueMicrotask(() => {
+            if (canceled)
+                return;
+            if (el.isConnected) {
+                loadCallback();
+            }
+        });
+        return () => {
+            canceled = true;
+        };
+    }
+    const observer = getLazyIntersectionObserver(threshold);
+    lazyObserverElements.set(el, { callback: loadCallback, threshold });
+    observer.observe(el);
+    // Return cleanup function
+    return () => {
+        lazyObserverElements.delete(el);
+        observer.unobserve(el);
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dalila",
-  "version": "1.9.8",
+  "version": "1.9.9",
   "description": "DOM-first reactive framework based on signals",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",