@revolist/revogrid 4.22.1 → 4.23.0

package/dist/types/plugins/sorting/sorting.plugin.d.ts

@@ -1,6 +1,6 @@
 import { BasePlugin } from '../base.plugin';
 import type { ColumnRegular, DimensionRows, PluginProviders } from "../../types/index";
-import type { SortingConfig, SortingOrder, SortingOrderFunction } from './sorting.types';
+import type { SortingColumnMap, SortingColumnOrder, SortingConfig, SortingOrder, SortingOrderFunction } from './sorting.types';
 export * from './sorting.types';
 export * from './sorting.func';
 export * from './sorting.sign';
@@ -15,34 +15,109 @@ export * from './sorting.sign';
  */
 export declare class SortingPlugin extends BasePlugin {
     revogrid: HTMLRevoGridElement;
+    /**
+     * Current sorting order per column property.
+     */
     sorting?: SortingOrder;
+    /**
+     * Comparator functions indexed by column property.
+     *
+     * Multiple columns can be sorted at the same time.
+     */
     sortingFunc?: SortingOrderFunction;
     /**
-     * Delayed sorting promise
+     * Column metadata for the current sorting state.
+     *
+     * Used internally to optimize default sorting without changing comparator
+     * functions or their public API contract.
+     */
+    private sortingColumns?;
+    /**
+     * Active sorting priority in click/config insertion order.
+     *
+     * Required for numeric column props because object key iteration does not
+     * preserve insertion order for integer-like keys.
+     */
+    private sortingOrder?;
+    /**
+     * Delayed sorting promise registered in the grid render job queue.
      */
     sortingPromise: (() => void) | null;
     /**
-     * We need to sort only so often
+     * Debounced sorting entry point.
+     *
+     * Sorting can be requested by column changes, source changes, and header
+     * clicks in quick succession, so the actual sort is delayed and coalesced.
      */
-    postponeSort: import("lodash").DebouncedFunc<(order?: SortingOrder, comparison?: SortingOrderFunction, ignoreViewportUpdate?: boolean) => void>;
+    postponeSort: import("lodash").DebouncedFunc<(order?: SortingOrder, comparison?: SortingOrderFunction, sortingColumns?: SortingColumnMap, sortingOrder?: SortingColumnOrder, ignoreViewportUpdate?: boolean) => void>;
     constructor(revogrid: HTMLRevoGridElement, providers: PluginProviders, config?: SortingConfig);
     /**
-     * Entry point for sorting, waits for all delays, registers jobs
+     * Creates mutable sorting maps from current state when additive sorting is requested.
+     */
+    private createSortingState;
+    /**
+     * Stores normalized sorting state, clearing inactive empty maps.
+     */
+    private setSortingState;
+    /**
+     * Adds or replaces a column in a sorting state.
+     */
+    private setColumnSorting;
+    /**
+     * Removes a column from a sorting state.
+     */
+    private clearColumnSorting;
+    /**
+     * Normalizes external sorting configuration into internal order,
+     * comparator, and column metadata maps.
+     */
+    private applySortingConfig;
+    /**
+     * Schedules sorting before the next render.
+     *
+     * @param order - Active sorting order by column property.
+     * @param sortingFunc - Comparator functions by column property.
+     * @param sortingColumns - Column metadata by property.
+     * @param sortingOrder - Active sorting priority in click/config insertion order.
+     * @param ignoreViewportUpdate - Skips dimension position recalculation when true.
      */
     startSorting(order?: SortingOrder, sortingFunc?: SortingOrderFunction, ignoreViewportUpdate?: boolean): void;
+    startSorting(order?: SortingOrder, sortingFunc?: SortingOrderFunction, sortingColumns?: SortingColumnMap, sortingOrder?: SortingColumnOrder, ignoreViewportUpdate?: boolean): void;
     /**
-     * Apply sorting to data on header click
-     * If additive - add to existing sorting, multiple columns can be sorted
+     * Applies sorting requested by a sortable header click.
+     *
+     * @param column - Column that initiated sorting.
+     * @param additive - If true, add/remove this column from the current multi-sort state.
      */
     headerclick(column: ColumnRegular, additive: boolean): void;
+    /**
+     * Applies sorting state produced by a header click.
+     */
+    private applyHeaderSorting;
+    /**
+     * Runs a scheduled sort and resolves the render-blocking sorting promise.
+     *
+     * @param order - Active sorting order by column property.
+     * @param comparison - Comparator functions by column property.
+     * @param sortingColumns - Column metadata by property.
+     * @param sortingOrder - Active sorting priority in click/config insertion order.
+     * @param ignoreViewportUpdate - Skips dimension position recalculation when true.
+     */
     runSorting(order?: SortingOrder, comparison?: SortingOrderFunction, ignoreViewportUpdate?: boolean): void;
+    runSorting(order?: SortingOrder, comparison?: SortingOrderFunction, sortingColumns?: SortingColumnMap, sortingOrder?: SortingColumnOrder, ignoreViewportUpdate?: boolean): void;
     /**
-     * Sort items by sorting function
+     * Sorts row proxy indexes by sorting functions.
+     *
      * @requires proxyItems applied to row store
      * @requires source applied to row store
      *
      * @param sorting - per column sorting
-     * @param data - this.stores['rgRow'].store.get('source')
+     * @param sortingFunc - Comparator functions by column property.
+     * @param sortingColumns - Column metadata by property.
+     * @param sortingOrder - Active sorting priority in click/config insertion order.
+     * @param types - Row stores to sort.
+     * @param ignoreViewportUpdate - Skips dimension position recalculation when true.
      */
     sort(sorting?: SortingOrder, sortingFunc?: SortingOrderFunction, types?: DimensionRows[], ignoreViewportUpdate?: boolean): void;
+    sort(sorting?: SortingOrder, sortingFunc?: SortingOrderFunction, sortingColumns?: SortingColumnMap, sortingOrder?: SortingColumnOrder, types?: DimensionRows[], ignoreViewportUpdate?: boolean): void;
 }

