dalila 1.9.5 → 1.9.7

package/README.md

@@ -58,7 +58,7 @@ bind(document.getElementById('app')!, ctx);
 
 ### Runtime
 
-- [Template Binding](./docs/runtime/bind.md) — `bind()`, `mount()`, `configure()`, text interpolation, events
+- [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
 - [FOUC Prevention](./docs/runtime/fouc-prevention.md) — Automatic token hiding
 
@@ -76,7 +76,7 @@ bind(document.getElementById('app')!, ctx);
 - [when](./docs/core/when.md) — Conditional visibility
 - [match](./docs/core/match.md) — Switch-style rendering
 - [for](./docs/core/for.md) — List rendering with keyed diffing
-- [Virtual Lists](./docs/core/virtual.md) — Fixed-height windowed rendering for large datasets
+- [Virtual Lists](./docs/core/virtual.md) — Fixed and dynamic-height windowed rendering with infinite-scroll hooks
 
 ### Data
 
@@ -108,7 +108,7 @@ Firefox extension workflows:
 
 ```
 dalila           → signal, computed, effect, batch, ...
-dalila/runtime   → bind(), mount(), configure(), defineComponent()
+dalila/runtime   → bind(), mount(), configure(), createPortalTarget(), defineComponent()
 dalila/context   → createContext, provide, inject
 dalila/http      → createHttpClient with XSRF protection
 ```
@@ -143,6 +143,23 @@ const dispose = mount('.app', { count: signal(0) });
 dispose();
 ```
 
+### Transitions and Portal
+
+```html
+<div d-when="open" d-transition="fade">Panel</div>
+<div d-portal="showModal ? '#modal-root' : null">Modal content</div>
+```
+
+```ts
+import { configure, createPortalTarget } from 'dalila/runtime';
+
+const modalTarget = createPortalTarget('modal-root');
+
+configure({
+  transitions: [{ name: 'fade', duration: 250 }],
+});
+```
+
 ### Scopes
 
 ```ts

package/dist/cli/check.js

@@ -520,7 +520,7 @@ function extractTemplateIdentifiers(html) {
         i++;
     }
     // --- 2. Directive scanning (supports single and double quotes) ---
-    const DIRECTIVE_RE = /\b(d-each|d-virtual-each|d-virtual-height|d-virtual-item-height|d-virtual-overscan|d-if|d-when|d-match|d-html|d-attr-[a-zA-Z][\w-]*|d-bind-[a-zA-Z][\w-]*|d-on-[a-zA-Z][\w-]*|d-form-error|d-form|d-array)\s*=\s*(['"])([\s\S]*?)\2/g;
+    const DIRECTIVE_RE = /\b(d-each|d-virtual-each|d-virtual-height|d-virtual-item-height|d-virtual-estimated-height|d-virtual-measure|d-virtual-infinite|d-virtual-overscan|d-if|d-when|d-match|d-portal|d-html|d-attr-[a-zA-Z][\w-]*|d-bind-[a-zA-Z][\w-]*|d-on-[a-zA-Z][\w-]*|d-form-error|d-form|d-array)\s*=\s*(['"])([\s\S]*?)\2/g;
     DIRECTIVE_RE.lastIndex = 0;
     let match;
     while ((match = DIRECTIVE_RE.exec(html))) {
@@ -528,6 +528,8 @@ function extractTemplateIdentifiers(html) {
         const value = match[3].trim();
         if (!value)
             continue;
+        if (directive === 'd-virtual-measure' && value.toLowerCase() === 'auto')
+            continue;
         const roots = extractRootIdentifiers(value);
         const loc = offsetToLineCol(match.index);
         for (const name of roots) {
@@ -691,6 +693,9 @@ const LOOP_FORCED_CHECK_SOURCES = new Set([
     'd-virtual-each',
     'd-virtual-height',
     'd-virtual-item-height',
+    'd-virtual-estimated-height',
+    'd-virtual-measure',
+    'd-virtual-infinite',
     'd-virtual-overscan',
 ]);
 function checkHtmlContent(html, filePath, validIdentifiers, diagnostics) {

package/dist/runtime/bind.d.ts

@@ -6,6 +6,7 @@
  *
  * @module dalila/runtime
  */
+import { Signal } from '../core/index.js';
 import type { Component } from './component.js';
 export interface BindOptions {
     /**
@@ -30,6 +31,10 @@ export interface BindOptions {
     components?: Record<string, Component> | Component[];
     /** Error policy for component `ctx.onMount()` callbacks. Default: 'log'. */
     onMountError?: 'log' | 'throw';
+    /**
+     * Optional runtime transition registry used by `d-transition`.
+     */
+    transitions?: TransitionConfig[];
     /**
      * Internal flag — set by fromHtml for router/template rendering.
      * Skips HMR context registration but KEEPS d-ready/d-loading lifecycle.
@@ -59,6 +64,24 @@ export interface BindHandle {
     getRef(name: string): Element | null;
     getRefs(): Readonly<Record<string, Element>>;
 }
+export interface TransitionConfig {
+    name: string;
+    enter?: (el: HTMLElement) => void;
+    leave?: (el: HTMLElement) => void;
+    duration?: number;
+}
+export type VirtualListAlign = 'start' | 'center' | 'end';
+export interface VirtualScrollToIndexOptions {
+    align?: VirtualListAlign;
+    behavior?: ScrollBehavior;
+}
+export interface VirtualListController {
+    scrollToIndex: (index: number, options?: VirtualScrollToIndexOptions) => void;
+    refresh: () => void;
+}
+export declare function getVirtualListController(target: Element | null): VirtualListController | null;
+export declare function scrollToVirtualIndex(target: Element | null, index: number, options?: VirtualScrollToIndexOptions): boolean;
+export declare function createPortalTarget(id: string): Signal<Element | null>;
 /**
  * Set global defaults for all `bind()` / `mount()` calls.
  *

package/dist/runtime/bind.js

@@ -97,6 +97,7 @@ function warn(message) {
         console.warn(`[Dalila] ${message}`);
     }
 }
+const portalSyncByElement = new WeakMap();
 function describeBindRoot(root) {
     const explicit = root.getAttribute('data-component') ||
         root.getAttribute('data-devtools-label') ||
@@ -1135,13 +1136,231 @@ function bindEmit(root, ctx, cleanups) {
         }
     }
 }
+function createTransitionRegistry(transitions) {
+    const registry = new Map();
+    if (!transitions)
+        return registry;
+    for (const cfg of transitions) {
+        if (!cfg || typeof cfg !== 'object')
+            continue;
+        const name = typeof cfg.name === 'string' ? cfg.name.trim() : '';
+        if (!name) {
+            warn('configure({ transitions }): each transition must have a non-empty "name"');
+            continue;
+        }
+        registry.set(name, cfg);
+    }
+    return registry;
+}
+function readTransitionNames(el) {
+    const raw = el.getAttribute('d-transition');
+    if (!raw)
+        return [];
+    return raw
+        .split(/\s+/)
+        .map(v => v.trim())
+        .filter(Boolean);
+}
+function parseCssTimeToMs(value) {
+    const token = value.trim();
+    if (!token)
+        return 0;
+    if (token.endsWith('ms')) {
+        const ms = Number(token.slice(0, -2));
+        return Number.isFinite(ms) ? Math.max(0, ms) : 0;
+    }
+    if (token.endsWith('s')) {
+        const seconds = Number(token.slice(0, -1));
+        return Number.isFinite(seconds) ? Math.max(0, seconds * 1000) : 0;
+    }
+    const fallback = Number(token);
+    return Number.isFinite(fallback) ? Math.max(0, fallback) : 0;
+}
+function getTransitionDurationMs(el, names, registry) {
+    let durationFromRegistry = 0;
+    for (const name of names) {
+        const cfg = registry.get(name);
+        if (!cfg)
+            continue;
+        if (typeof cfg.duration === 'number' && Number.isFinite(cfg.duration)) {
+            durationFromRegistry = Math.max(durationFromRegistry, Math.max(0, cfg.duration));
+        }
+    }
+    let durationFromCss = 0;
+    if (typeof window !== 'undefined' && typeof window.getComputedStyle === 'function') {
+        const style = window.getComputedStyle(el);
+        const durations = style.transitionDuration.split(',');
+        const delays = style.transitionDelay.split(',');
+        const total = Math.max(durations.length, delays.length);
+        for (let i = 0; i < total; i++) {
+            const duration = parseCssTimeToMs(durations[Math.min(i, durations.length - 1)] ?? '0ms');
+            const delay = parseCssTimeToMs(delays[Math.min(i, delays.length - 1)] ?? '0ms');
+            durationFromCss = Math.max(durationFromCss, duration + delay);
+        }
+    }
+    return Math.max(durationFromRegistry, durationFromCss);
+}
+function runTransitionHook(phase, el, names, registry) {
+    for (const name of names) {
+        const cfg = registry.get(name);
+        const hook = phase === 'enter' ? cfg?.enter : cfg?.leave;
+        if (typeof hook !== 'function')
+            continue;
+        try {
+            hook(el);
+        }
+        catch (err) {
+            warn(`d-transition (${name}): ${phase} hook failed (${err.message || String(err)})`);
+        }
+    }
+}
+function syncPortalElement(el) {
+    const sync = portalSyncByElement.get(el);
+    sync?.();
+}
+function createTransitionController(el, registry, cleanups) {
+    const names = readTransitionNames(el);
+    const hasTransition = names.length > 0;
+    let token = 0;
+    let timeoutId = null;
+    const cancelPending = () => {
+        token++;
+        if (timeoutId != null) {
+            clearTimeout(timeoutId);
+            timeoutId = null;
+        }
+    };
+    cleanups.push(cancelPending);
+    const enter = () => {
+        cancelPending();
+        if (!hasTransition)
+            return;
+        el.removeAttribute('data-leave');
+        el.setAttribute('data-enter', '');
+        runTransitionHook('enter', el, names, registry);
+    };
+    const leave = (onDone) => {
+        cancelPending();
+        if (!hasTransition) {
+            onDone();
+            return;
+        }
+        const current = ++token;
+        el.removeAttribute('data-enter');
+        el.setAttribute('data-leave', '');
+        runTransitionHook('leave', el, names, registry);
+        const durationMs = getTransitionDurationMs(el, names, registry);
+        if (durationMs <= 0) {
+            if (current === token)
+                onDone();
+            return;
+        }
+        timeoutId = setTimeout(() => {
+            timeoutId = null;
+            if (current !== token)
+                return;
+            onDone();
+        }, durationMs);
+    };
+    return { hasTransition, enter, leave };
+}
+function bindPortal(root, ctx, cleanups) {
+    const elements = qsaIncludingRoot(root, '[d-portal]');
+    for (const el of elements) {
+        const rawExpression = el.getAttribute('d-portal')?.trim();
+        if (!rawExpression)
+            continue;
+        let expressionAst = null;
+        let fallbackSelector = null;
+        try {
+            expressionAst = parseExpression(rawExpression);
+        }
+        catch {
+            // Allow selector shorthand: d-portal="#modal-root"
+            fallbackSelector = rawExpression;
+        }
+        const htmlEl = el;
+        const anchor = document.createComment('d-portal');
+        htmlEl.parentNode?.insertBefore(anchor, htmlEl);
+        const coerceTarget = (value) => {
+            const resolved = resolve(value);
+            if (resolved == null || resolved === false)
+                return null;
+            if (typeof resolved === 'string') {
+                const selector = resolved.trim();
+                if (!selector)
+                    return null;
+                if (typeof document === 'undefined')
+                    return null;
+                const target = document.querySelector(selector);
+                if (!target) {
+                    warn(`d-portal: target "${selector}" not found`);
+                    return null;
+                }
+                return target;
+            }
+            if (typeof Element !== 'undefined' && resolved instanceof Element) {
+                return resolved;
+            }
+            warn('d-portal: expression must resolve to selector string, Element, or null');
+            return null;
+        };
+        const restoreToAnchor = () => {
+            const hostParent = anchor.parentNode;
+            if (!hostParent)
+                return;
+            if (htmlEl.parentNode === hostParent)
+                return;
+            const next = anchor.nextSibling;
+            if (next)
+                hostParent.insertBefore(htmlEl, next);
+            else
+                hostParent.appendChild(htmlEl);
+        };
+        const syncPortal = () => {
+            let target = null;
+            if (expressionAst) {
+                const result = evalExpressionAst(expressionAst, ctx);
+                if (!result.ok) {
+                    if (result.reason === 'missing_identifier') {
+                        warn(`d-portal: ${result.message}`);
+                    }
+                    else {
+                        warn(`d-portal: invalid expression "${rawExpression}"`);
+                    }
+                    target = null;
+                }
+                else {
+                    target = coerceTarget(result.value);
+                }
+            }
+            else {
+                target = coerceTarget(fallbackSelector);
+            }
+            if (!target) {
+                restoreToAnchor();
+                return;
+            }
+            if (htmlEl.parentNode !== target) {
+                target.appendChild(htmlEl);
+            }
+        };
+        portalSyncByElement.set(htmlEl, syncPortal);
+        bindEffect(htmlEl, syncPortal);
+        cleanups.push(() => {
+            portalSyncByElement.delete(htmlEl);
+            restoreToAnchor();
+            anchor.remove();
+        });
+    }
+}
 // ============================================================================
 // d-when Directive
 // ============================================================================
 /**
  * Bind all [d-when] directives within root
  */
-function bindWhen(root, ctx, cleanups) {
+function bindWhen(root, ctx, cleanups, transitionRegistry) {
     const elements = qsaIncludingRoot(root, '[when], [d-when]');
     for (const el of elements) {
         const attrName = el.hasAttribute('when') ? 'when' : 'd-when';
@@ -1154,13 +1373,32 @@ function bindWhen(root, ctx, cleanups) {
             continue;
         }
         const htmlEl = el;
+        const transitions = createTransitionController(htmlEl, transitionRegistry, cleanups);
         // Apply initial state synchronously to avoid FOUC (flash of unstyled content)
         const initialValue = !!resolve(binding);
-        htmlEl.style.display = initialValue ? '' : 'none';
+        if (initialValue) {
+            htmlEl.style.display = '';
+            if (transitions.hasTransition) {
+                htmlEl.removeAttribute('data-leave');
+                htmlEl.setAttribute('data-enter', '');
+            }
+        }
+        else {
+            htmlEl.style.display = 'none';
+            htmlEl.removeAttribute('data-enter');
+            htmlEl.removeAttribute('data-leave');
+        }
         // Then create reactive effect to keep it updated
         bindEffect(htmlEl, () => {
             const value = !!resolve(binding);
-            htmlEl.style.display = value ? '' : 'none';
+            if (value) {
+                htmlEl.style.display = '';
+                transitions.enter();
+                return;
+            }
+            transitions.leave(() => {
+                htmlEl.style.display = 'none';
+            });
         });
     }
 }
@@ -1260,6 +1498,47 @@ function readVirtualHeightOption(raw, ctx) {
     }
     return trimmed;
 }
+function readVirtualMeasureOption(raw, ctx) {
+    if (!raw)
+        return false;
+    const trimmed = raw.trim();
+    if (!trimmed)
+        return false;
+    if (trimmed.toLowerCase() === 'auto')
+        return true;
+    const fromCtx = ctx[trimmed];
+    if (fromCtx === undefined)
+        return false;
+    const resolved = resolve(fromCtx);
+    if (resolved === true)
+        return true;
+    if (typeof resolved === 'string' && resolved.trim().toLowerCase() === 'auto')
+        return true;
+    return false;
+}
+function readVirtualCallbackOption(raw, ctx, label) {
+    if (!raw)
+        return null;
+    const trimmed = raw.trim();
+    if (!trimmed)
+        return null;
+    const fromCtx = ctx[trimmed];
+    if (fromCtx === undefined) {
+        warn(`${label}: "${trimmed}" not found in context`);
+        return null;
+    }
+    if (typeof fromCtx === 'function' && !isSignal(fromCtx)) {
+        return fromCtx;
+    }
+    if (isSignal(fromCtx)) {
+        const resolved = fromCtx();
+        if (typeof resolved === 'function') {
+            return resolved;
+        }
+    }
+    warn(`${label}: "${trimmed}" must resolve to a function`);
+    return null;
+}
 function createVirtualSpacer(template, kind) {
     const spacer = template.cloneNode(false);
     spacer.removeAttribute('id');
@@ -1281,13 +1560,199 @@ function createVirtualSpacer(template, kind) {
     spacer.style.listStyle = 'none';
     return spacer;
 }
+const virtualScrollRestoreCache = new Map();
+const VIRTUAL_SCROLL_RESTORE_CACHE_MAX_ENTRIES = 256;
+function getVirtualScrollRestoreValue(key) {
+    const value = virtualScrollRestoreCache.get(key);
+    if (value === undefined)
+        return undefined;
+    // Touch entry to keep LRU ordering.
+    virtualScrollRestoreCache.delete(key);
+    virtualScrollRestoreCache.set(key, value);
+    return value;
+}
+function setVirtualScrollRestoreValue(key, value) {
+    virtualScrollRestoreCache.delete(key);
+    virtualScrollRestoreCache.set(key, value);
+    while (virtualScrollRestoreCache.size > VIRTUAL_SCROLL_RESTORE_CACHE_MAX_ENTRIES) {
+        const oldestKey = virtualScrollRestoreCache.keys().next().value;
+        if (!oldestKey)
+            break;
+        virtualScrollRestoreCache.delete(oldestKey);
+    }
+}
+function clampVirtual(value, min, max) {
+    return Math.max(min, Math.min(max, value));
+}
+function getElementPositionPath(el) {
+    const parts = [];
+    let current = el;
+    while (current) {
+        const tag = current.tagName.toLowerCase();
+        const parentEl = current.parentElement;
+        if (!parentEl) {
+            parts.push(tag);
+            break;
+        }
+        let index = 1;
+        let sib = current.previousElementSibling;
+        while (sib) {
+            index++;
+            sib = sib.previousElementSibling;
+        }
+        parts.push(`${tag}:${index}`);
+        current = parentEl;
+    }
+    return parts.reverse().join('>');
+}
+const virtualRestoreDocumentIds = new WeakMap();
+let nextVirtualRestoreDocumentId = 0;
+function getVirtualRestoreDocumentId(doc) {
+    const existing = virtualRestoreDocumentIds.get(doc);
+    if (existing !== undefined)
+        return existing;
+    const next = ++nextVirtualRestoreDocumentId;
+    virtualRestoreDocumentIds.set(doc, next);
+    return next;
+}
+function getVirtualRestoreKey(doc, templatePath, scrollContainer, bindingName, keyBinding) {
+    const locationPath = typeof window !== 'undefined'
+        ? `${window.location.pathname}${window.location.search}`
+        : '';
+    const containerIdentity = scrollContainer?.id
+        ? `#${scrollContainer.id}`
+        : (scrollContainer ? getElementPositionPath(scrollContainer) : '');
+    const docId = getVirtualRestoreDocumentId(doc);
+    return `${docId}|${locationPath}|${bindingName}|${keyBinding ?? ''}|${containerIdentity}|${templatePath}`;
+}
+class VirtualHeightsIndex {
+    constructor(itemCount, estimatedHeight) {
+        this.itemCount = 0;
+        this.estimatedHeight = 1;
+        this.tree = [0];
+        this.overrides = new Map();
+        this.reset(itemCount, estimatedHeight);
+    }
+    get count() {
+        return this.itemCount;
+    }
+    snapshotOverrides() {
+        return new Map(this.overrides);
+    }
+    reset(itemCount, estimatedHeight, seed) {
+        this.itemCount = Number.isFinite(itemCount) ? Math.max(0, Math.floor(itemCount)) : 0;
+        this.estimatedHeight = Number.isFinite(estimatedHeight) ? Math.max(1, estimatedHeight) : 1;
+        this.tree = new Array(this.itemCount + 1).fill(0);
+        this.overrides.clear();
+        for (let i = 0; i < this.itemCount; i++) {
+            this.addAt(i + 1, this.estimatedHeight);
+        }
+        if (!seed)
+            return;
+        for (const [index, height] of seed.entries()) {
+            if (index < 0 || index >= this.itemCount)
+                continue;
+            this.set(index, height);
+        }
+    }
+    set(index, height) {
+        if (!Number.isFinite(height) || height <= 0)
+            return false;
+        if (index < 0 || index >= this.itemCount)
+            return false;
+        const next = Math.max(1, height);
+        const current = this.get(index);
+        if (Math.abs(next - current) < 0.5)
+            return false;
+        this.addAt(index + 1, next - current);
+        if (Math.abs(next - this.estimatedHeight) < 0.5) {
+            this.overrides.delete(index);
+        }
+        else {
+            this.overrides.set(index, next);
+        }
+        return true;
+    }
+    get(index) {
+        if (index < 0 || index >= this.itemCount)
+            return this.estimatedHeight;
+        return this.overrides.get(index) ?? this.estimatedHeight;
+    }
+    prefix(endExclusive) {
+        if (endExclusive <= 0)
+            return 0;
+        const clampedEnd = Math.min(this.itemCount, Math.max(0, Math.floor(endExclusive)));
+        let i = clampedEnd;
+        let sum = 0;
+        while (i > 0) {
+            sum += this.tree[i];
+            i -= i & -i;
+        }
+        return sum;
+    }
+    total() {
+        return this.prefix(this.itemCount);
+    }
+    lowerBound(target) {
+        if (this.itemCount === 0 || target <= 0)
+            return 0;
+        let idx = 0;
+        let bit = 1;
+        while ((bit << 1) <= this.itemCount)
+            bit <<= 1;
+        let sum = 0;
+        while (bit > 0) {
+            const next = idx + bit;
+            if (next <= this.itemCount && sum + this.tree[next] < target) {
+                idx = next;
+                sum += this.tree[next];
+            }
+            bit >>= 1;
+        }
+        return Math.min(this.itemCount, idx);
+    }
+    indexAtOffset(offset) {
+        if (this.itemCount === 0)
+            return 0;
+        if (!Number.isFinite(offset) || offset <= 0)
+            return 0;
+        const totalHeight = this.total();
+        if (offset >= totalHeight)
+            return this.itemCount - 1;
+        const idx = this.lowerBound(offset + 0.0001);
+        return clampVirtual(idx, 0, this.itemCount - 1);
+    }
+    addAt(treeIndex, delta) {
+        let i = treeIndex;
+        while (i <= this.itemCount) {
+            this.tree[i] += delta;
+            i += i & -i;
+        }
+    }
+}
+function readVirtualListApi(target) {
+    if (!target)
+        return null;
+    return target.__dalilaVirtualList ?? null;
+}
+export function getVirtualListController(target) {
+    return readVirtualListApi(target);
+}
+export function scrollToVirtualIndex(target, index, options) {
+    const controller = readVirtualListApi(target);
+    if (!controller)
+        return false;
+    controller.scrollToIndex(index, options);
+    return true;
+}
 /**
  * Bind all [d-virtual-each] directives within root.
  *
- * V1 constraints:
- * - Fixed item height (required via d-virtual-item-height)
- * - Vertical virtualization only
- * - Parent element is the scroll container
+ * Supports:
+ * - Fixed item height (`d-virtual-item-height`)
+ * - Dynamic item height (`d-virtual-measure="auto"`)
+ * - Infinite scroll callback (`d-virtual-infinite`)
+ * - Parent element as vertical scroll container
  */
 function bindVirtualEach(root, ctx, cleanups) {
     const elements = qsaIncludingRoot(root, '[d-virtual-each]')
@@ -1299,16 +1764,28 @@ function bindVirtualEach(root, ctx, cleanups) {
         const itemHeightBinding = normalizeBinding(el.getAttribute('d-virtual-item-height'));
         const itemHeightRaw = itemHeightBinding ?? el.getAttribute('d-virtual-item-height');
         const itemHeightValue = readVirtualNumberOption(itemHeightRaw, ctx, 'd-virtual-item-height');
-        const itemHeight = itemHeightValue == null ? NaN : itemHeightValue;
-        if (!Number.isFinite(itemHeight) || itemHeight <= 0) {
+        const fixedItemHeight = Number.isFinite(itemHeightValue) && itemHeightValue > 0
+            ? itemHeightValue
+            : NaN;
+        const dynamicHeight = readVirtualMeasureOption(normalizeBinding(el.getAttribute('d-virtual-measure')) ?? el.getAttribute('d-virtual-measure'), ctx);
+        if (!dynamicHeight && (!Number.isFinite(fixedItemHeight) || fixedItemHeight <= 0)) {
             warn(`d-virtual-each: invalid item height on "${bindingName}". Falling back to d-each.`);
             el.setAttribute('d-each', bindingName);
             el.removeAttribute('d-virtual-each');
             el.removeAttribute('d-virtual-item-height');
+            el.removeAttribute('d-virtual-estimated-height');
+            el.removeAttribute('d-virtual-measure');
+            el.removeAttribute('d-virtual-infinite');
             el.removeAttribute('d-virtual-overscan');
             el.removeAttribute('d-virtual-height');
             continue;
         }
+        const estimatedHeightBinding = normalizeBinding(el.getAttribute('d-virtual-estimated-height'));
+        const estimatedHeightRaw = estimatedHeightBinding ?? el.getAttribute('d-virtual-estimated-height');
+        const estimatedHeightValue = readVirtualNumberOption(estimatedHeightRaw, ctx, 'd-virtual-estimated-height');
+        const estimatedItemHeight = Number.isFinite(estimatedHeightValue) && estimatedHeightValue > 0
+            ? estimatedHeightValue
+            : (Number.isFinite(fixedItemHeight) ? fixedItemHeight : 48);
         const overscanBinding = normalizeBinding(el.getAttribute('d-virtual-overscan'));
         const overscanRaw = overscanBinding ?? el.getAttribute('d-virtual-overscan');
         const overscanValue = readVirtualNumberOption(overscanRaw, ctx, 'd-virtual-overscan');
@@ -1316,15 +1793,20 @@ function bindVirtualEach(root, ctx, cleanups) {
             ? Math.max(0, Math.floor(overscanValue))
             : 6;
         const viewportHeight = readVirtualHeightOption(normalizeBinding(el.getAttribute('d-virtual-height')) ?? el.getAttribute('d-virtual-height'), ctx);
+        const onEndReached = readVirtualCallbackOption(normalizeBinding(el.getAttribute('d-virtual-infinite')) ?? el.getAttribute('d-virtual-infinite'), ctx, 'd-virtual-infinite');
         let binding = ctx[bindingName];
         if (binding === undefined) {
             warn(`d-virtual-each: "${bindingName}" not found in context`);
             binding = [];
         }
+        const templatePathBeforeDetach = getElementPositionPath(el);
         const comment = document.createComment('d-virtual-each');
         el.parentNode?.replaceChild(comment, el);
         el.removeAttribute('d-virtual-each');
         el.removeAttribute('d-virtual-item-height');
+        el.removeAttribute('d-virtual-estimated-height');
+        el.removeAttribute('d-virtual-measure');
+        el.removeAttribute('d-virtual-infinite');
         el.removeAttribute('d-virtual-overscan');
         el.removeAttribute('d-virtual-height');
         const keyBinding = normalizeBinding(el.getAttribute('d-key'));
@@ -1341,8 +1823,14 @@ function bindVirtualEach(root, ctx, cleanups) {
             if (!scrollContainer.style.overflowY)
                 scrollContainer.style.overflowY = 'auto';
         }
+        const restoreKey = getVirtualRestoreKey(el.ownerDocument, templatePathBeforeDetach, scrollContainer, bindingName, keyBinding);
+        const savedScrollTop = getVirtualScrollRestoreValue(restoreKey);
+        if (scrollContainer && Number.isFinite(savedScrollTop)) {
+            scrollContainer.scrollTop = Math.max(0, savedScrollTop);
+        }
         const clonesByKey = new Map();
         const disposesByKey = new Map();
+        const observedElements = new Set();
         const metadataByKey = new Map();
         const itemsByKey = new Map();
         const objectKeyIds = new WeakMap();
@@ -1352,6 +1840,7 @@ function bindVirtualEach(root, ctx, cleanups) {
         const missingKeyWarned = new Set();
         let warnedNonArray = false;
         let warnedViewportFallback = false;
+        let heightsIndex = dynamicHeight ? new VirtualHeightsIndex(0, estimatedItemHeight) : null;
         const getObjectKeyId = (value) => {
             const existing = objectKeyIds.get(value);
             if (existing !== undefined)
@@ -1406,6 +1895,7 @@ function bindVirtualEach(root, ctx, cleanups) {
             }
             return index;
         };
+        let rowResizeObserver = null;
         function createClone(key, item, index, count) {
             const clone = template.cloneNode(true);
             const itemCtx = Object.create(ctx);
@@ -1431,6 +1921,7 @@ function bindVirtualEach(root, ctx, cleanups) {
             itemCtx.$odd = metadata.$odd;
             itemCtx.$even = metadata.$even;
             clone.setAttribute('data-dalila-internal-bound', '');
+            clone.setAttribute('data-dalila-virtual-index', String(index));
             const dispose = bind(clone, itemCtx, { _skipLifecycle: true });
             disposesByKey.set(key, dispose);
             clonesByKey.set(key, clone);
@@ -1446,9 +1937,17 @@ function bindVirtualEach(root, ctx, cleanups) {
                 metadata.$odd.set(index % 2 !== 0);
                 metadata.$even.set(index % 2 === 0);
             }
+            const clone = clonesByKey.get(key);
+            if (clone) {
+                clone.setAttribute('data-dalila-virtual-index', String(index));
+            }
         }
         function removeKey(key) {
             const clone = clonesByKey.get(key);
+            if (clone && rowResizeObserver && observedElements.has(clone)) {
+                rowResizeObserver.unobserve(clone);
+                observedElements.delete(clone);
+            }
             clone?.remove();
             clonesByKey.delete(key);
             metadataByKey.delete(key);
@@ -1460,31 +1959,106 @@ function bindVirtualEach(root, ctx, cleanups) {
             }
         }
         let currentItems = [];
+        let lastEndReachedCount = -1;
+        let endReachedPending = false;
+        const remapDynamicHeights = (prevItems, nextItems) => {
+            if (!dynamicHeight || !heightsIndex)
+                return;
+            const heightsByKey = new Map();
+            for (let i = 0; i < prevItems.length; i++) {
+                const key = keyValueToString(readKeyValue(prevItems[i], i), i);
+                if (!heightsByKey.has(key)) {
+                    heightsByKey.set(key, heightsIndex.get(i));
+                }
+            }
+            heightsIndex.reset(nextItems.length, estimatedItemHeight);
+            for (let i = 0; i < nextItems.length; i++) {
+                const key = keyValueToString(readKeyValue(nextItems[i], i), i);
+                const height = heightsByKey.get(key);
+                if (height !== undefined) {
+                    heightsIndex.set(i, height);
+                }
+            }
+        };
+        const replaceItems = (nextItems) => {
+            remapDynamicHeights(currentItems, nextItems);
+            currentItems = nextItems;
+        };
+        const maybeTriggerEndReached = (visibleEnd, totalCount) => {
+            if (!onEndReached || totalCount === 0)
+                return;
+            if (visibleEnd < totalCount)
+                return;
+            if (lastEndReachedCount === totalCount || endReachedPending)
+                return;
+            lastEndReachedCount = totalCount;
+            const result = onEndReached();
+            if (result && typeof result.then === 'function') {
+                endReachedPending = true;
+                Promise.resolve(result)
+                    .catch(() => { })
+                    .finally(() => {
+                    endReachedPending = false;
+                });
+            }
+        };
         function renderVirtualList(items) {
             const parent = comment.parentNode;
             if (!parent)
                 return;
+            if (dynamicHeight && heightsIndex && heightsIndex.count !== items.length) {
+                heightsIndex.reset(items.length, estimatedItemHeight);
+            }
             const viewportHeightValue = scrollContainer?.clientHeight ?? 0;
-            const effectiveViewportHeight = viewportHeightValue > 0 ? viewportHeightValue : itemHeight * 10;
+            const effectiveViewportHeight = viewportHeightValue > 0
+                ? viewportHeightValue
+                : (dynamicHeight ? estimatedItemHeight * 10 : fixedItemHeight * 10);
             const scrollTop = scrollContainer?.scrollTop ?? 0;
             if (viewportHeightValue <= 0 && !warnedViewportFallback) {
                 warnedViewportFallback = true;
                 warn('d-virtual-each: scroll container has no measurable height. Using fallback viewport size.');
             }
-            const range = computeVirtualRange({
-                itemCount: items.length,
-                itemHeight,
-                scrollTop,
-                viewportHeight: effectiveViewportHeight,
-                overscan,
-            });
-            topSpacer.style.height = `${range.topOffset}px`;
-            bottomSpacer.style.height = `${range.bottomOffset}px`;
+            let start = 0;
+            let end = 0;
+            let topOffset = 0;
+            let bottomOffset = 0;
+            let totalHeight = 0;
+            let visibleEndForEndReached = 0;
+            if (dynamicHeight && heightsIndex) {
+                totalHeight = heightsIndex.total();
+                if (items.length > 0) {
+                    const visibleStart = heightsIndex.indexAtOffset(scrollTop);
+                    const visibleEnd = clampVirtual(heightsIndex.lowerBound(scrollTop + effectiveViewportHeight) + 1, visibleStart + 1, items.length);
+                    visibleEndForEndReached = visibleEnd;
+                    start = clampVirtual(visibleStart - overscan, 0, items.length);
+                    end = clampVirtual(visibleEnd + overscan, start, items.length);
+                    topOffset = heightsIndex.prefix(start);
+                    bottomOffset = Math.max(0, totalHeight - heightsIndex.prefix(end));
+                }
+            }
+            else {
+                const range = computeVirtualRange({
+                    itemCount: items.length,
+                    itemHeight: fixedItemHeight,
+                    scrollTop,
+                    viewportHeight: effectiveViewportHeight,
+                    overscan,
+                });
+                start = range.start;
+                end = range.end;
+                topOffset = range.topOffset;
+                bottomOffset = range.bottomOffset;
+                totalHeight = range.totalHeight;
+                visibleEndForEndReached = clampVirtual(Math.ceil((scrollTop + effectiveViewportHeight) / fixedItemHeight), 0, items.length);
+            }
+            topSpacer.style.height = `${topOffset}px`;
+            bottomSpacer.style.height = `${bottomOffset}px`;
+            topSpacer.setAttribute('data-dalila-virtual-total', String(totalHeight));
             const orderedClones = [];
             const orderedKeys = [];
             const nextKeys = new Set();
             const changedKeys = new Set();
-            for (let i = range.start; i < range.end; i++) {
+            for (let i = start; i < end; i++) {
                 const item = items[i];
                 let key = keyValueToString(readKeyValue(item, i), i);
                 if (nextKeys.has(key)) {
@@ -1510,7 +2084,7 @@ function bindVirtualEach(root, ctx, cleanups) {
                 if (!changedKeys.has(key))
                     continue;
                 removeKey(key);
-                orderedClones[i] = createClone(key, items[range.start + i], range.start + i, items.length);
+                orderedClones[i] = createClone(key, items[start + i], start + i, items.length);
             }
             for (const key of Array.from(clonesByKey.keys())) {
                 if (nextKeys.has(key))
@@ -1525,6 +2099,22 @@ function bindVirtualEach(root, ctx, cleanups) {
                 }
                 referenceNode = clone;
             }
+            if (dynamicHeight && rowResizeObserver) {
+                const nextObserved = new Set(orderedClones);
+                for (const clone of Array.from(observedElements)) {
+                    if (nextObserved.has(clone))
+                        continue;
+                    rowResizeObserver.unobserve(clone);
+                    observedElements.delete(clone);
+                }
+                for (const clone of orderedClones) {
+                    if (observedElements.has(clone))
+                        continue;
+                    rowResizeObserver.observe(clone);
+                    observedElements.add(clone);
+                }
+            }
+            maybeTriggerEndReached(visibleEndForEndReached, items.length);
         }
         let framePending = false;
         let pendingRaf = null;
@@ -1552,28 +2142,89 @@ function bindVirtualEach(root, ctx, cleanups) {
         const onScroll = () => scheduleRender();
         const onResize = () => scheduleRender();
         scrollContainer?.addEventListener('scroll', onScroll, { passive: true });
-        if (typeof window !== 'undefined') {
+        let containerResizeObserver = null;
+        if (typeof ResizeObserver !== 'undefined' && scrollContainer) {
+            containerResizeObserver = new ResizeObserver(() => scheduleRender());
+            containerResizeObserver.observe(scrollContainer);
+        }
+        else if (typeof window !== 'undefined') {
             window.addEventListener('resize', onResize);
         }
+        if (dynamicHeight && typeof ResizeObserver !== 'undefined' && heightsIndex) {
+            rowResizeObserver = new ResizeObserver((entries) => {
+                let changed = false;
+                for (const entry of entries) {
+                    const target = entry.target;
+                    const indexRaw = target.getAttribute('data-dalila-virtual-index');
+                    if (!indexRaw)
+                        continue;
+                    const index = Number(indexRaw);
+                    if (!Number.isFinite(index))
+                        continue;
+                    const measured = entry.contentRect?.height;
+                    if (!Number.isFinite(measured) || measured <= 0)
+                        continue;
+                    changed = heightsIndex.set(index, measured) || changed;
+                }
+                if (changed)
+                    scheduleRender();
+            });
+        }
+        const scrollToIndex = (index, options) => {
+            if (!scrollContainer || currentItems.length === 0)
+                return;
+            const safeIndex = clampVirtual(Math.floor(index), 0, currentItems.length - 1);
+            const viewportSize = scrollContainer.clientHeight > 0
+                ? scrollContainer.clientHeight
+                : (dynamicHeight ? estimatedItemHeight * 10 : fixedItemHeight * 10);
+            const align = options?.align ?? 'start';
+            let top = dynamicHeight && heightsIndex
+                ? heightsIndex.prefix(safeIndex)
+                : safeIndex * fixedItemHeight;
+            const itemSize = dynamicHeight && heightsIndex
+                ? heightsIndex.get(safeIndex)
+                : fixedItemHeight;
+            if (align === 'center') {
+                top = top - (viewportSize / 2) + (itemSize / 2);
+            }
+            else if (align === 'end') {
+                top = top - viewportSize + itemSize;
+            }
+            top = Math.max(0, top);
+            if (options?.behavior && typeof scrollContainer.scrollTo === 'function') {
+                scrollContainer.scrollTo({ top, behavior: options.behavior });
+            }
+            else {
+                scrollContainer.scrollTop = top;
+            }
+            scheduleRender();
+        };
+        const virtualApi = {
+            scrollToIndex,
+            refresh: scheduleRender,
+        };
+        if (scrollContainer) {
+            scrollContainer.__dalilaVirtualList = virtualApi;
+        }
         if (isSignal(binding)) {
             bindEffect(scrollContainer ?? el, () => {
                 const value = binding();
                 if (Array.isArray(value)) {
                     warnedNonArray = false;
-                    currentItems = value;
+                    replaceItems(value);
                 }
                 else {
                     if (!warnedNonArray) {
                         warnedNonArray = true;
                         warn(`d-virtual-each: "${bindingName}" is not an array or signal-of-array`);
                     }
-                    currentItems = [];
+                    replaceItems([]);
                 }
                 renderVirtualList(currentItems);
             });
         }
         else if (Array.isArray(binding)) {
-            currentItems = binding;
+            replaceItems(binding);
             renderVirtualList(currentItems);
         }
         else {
@@ -1581,7 +2232,10 @@ function bindVirtualEach(root, ctx, cleanups) {
         }
         cleanups.push(() => {
             scrollContainer?.removeEventListener('scroll', onScroll);
-            if (typeof window !== 'undefined') {
+            if (containerResizeObserver) {
+                containerResizeObserver.disconnect();
+            }
+            else if (typeof window !== 'undefined') {
                 window.removeEventListener('resize', onResize);
             }
             if (pendingRaf != null && typeof cancelAnimationFrame === 'function') {
@@ -1591,6 +2245,17 @@ function bindVirtualEach(root, ctx, cleanups) {
             if (pendingTimeout != null)
                 clearTimeout(pendingTimeout);
             pendingTimeout = null;
+            if (rowResizeObserver) {
+                rowResizeObserver.disconnect();
+            }
+            observedElements.clear();
+            if (scrollContainer) {
+                setVirtualScrollRestoreValue(restoreKey, scrollContainer.scrollTop);
+                const host = scrollContainer;
+                if (host.__dalilaVirtualList === virtualApi) {
+                    delete host.__dalilaVirtualList;
+                }
+            }
             for (const key of Array.from(clonesByKey.keys()))
                 removeKey(key);
             topSpacer.remove();
@@ -1851,7 +2516,7 @@ function bindEach(root, ctx, cleanups) {
  * Unlike [d-when] which toggles display, d-if adds/removes the element from
  * the DOM entirely. A comment node is left as placeholder for insertion position.
  */
-function bindIf(root, ctx, cleanups) {
+function bindIf(root, ctx, cleanups, transitionRegistry) {
     const elements = qsaIncludingRoot(root, '[d-if]');
     const processedElse = new Set();
     for (const el of elements) {
@@ -1869,23 +2534,36 @@ function bindIf(root, ctx, cleanups) {
         el.parentNode?.replaceChild(comment, el);
         el.removeAttribute('d-if');
         const htmlEl = el;
+        const transitions = createTransitionController(htmlEl, transitionRegistry, cleanups);
         // Handle d-else branch
         let elseHtmlEl = null;
         let elseComment = null;
+        let elseTransitions = null;
         if (elseEl) {
             processedElse.add(elseEl);
             elseComment = document.createComment('d-else');
             elseEl.parentNode?.replaceChild(elseComment, elseEl);
             elseEl.removeAttribute('d-else');
             elseHtmlEl = elseEl;
+            elseTransitions = createTransitionController(elseHtmlEl, transitionRegistry, cleanups);
         }
         // Apply initial state synchronously to avoid FOUC
         const initialValue = !!resolve(binding);
         if (initialValue) {
             comment.parentNode?.insertBefore(htmlEl, comment);
+            syncPortalElement(htmlEl);
+            if (transitions.hasTransition) {
+                htmlEl.removeAttribute('data-leave');
+                htmlEl.setAttribute('data-enter', '');
+            }
         }
         else if (elseHtmlEl && elseComment) {
             elseComment.parentNode?.insertBefore(elseHtmlEl, elseComment);
+            syncPortalElement(elseHtmlEl);
+            if (elseTransitions?.hasTransition) {
+                elseHtmlEl.removeAttribute('data-leave');
+                elseHtmlEl.setAttribute('data-enter', '');
+            }
         }
         // Then create reactive effect to keep it updated
         if (elseHtmlEl && elseComment) {
@@ -1896,18 +2574,26 @@ function bindIf(root, ctx, cleanups) {
                 if (value) {
                     if (!htmlEl.parentNode) {
                         comment.parentNode?.insertBefore(htmlEl, comment);
+                        syncPortalElement(htmlEl);
                     }
-                    if (capturedElseEl.parentNode) {
-                        capturedElseEl.parentNode.removeChild(capturedElseEl);
-                    }
+                    transitions.enter();
+                    elseTransitions?.leave(() => {
+                        if (capturedElseEl.parentNode) {
+                            capturedElseEl.parentNode.removeChild(capturedElseEl);
+                        }
+                    });
                 }
                 else {
-                    if (htmlEl.parentNode) {
-                        htmlEl.parentNode.removeChild(htmlEl);
-                    }
+                    transitions.leave(() => {
+                        if (htmlEl.parentNode) {
+                            htmlEl.parentNode.removeChild(htmlEl);
+                        }
+                    });
                     if (!capturedElseEl.parentNode) {
                         capturedElseComment.parentNode?.insertBefore(capturedElseEl, capturedElseComment);
+                        syncPortalElement(capturedElseEl);
                     }
+                    elseTransitions?.enter();
                 }
             });
         }
@@ -1917,12 +2603,16 @@ function bindIf(root, ctx, cleanups) {
                 if (value) {
                     if (!htmlEl.parentNode) {
                         comment.parentNode?.insertBefore(htmlEl, comment);
+                        syncPortalElement(htmlEl);
                     }
+                    transitions.enter();
                 }
                 else {
-                    if (htmlEl.parentNode) {
-                        htmlEl.parentNode.removeChild(htmlEl);
-                    }
+                    transitions.leave(() => {
+                        if (htmlEl.parentNode) {
+                            htmlEl.parentNode.removeChild(htmlEl);
+                        }
+                    });
                 }
             });
         }
@@ -3064,6 +3754,20 @@ function bindComponents(root, ctx, events, cleanups, onMountError) {
 // Global Configuration
 // ============================================================================
 let globalConfig = {};
+export function createPortalTarget(id) {
+    const targetSignal = signal(null);
+    if (typeof document === 'undefined') {
+        return targetSignal;
+    }
+    let target = document.getElementById(id);
+    if (!target) {
+        target = document.createElement('div');
+        target.id = id;
+        document.body.appendChild(target);
+    }
+    targetSignal.set(target);
+    return targetSignal;
+}
 /**
  * Set global defaults for all `bind()` / `mount()` calls.
  *
@@ -3116,8 +3820,8 @@ export function configure(config) {
 export function bind(root, ctx, options = {}) {
     // ── Merge global config with per-call options ──
     if (Object.keys(globalConfig).length > 0) {
-        const { components: globalComponents, ...globalRest } = globalConfig;
-        const { components: localComponents, ...localRest } = options;
+        const { components: globalComponents, transitions: globalTransitions, ...globalRest } = globalConfig;
+        const { components: localComponents, transitions: localTransitions, ...localRest } = options;
         const mergedOpts = { ...globalRest, ...localRest };
         // Combine component registries: local takes precedence over global
         if (globalComponents || localComponents) {
@@ -3142,6 +3846,20 @@ export function bind(root, ctx, options = {}) {
             mergeComponents(localComponents); // local wins
             mergedOpts.components = combined;
         }
+        if (globalTransitions || localTransitions) {
+            const byName = new Map();
+            for (const item of globalTransitions ?? []) {
+                if (!item || typeof item.name !== 'string')
+                    continue;
+                byName.set(item.name, item);
+            }
+            for (const item of localTransitions ?? []) {
+                if (!item || typeof item.name !== 'string')
+                    continue;
+                byName.set(item.name, item);
+            }
+            mergedOpts.transitions = Array.from(byName.values());
+        }
         options = mergedOpts;
     }
     // ── Resolve string selector ──
@@ -3186,6 +3904,7 @@ export function bind(root, ctx, options = {}) {
     const onMountError = options.onMountError ?? 'log';
     const rawTextSelectors = options.rawTextSelectors ?? DEFAULT_RAW_TEXT_SELECTORS;
     const templatePlanCacheConfig = resolveTemplatePlanCacheConfig(options);
+    const transitionRegistry = createTransitionRegistry(options.transitions);
     const benchSession = createBindBenchSession();
     const htmlRoot = root;
     // HMR support: Register binding context globally in dev mode.
@@ -3229,14 +3948,16 @@ export function bind(root, ctx, options = {}) {
         // 13. d-emit-* bindings (component template → parent)
         bindEmit(root, ctx, cleanups);
         // 14. d-when directive
-        bindWhen(root, ctx, cleanups);
+        bindWhen(root, ctx, cleanups, transitionRegistry);
         // 15. d-match directive
         bindMatch(root, ctx, cleanups);
         // 16. Form error displays — BEFORE d-if to bind errors in conditionally rendered sections
         bindError(root, ctx, cleanups);
         bindFormError(root, ctx, cleanups);
-        // 17. d-if — must run last: elements are fully bound before conditional removal
-        bindIf(root, ctx, cleanups);
+        // 17. d-portal — move already-bound elements to external targets
+        bindPortal(root, ctx, cleanups);
+        // 18. d-if — must run last: elements are fully bound before conditional removal
+        bindIf(root, ctx, cleanups, transitionRegistry);
     });
     // Bindings complete: remove loading state and mark as ready.
     // Only the top-level bind owns this lifecycle — d-each clones skip it.

package/dist/runtime/index.d.ts

@@ -6,8 +6,8 @@
  *
  * @module dalila/runtime
  */
-export { bind, autoBind, mount, configure } from './bind.js';
-export type { BindOptions, BindContext, BindData, DisposeFunction, BindHandle } from './bind.js';
+export { bind, autoBind, mount, configure, createPortalTarget, getVirtualListController, scrollToVirtualIndex } from './bind.js';
+export type { BindOptions, BindContext, BindData, DisposeFunction, BindHandle, TransitionConfig, VirtualListAlign, VirtualScrollToIndexOptions, VirtualListController } from './bind.js';
 export { fromHtml } from './fromHtml.js';
 export type { FromHtmlOptions } from './fromHtml.js';
 export { defineComponent } from './component.js';

package/dist/runtime/index.js

@@ -6,6 +6,6 @@
  *
  * @module dalila/runtime
  */
-export { bind, autoBind, mount, configure } from './bind.js';
+export { bind, autoBind, mount, configure, createPortalTarget, getVirtualListController, scrollToVirtualIndex } from './bind.js';
 export { fromHtml } from './fromHtml.js';
 export { defineComponent } from './component.js';

package/package.json

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