ngx-kit 6.3.0 → 7.0.1

package/types/ngx-kit-virtual-scroll.d.ts

@@ -0,0 +1,179 @@
+import * as _angular_core from '@angular/core';
+
+/**
+ * A "line" index range that is currently rendered.
+ * A "line" is one item for a plain list, or one row/column of N items
+ * for an auto-detected wrapping grid. `end` is exclusive.
+ */
+interface NgxVirtualScrollRange {
+    start: number;
+    end: number;
+}
+declare function rangesEqual(a: NgxVirtualScrollRange, b: NgxVirtualScrollRange): boolean;
+
+/**
+ * The scroll axis along which content is virtualized.
+ * This is never provided by the consumer — it is always derived from the
+ * real, rendered layout of the projected content (see `measureLayout`).
+ */
+type NgxVirtualScrollAxis = 'vertical' | 'horizontal';
+/**
+ * Result of measuring the real DOM layout of a small probe batch of items.
+ *
+ * - `crossCount === 1`  -> a plain list (the common case: vertical stack of
+ *   rows, or a horizontal row of columns).
+ * - `crossCount > 1`    -> a wrapping grid (e.g. cards laid out with
+ *   `display: flex; flex-wrap: wrap`): `crossCount` items share a line
+ *   before wrapping to the next one. The grid still scrolls along a single
+ *   `axis`, while the cross axis lays out natively (this is how "mixed"
+ *   horizontal + vertical layouts are supported without a 2D data model).
+ */
+interface NgxVirtualScrollMeasurement {
+    axis: NgxVirtualScrollAxis;
+    crossCount: number;
+    /** Size (px) of one line along `axis`, including margins/border/shadow. */
+    lineSize: number;
+}
+/** Escape hatch for consumers who need full control over layout detection. */
+type NgxVirtualScrollMeasureFn = (probeElements: readonly Element[]) => NgxVirtualScrollMeasurement | null;
+
+/**
+ * Headless, signal-based virtual scroll viewport.
+ *
+ * There is no `itemSize` and no `orientation` input by design: both are
+ * derived by measuring the real, rendered bounding boxes of a small probe
+ * batch (see `measure-layout.ts`), so margins/border/box-shadow on your own
+ * item styles are always accounted for correctly, and mixed layouts
+ * (vertical list of wrapping rows, i.e. a card grid) are supported out of
+ * the box.
+ *
+ * The component does not render your items itself — it exposes reactive
+ * signals (`visibleItems`, `range`, `baseIndex`, `axis`, ...) that you
+ * consume with a native `@for` block in your own template. This keeps the
+ * repeat/track logic entirely under your control (custom track expressions,
+ * `@empty` blocks, etc.) instead of hiding it behind a structural directive.
+ *
+ * @example
+ * ```html
+ * <ngx-virtual-scroll-viewport #vs="ngxVirtualScrollViewport" [items]="rows" style="height: 480px">
+ *   @for (row of vs.visibleItems(); track row.id; let i = $index) {
+ *     <div class="row">{{ vs.baseIndex() + i }} - {{ row.name }}</div>
+ *   }
+ * </ngx-virtual-scroll-viewport>
+ * ```
+ */
+declare class NgxVirtualScrollViewport<T = unknown> {
+    /** The full, unvirtualized data set. */
+    readonly items: _angular_core.InputSignal<readonly T[]>;
+    /** Minimum buffer (px) left before the render range is recomputed. */
+    readonly minBufferPx: _angular_core.InputSignal<number>;
+    /** Extra buffer (px) rendered outside the visible area on each side. */
+    readonly maxBufferPx: _angular_core.InputSignal<number>;
+    /** Advanced escape hatch: replace the built-in layout probe entirely. */
+    readonly measureFn: _angular_core.InputSignal<NgxVirtualScrollMeasureFn | undefined>;
+    /**
+     * Safe ceiling (px) for the scrollable axis's real DOM size. Only relevant
+     * for very large data sets — see `DEFAULT_MAX_AXIS_SIZE_PX`. You should
+     * not need to change this; it's exposed only for advanced cases (e.g. you
+     * know your app never targets older WebKit and want to raise the ceiling).
+     */
+    readonly maxAxisSizePx: _angular_core.InputSignal<number>;
+    /** Emits the index of the first fully-visible item as the user scrolls. */
+    readonly scrolledIndexChange: _angular_core.OutputEmitterRef<number>;
+    /** Emits whenever the rendered line range changes. */
+    readonly rangeChange: _angular_core.OutputEmitterRef<NgxVirtualScrollRange>;
+    private readonly scrollableRef;
+    private readonly wrapperRef;
+    private readonly destroyRef;
+    private readonly measurement;
+    private readonly scrollOffset;
+    private readonly viewportSize;
+    /** Whether the user is actively scrolling (used only to toggle `will-change`). */
+    readonly isScrolling: _angular_core.WritableSignal<boolean>;
+    /** Currently rendered line range. */
+    readonly range: _angular_core.WritableSignal<NgxVirtualScrollRange>;
+    readonly axis: _angular_core.Signal<NgxVirtualScrollAxis>;
+    readonly crossCount: _angular_core.Signal<number>;
+    readonly lineSize: _angular_core.Signal<number>;
+    readonly isMeasured: _angular_core.Signal<boolean>;
+    readonly lineCount: _angular_core.Signal<number>;
+    /** Real, uncompressed total size along the scroll axis — can exceed the browser's element-size cap. */
+    readonly naturalTotalSize: _angular_core.Signal<number>;
+    /**
+     * Size actually applied to the spacer element, clamped to `maxAxisSizePx`.
+     * Equal to `naturalTotalSize()` for any data set small enough to matter in
+     * practice — the compression only ever engages for extreme list sizes.
+     */
+    readonly totalSize: _angular_core.Signal<number>;
+    /**
+     * Ratio between the (possibly capped) DOM scroll space and the real,
+     * uncompressed content size. `1` unless `naturalTotalSize()` exceeds
+     * `maxAxisSizePx()`, in which case it's `< 1` and the DOM scrollbar
+     * represents the whole data set in a compressed coordinate space.
+     */
+    readonly scaleFactor: _angular_core.Signal<number>;
+    /** Absolute index of the first item in `visibleItems()`, for display purposes. */
+    readonly baseIndex: _angular_core.Signal<number>;
+    /** Slice of `items()` that should actually be rendered right now. */
+    readonly visibleItems: _angular_core.Signal<readonly T[]>;
+    private readonly renderedBlockSize;
+    private readonly contentOffset;
+    protected readonly wrapperTransform: _angular_core.Signal<string>;
+    protected readonly spacerWidth: _angular_core.Signal<number>;
+    protected readonly spacerHeight: _angular_core.Signal<number>;
+    private resizeObserver?;
+    private scrollingIdleTimer?;
+    private scrollRaf;
+    constructor();
+    /** Programmatically scroll to a given item index. */
+    scrollToIndex(index: number, behavior?: ScrollBehavior): void;
+    /**
+     * Programmatically scroll to a given pixel offset along the scroll axis.
+     * `offset` is expressed in real, uncompressed content px (i.e. the same
+     * space as `index * lineSize()`) — internally converted to the
+     * (possibly compressed) DOM scroll coordinate via `scaleFactor()`.
+     */
+    scrollToOffset(offset: number, behavior?: ScrollBehavior): void;
+    /** Force a re-measure, e.g. after the container was resized by external layout logic. */
+    checkViewportSize(): void;
+    private setupListeners;
+    private readonly onScroll;
+    private markScrolling;
+    private measureViewportSize;
+    /**
+     * Recomputes the rendered line range. Mirrors the CDK "fixed size"
+     * strategy: only recompute once the scroll offset gets within
+     * `minBufferPx` of the current range's edge, instead of on every pixel.
+     *
+     * All math here happens in *real* (uncompressed) content px, obtained by
+     * dividing the raw DOM scroll offset/viewport size by `scaleFactor()`.
+     * This is what makes the very last items reachable even when the total
+     * content size has been compressed into a browser-safe DOM range: as
+     * `domScrollOffset` sweeps its full (capped) range, `realOffset` still
+     * sweeps the entire, real `naturalTotalSize()`.
+     */
+    private recomputeRange;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<NgxVirtualScrollViewport<any>, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<NgxVirtualScrollViewport<any>, "ngx-virtual-scroll-viewport, ngx-virtual-scroll", ["ngxVirtualScrollViewport"], { "items": { "alias": "items"; "required": false; "isSignal": true; }; "minBufferPx": { "alias": "minBufferPx"; "required": false; "isSignal": true; }; "maxBufferPx": { "alias": "maxBufferPx"; "required": false; "isSignal": true; }; "measureFn": { "alias": "measureFn"; "required": false; "isSignal": true; }; "maxAxisSizePx": { "alias": "maxAxisSizePx"; "required": false; "isSignal": true; }; }, { "scrolledIndexChange": "scrolledIndexChange"; "rangeChange": "rangeChange"; }, never, ["*"], true, never>;
+}
+
+/**
+ * Pure, framework-agnostic layout probe.
+ *
+ * Reads the real bounding boxes of a small batch of already-rendered
+ * elements and infers, purely from actual layout:
+ *  - the scroll axis (vertical vs horizontal)
+ *  - how many items share a single line (1 for a plain list, N for a
+ *    wrapping grid)
+ *  - the real size of one line, INCLUDING margins/border/box-shadow,
+ *    because it is derived from the delta between two real sibling
+ *    positions in normal document flow rather than from a hardcoded
+ *    itemSize input.
+ *
+ * No orientation/itemSize is ever supplied by the consumer — this is the
+ * single source of truth for both.
+ */
+declare function measureLayout(probeElements: readonly Element[]): NgxVirtualScrollMeasurement | null;
+
+export { NgxVirtualScrollViewport, measureLayout, rangesEqual };
+export type { NgxVirtualScrollAxis, NgxVirtualScrollMeasureFn, NgxVirtualScrollMeasurement, NgxVirtualScrollRange };