package/dist/types/plugins/sorting/sorting.sign.d.ts

@@ -1,6 +1,10 @@
 import { ColumnRegular } from "../../types/index";
+import type { SortingColumnRender } from './sorting.types';
 type Props = {
-    column: ColumnRegular;
+    column: ColumnRegular & SortingColumnRender;
 };
+/**
+ * Renders sorting direction and optional additive sorting rank.
+ */
 export declare const SortingSign: ({ column }: Props) => any;
 export {};

package/dist/types/plugins/sorting/sorting.types.d.ts

@@ -1,14 +1,59 @@
-import type { CellCompareFunc, ColumnProp, Order } from "../../types/index";
+import type { CellCompareFunc, ColumnProp, ColumnRegular, Order } from "../../types/index";
+/**
+ * Current sorting order per column property.
+ */
 export type SortingOrder = Record<ColumnProp, Order>;
+/**
+ * Comparator functions indexed by column property.
+ *
+ * Undefined comparator entries are treated as inactive sorting entries.
+ */
 export type SortingOrderFunction = Record<ColumnProp, CellCompareFunc | undefined>;
+/**
+ * Column metadata indexed by column property.
+ *
+ * This is an internal companion map for `SortingOrderFunction`. It lets the
+ * sorting helper detect the default comparer path without mutating
+ * `CellCompareFunc` instances or changing the public comparator contract.
+ */
+export type SortingColumnMap = Record<ColumnProp, Partial<ColumnRegular> | undefined>;
+/**
+ * Active sorting priority in click/config insertion order.
+ *
+ * This is stored separately from `SortingOrder` because JavaScript object keys
+ * that look like integers are enumerated in numeric order, not insertion order.
+ */
+export type SortingColumnOrder = ColumnProp[];
+/**
+ * Header metadata used to display additive sort priority.
+ */
+export type SortingColumnRender = {
+    /**
+     * One-based additive sorting rank.
+     */
+    sortIndex?: number;
+};
+/**
+ * Sorting information emitted after columns are set.
+ */
 export type ColumnSetEvent = {
     order: SortingOrder;
 };
+/**
+ * External sorting configuration.
+ */
 export type SortingConfig = {
+    /**
+     * Columns to sort by.
+     */
     columns?: {
         prop: ColumnProp;
         order: Order;
         cellCompare?: CellCompareFunc;
     }[];
+    /**
+     * If true, merge provided columns with the current sorting state.
+     * If false or omitted, replace current sorting state.
+     */
     additive?: boolean;
 };

package/dist/types/services/local.scroll.service.d.ts

@@ -1,4 +1,5 @@
 import type { DimensionType, ViewPortScrollEvent } from "../types/index";
