ngx-kit 6.2.0 → 7.0.0

package/types/ngx-kit-grid-layout.d.ts

@@ -0,0 +1,310 @@
+import * as _angular_core from '@angular/core';
+import { AfterViewInit, OnDestroy, OnInit } from '@angular/core';
+import * as i1 from 'ngx-kit/drag-resize';
+
+type GridFlow = 'free' | 'horizontal' | 'vertical';
+type CompactMode = 'none' | 'vertical' | 'horizontal' | 'both';
+interface IGridBackgroundCfg {
+    show?: 'never' | 'always' | 'whenDragging';
+    borderColor?: string;
+    gapColor?: string;
+    rowColor?: string;
+    columnColor?: string;
+    borderWidth?: number;
+}
+interface IGridLayoutOptions {
+    cols: number;
+    rowHeight: number | 'fit';
+    gap?: number;
+    padding?: number;
+    flow?: GridFlow;
+    compact?: CompactMode;
+    allowOverlap?: boolean;
+    pushItems?: boolean;
+    /** When two items would swap places, prefer swapping over cascading a push. */
+    swap?: boolean;
+    dragThreshold?: number;
+    animate?: boolean;
+    /**
+     * `true` / `false` force a direction; `'auto'` (default) reads the host element's
+     * computed `direction`, so the grid follows the surrounding page automatically.
+     */
+    rtl?: boolean | 'auto';
+    /** Caps the number of rows the grid can grow to. `undefined` = unbounded. */
+    maxRows?: number;
+    gridBackgroundConfig?: IGridBackgroundCfg;
+}
+declare class GridLayoutOptions implements IGridLayoutOptions {
+    cols: number;
+    rowHeight: number | 'fit';
+    gap: number;
+    padding: number;
+    flow: GridFlow;
+    compact: CompactMode;
+    allowOverlap: boolean;
+    pushItems: boolean;
+    swap: boolean;
+    dragThreshold: number;
+    animate: boolean;
+    rtl: boolean | "auto";
+    maxRows?: number;
+    gridBackgroundConfig: IGridBackgroundCfg;
+}
+
+declare class GridItemConfig {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+    minW?: number;
+    minH?: number;
+    maxW?: number;
+    maxH?: number;
+    /** Item can't be dragged or resized, and never moves during compaction/push. */
+    static?: boolean;
+    /** Overrides the layout-level draggable/resizable flags for this item only. */
+    isDraggable?: boolean;
+    isResizable?: boolean;
+    constructor(x?: number, y?: number, w?: number, h?: number, s?: boolean);
+}
+declare const normalizeGridItem: (value?: Partial<GridItemConfig>) => GridItemConfig;
+/**
+ * Value equality for two (already-normalized) configs.
+ *
+ * This is what breaks the register -> settle -> new-object -> re-register
+ * feedback loop: signals compare by *reference*, so anything that recomputes
+ * a fresh config object on every change-detection pass (a `computed()` layout,
+ * an inline object literal in a template, etc.) will always look "changed" to
+ * an `effect()` even when nothing meaningful did. Callers must compare by
+ * value before writing back to a signal, otherwise the write itself produces
+ * a new reference that trips the same effect again — forever.
+ */
+declare function gridItemConfigsEqual(a: GridItemConfig, b: GridItemConfig): boolean;
+
+interface LayoutOutput extends GridItemConfig {
+    id?: string;
+}
+
+interface LayoutNode {
+    id: string;
+    config: GridItemConfig;
+}
+/** Axis-aligned bounding-box overlap test in grid-cell space. */
+declare function collides(a: GridItemConfig, b: GridItemConfig): boolean;
+/** First item (other than `self`) whose cells overlap `config`, or null. */
+declare function getFirstCollision<T extends LayoutNode>(items: readonly T[], selfId: string, config: GridItemConfig): T | null;
+/** All items whose cells overlap `config`, excluding `selfId`. */
+declare function getAllCollisions<T extends LayoutNode>(items: readonly T[], selfId: string, config: GridItemConfig): T[];
+
+interface MoveOptions {
+    cols: number;
+    compact: CompactMode;
+    allowOverlap: boolean;
+    maxRows?: number;
+}
+/**
+ * Moves `id` to grid cell (x, y) and, unless overlap is explicitly allowed,
+ * cascades any resulting collisions by pushing the colliding items out of the
+ * way (downward for vertical-flow grids, rightward for horizontal-flow ones).
+ * Static items are treated as fixed obstacles: they block, but never move.
+ * Pure function — returns a new array, never mutates its input.
+ */
+declare function moveItem<T extends LayoutNode>(items: readonly T[], id: string, x: number, y: number, opts: MoveOptions, depth?: number): T[];
+/**
+ * When the actively-moved item directly overlaps exactly one same-size item,
+ * exchanging their positions reads much better than a cascading push. The
+ * caller (service) decides when to offer this vs. falling back to `moveItem`.
+ */
+declare function trySwap<T extends LayoutNode>(items: readonly T[], id: string, previous: GridItemConfig, next: GridItemConfig): T[] | null;
+/**
+ * Removes gaps by pulling every non-static item as far toward the start of the
+ * grid as it can go without overlapping another item, in reading order.
+ */
+declare function compact<T extends LayoutNode>(items: readonly T[], mode: CompactMode): T[];
+/** Highest occupied row (0-based, exclusive) across all items — drives the grid's auto-height. */
+declare function maxOccupiedRow(items: readonly LayoutNode[]): number;
+
+/**
+ * All pixel <-> grid-cell math lives here, in one RTL-aware place.
+ *
+ * Grid coordinates are always *logical* (reading-order): x = 0 is the first
+ * column in the direction text flows — the left edge in LTR, the right edge
+ * in RTL. Every physical (CSS `left`/pixel) calculation goes through here so
+ * the rest of the codebase never has to think about direction again.
+ */
+interface GridMetrics {
+    /** Inner content width available for columns (container width minus padding). */
+    contentWidth: number;
+    colWidth: number;
+    rowHeight: number;
+    gap: number;
+    padding: number;
+}
+declare function computeMetrics(containerWidth: number, options: IGridLayoutOptions): GridMetrics;
+/** Physical CSS `left` (px, relative to the grid surface's content box) for a logical column. */
+declare function colToLeft(colIndex: number, spanCols: number, m: GridMetrics, rtl: boolean): number;
+declare function rowToTop(rowIndex: number, m: GridMetrics): number;
+declare function spanToWidthPx(spanCols: number, m: GridMetrics): number;
+declare function spanToHeightPx(spanRows: number, m: GridMetrics): number;
+/** Physical left px (as above) -> nearest logical column index. Inverse of `colToLeft`. */
+declare function leftToCol(leftPx: number, spanCols: number, m: GridMetrics, rtl: boolean): number;
+declare function topToRow(topPx: number, m: GridMetrics): number;
+/** Places an item's pixel box (left/top/width/height) inside the grid surface, RTL-aware. */
+declare function placeItem(config: GridItemConfig, m: GridMetrics, rtl: boolean): {
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+};
+
+interface GridItemState {
+    id: string;
+    config: GridItemConfig;
+    element?: HTMLElement;
+    dragging?: boolean;
+    resizing?: boolean;
+}
+declare class GridLayoutService {
+    readonly options: _angular_core.WritableSignal<GridLayoutOptions>;
+    readonly items: _angular_core.WritableSignal<readonly GridItemState[]>;
+    readonly editMode: _angular_core.WritableSignal<boolean>;
+    readonly activeId: _angular_core.WritableSignal<string | null>;
+    readonly isInteracting: _angular_core.Signal<boolean>;
+    readonly height: _angular_core.Signal<number>;
+    readonly layout: _angular_core.Signal<LayoutOutput[]>;
+    readonly columns: _angular_core.Signal<number>;
+    /** Resolves `rtl: 'auto'` against the attached element's *actual* computed direction. */
+    readonly rtl: _angular_core.Signal<boolean>;
+    private rtlTick;
+    private layoutListener?;
+    private startConfig;
+    private startItems;
+    private previewItems;
+    private _element;
+    private placeholder?;
+    constructor();
+    connect(onLayout: (layout: LayoutOutput[]) => void): void;
+    setOptions(value: Partial<IGridLayoutOptions>): void;
+    setEditMode(value: boolean): void;
+    setItems(items: GridItemState[]): void;
+    /**
+     * Registers a new item, or refreshes the DOM element reference of one that's
+     * already tracked. Adding an item can shift the whole layout (compaction /
+     * push), so that path settles. Merely re-supplying the same element on an
+     * already-known id has no geometric effect, so it is a deliberate no-op —
+     * skipping it is what keeps a per-item `effect()` that calls this on every
+     * change-detection pass from re-triggering `settle()` indefinitely.
+     */
+    registerItem(item: GridItemState): void;
+    /**
+     * Updates an item's config. Only writes the signal and re-settles the layout
+     * when the *value* actually changed. Without this guard, any caller that
+     * supplies a structurally-equal but referentially-new config object (e.g. a
+     * template bound to a `computed()` layout) would cause an unconditional
+     * `items.set()` on every run — which produces new output objects, which
+     * feed back into that same new config reference, forever.
+     */
+    updateItemConfig(id: string, config: GridItemConfig): void;
+    unregisterItem(id: string): void;
+    /** Called once the grid surface element exists (e.g. from `ngAfterViewInit`). */
+    attachElement(el: HTMLElement): void;
+    /** Recomputes pixel positions after the surface resizes. Call from a `ResizeObserver`. */
+    refreshMetrics(): void;
+    isItemDraggable(item: GridItemState): boolean;
+    isItemResizable(item: GridItemState): boolean;
+    begin(id: string): void;
+    move(id: string): void;
+    resize(id: string, out: {
+        width: number;
+        height: number;
+        moveLeft: number;
+        moveTop: number;
+    }): void;
+    end(id: string): void;
+    /** Moves an item by whole grid cells — used by arrow-key handling in the item component. */
+    moveByCells(id: string, dCols: number, dRows: number): void;
+    /** Resizes an item by whole grid cells — used by shift+arrow handling in the item component. */
+    resizeByCells(id: string, dCols: number, dRows: number): void;
+    private preview;
+    private screenToGrid;
+    private screenResizeToGrid;
+    private clamp;
+    private clampSize;
+    /** Applies pushes on drag-end and, when configured, removes gaps via compaction. */
+    private settle;
+    private applyCss;
+    private metrics;
+    private resolveRtl;
+    private calculateHeight;
+    private emit;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<GridLayoutService, never>;
+    static ɵprov: _angular_core.ɵɵInjectableDeclaration<GridLayoutService>;
+}
+
+declare class NgxGridLayoutComponent implements AfterViewInit, OnDestroy {
+    readonly options: _angular_core.InputSignal<IGridLayoutOptions>;
+    readonly editMode: _angular_core.InputSignal<boolean>;
+    readonly layoutChange: _angular_core.OutputEmitterRef<LayoutOutput[]>;
+    /** Explicit direction override. Leave unset to inherit the page/host direction automatically. */
+    readonly dir: _angular_core.InputSignal<"ltr" | "rtl" | undefined>;
+    readonly dirOverride: _angular_core.InputSignal<"ltr" | "rtl" | undefined>;
+    readonly service: GridLayoutService;
+    private readonly el;
+    private surface?;
+    private resizeObserver?;
+    constructor();
+    ngAfterViewInit(): void;
+    ngOnDestroy(): void;
+    setItems(items: GridItemState[]): void;
+    update(options: Partial<IGridLayoutOptions>): void;
+    private setCss;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<NgxGridLayoutComponent, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<NgxGridLayoutComponent, "ngx-grid-layout", never, { "options": { "alias": "options"; "required": false; "isSignal": true; }; "editMode": { "alias": "editMode"; "required": false; "isSignal": true; }; "dir": { "alias": "dir"; "required": false; "isSignal": true; }; }, { "layoutChange": "layoutChange"; }, never, ["*"], true, never>;
+}
+
+declare class NgxGridItemComponent implements OnDestroy, OnInit {
+    /** Bound as `[id]` in templates (matches the demo app's existing usage). */
+    readonly itemId: _angular_core.InputSignal<string | undefined>;
+    readonly config: _angular_core.InputSignal<GridItemConfig>;
+    readonly layoutChange: _angular_core.OutputEmitterRef<GridItemConfig>;
+    readonly dragging: _angular_core.WritableSignal<boolean>;
+    readonly resizing: _angular_core.WritableSignal<boolean>;
+    readonly active: _angular_core.Signal<boolean>;
+    readonly transitionStyle: _angular_core.Signal<"none" | "left .18s ease, top .18s ease, width .18s ease, height .18s ease">;
+    readonly interactive: _angular_core.Signal<boolean>;
+    private readonly service;
+    private readonly el;
+    private readonly drag;
+    private readonly resize;
+    readonly resizable: _angular_core.Signal<boolean>;
+    constructor();
+    ngOnInit(): void;
+    ngOnDestroy(): void;
+    onDragStart: () => void;
+    onDragMove: () => void;
+    onDragEnd: () => void;
+    onResizeStart: () => void;
+    onResizeMove: (v: {
+        width: number;
+        height: number;
+        moveLeft: number;
+        moveTop: number;
+    }) => void;
+    onResizeEnd: () => void;
+    /** Arrow keys move the item by one cell; Shift+arrow resizes it by one cell. */
+    onKeyDown(e: KeyboardEvent): void;
+    private finishInteraction;
+    /** Converts the item's min/max cell counts (config) into px for the resize directive. */
+    private applySizeConstraints;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<NgxGridItemComponent, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<NgxGridItemComponent, "ngx-grid-item", never, { "itemId": { "alias": "id"; "required": false; "isSignal": true; }; "config": { "alias": "config"; "required": false; "isSignal": true; }; }, { "layoutChange": "layoutChange"; }, never, ["*"], true, [{ directive: typeof i1.NgxDraggable; inputs: { "dragHandle": "dragHandle"; "lockAxis": "lockAxis"; }; outputs: {}; }, { directive: typeof i1.NgxResizable; inputs: {}; outputs: {}; }]>;
+}
+
+declare class NgxGridLayoutModule {
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<NgxGridLayoutModule, never>;
+    static ɵmod: _angular_core.ɵɵNgModuleDeclaration<NgxGridLayoutModule, never, [typeof NgxGridLayoutComponent, typeof NgxGridItemComponent], [typeof NgxGridLayoutComponent, typeof NgxGridItemComponent]>;
+    static ɵinj: _angular_core.ɵɵInjectorDeclaration<NgxGridLayoutModule>;
+}
+
+export { GridItemConfig, GridLayoutOptions, GridLayoutService, NgxGridItemComponent, NgxGridLayoutComponent, NgxGridLayoutModule, colToLeft, collides, compact, computeMetrics, getAllCollisions, getFirstCollision, gridItemConfigsEqual, leftToCol, maxOccupiedRow, moveItem, normalizeGridItem, placeItem, rowToTop, spanToHeightPx, spanToWidthPx, topToRow, trySwap };
+export type { CompactMode, GridFlow, GridItemState, GridMetrics, IGridBackgroundCfg, IGridLayoutOptions, LayoutNode, LayoutOutput, MoveOptions };

