# Dimension Animation
URL: https://pro.rv-grid.com/api/dimension-animation/
Source: src/content/docs/api/dimension-animation.md
## Module Extensions

### `HTMLRevoGridElement` (Extended from `global`)

```ts
interface HTMLRevoGridElement {
  dimensionAnimation?: DimensionAnimationConfig
}
```

---

### `AdditionalData` (Extended from `@revolist/revogrid`)

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

---

### `HTMLRevoGridElementEventMap` (Extended from `global`)

```ts
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.

```ts
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`.

```ts
/** 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`.

```ts
/**
 * 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.

```ts
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.

```ts
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.

```ts
/**
 * 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`

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

---

### `DimensionAnimationIndexesByType`

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

---

### `DimensionAnimationFrameInput`

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

```ts
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.

```ts
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.

```ts
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.

```ts
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`.

```ts
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.

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

---

### `DimensionAnimationSizeCache`

Internal cache of sizes keyed by dimension and physical index.

```ts
/** 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.

```ts
/** 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.

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

---

### `DEFAULT_DIMENSION_ANIMATION_DURATION`

Default dimension animation duration, in milliseconds.

```ts
DEFAULT_DIMENSION_ANIMATION_DURATION: 180;
```

---

### `DEFAULT_DIMENSION_ANIMATION_FALLBACK_ROW_SIZE`

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

```ts
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.

```ts
DEFAULT_DIMENSION_ANIMATION_FALLBACK_COLUMN_SIZE: 100;
```

---

### `DEFAULT_DIMENSION_ANIMATION_TYPES`

```ts
DEFAULT_DIMENSION_ANIMATION_TYPES: (DimensionRows | DimensionCols)[];
```

---

### `NormalizedDimensionAnimationConfig`

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

---

### `DEFAULT_DIMENSION_ANIMATION_CONFIG`

```ts
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.

```ts
DIMENSION_ANIMATE_EVENT: string;
```

---

### `BEFORE_DIMENSION_ANIMATE_EVENT`

Cancelable event emitted before a dimension animation operation starts.

```ts
BEFORE_DIMENSION_ANIMATE_EVENT: string;
```

---

### `AFTER_DIMENSION_ANIMATE_EVENT`

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

```ts
AFTER_DIMENSION_ANIMATE_EVENT: string;
```

---

### `DimensionAnimationAnimator`

Manages dimension size animation frames and cancellation.

```ts
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.

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

---

### `normalizeDimensionAnimationIndexes`

Converts iterable or record input into a finite index array.

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

---

### `resolveDimensionAnimationRequestIndexes`

Resolves a request into dimension buckets with normalized indexes.

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