package/types/ngx-kit-webflow.d.ts

@@ -0,0 +1,286 @@
+import * as i0 from '@angular/core';
+import { OnDestroy, EventEmitter, OnInit } from '@angular/core';
+import * as ngx_kit_webflow from 'ngx-kit/webflow';
+
+/**
+ * ngx-flowbuilder — مدل‌های پایه
+ */
+type FlowAxis = 'row' | 'column';
+/** موقعیت درج نسبت به آیتمی که ماوس روی آن است */
+type DropZone = 'before' | 'after' | 'above' | 'below' | 'inside';
+interface DropResult {
+    targetId: string;
+    zone: DropZone;
+}
+interface Rect {
+    top: number;
+    left: number;
+    width: number;
+    height: number;
+    right: number;
+    bottom: number;
+}
+interface IndicatorState {
+    visible: boolean;
+    /** خط باریک: 'h' یعنی خط افقی (جدا کردن ردیف‌ها)، 'v' یعنی خط عمودی (جدا کردن کنار هم) */
+    orientation: 'h' | 'v' | null;
+    x: number;
+    y: number;
+    length: number;
+    /** حالت nest: به‌جای خط، یک کادر دور کل container هایلایت می‌شود */
+    highlightRect: Rect | null;
+}
+interface DragStartEvent {
+    id: string;
+    pointerId: number;
+    originRect: Rect;
+}
+interface DragMoveEvent {
+    id: string;
+    clientX: number;
+    clientY: number;
+    deltaX: number;
+    deltaY: number;
+}
+interface DragEndEvent {
+    id: string;
+    drop: DropResult | null;
+}
+type ResizeHandlePosition = 'n' | 's' | 'e' | 'w' | 'ne' | 'nw' | 'se' | 'sw';
+interface ResizeMoveEvent {
+    id: string;
+    handle: ResizeHandlePosition;
+    width: number;
+    height: number;
+    /** فقط برای هندل‌های شمال/غرب که مبدأ عنصر هم جابجا می‌شود */
+    offsetX: number;
+    offsetY: number;
+}
+
+/**
+ * ngxDraggable
+ * -------------------------------------------------------------
+ * تنها دایرکتیو مسئول درگ. کل منطق حرکت با CSS transform (translate3d)
+ * روی خودِ عنصر درگ‌شونده انجام می‌شود — نه با جابجایی واقعی در DOM لیست.
+ * جابجاییِ واقعیِ داده فقط یک‌بار، در لحظهٔ drop، از طریق خروجی
+ * (flowDrop) اتفاق می‌افتد و آن‌وقت مصرف‌کننده (کامپوننت کانتینر) با
+ * *ngFor + trackBy مدل را آپدیت می‌کند.
+ *
+ * دلیل مقیاس‌پذیری با هزاران آیتم:
+ *  - در حین pointermove هیچ آیتم دیگری لمس/محاسبه نمی‌شود.
+ *  - listener مربوط به تشخیص هدف روی کانتینر (event delegation) است،
+ *    نه روی تک‌تک آیتم‌ها (این بخش در ContainerDropzoneDirective است).
+ *  - آپدیت transform با requestAnimationFrame throttle می‌شود تا از
+ *    چندبار layout/paint در هر فریم جلوگیری شود.
+ */
+declare class DraggableDirective implements OnDestroy {
+    private readonly el;
+    private readonly renderer;
+    private readonly zone;
+    private readonly dragDrop;
+    private readonly dropPos;
+    /** شناسهٔ یکتای بلاک — برای شناسایی هنگام درگ لازم است */
+    ngxDraggableId: string;
+    /** غیرفعال کردن موقت درگ (مثلاً حین ادیت متن داخل بلاک) */
+    ngxDraggableDisabled: boolean;
+    /** هندلِ اختصاصی؛ اگر ندهی، کل عنصر هندل می‌شود */
+    ngxDragHandleSelector: string | null;
+    flowDragStart: EventEmitter<DragStartEvent>;
+    flowDragEnd: EventEmitter<DragEndEvent>;
+    readonly dragging: i0.WritableSignal<boolean>;
+    get draggingClass(): boolean;
+    get touchAction(): string;
+    private startX;
+    private startY;
+    private originLeft;
+    private originTop;
+    private rafId;
+    private pendingTransform;
+    private cleanupFns;
+    constructor();
+    private onPointerDown;
+    private onPointerMove;
+    private onPointerUp;
+    ngOnDestroy(): void;
+    static ɵfac: i0.ɵɵFactoryDeclaration<DraggableDirective, never>;
+    static ɵdir: i0.ɵɵDirectiveDeclaration<DraggableDirective, "[ngxDraggable]", ["ngxDraggable"], { "ngxDraggableId": { "alias": "ngxDraggableId"; "required": true; }; "ngxDraggableDisabled": { "alias": "ngxDraggableDisabled"; "required": false; }; "ngxDragHandleSelector": { "alias": "ngxDragHandleSelector"; "required": false; }; }, { "flowDragStart": "flowDragStart"; "flowDragEnd": "flowDragEnd"; }, never, never, true, never>;
+}
+
+/**
+ * ngxResizable
+ * -------------------------------------------------------------
+ * تنها دایرکتیو مسئول ریسایز. مستقل از DraggableDirective.
+ * روی عنصر اصلی قرار می‌گیرد و به همراه ۸ هندل (که خودت در تمپلیت با
+ * class مشخص می‌کنی، مثلاً <span class="rz-handle" data-handle="se">)
+ * کار می‌کند.
+ *
+ * فقط CSS width/height/left/top آپدیت می‌شود (از طریق خروجی flowResize)
+ * و مصرف‌کننده تصمیم می‌گیرد این مقادیر را چطور به مدل/استایل بایند کند —
+ * دایرکتیو خودش مستقیماً مدل داده را تغییر نمی‌دهد.
+ */
+declare class ResizableDirective implements OnDestroy {
+    private readonly el;
+    private readonly renderer;
+    private readonly zone;
+    ngxResizableId: string;
+    ngxResizableMinWidth: number;
+    ngxResizableMinHeight: number;
+    ngxResizableDisabled: boolean;
+    /** انتخاب‌گر هندل‌ها؛ باید attribute یا data-handle داشته باشند */
+    ngxResizeHandleSelector: string;
+    flowResizeStart: EventEmitter<{
+        id: string;
+        handle: ResizeHandlePosition;
+    }>;
+    flowResizeMove: EventEmitter<ResizeMoveEvent>;
+    flowResizeEnd: EventEmitter<ResizeMoveEvent>;
+    readonly resizing: i0.WritableSignal<boolean>;
+    private startX;
+    private startY;
+    private startW;
+    private startH;
+    private handle;
+    private rafId;
+    private pending;
+    private unlisten;
+    constructor();
+    private onDown;
+    private onMove;
+    private onUp;
+    ngOnDestroy(): void;
+    static ɵfac: i0.ɵɵFactoryDeclaration<ResizableDirective, never>;
+    static ɵdir: i0.ɵɵDirectiveDeclaration<ResizableDirective, "[ngxResizable]", ["ngxResizable"], { "ngxResizableId": { "alias": "ngxResizableId"; "required": true; }; "ngxResizableMinWidth": { "alias": "ngxResizableMinWidth"; "required": false; }; "ngxResizableMinHeight": { "alias": "ngxResizableMinHeight"; "required": false; }; "ngxResizableDisabled": { "alias": "ngxResizableDisabled"; "required": false; }; "ngxResizeHandleSelector": { "alias": "ngxResizeHandleSelector"; "required": false; }; }, { "flowResizeStart": "flowResizeStart"; "flowResizeMove": "flowResizeMove"; "flowResizeEnd": "flowResizeEnd"; }, never, never, true, never>;
+}
+
+/**
+ * ngxDropzoneContainer
+ * -------------------------------------------------------------
+ * روی هر کانتینری که فرزندانش قابل‌درگ‌اند‌دراپ هستند قرار می‌گیرد
+ * (چه ریشهٔ صفحه، چه یک بلاک تو‌در‌تو).
+ *
+ * فقط یک pointermove-listener سراسری (روی document، حین یک درگ فعال)
+ * دارد و با event.target.closest('[data-flow-id]') هدف را پیدا می‌کند.
+ * این یعنی صرف‌نظر از اینکه چند هزار فرزند وجود دارد، هزینهٔ هر حرکتِ
+ * ماوس ثابت (O(1)) است — نه O(n).
+ *
+ * هر فرزند مستقیمِ قابل‌درگ باید attribute زیر را داشته باشد
+ * (به‌صورت خودکار توسط DraggableDirective/تمپلیت ست می‌شود):
+ *   [attr.data-flow-id]="item.id"
+ *   [attr.data-flow-container]="isContainer ? '' : null"
+ */
+declare class DropzoneContainerDirective implements OnInit, OnDestroy {
+    private readonly el;
+    private readonly zone;
+    private readonly renderer;
+    private readonly dragDrop;
+    private readonly dropPos;
+    /** جهت چیدمان فرزندان مستقیم این کانتینر */
+    ngxDropzoneAxis: FlowAxis;
+    /** آیا خودِ این کانتینر می‌تواند میزبان nest شدن باشد */
+    ngxDropzoneNestable: boolean;
+    private unlistenMove;
+    private unlistenLeave;
+    ngOnInit(): void;
+    private handleMove;
+    ngOnDestroy(): void;
+    static ɵfac: i0.ɵɵFactoryDeclaration<DropzoneContainerDirective, never>;
+    static ɵdir: i0.ɵɵDirectiveDeclaration<DropzoneContainerDirective, "[ngxDropzoneContainer]", ["ngxDropzoneContainer"], { "ngxDropzoneAxis": { "alias": "ngxDropzoneAxis"; "required": false; }; "ngxDropzoneNestable": { "alias": "ngxDropzoneNestable"; "required": false; }; }, {}, never, never, true, never>;
+}
+
+/**
+ * FlowDropIndicatorComponent
+ * -------------------------------------------------------------
+ * یک‌بار در ریشهٔ صفحه‌ساز قرار می‌گیرد (position: fixed).
+ * تنها المنتی است که در طول درگ مدام آپدیت می‌شود؛ بقیهٔ آیتم‌های
+ * لیست دست‌نخورده باقی می‌مانند. کاملاً با computed از signal سرویس
+ * تغذیه می‌شود، بدون هیچ منطق اضافه در کامپوننت.
+ */
+declare class FlowDropIndicatorComponent {
+    private readonly dropPos;
+    readonly indicator: i0.Signal<ngx_kit_webflow.IndicatorState>;
+    static ɵfac: i0.ɵɵFactoryDeclaration<FlowDropIndicatorComponent, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<FlowDropIndicatorComponent, "flow-drop-indicator", never, {}, {}, never, never, true, never>;
+}
+
+/**
+ * DragDropService
+ * -------------------------------------------------------------
+ * وضعیت سراسریِ «چه چیزی الان در حال درگ است» را نگه می‌دارد.
+ * فقط signal، بدون هیچ Subject/Observable اضافه — سبک و قابل‌پیش‌بینی.
+ */
+declare class DragDropService {
+    /** id آیتمی که هم‌اکنون درگ می‌شود، یا null */
+    readonly activeId: i0.WritableSignal<string | null>;
+    /** آخرین نتیجهٔ محاسبه‌شدهٔ drop توسط DropPositionService */
+    readonly pendingDrop: i0.WritableSignal<DropResult | null>;
+    startDrag(id: string): void;
+    setPendingDrop(result: DropResult | null): void;
+    endDrag(): DropResult | null;
+    get isDragging(): boolean;
+    static ɵfac: i0.ɵɵFactoryDeclaration<DragDropService, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<DragDropService>;
+}
+
+declare class DropPositionService {
+    private readonly _indicator;
+    /** استیت فقط‌خواندنیِ اندیکاتور برای بایند در تمپلیت */
+    readonly indicator: i0.Signal<IndicatorState>;
+    private lastTargetId;
+    private lastZone;
+    /**
+     * فراخوانی در هر pointermove حین درگ.
+     * targetEl باید همان element.closest('[data-flow-id]') باشد که در
+     * دایرکتیو کانتینر با event delegation پیدا شده — نه یک لوپ روی آیتم‌ها.
+     */
+    evaluate(params: {
+        targetEl: HTMLElement;
+        targetId: string;
+        isContainer: boolean;
+        parentAxis: 'row' | 'column';
+        clientX: number;
+        clientY: number;
+    }): {
+        targetId: string;
+        zone: DropZone;
+    };
+    /** رسم خط/کادر راهنما - فقط نوشتن به یک signal، بدون لمس بقیهٔ DOM */
+    private paintIndicator;
+    clear(): void;
+    get current(): {
+        targetId: string;
+        zone: DropZone;
+    } | null;
+    static ɵfac: i0.ɵɵFactoryDeclaration<DropPositionService, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<DropPositionService>;
+}
+
+interface FlowNode {
+    id: string;
+    type: string;
+    axis: 'row' | 'column';
+    isContainer: boolean;
+    props?: Record<string, unknown>;
+    children: FlowNode[];
+}
+/**
+ * FlowTreeService
+ * -------------------------------------------------------------
+ * مدل درختیِ صفحه (دقیقاً همان چیزی که Webflow "Element Panel" اسمش
+ * می‌گذارد). تغییر مدل فقط در لحظهٔ drop رخ می‌دهد (نه در هر
+ * pointermove) — به همین دلیل حتی با هزاران بلاک، re-render فقط
+ * یک‌بار در پایان درگ اتفاق می‌افتد.
+ *
+ * پیاده‌سازی immutable-ish: فقط مسیر تغییر‌یافته کپی می‌شود، نه کل
+ * درخت (structural sharing) تا با درخت‌های بزرگ هم CPU/GC اذیت نشود.
+ */
+declare class FlowTreeService {
+    private readonly _root;
+    readonly root: i0.Signal<FlowNode>;
+    setRoot(node: FlowNode): void;
+    applyDrop(draggedId: string, drop: DropResult): void;
+    static ɵfac: i0.ɵɵFactoryDeclaration<FlowTreeService, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<FlowTreeService>;
+}
+
+export { DragDropService, DraggableDirective, DropPositionService, DropzoneContainerDirective, FlowDropIndicatorComponent, FlowTreeService, ResizableDirective };
+export type { DragEndEvent, DragMoveEvent, DragStartEvent, DropResult, DropZone, FlowAxis, FlowNode, IndicatorState, Rect, ResizeHandlePosition, ResizeMoveEvent };