package/types/ngx-kit-image-editor.d.ts

@@ -96,7 +96,7 @@ declare const DEFAULT_NGX_IMAGE_EDITOR_LOCALIZATION: NgxImageEditorLocalization;
  * شدن‌شون می‌شد).
  */
 declare class NgxImageEditorComponent {
-    source: _angular_core.InputSignal<string | File | Blob | null>;
+    source: _angular_core.InputSignal<string | Blob | File | null>;
     /** قفل نسبتِ کراپ (مثلاً ۱ برای آواتار مربعی)؛ undefined یعنی آزاد */
     aspectRatio: _angular_core.InputSignal<number | undefined>;
     outputMaxWidth: _angular_core.InputSignal<number | undefined>;

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

@@ -210,6 +210,17 @@ declare function randomStrnig(extraLength?: number, useNumeric?: boolean): strin
 
 declare function makeConfetti(doc: Document, wrap: HTMLElement): void;
 
+declare function generateSequentialGuid(): string;
+
+/**
+ * Performs a deep merge of objects and returns new object. Does not modify
+ * objects (immutable) and merges arrays via concatenation.
+ *
+ * @param {...object} objects - Objects to merge
+ * @returns {object} New object with merged key/values
+ */
+declare function mergeDeep(...objects: any[]): any;
+
 declare class BrowserService {
     private platformId;
     constructor(platformId: object);
@@ -331,5 +342,5 @@ interface OverlayInstance {
     cleanup: () => void;
 }
 
-export { BrowserService, DIALOG_OVERLAY_CLASSNAME, DirectionService, FOCUSABLE_SELECTOR, OverlayRef, OverlayService, RangeSliderComponent, SaturationComponent, SliderComponent, ValueModel, WINDOW, getOffsetPosition, makeConfetti, mergeConfig, randomStrnig, startDragSession };
+export { BrowserService, DIALOG_OVERLAY_CLASSNAME, DirectionService, FOCUSABLE_SELECTOR, OverlayRef, OverlayService, RangeSliderComponent, SaturationComponent, SliderComponent, ValueModel, WINDOW, generateSequentialGuid, getOffsetPosition, makeConfetti, mergeConfig, mergeDeep, randomStrnig, startDragSession };
 export type { Alignment, BaseOverlayOptions, Direction, DragSessionCallbacks, IPosition, IValue, OverlayInstance, OverlayOptions, Placement, Point, TemplateOptions };

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 };