Dimension Animation

Module Extensions

HTMLRevoGridElement (Extended from global)

interface HTMLRevoGridElement {
  dimensionAnimation?: DimensionAnimationConfig
}

---

AdditionalData (Extended from @revolist/revogrid)

interface AdditionalData {
  /**
       * Additional data property dimensionAnimation
       * @deprecated Use `grid.dimensionAnimation` instead.
       */
      dimensionAnimation?: DimensionAnimationConfig
}

---

HTMLRevoGridElementEventMap (Extended from global)

interface HTMLRevoGridElementEventMap {
  dimensionanimate: DimensionAnimationEventDetail;
  beforedimensionanimate: DimensionAnimationEventDetail;
  afterdimensionanimate: DimensionAnimationEventDetail
}

Plugin API

DimensionAnimationPlugin

RevoGrid Pro plugin that animates dimension sizes without owning visibility state.

Rows and columns can be addressed by physical source index or by current visual index. Callers own follow-up state changes such as applying trim or mutating proxy order.

class DimensionAnimationPlugin {
  /** Collapse dimensions by animating their current size to zero. */
  collapse(indexes: DimensionAnimationIndexes, options: DimensionAnimationOptions =;

  /** Expand dimensions from zero size to their cached/default size. */
  expand(indexes: DimensionAnimationIndexes, options: DimensionAnimationOptions =;

  /** Animate explicit dimension-size frames. */
  animate(frames: DimensionAnimationFrameInput[], options: DimensionAnimationOptions =;

  /** Cancels in-flight animations. Omit arguments to cancel all animations. */
  cancel(type?: MultiDimensionType, indexes?: DimensionAnimationIndexes);

  destroy();
}

---

DimensionAnimationAction

Supported dimension size animation operations for DimensionAnimationPlugin.

/** Supported dimension size animation operations for `DimensionAnimationPlugin`. */
export type DimensionAnimationAction = 'collapse' | 'expand' | 'animate';

---

DimensionAnimationEasing

Animation easing used when interpolating dimension sizes.

• linear: direct progress mapping.
• easeOutCubic: default easing, fast start with soft finish.
• function: receives normalized progress from 0 to 1.

/**
 * Animation easing used when interpolating dimension sizes.
 *
 * - `linear`: direct progress mapping.
 * - `easeOutCubic`: default easing, fast start with soft finish.
 * - function: receives normalized progress from `0` to `1`.
 */
export type DimensionAnimationEasing =
  | 'linear'
  | 'easeOutCubic'
  | ((progress: number) => number);

---

DimensionAnimationConfig

Plugin-level configuration for dimension size animation behavior.

interface DimensionAnimationConfig {
  /** Animation duration in milliseconds. Use `0` to apply synchronously. */
    duration?: number;
  /** Easing function or named easing. Defaults to `easeOutCubic`. */
    easing?: DimensionAnimationEasing;
  /** Dimensions affected by requests that do not specify a single `type`. */
    types?: MultiDimensionType[]
}

---

DimensionAnimationOptions (Extended from index.ts)

Per-call options for controller methods and event requests.

interface DimensionAnimationOptions {
  /** Single dimension to target for the request. */
    type?: MultiDimensionType;
  /** Whether `indexes` are source physical indexes or current visible indexes. */
    indexKind?: DimensionAnimationIndexKind
}

---

DimensionAnimationIndexes

Dimension indexes accepted by the controller.

Iterables such as arrays are treated as indexes to affect. Records use truthy values to mark affected indexes.

/**
 * Dimension indexes accepted by the controller.
 *
 * Iterables such as arrays are treated as indexes to affect. Records use
 * truthy values to mark affected indexes.
 */
export type DimensionAnimationIndexes = Iterable<number> | Record<number, boolean | undefined>;

---

DimensionAnimationIndexKind

export type DimensionAnimationIndexKind = 'physical' | 'visual';

---

DimensionAnimationIndexesByType

export type DimensionAnimationIndexesByType = Partial<Record<MultiDimensionType, DimensionAnimationIndexes>>;

---

DimensionAnimationFrameInput

Explicit animation frame input used by callers that already know visual positions.

interface DimensionAnimationFrameInput {
  /** Dimension containing this frame. Defaults to request `type` or `rgRow`. */
    type?: MultiDimensionType;
  /** Current visual index in the dimension. */
    visualIndex: number;
  /** Optional physical index used for cancellation/cache identity. */
    physicalIndex?: number;
  /** Start size. If omitted, the current/cached size is used. */
    from?: number;
  /** End size. If omitted, the current/cached size is used. */
    to?: number
}

---

DimensionAnimationRequest (Extended from index.ts)

Event/controller request payload for dimension animation operations.

interface DimensionAnimationRequest {
  /** Operation to perform. */
    action: DimensionAnimationAction;
  /** Indexes for `collapse` and `expand`. */
    indexes?: DimensionAnimationIndexes;
  /** Target indexes keyed by dimension. */
    byType?: DimensionAnimationIndexesByType;
  /** Explicit frame inputs for `animate`. */
    frames?: DimensionAnimationFrameInput[]
}

---

DimensionAnimationResult

Result emitted for each dimension touched by a request.

interface DimensionAnimationResult {
  /** Operation that produced this result. */
    action: DimensionAnimationAction;
  /** Dimension affected by this result. */
    type: MultiDimensionType;
  /** Input indexes included in the operation. Empty for explicit frame requests. */
    indexes: number[];
  /** Whether the animation was cancelled before normal completion. */
    cancelled: boolean;
  /** Internal frames resolved and animated for this result. */
    frames: DimensionAnimationFrame[]
}

---

DimensionAnimationEventDetail (Extended from index.ts)

Detail payload for dimension animation events.

interface DimensionAnimationEventDetail {
  /** Promise attached synchronously by the plugin for event-driven callers that need completion ordering. */
    done?: Promise<DimensionAnimationResult[]>;
  /** Filled by the plugin after a `dimensionanimate` event request completes. */
    results?: DimensionAnimationResult[]
}

---

DimensionAnimationController

Public controller API implemented by DimensionAnimationPlugin.

interface DimensionAnimationController {
  /** Collapse dimensions with animation by animating their size to zero. */
    collapse(indexes: DimensionAnimationIndexes, options?: DimensionAnimationOptions): Promise<DimensionAnimationResult[]>;
  /** Expand dimensions by starting them at zero, then animating to their cached/default size. */
    expand(indexes: DimensionAnimationIndexes, options?: DimensionAnimationOptions): Promise<DimensionAnimationResult[]>;
  /** Animate explicit dimension-size frames. */
    animate(frames: DimensionAnimationFrameInput[], options?: DimensionAnimationOptions): Promise<DimensionAnimationResult[]>;
  /** Cancel matching in-flight animations. */
    cancel(type?: MultiDimensionType, indexes?: DimensionAnimationIndexes): void
}

---

DimensionAnimationFrame

Internal dimension-size animation frame resolved from physical to visual index.

interface DimensionAnimationFrame {
  type: MultiDimensionType;
  physicalIndex: number;
  visualIndex: number;
  from: number;
  to: number
}

---

DimensionAnimationSizeCache

Internal cache of sizes keyed by dimension and physical index.

/** Internal cache of sizes keyed by dimension and physical index. */
export type DimensionAnimationSizeCache = Partial<Record<MultiDimensionType, Record<number, number>>>;

---

DimensionAnimationSizePatch

Internal patch of visual sizes passed to the dimension provider.

/** Internal patch of visual sizes passed to the dimension provider. */
export type DimensionAnimationSizePatch = ViewSettingSizeProp;

---

normalizeDimensionAnimationConfig

Normalizes partial dimension-animation plugin config into the complete runtime shape.

export function normalizeDimensionAnimationConfig(
  config?: DimensionAnimationConfig,
): NormalizedDimensionAnimationConfig;

---

DEFAULT_DIMENSION_ANIMATION_DURATION

Default dimension animation duration, in milliseconds.

DEFAULT_DIMENSION_ANIMATION_DURATION: 180;

---

DEFAULT_DIMENSION_ANIMATION_FALLBACK_ROW_SIZE

Last-resort row size used when neither dimension nor grid defaults are configured.

DEFAULT_DIMENSION_ANIMATION_FALLBACK_ROW_SIZE: 24;

---

DEFAULT_DIMENSION_ANIMATION_FALLBACK_COLUMN_SIZE

Last-resort column size used when neither dimension nor grid defaults are configured.

DEFAULT_DIMENSION_ANIMATION_FALLBACK_COLUMN_SIZE: 100;

---

DEFAULT_DIMENSION_ANIMATION_TYPES

DEFAULT_DIMENSION_ANIMATION_TYPES: (DimensionRows | DimensionCols)[];

---

NormalizedDimensionAnimationConfig

export type NormalizedDimensionAnimationConfig = Required<Pick<
  DimensionAnimationConfig,
  'duration' | 'easing' | 'types'
>>;

---

DEFAULT_DIMENSION_ANIMATION_CONFIG

DEFAULT_DIMENSION_ANIMATION_CONFIG: {
  duration: number;
  easing: string;
  types: (DimensionRows | DimensionCols)[];
};

---

DIMENSION_ANIMATE_EVENT

Event dispatched to request a dimension-size animation from the grid element.

The plugin attaches detail.done synchronously so event-driven integrations can await completion before running follow-up logic such as trimming or reorder.

DIMENSION_ANIMATE_EVENT: string;

---

BEFORE_DIMENSION_ANIMATE_EVENT

Cancelable event emitted before a dimension animation operation starts.

BEFORE_DIMENSION_ANIMATE_EVENT: string;

---

AFTER_DIMENSION_ANIMATE_EVENT

Event emitted after a dimension animation operation finishes or is cancelled.

AFTER_DIMENSION_ANIMATE_EVENT: string;

---

DimensionAnimationAnimator

Manages dimension size animation frames and cancellation.

class DimensionAnimationAnimator {
  /** Animates frame sizes and returns `false` if the run is cancelled. */
  animate(
    frames: DimensionAnimationFrame[],
    options: NormalizedDimensionAnimationConfig,
  ): Promise<boolean>;

  /** Cancels matching dimension animations. Omitted arguments cancel all animations. */
  cancel(type?: MultiDimensionType, indexes?: DimensionAnimationIndexes);

  /** Applies interpolated sizes for a group of animation frames. */
  applyFrameSizes(type: MultiDimensionType, frames: DimensionAnimationFrame[], progress: number);
}

---

resolveDimensionAnimationEasing

Resolves a named or custom easing into a normalized progress function.

export function resolveDimensionAnimationEasing(
  easing: DimensionAnimationEasing,
): (progress: number) => number;

---

normalizeDimensionAnimationIndexes

Converts iterable or record input into a finite index array.

export function normalizeDimensionAnimationIndexes(
  indexes: DimensionAnimationIndexes | undefined,
): number[];

---

resolveDimensionAnimationRequestIndexes

Resolves a request into dimension buckets with normalized indexes.

export function resolveDimensionAnimationRequestIndexes(
  request: DimensionAnimationRequest,
  defaultTypes: MultiDimensionType[],
): Partial<Record<MultiDimensionType, number[]>>;