forty-cdk 0.0.4 → 0.2.0

package/fesm2022/forty-cdk-virtualization.mjs

@@ -0,0 +1,647 @@
+import { isPlatformBrowser } from '@angular/common';
+import * as i0 from '@angular/core';
+import { inject, DestroyRef, afterNextRender, PLATFORM_ID, computed, signal, effect, linkedSignal, untracked, InjectionToken, ElementRef, Injector, input, output, runInInjectionContext, ChangeDetectionStrategy, Component, TemplateRef, ViewContainerRef, Directive, numberAttribute } from '@angular/core';
+import { observeElementOffset, observeElementRect, elementScroll, Virtualizer } from '@tanstack/virtual-core';
+import { FOR_TABLE_CONTEXT } from 'forty-cdk';
+
+/**
+ * `afterNextRender` whose queued callback is cancelled on destroy, guarding the
+ * destroy-before-first-render hazard (a directive torn down between construction
+ * and the next render would otherwise still run the queued callback). It both
+ * `.destroy()`s the render ref from the destroy hook and re-checks a `destroyed`
+ * flag before invoking `fn`, covering the async and synchronous teardown orders.
+ *
+ * A standalone twin of the main entry point's
+ * `_internal/after-next-render-cancellable`: a secondary entry point cannot reach
+ * the main entry's internals across the package boundary, so the helper is
+ * mirrored here. Keep the two in sync; see that file for the full rationale.
+ *
+ * Must be called from an injection context. SSR-safe: `afterNextRender` never
+ * runs on the server, so the callback simply never fires.
+ */
+function afterNextRenderCancellable(fn) {
+    const destroyRef = inject(DestroyRef);
+    let destroyed = false;
+    const ref = afterNextRender(() => {
+        if (destroyed)
+            return;
+        fn();
+    });
+    destroyRef.onDestroy(() => {
+        destroyed = true;
+        ref.destroy();
+    });
+}
+
+/** Default number of items rendered beyond the visible window on each side. */
+const DEFAULT_OVERSCAN$1 = 5;
+/**
+ * Sum of the estimated size of every item: `count` × the estimate when it's
+ * uniform, else the per-index estimator summed. Used as the SSR / pre-mount
+ * total before the core has measured any item, and shared with the ergonomic
+ * viewport layer so the estimate-total math lives in one place.
+ */
+function estimateTotal(count, estimateSize) {
+    let total = 0;
+    for (let index = 0; index < count; index++) {
+        total += estimateSize(index);
+    }
+    return total;
+}
+function toVirtualItem(item) {
+    return {
+        index: item.index,
+        key: item.key,
+        start: item.start,
+        size: item.size,
+    };
+}
+/**
+ * Headless windowing core: given a reactive item count, a size estimator and a
+ * scroll container, returns the slice of items currently visible (plus
+ * overscan), the total scroll size, and imperative scroll/measure helpers. The
+ * consumer renders the items with their own `@for` and applies the position
+ * transform — this primitive owns no DOM.
+ *
+ * Backed by `@tanstack/virtual-core`. SSR-safe: off-browser it returns an empty
+ * window and the estimate-based total without touching `document`/`window`; the
+ * first real window is produced after the first browser render.
+ *
+ * Must be called from an injection context (a component/directive constructor
+ * or field initializer).
+ *
+ * @param options Reactive count, size estimator, scroll element and tuning.
+ * @returns A {@link ForVirtualizer} handle of signals + imperative methods.
+ */
+function injectVirtualizer(options) {
+    if (!isPlatformBrowser(inject(PLATFORM_ID))) {
+        return {
+            virtualItems: signal([]).asReadonly(),
+            totalSize: computed(() => estimateTotal(options.count(), options.estimateSize)),
+            range: computed(() => [0, 0]),
+            scrollToIndex: () => undefined,
+            scrollToOffset: () => undefined,
+            measureElement: () => undefined,
+        };
+    }
+    const horizontal = (options.orientation ?? 'vertical') === 'horizontal';
+    const overscan = options.overscan ?? DEFAULT_OVERSCAN$1;
+    const notify = signal(0, { ...(ngDevMode ? { debugName: "notify" } : /* istanbul ignore next */ {}), equal: () => false });
+    const mounted = signal(false, /* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "mounted" }] : /* istanbul ignore next */ []));
+    const buildCoreOptions = (count, scrollElement) => ({
+        count,
+        getScrollElement: () => scrollElement,
+        estimateSize: options.estimateSize,
+        getItemKey: options.getItemKey,
+        overscan,
+        horizontal,
+        scrollToFn: elementScroll,
+        observeElementRect,
+        observeElementOffset,
+        onChange: () => notify.set(0),
+    });
+    const virtualizer = new Virtualizer(buildCoreOptions(options.count(), options.scrollElement()));
+    effect(() => {
+        virtualizer.setOptions(buildCoreOptions(options.count(), options.scrollElement()));
+        virtualizer._willUpdate();
+        notify.set(0);
+    });
+    let cleanup;
+    afterNextRenderCancellable(() => {
+        cleanup = virtualizer._didMount();
+        mounted.set(true);
+    });
+    inject(DestroyRef).onDestroy(() => cleanup?.());
+    const virtualItems = computed(() => {
+        notify();
+        if (!mounted())
+            return [];
+        return virtualizer.getVirtualItems().map(toVirtualItem);
+    }, /* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "virtualItems" }] : /* istanbul ignore next */ []));
+    const totalSize = computed(() => {
+        notify();
+        if (!mounted())
+            return estimateTotal(options.count(), options.estimateSize);
+        return virtualizer.getTotalSize();
+    }, /* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "totalSize" }] : /* istanbul ignore next */ []));
+    const range = computed(() => {
+        const items = virtualItems();
+        if (items.length === 0)
+            return [0, 0];
+        return [items[0].index, items[items.length - 1].index + 1];
+    }, /* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "range" }] : /* istanbul ignore next */ []));
+    return {
+        virtualItems,
+        totalSize,
+        range,
+        scrollToIndex: (index, scrollOptions) => virtualizer.scrollToIndex(index, scrollOptions),
+        scrollToOffset: (offset) => virtualizer.scrollToOffset(offset),
+        measureElement: (element) => virtualizer.measureElement(element),
+    };
+}
+
+const DEFAULT_THRESHOLD = 5;
+/**
+ * Headless infinite-scroll detector: composes on top of any windowed list's
+ * `range` + `count` signals and fires `onLoadMore` once per threshold crossing,
+ * suppressing re-fire while a returned promise is pending and re-arming when
+ * `count` grows (a page was appended). It owns no DOM, adds no scroll listener —
+ * the trigger rides the existing reactive recompute — and is SSR-safe by
+ * construction: off-browser the window is `[0, 0]`, so it never fires.
+ *
+ * Must be called from an injection context (a component/directive constructor
+ * or field initializer).
+ *
+ * @param options Reactive `range` + `count`, an optional `threshold`/`disabled`,
+ *   and the `onLoadMore` callback.
+ * @returns A {@link ForInfiniteScroll} handle exposing the `pending` signal.
+ */
+function injectInfiniteScroll(options) {
+    const threshold = options.threshold ?? DEFAULT_THRESHOLD;
+    const pending = signal(false, /* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "pending" }] : /* istanbul ignore next */ []));
+    const nearEnd = computed(() => {
+        if (options.disabled?.())
+            return false;
+        const [start, end] = options.range();
+        if (end <= start)
+            return false;
+        const total = options.count();
+        return total > 0 && end >= total - threshold;
+    }, /* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "nearEnd" }] : /* istanbul ignore next */ []));
+    const armed = linkedSignal({ ...(ngDevMode ? { debugName: "armed" } : /* istanbul ignore next */ {}), source: () => options.count(),
+        computation: () => true });
+    effect(() => {
+        options.count();
+        if (!nearEnd() || !untracked(armed))
+            return;
+        if (untracked(pending))
+            return;
+        armed.set(false);
+        const result = options.onLoadMore();
+        if (result instanceof Promise) {
+            pending.set(true);
+            void result.finally(() => pending.set(false));
+        }
+    });
+    return { pending: pending.asReadonly() };
+}
+
+/** DI token carrying the {@link ForVirtualViewportContext}. */
+const FOR_VIRTUAL_VIEWPORT_CONTEXT = new InjectionToken('FOR_VIRTUAL_VIEWPORT_CONTEXT');
+/**
+ * Resolve the enclosing viewport context, throwing a primitive-prefixed error
+ * when the piece is used outside a `[forVirtualViewport]`. Internal — never
+ * re-exported from the primitive barrel.
+ */
+function injectVirtualViewportContext(consumer) {
+    const context = inject(FOR_VIRTUAL_VIEWPORT_CONTEXT, { optional: true });
+    if (!context) {
+        throw new Error(`[forty-cdk/virtualization] ${consumer} must be used inside a [forVirtualViewport].`);
+    }
+    return context;
+}
+
+/** Default estimated item size, in CSS pixels, when none is provided. */
+const DEFAULT_ESTIMATE_SIZE = 50;
+/** Default number of items rendered beyond the visible window on each side. */
+const DEFAULT_OVERSCAN = 5;
+/**
+ * Scroll viewport for the ergonomic virtualization layer. Decorate a fixed-size
+ * scroll container with `[forVirtualViewport]`, give it `[virtualCount]` and an
+ * `[estimateSize]`, and nest a single `*forVirtualFor` inside it — the viewport
+ * owns the scroll container, the total-size sizer, and the windowing core, so
+ * the consumer writes no manual spacer or position transform.
+ *
+ * Built on the headless {@link injectVirtualizer} core; for full manual control
+ * (custom DOM, dynamic measurement, window/document scroller) use that directly.
+ *
+ * The viewport forces `overflow: auto` on its host and renders a relatively
+ * positioned sizer whose main-axis size tracks `totalSize()`; `*forVirtualFor`
+ * projects its rows into that sizer and positions each one absolutely.
+ *
+ * `orientation` and `overscan` are read once when the viewport initializes;
+ * change them before first render, not at runtime.
+ */
+class ForVirtualViewport {
+    #host = inject(ElementRef);
+    #injector = inject(Injector);
+    #scrollElement = signal(this.#host.nativeElement, /* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "#scrollElement" }] : /* istanbul ignore next */ []));
+    #virtualizer = signal(null, /* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "#virtualizer" }] : /* istanbul ignore next */ []));
+    /** Total number of items in the full list. */
+    virtualCount = input.required(/* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "virtualCount" }] : /* istanbul ignore next */ []));
+    /** Estimated item size in px along the scroll axis: a number or a per-index estimator. */
+    estimateSize = input(DEFAULT_ESTIMATE_SIZE, /* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "estimateSize" }] : /* istanbul ignore next */ []));
+    /** Scroll axis. Resolved once on init; runtime changes are not tracked by the core. */
+    orientation = input('vertical', /* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "orientation" }] : /* istanbul ignore next */ []));
+    /** Items rendered beyond the visible window on each side. Resolved once on init. */
+    overscan = input(DEFAULT_OVERSCAN, /* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "overscan" }] : /* istanbul ignore next */ []));
+    /** Stable key for the item at `index`. Defaults to the index. */
+    getItemKey = input(undefined, /* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "getItemKey" }] : /* istanbul ignore next */ []));
+    /**
+     * Emits when the rendered window comes within ~`overscan` items of the end of
+     * the list, signalling the consumer to load the next page. Built on
+     * {@link injectInfiniteScroll}; fires once per threshold crossing and re-arms
+     * when the bound count grows. The consumer owns the fetch (e.g. via `resource()`).
+     */
+    endReached = output();
+    /**
+     * The total number of items in the full (non-windowed) list — the
+     * {@link ForVirtualViewportContext.count} the nested `*forVirtualFor` reads.
+     * Aliases the `virtualCount` input signal directly (no wrapper node).
+     */
+    count = this.virtualCount;
+    #estimator = computed(() => {
+        const estimate = this.estimateSize();
+        return typeof estimate === 'function' ? estimate : () => estimate;
+    }, /* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "#estimator" }] : /* istanbul ignore next */ []));
+    #estimateTotal = computed(() => estimateTotal(this.count(), this.#estimator()), /* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "#estimateTotal" }] : /* istanbul ignore next */ []));
+    /** The items in the currently visible window plus overscan. */
+    virtualItems = computed(() => this.#virtualizer()?.virtualItems() ?? [], /* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "virtualItems" }] : /* istanbul ignore next */ []));
+    /** Total scroll size of all items, in pixels (drives the sizer). */
+    totalSize = computed(() => this.#virtualizer()?.totalSize() ?? this.#estimateTotal(), /* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "totalSize" }] : /* istanbul ignore next */ []));
+    #range = computed(() => this.#virtualizer()?.range() ?? [0, 0], /* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "#range" }] : /* istanbul ignore next */ []));
+    sizerWidth = computed(() => this.orientation() === 'horizontal' ? `${this.totalSize()}px` : '100%', /* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "sizerWidth" }] : /* istanbul ignore next */ []));
+    sizerHeight = computed(() => this.orientation() === 'horizontal' ? '100%' : `${this.totalSize()}px`, /* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "sizerHeight" }] : /* istanbul ignore next */ []));
+    ngOnInit() {
+        runInInjectionContext(this.#injector, () => {
+            this.#virtualizer.set(injectVirtualizer({
+                count: this.count,
+                estimateSize: (index) => this.#estimator()(index),
+                scrollElement: this.#scrollElement,
+                orientation: this.orientation(),
+                overscan: this.overscan(),
+                getItemKey: this.getItemKey(),
+            }));
+            injectInfiniteScroll({
+                range: this.#range,
+                count: this.count,
+                onLoadMore: () => this.endReached.emit(),
+            });
+        });
+    }
+    /** Scroll the container so the item at `index` is in view. No-op until initialized. */
+    scrollToIndex(index, options) {
+        this.#virtualizer()?.scrollToIndex(index, options);
+    }
+    /** Scroll the container to an absolute pixel offset. No-op until initialized. */
+    scrollToOffset(offset) {
+        this.#virtualizer()?.scrollToOffset(offset);
+    }
+    /** Record the measured size of a rendered item element. No-op until initialized. */
+    measureElement(element) {
+        this.#virtualizer()?.measureElement(element);
+    }
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "22.0.2", ngImport: i0, type: ForVirtualViewport, deps: [], target: i0.ɵɵFactoryTarget.Component });
+    static ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "17.1.0", version: "22.0.2", type: ForVirtualViewport, isStandalone: true, selector: "for-virtual-viewport, [forVirtualViewport]", inputs: { virtualCount: { classPropertyName: "virtualCount", publicName: "virtualCount", isSignal: true, isRequired: true, transformFunction: null }, estimateSize: { classPropertyName: "estimateSize", publicName: "estimateSize", isSignal: true, isRequired: false, transformFunction: null }, orientation: { classPropertyName: "orientation", publicName: "orientation", isSignal: true, isRequired: false, transformFunction: null }, overscan: { classPropertyName: "overscan", publicName: "overscan", isSignal: true, isRequired: false, transformFunction: null }, getItemKey: { classPropertyName: "getItemKey", publicName: "getItemKey", isSignal: true, isRequired: false, transformFunction: null } }, outputs: { endReached: "endReached" }, host: { properties: { "style.overflow": "\"auto\"" } }, providers: [{ provide: FOR_VIRTUAL_VIEWPORT_CONTEXT, useExisting: ForVirtualViewport }], exportAs: ["forVirtualViewport"], ngImport: i0, template: `
+    <div style="position: relative" [style.width]="sizerWidth()" [style.height]="sizerHeight()">
+      <ng-content />
+    </div>
+  `, isInline: true, changeDetection: i0.ChangeDetectionStrategy.OnPush });
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.0.2", ngImport: i0, type: ForVirtualViewport, decorators: [{
+            type: Component,
+            args: [{
+                    selector: 'for-virtual-viewport, [forVirtualViewport]',
+                    exportAs: 'forVirtualViewport',
+                    changeDetection: ChangeDetectionStrategy.OnPush,
+                    providers: [{ provide: FOR_VIRTUAL_VIEWPORT_CONTEXT, useExisting: ForVirtualViewport }],
+                    host: {
+                        '[style.overflow]': '"auto"',
+                    },
+                    template: `
+    <div style="position: relative" [style.width]="sizerWidth()" [style.height]="sizerHeight()">
+      <ng-content />
+    </div>
+  `,
+                }]
+        }], propDecorators: { virtualCount: [{ type: i0.Input, args: [{ isSignal: true, alias: "virtualCount", required: true }] }], estimateSize: [{ type: i0.Input, args: [{ isSignal: true, alias: "estimateSize", required: false }] }], orientation: [{ type: i0.Input, args: [{ isSignal: true, alias: "orientation", required: false }] }], overscan: [{ type: i0.Input, args: [{ isSignal: true, alias: "overscan", required: false }] }], getItemKey: [{ type: i0.Input, args: [{ isSignal: true, alias: "getItemKey", required: false }] }], endReached: [{ type: i0.Output, args: ["endReached"] }] } });
+
+/**
+ * Structural directive that renders only the visible window of a list inside a
+ * `[forVirtualViewport]`. Pass the full data array; the directive iterates the
+ * viewport's `virtualItems()`, exposes each row plus its `virtualItem` to the
+ * template, positions it absolutely (so the consumer writes no transform), and
+ * binds `aria-setsize` (true total) / `aria-posinset` (`index + 1`) so screen
+ * readers announce the real list size.
+ *
+ * ```html
+ * <div forVirtualViewport [virtualCount]="rows().length" [estimateSize]="44">
+ *   <div *forVirtualFor="let row of rows(); let item = virtualItem">{{ row.label }}</div>
+ * </div>
+ * ```
+ */
+class ForVirtualFor {
+    #template = inject(TemplateRef);
+    #viewContainer = inject(ViewContainerRef);
+    #viewport = injectVirtualViewportContext('ForVirtualFor');
+    #views = new Map();
+    /** The full list of items to virtualize. */
+    forVirtualForOf = input.required({ ...(ngDevMode ? { debugName: "forVirtualForOf" } : /* istanbul ignore next */ {}), alias: 'forVirtualForOf' });
+    constructor() {
+        effect(() => this.#render());
+    }
+    /** Narrows the template context type for `let row of …` strict template checking. */
+    static ngTemplateContextGuard(_directive, _context) {
+        return true;
+    }
+    #render() {
+        const items = this.#viewport.virtualItems();
+        const data = this.forVirtualForOf();
+        const count = this.#viewport.count();
+        const horizontal = this.#viewport.orientation() === 'horizontal';
+        const seen = new Set();
+        items.forEach((item, position) => {
+            seen.add(item.key);
+            let view = this.#views.get(item.key);
+            if (!view) {
+                view = this.#viewContainer.createEmbeddedView(this.#template, { $implicit: data[item.index], virtualItem: item, index: item.index, count }, position);
+                this.#views.set(item.key, view);
+            }
+            else {
+                if (this.#viewContainer.indexOf(view) !== position) {
+                    this.#viewContainer.move(view, position);
+                }
+                view.context.$implicit = data[item.index];
+                view.context.virtualItem = item;
+                view.context.index = item.index;
+                view.context.count = count;
+                view.markForCheck();
+            }
+            this.#applyLayout(view, item, count, horizontal);
+        });
+        for (const [key, view] of this.#views) {
+            if (seen.has(key)) {
+                continue;
+            }
+            const index = this.#viewContainer.indexOf(view);
+            if (index >= 0) {
+                this.#viewContainer.remove(index);
+            }
+            this.#views.delete(key);
+        }
+    }
+    #applyLayout(view, item, count, horizontal) {
+        const node = view.rootNodes[0];
+        if (!(node instanceof HTMLElement)) {
+            return;
+        }
+        node.style.position = 'absolute';
+        node.style.top = '0';
+        node.style.left = '0';
+        if (horizontal) {
+            node.style.height = '100%';
+            node.style.transform = `translateX(${item.start}px)`;
+        }
+        else {
+            node.style.width = '100%';
+            node.style.transform = `translateY(${item.start}px)`;
+        }
+        node.setAttribute('data-index', String(item.index));
+        node.setAttribute('aria-setsize', String(count));
+        node.setAttribute('aria-posinset', String(item.index + 1));
+    }
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "22.0.2", ngImport: i0, type: ForVirtualFor, deps: [], target: i0.ɵɵFactoryTarget.Directive });
+    static ɵdir = i0.ɵɵngDeclareDirective({ minVersion: "17.1.0", version: "22.0.2", type: ForVirtualFor, isStandalone: true, selector: "[forVirtualFor][forVirtualForOf]", inputs: { forVirtualForOf: { classPropertyName: "forVirtualForOf", publicName: "forVirtualForOf", isSignal: true, isRequired: true, transformFunction: null } }, ngImport: i0 });
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.0.2", ngImport: i0, type: ForVirtualFor, decorators: [{
+            type: Directive,
+            args: [{
+                    selector: '[forVirtualFor][forVirtualForOf]',
+                }]
+        }], ctorParameters: () => [], propDecorators: { forVirtualForOf: [{ type: i0.Input, args: [{ isSignal: true, alias: "forVirtualForOf", required: true }] }] } });
+
+/**
+ * Cross-window keyboard-navigation bridge for a virtualized `[forTable]` grid,
+ * owned by `[forTableVirtualized]`. The grid keeps roving-tabindex and renders
+ * only a window of rows, so a navigation target can land on a row that is not
+ * currently mounted. This bridge resolves that:
+ *
+ * - **Move** — `navigateTo(row, col)` focuses the cell at the absolute
+ *   `(row, col)` when its row is already rendered; otherwise it stashes the
+ *   target and calls `scrollToRow(row)` to mount it.
+ * - **Resolve** — once the freshly-mounted row registers, the companion's bridge
+ *   effect calls `tryResolvePending`, which moves roving focus onto the target
+ *   cell (its `(focus)` handler promotes it to the active roving cell) and clears
+ *   the pending target.
+ *
+ * Mirrors the 1D `ListboxVirtualizedNavigator` precedent, adapted to the table's
+ * roving + focused-row-retention model. Internal — not re-exported from
+ * `table/index.ts` or `public-api.ts`.
+ */
+class TableVirtualizedNavigator {
+    #deps;
+    #pending = signal(null, /* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "#pending" }] : /* istanbul ignore next */ []));
+    constructor(deps) {
+        this.#deps = deps;
+    }
+    /**
+     * Move roving focus to the data cell at the absolute `(row, col)`. When the
+     * target row is already rendered, focuses immediately. Otherwise stashes the
+     * target and scrolls it into the window; the bridge effect resolves it once
+     * the row mounts.
+     */
+    navigateTo(row, col) {
+        if (this.#focusCell(row, col)) {
+            this.#pending.set(null);
+            return;
+        }
+        this.#pending.set({ row, col });
+        this.#deps.scrollToRow(row);
+    }
+    /** Scroll the virtualizer so the row at the absolute `index` is in the window. */
+    scrollToRow(index) {
+        this.#deps.scrollToRow(index);
+    }
+    /**
+     * Resolve a pending cross-window navigation: once the row carrying the pending
+     * absolute index mounts, focus its cell and clear the pending target. Returns
+     * `true` when a pending request was resolved, `false` otherwise. Called from
+     * the companion's bridge effect whenever the rendered rows change.
+     */
+    tryResolvePending() {
+        const pending = this.#pending();
+        if (pending === null) {
+            return false;
+        }
+        if (this.#focusCell(pending.row, pending.col)) {
+            this.#pending.set(null);
+            return true;
+        }
+        return false;
+    }
+    #focusCell(row, col) {
+        const handle = this.#deps.rows().find((r) => r.virtualIndex() === row);
+        if (!handle) {
+            return false;
+        }
+        const cells = handle.cells();
+        const cell = cells[col] ?? cells[cells.length - 1];
+        if (!cell) {
+            return false;
+        }
+        cell.host.focus();
+        return true;
+    }
+}
+
+function injectTableContext() {
+    const ctx = inject(FOR_TABLE_CONTEXT, { optional: true });
+    if (!ctx) {
+        throw new Error('[forty-cdk/table] ForTableVirtualized must be used inside a [forTable] element.');
+    }
+    return ctx;
+}
+/**
+ * Opt-in row-virtualization companion for `[forTable]` in `<div role>` grid mode. Place it on the
+ * same element as `[forTable]`; it builds the windowing core from the table's `[rowCount]` and
+ * exposes the visible window for the consumer to render with their own `@for` + position transform.
+ *
+ * Tree-shakeable: `ForTable` never imports the virtualization core — only consumers that import
+ * `ForTableVirtualized` bundle `@tanstack/virtual-core`.
+ *
+ * The focused row is kept mounted even when scrolled out of the window so the roving-focused
+ * `gridcell` is never unmounted. SSR-safe: off-browser the window is empty and
+ * `totalSize` is the estimate-based total.
+ *
+ * Also drives cross-window keyboard navigation: when an Arrow / Page / Ctrl+Home / Ctrl+End grid
+ * action resolves a row outside the rendered window, it scrolls that row into view and moves roving
+ * focus onto the target cell once it mounts (preserving the current column). `ForTable` stays
+ * unaware of virtualization — it delegates the row-crossing move through the table context.
+ */
+class ForTableVirtualized {
+    #ctx = injectTableContext();
+    #rootEl = inject(ElementRef).nativeElement;
+    /** Estimated row size in px along the scroll axis (the fixed-size fast path). Read for the size estimate. */
+    estimateRowSize = input(44, { ...(ngDevMode ? { debugName: "estimateRowSize" } : /* istanbul ignore next */ {}), transform: numberAttribute });
+    /**
+     * Scroll container. Defaults to the table root element (the scroll container in `<div>` grid
+     * mode). Bind it explicitly when the scroll container is an **ancestor** of the table — e.g. an
+     * app-shell viewport that scrolls projected content — since the table cannot inject an ancestor
+     * it does not own. A design-system wrapper can re-expose or rename this input through
+     * `hostDirectives` input aliasing (`inputs: ['scrollElement: scrollContainer']`) with no bridging
+     * effect required.
+     */
+    scrollElement = input(null, /* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "scrollElement" }] : /* istanbul ignore next */ []));
+    #scrollElement = computed(() => this.scrollElement() ?? this.#rootEl, /* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "#scrollElement" }] : /* istanbul ignore next */ []));
+    #virtualizer = injectVirtualizer({
+        count: computed(() => this.#ctx.rowCount() ?? 0),
+        estimateSize: () => this.estimateRowSize(),
+        scrollElement: this.#scrollElement,
+    });
+    #navigator = new TableVirtualizedNavigator({
+        rows: this.#ctx.rows,
+        scrollToRow: (index) => this.scrollToRow(index),
+    });
+    constructor() {
+        this.#ctx.registerVirtualNavigation(this.#navigator);
+        inject(DestroyRef).onDestroy(() => this.#ctx.registerVirtualNavigation(null));
+        effect(() => {
+            this.#ctx.rows();
+            this.#navigator.tryResolvePending();
+        });
+    }
+    /**
+     * The rows in the visible window plus overscan, augmented to always include the focused row and
+     * the row being reordered even when they are scrolled out of view (so the roving-focused cell
+     * stays mounted, and a pointer reorder drag never unmounts the lifted row). Render these with
+     * `@for (vrow of v.virtualRows(); track vrow.index)` and position each row absolutely with
+     * `transform: translateY(vrow.start + 'px')`. Bind each row's `[virtualIndex]="vrow.index"`.
+     */
+    virtualRows = computed(() => {
+        const items = this.#virtualizer.virtualItems();
+        const retain = new Set();
+        const focused = this.#ctx.focusedRowIndex();
+        if (focused !== null) {
+            retain.add(focused);
+        }
+        const reordering = this.#ctx.reorderingRowIndex();
+        if (reordering !== null) {
+            retain.add(reordering);
+        }
+        for (const it of items) {
+            retain.delete(it.index);
+        }
+        if (retain.size === 0) {
+            return items;
+        }
+        const size = this.estimateRowSize();
+        const retained = [...retain].map((index) => ({
+            index,
+            key: index,
+            start: index * size,
+            size,
+        }));
+        return [...items, ...retained].sort((a, b) => a.index - b.index);
+    }, /* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "virtualRows" }] : /* istanbul ignore next */ []));
+    /** Total scroll size of all rows in px. Bind to the body container's height to size the scroll range. */
+    totalSize = this.#virtualizer.totalSize;
+    /**
+     * The rendered window as the inclusive-exclusive `[firstIndex, lastIndex + 1)` index range,
+     * sourced from the underlying virtualizer (the true window) — not from {@link virtualRows},
+     * which is augmented with the focused / reordering rows. So a row retained out of the window
+     * never widens this range. Plugs straight into `injectInfiniteScroll({ range, count, onLoadMore })`.
+     */
+    range = this.#virtualizer.range;
+    /**
+     * Scroll the container so the row at `index` is in view. Cross-window keyboard
+     * navigation calls this internally; consumers may also call it to scroll
+     * programmatically.
+     */
+    scrollToRow(index, options) {
+        this.#virtualizer.scrollToIndex(index, options);
+    }
+    /** Record the measured size of a rendered row element (dynamic / measured row heights). */
+    measureRow(element) {
+        this.#virtualizer.measureElement(element);
+    }
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "22.0.2", ngImport: i0, type: ForTableVirtualized, deps: [], target: i0.ɵɵFactoryTarget.Directive });
+    static ɵdir = i0.ɵɵngDeclareDirective({ minVersion: "17.1.0", version: "22.0.2", type: ForTableVirtualized, isStandalone: true, selector: "[forTableVirtualized]", inputs: { estimateRowSize: { classPropertyName: "estimateRowSize", publicName: "estimateRowSize", isSignal: true, isRequired: false, transformFunction: null }, scrollElement: { classPropertyName: "scrollElement", publicName: "scrollElement", isSignal: true, isRequired: false, transformFunction: null } }, exportAs: ["forTableVirtualized"], ngImport: i0 });
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.0.2", ngImport: i0, type: ForTableVirtualized, decorators: [{
+            type: Directive,
+            args: [{
+                    selector: '[forTableVirtualized]',
+                    exportAs: 'forTableVirtualized',
+                }]
+        }], ctorParameters: () => [], propDecorators: { estimateRowSize: [{ type: i0.Input, args: [{ isSignal: true, alias: "estimateRowSize", required: false }] }], scrollElement: [{ type: i0.Input, args: [{ isSignal: true, alias: "scrollElement", required: false }] }] } });
+
+/*
+ * Public API surface of forty-cdk/virtualization.
+ *
+ * Virtualization (the windowing core, the Shape A viewport directives,
+ * infinite-scroll, and the `[forTableVirtualized]` companion) ships from this
+ * secondary entry point so that `@tanstack/virtual-core` is isolated to its own
+ * bundle chunk: only consumers importing from `forty-cdk/virtualization` pull
+ * it in, even when another lazy route in the same app virtualizes.
+ */
+
+/**
+ * Generated bundle index. Do not edit.
+ */
+
+export { FOR_VIRTUAL_VIEWPORT_CONTEXT, ForTableVirtualized, ForVirtualFor, ForVirtualViewport, injectInfiniteScroll, injectVirtualizer };
+//# sourceMappingURL=forty-cdk-virtualization.mjs.map