package/virtual-scroll/README.md

@@ -0,0 +1,199 @@
+# @ngx-kit/virtual-scroll
+
+A zoneless, signal-based virtual scroll viewport for Angular. No `@angular/material`
+or `@angular/cdk` dependency, no `NgZone`, no `ngOnChanges`, no `@Input() itemSize`,
+no `@Input() orientation` — everything that can be derived from the real DOM is
+derived from the real DOM.
+
+## Why this rewrite
+
+| Old design                                                                    | This design                                                                                                                                                  |
+| ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `NgZone` injected, `zone.run` everywhere                                      | No `NgZone` at all — works natively under `provideZonelessChangeDetection()`                                                                                 |
+| `ngOnChanges` + `SimpleChanges`                                               | `input()` signals + `computed()` / `effect()`                                                                                                                |
+| `@Input() itemSize` (broke as soon as your item had margin/border/box-shadow) | Real item size is **measured** from `getBoundingClientRect()` deltas between actually rendered siblings, so margins/borders/shadows are always accounted for |
+| `@Input() orientation`                                                        | Axis is **auto-detected** from the real layout of your own item markup                                                                                       |
+| Custom `*ngxVirtualFor` structural directive                                  | Plain native `@for` over a `visibleItems()` signal — you keep full control of `track`, `@empty`, etc.                                                        |
+
+## Install & import
+
+```ts
+import { NgxVirtualScrollViewport } from '@ngx-kit/virtual-scroll';
+
+@Component({
+  standalone: true,
+  imports: [NgxVirtualScrollViewport],
+  ...
+})
+```
+
+## Basic usage — vertical list (auto-detected)
+
+```html
+<ngx-virtual-scroll-viewport #vs="ngxVirtualScrollViewport" [items]="items" style="height: 400px">
+  @for (item of vs.visibleItems(); track $index; let i = $index) {
+  <div class="row">{{ vs.baseIndex() + i | number }} - {{ item.name }}</div>
+  }
+</ngx-virtual-scroll-viewport>
+```
+
+This is exactly the case that used to break: `.row` can have `margin`, `border`,
+`box-shadow`, `padding` — anything. The viewport measures the real distance between
+two consecutively rendered rows and uses that, not a number you have to keep in sync
+with your CSS.
+
+```css
+.row {
+  height: 48px;
+  border: 1px rgb(166 166 166 / 51%) solid;
+  box-shadow: 0px 0px 20px rgb(122 122 122 / 20%);
+  border-radius: 5px;
+  display: flex;
+  align-items: center;
+  margin: 10px;
+  padding: 15px;
+}
+```
+
+## Horizontal lists & wrapping grids (auto-detected)
+
+The axis is inferred purely from how your own items lay out:
+
+- Items stack top-to-bottom (default block flow) → **vertical** list.
+- Items lay out left-to-right in a single line (e.g. `display: inline-flex` on the
+  item, or a `flex-wrap: nowrap` row) → **horizontal** list.
+- Items lay out left-to-right and _wrap_ to a new line (e.g. cards with
+  `display: flex; flex-wrap: wrap`) → treated as a **vertical** list of "lines",
+  where each line holds N items. This is how mixed horizontal + vertical layouts
+  (a card grid that scrolls vertically) are supported without a separate 2D data
+  model — the cross axis (row width) lays out and scrolls natively, only the line
+  axis is virtualized.
+
+You don't configure any of this — you only make sure your `.item` CSS actually lays
+out the way you want, and the viewport detects it.
+
+## Mixed content (e.g. wide, virtualized table)
+
+Both axes of the scroll container are always natively scrollable
+(`overflow: auto` on both). Only the detected axis is virtualized; the cross axis
+(for example, a table wider than its container) scrolls with the browser's native
+scrollbar, so wide tables with virtualized rows work out of the box:
+
+```html
+<div class="table-shell">
+  <table><thead>...</thead></table>
+  <!-- kept outside, sticky/fixed header -->
+
+  <ngx-virtual-scroll-viewport #vs="ngxVirtualScrollViewport" [items]="rows" style="height: 480px">
+    <table>
+      <tbody>
+        @for (row of vs.visibleItems(); track row.id; let i = $index) {
+        <tr>
+          <td>{{ vs.baseIndex() + i }}</td>
+          ...
+        </tr>
+        }
+      </tbody>
+    </table>
+  </ngx-virtual-scroll-viewport>
+</div>
+```
+
+## Very large data sets (1M+ rows)
+
+Browsers clamp any element's real CSS `height`/`width` to a hard maximum
+(~33.5M px in Chromium, far less in older WebKit/Gecko). Once a naive
+"spacer" element crosses that ceiling, the browser silently clamps it,
+`scrollHeight` stops growing, and everything past that point becomes
+unreachable — the classic "scroll gets stuck around ~500k rows" symptom.
+
+This viewport handles it automatically: the spacer's real DOM size is capped
+at `maxAxisSizePx` (6,000,000px by default — safely under every known
+browser limit), and the DOM scrollbar operates in a _compressed_ coordinate
+space via `scaleFactor()`. All range/index math is done against the real,
+uncompressed content size (`naturalTotalSize()`), so scrolling the
+(compressed) native scrollbar all the way to the end still lands you exactly
+on the last item, no matter how many millions of rows you have. The only
+user-visible trade-off for truly massive lists is that the scrollbar thumb's
+motion is no longer perfectly 1:1 with "one row per pixel" — an unavoidable
+consequence of representing an arbitrarily large data set inside a bounded
+native scrollbar, and the same trade-off every large-scale virtual scroll
+implementation makes.
+
+You don't need to configure anything for this — it only engages once
+`naturalTotalSize()` actually exceeds `maxAxisSizePx`, and is a no-op
+(`scaleFactor() === 1`) for the vast majority of real-world lists.
+
+## API
+
+### Inputs
+
+| Input           | Type                        | Default     | Notes                                                                        |
+| --------------- | --------------------------- | ----------- | ---------------------------------------------------------------------------- |
+| `items`         | `readonly T[]`              | `[]`        | Full data set                                                                |
+| `minBufferPx`   | `number`                    | `150`       | Buffer left before recomputing the range                                     |
+| `maxBufferPx`   | `number`                    | `300`       | Extra px rendered outside the viewport                                       |
+| `measureFn`     | `NgxVirtualScrollMeasureFn` | `undefined` | Advanced override for the built-in layout probe                              |
+| `maxAxisSizePx` | `number`                    | `6_000_000` | Safe ceiling for the real DOM scroll size — see "Very large data sets" below |
+
+### Outputs
+
+| Output                | Type                                      |
+| --------------------- | ----------------------------------------- |
+| `scrolledIndexChange` | `OutputEmitterRef<number>`                |
+| `rangeChange`         | `OutputEmitterRef<NgxVirtualScrollRange>` |
+
+### Public signals (via `#vs="ngxVirtualScrollViewport"`)
+
+| Signal               | Type                         | Meaning                                                                        |
+| -------------------- | ---------------------------- | ------------------------------------------------------------------------------ |
+| `visibleItems()`     | `readonly T[]`               | Slice of `items()` to render right now                                         |
+| `range()`            | `{ start, end }`             | Currently rendered line range                                                  |
+| `baseIndex()`        | `number`                     | Absolute index of `visibleItems()[0]`                                          |
+| `axis()`             | `'vertical' \| 'horizontal'` | Auto-detected scroll axis                                                      |
+| `crossCount()`       | `number`                     | Items per line (1 for a plain list)                                            |
+| `lineSize()`         | `number`                     | Measured px size of one line                                                   |
+| `isMeasured()`       | `boolean`                    | Whether the initial layout probe has completed                                 |
+| `isScrolling()`      | `boolean`                    | True while an active scroll gesture is in progress                             |
+| `naturalTotalSize()` | `number`                     | Real, uncompressed total size along the scroll axis                            |
+| `totalSize()`        | `number`                     | Size actually applied to the spacer (capped at `maxAxisSizePx`)                |
+| `scaleFactor()`      | `number`                     | `totalSize() / naturalTotalSize()`; `1` unless the data set is extremely large |
+
+### Methods
+
+| Method                                | Description                                                                               |
+| ------------------------------------- | ----------------------------------------------------------------------------------------- |
+| `scrollToIndex(index, behavior?)`     | Scroll to a given item index                                                              |
+| `scrollToOffset(offsetPx, behavior?)` | Scroll to a given pixel offset                                                            |
+| `checkViewportSize()`                 | Force a re-measure (rarely needed — a `ResizeObserver` already handles container resizes) |
+
+## Performance notes
+
+- Fully `ChangeDetectionStrategy.OnPush` and zoneless-compatible — no `NgZone`
+  import anywhere; signal writes are what schedule change detection.
+- Scroll handling is `requestAnimationFrame`-throttled and the listener is
+  registered with `{ passive: true }`.
+- The range is only recomputed once the scroll offset gets within
+  `minBufferPx` of the current range's edge — not on every scroll event.
+- Layout is only ever **read** (`getBoundingClientRect`) inside an
+  `afterRenderEffect({ read: ... })` block, so DOM measurement never
+  interleaves with — and never forces — a layout/style write.
+- `will-change: transform` is only applied to the content wrapper while
+  `isScrolling()` is true, and removed ~150ms after the last scroll event, to
+  avoid holding a compositor layer alive for the component's entire lifetime.
+- `contain: strict` / `contain: layout style` isolate the viewport's layout
+  and paint from the rest of the page.
+
+## How auto-measurement works
+
+On first render, up to 24 items are rendered "in the open" (un-transformed) purely
+to be measured — see `measure-layout.ts`. Their real `getBoundingClientRect()`
+deltas are used to infer axis, items-per-line, and line size in one pass, all pure
+functions with no Angular dependency (so they are trivially unit-testable). Once
+measured, the real virtualized range replaces the probe range and rendering
+proceeds normally. If your rows can change size at runtime (e.g. responsive
+breakpoints), a `ResizeObserver` on the scroll container triggers `checkViewportSize()`
+automatically to re-fit the viewport dimension; if the _line size itself_ changes at
+runtime you can force a full re-measure by re-creating the component (e.g. keyed with
+`@if`/`*ngIf` + a changing key), which is the same limitation `cdk-virtual-scroll-viewport`
+has with its own `FixedSizeVirtualScrollStrategy`.