+import { type ScrollDimension } from './scroll.dimension.helpers';
 interface Config {
     skipAnimationFrame?: boolean;
     runScroll(e: ViewPortScrollEvent): void;
@@ -10,6 +11,8 @@ type Params = {
     clientSize: number;
     virtualSize: number;
     maxSize?: number;
+    maxScrollSize?: number;
+    scrollDimension?: ScrollDimension;
 };
 /**
  * Based on content size, client size and virtual size
@@ -20,17 +23,22 @@ export default class LocalScrollService {
     private cfg;
     private preventArtificialScroll;
     private previousScroll;
+    private previousLogicalScroll;
     private params;
     constructor(cfg: Config);
     setParams(params: Params, dimension: DimensionType): void;
     setScroll(e: ViewPortScrollEvent): Promise<void>;
+    setScrollByDelta(e: ViewPortScrollEvent, currentPhysicalCoordinate: number): Promise<ViewPortScrollEvent>;
     /**
      * On scroll event started
      */
     scroll(coordinate: number, dimension: DimensionType, force?: boolean, delta?: number, outside?: boolean): void;
     private getParams;
-    private wrapCoordinate;
+    private wrapPhysicalCoordinate;
+    private wrapLogicalCoordinate;
     private cancelScroll;
-    private convert;
+    private toLogicalScrollCoordinate;
+    private toPhysicalCoordinate;
+    private toLogicalCoordinate;
 }
 export {};

package/dist/types/services/scroll.dimension.helpers.d.ts

@@ -0,0 +1,20 @@
+export type ScrollDimensionInput = {
+    contentSize: number;
+    clientSize: number;
+    virtualSize?: number;
+    maxScrollSize?: number;
+};
+export type ScrollDimension = {
+    contentSize: number;
+    clientSize: number;
+    viewportSize: number;
+    physicalContentSize: number;
+    logicalScrollSize: number;
+    physicalScrollSize: number;
+    isCompressed: boolean;
+    toLogicalCoordinate(coordinate: number): number;
+    toPhysicalCoordinate(coordinate: number): number;
+    getRenderOffset(coordinate: number): number;
+};
+export declare function getMaxScrollSize(doc?: Document | undefined): number;
+export declare function getScrollDimension({ contentSize, clientSize, virtualSize, maxScrollSize, }: ScrollDimensionInput): ScrollDimension;

package/dist/types/store/vp/viewport.helpers.d.ts

@@ -1,6 +1,8 @@
 import type { DimensionSettingsState, PositionItem, ViewSettingSizeProp, ViewportStateItems, VirtualPositionItem, Range } from "../../types/index";
 export type DimensionDataViewport = Pick<DimensionSettingsState, 'indexes' | 'positionIndexes' | 'positionIndexToItem' | 'sizes' | 'originItemSize' | 'realSize'>;
 export type ItemsToUpdate = Pick<ViewportStateItems, 'items' | 'start' | 'end'>;
+export declare function getViewportMaxCoordinate(dimension: Pick<DimensionSettingsState, 'realSize' | 'originItemSize'>, viewportSize: number, frameOffset?: number): number;
+export declare function clampViewportCoordinate(coordinate: number, dimension: Pick<DimensionSettingsState, 'realSize' | 'originItemSize'>, viewportSize: number, frameOffset?: number): number;
 /**
  * Update items based on new scroll position
  * If viewport wasn't changed fully simple recombination of positions

package/dist/types/types/interfaces.d.ts

@@ -509,6 +509,12 @@ export interface ViewportState extends ViewportStateItems {
      * Until virtualization is not disabled.
      */
     clientSize: number;
+    /**
+     * Difference between logical coordinate and browser-safe rendered coordinate.
+     * Internal scroll virtualization offset used when content exceeds browser
+     * native scroll size limits.
+     */
+    renderOffset?: number;
 }
 /**
  * `ViewSettingSizeProp` is a record that maps column or row indexes to their
@@ -625,6 +631,11 @@ export interface DimensionSettingsState extends DimensionCalc {
      * Represents the origin item size of the dimension.
      */
     originItemSize: number;
+    /**
+     * Internal render offset applied when logical scroll space is compressed into
+     * a browser-safe physical scroll range.
+     */
+    renderOffset?: number;
 }
 /**
  * Represents the mapping of dimension types to their corresponding observable stores.