# Autofill
URL: https://pro.rv-grid.com/api/autofill/
Source: src/content/docs/api/autofill.md
### `createDefaultAutoFillStrategies`

Creates the default AutoFill strategy list in evaluation order.

Strategies are ordered from specific to general, with copy fallback last. The
same list is used by AutoFillPlugin and AutoFillPreviewPlugin when no active
AutoFillPlugin instance can be resolved.

**@returns** Default AutoFill strategies.

```ts
export function createDefaultAutoFillStrategies(): AutoFillStrategy[];
```

---

### `AutoFillPlugin`

The `AutoFillPlugin` enhances RevoGrid with advanced autofill capabilities,
allowing users to automatically fill cell ranges based on various sequence
strategies. This plugin supports numeric, date, and text sequences, making it
versatile for different data types and user needs.

 **Features**:
- Utilizes multiple pre-defined strategies for numbers, dates, time values,
  text-number labels, weekday/month names, boolean cycles, and copy fallback.
- Listens for the `beforeautofill` to trigger autofill actions based on user
  interactions.
- Allows registration of additional custom autofill strategies.
- Applies autofilled data directly to the grid, updating the data store efficiently.

**Usage**:
- Import `AutoFillPlugin` and add it to the RevoGrid's plugin list.
- The grid will automatically handle range selection and autofilling based on the
  registered strategies.

### Example
```typescript
import { AutoFillPlugin } from '@revolist/revogrid-pro'

const grid = document.createElement('revo-grid');
grid.plugins = [AutoFillPlugin]; // Add autofill functionality to the grid
```

This plugin is ideal for enhancing user productivity in data entry tasks by
providing intelligent filling of repetitive or sequential data patterns, commonly
used in spreadsheets and data management applications.

```ts
class AutoFillPlugin {
  /**
     * Registers a custom autofill strategy.
     *
     * Custom strategies are inserted before the copy fallback strategy so they can
     * override generic copy behavior.
     *
     * @param strategy Strategy function to register.
     */
  registerStrategy(strategy: AutoFillStrategy);

  /**
     * Returns the active strategy list.
     *
     * The preview plugin reads this list from the active AutoFillPlugin instance so
     * preview and final commit use identical strategy order.
     *
     * @returns Registered strategy list in evaluation order.
     */
  getStrategies();
}
```

---

### `computeAutoFillData`

```ts
export function computeAutoFillData(;
```

---

### `mapAutoFillMatrixToData`

```ts
export function mapAutoFillMatrixToData(
  matrix: any[][],
  target: RangeArea,
  providers: Pick<PluginProviders, 'column'>,
  colType: DimensionCols,
): Record<number, DataType>;
```

---

### `AutoFillComputedData`

```ts
export type AutoFillComputedData = {
  matrix: any[][];
  data: Record<number, DataType>;
};
```

---

### `AutoFillComputeOptions` (Extended from `index.ts`)

```ts
export type AutoFillComputeOptions = Pick<ChangedRange, 'oldRange' | 'newRange'> & {
  type: DimensionRows;
  colType: DimensionCols;
  providers: PluginProviders;
  strategies: AutoFillStrategy[];
};
```

---

### `AutoFillPreviewPlugin`

```ts
class AutoFillPreviewPlugin {
  destroy();
}
```

---

### `AutoFillDirection`

Direction in which the autofill drag expands from the selected source range.

`both` is used when the source and target ranges cannot be reduced to a single
horizontal or vertical direction.

```ts
/**
 * Direction in which the autofill drag expands from the selected source range.
 *
 * `both` is used when the source and target ranges cannot be reduced to a single
 * horizontal or vertical direction.
 */
export type AutoFillDirection = 'up' | 'down' | 'left' | 'right' | 'both';
```

---

### `AutoFillStrategyContext`

Rich context passed to autofill strategies.

Existing custom strategies can keep using the legacy three-argument signature.
New strategies can read this object when they need selection metadata, drag
direction, dimension types, or plugin providers.

```ts
/**
 * Rich context passed to autofill strategies.
 *
 * Existing custom strategies can keep using the legacy three-argument signature.
 * New strategies can read this object when they need selection metadata, drag
 * direction, dimension types, or plugin providers.
 */
export type AutoFillStrategyContext = {
  /** Original selected/source range used as the autofill seed. */
  oldRange: RangeArea;

  /** Target range that will be previewed or committed. */
  newRange: RangeArea;

  /** Direction in which the target range expands from the source range. */
  direction: AutoFillDirection;

  /** Row dimension type for the active autofill operation. */
  rowType: DimensionRows;

  /** Column dimension type for the active autofill operation. */
  colType: DimensionCols;

  /** Plugin providers available to advanced strategy implementations. */
  providers: PluginProviders;

  /**
   * Cross-viewport autofill metadata when a plugin maps one visual gesture to
   * several viewport-scoped target ranges.
   */
  crossViewport?: {
    source: {
      rowType: DimensionRows;
      colType: DimensionCols;
      range: RangeArea;
    };
    targets: {
      rowType: DimensionRows;
      colType: DimensionCols;
      range: RangeArea;
    }[];
  };
};
```

---

### `AutoFillStrategy`

Autofill strategy function.

**@param** selectedData Matrix of selected source values, ordered row-major.
 *
**@param** direction Direction in which the autofill drag expands.
 *
**@param** newRange Target range that should be generated.
 *
**@param** context Optional rich strategy context for advanced strategies.
 *
**@returns** Generated target matrix, or `null` when the strategy does not support
 * the selected values.
 *
 *
**Example:**
```typescript
* ```typescript
 * const copyStrategy: AutoFillStrategy = selectedData => selectedData;
 * AutoFillPlugin.registerStrategy(copyStrategy);
 * ```
```

```ts
/**
 * Autofill strategy function.
 *
 * @param selectedData Matrix of selected source values, ordered row-major.
 * @param direction Direction in which the autofill drag expands.
 * @param newRange Target range that should be generated.
 * @param context Optional rich strategy context for advanced strategies.
 * @returns Generated target matrix, or `null` when the strategy does not support
 * the selected values.
 *
 * @example
 * ```typescript
 * const copyStrategy: AutoFillStrategy = selectedData => selectedData;
 * AutoFillPlugin.registerStrategy(copyStrategy);
 * ```
 */
export type AutoFillStrategy = (
  selectedData: any[][],
  direction: AutoFillDirection,
  newRange: RangeArea,
  context?: AutoFillStrategyContext,
) => any[][] | null;
```

---

### `getMatrixSize`

Calculates the row and column count for a RevoGrid range.

**@param** range Range to measure.
 *
**@returns** Matrix size matching the inclusive range coordinates.

```ts
export function getMatrixSize(range: RangeArea): MatrixSize;
```

---

### `flattenMatrix`

Flattens a row-major matrix into a one-dimensional sequence.

**@param** data Matrix to flatten.
 *
**@returns** Row-major sequence of values.

```ts
export function flattenMatrix<T = unknown>(data: T[][]): T[];
```

---

### `createMatrix`

Creates a matrix for a target range.

**@param** range Target range that defines output dimensions.
 *
**@param** getValue Callback invoked for each cell position.
 *
**@returns** Generated matrix in row-major order.

```ts
export function createMatrix<T>(
  range: RangeArea,
  getValue: (position: number, rowIndex: number, colIndex: number) => T,
): T[][];
```

---

### `repeatMatrix`

Tiles source values across the target range while preserving source rows and
columns.

**@param** selectedData Source matrix to repeat.
 *
**@param** targetRange Target range that defines output dimensions.
 *
**@returns** Generated matrix containing repeated source values.

```ts
export function repeatMatrix<T>(selectedData: T[][], targetRange: RangeArea): T[][];
```

---

### `isNil`

Checks whether a value is `null` or `undefined`.

**@param** value Value to check.
 *
**@returns** `true` when the value is missing.

```ts
export function isNil(value: unknown): value is null | undefined;
```

---

### `isNumericValue`

Checks whether a value can be treated as a finite number.

**@param** value Value to check.
 *
**@returns** `true` for finite numbers and numeric strings.

```ts
export function isNumericValue(value: unknown): value is number | string;
```

---

### `parseTextNumber`

Parses the first integer segment inside a text value.

**@param** value Value to parse.
 *
**@returns** Prefix, numeric value, suffix, and zero-padding width, or `null`
 * when the value does not contain an integer segment.

```ts
export function parseTextNumber(value: unknown);
```

---

### `formatTextNumber`

Formats a text value with a numeric segment and preserved padding.

**@param** prefix Text before the number.
 *
**@param** value Number to format.
 *
**@param** suffix Text after the number.
 *
**@param** width Minimum digit width for zero padding.
 *
**@returns** Formatted text-number value.

```ts
export function formatTextNumber(prefix: string, value: number, suffix: string, width: number);
```

---

### `parseDateValue`

Parses a Date object or supported date string.

**@param** value Value to parse.
 *
**@returns** Parsed date and original format, or `null` for unsupported values.

```ts
export function parseDateValue(value: unknown): ParsedDateValue | null;
```

---

### `formatDateValue`

Formats a date using the preserved input format.

**@param** date Date to format.
 *
**@param** format Output format captured from the selected source value.
 *
**@returns** Date object copy or formatted date string.

```ts
export function formatDateValue(date: Date, format: ParsedDateValue['format']);
```

---

### `addUtcDays`

Adds a number of days using UTC date math.

**@param** date Source date.
 *
**@param** days Number of days to add.
 *
**@returns** New Date instance.

```ts
export function addUtcDays(date: Date, days: number);
```

---

### `addUtcMonths`

Adds a number of months using UTC date math.

**@param** date Source date.
 *
**@param** months Number of months to add.
 *
**@returns** New Date instance.

```ts
export function addUtcMonths(date: Date, months: number);
```

---

### `monthDiff`

Calculates whole-month distance between two UTC dates.

**@param** a Start date.
 *
**@param** b End date.
 *
**@returns** Number of calendar months from `a` to `b`.

```ts
export function monthDiff(a: Date, b: Date);
```

---

### `parseTimeValue`

Parses a supported clock-time string.

**@param** value Value to parse.
 *
**@returns** Parsed seconds and original format, or `null` for unsupported values.

```ts
export function parseTimeValue(value: unknown): ParsedTimeValue | null;
```

---

### `formatTimeValue`

Formats seconds since midnight as a clock-time string.

**@param** totalSeconds Seconds since midnight. Values wrap around 24 hours.
 *
**@param** format Output format captured from the selected source value.
 *
**@returns** Formatted clock-time string.

```ts
export function formatTimeValue(totalSeconds: number, format: ParsedTimeValue['format']);
```

---

### `MatrixSize`

Size of a two-dimensional autofill matrix.

```ts
/**
 * Size of a two-dimensional autofill matrix.
 */
export type MatrixSize = {
  /** Number of rows in the target matrix. */
  rows: number;

  /** Number of columns in the target matrix. */
  cols: number;
};
```

---

### `ParsedDateValue`

Parsed date value with the visible input format needed for output.

```ts
/**
 * Parsed date value with the visible input format needed for output.
 */
export type ParsedDateValue = {
  /** Parsed date normalized to a Date object. */
  date: Date;

  /** Original visible input format. */
  format: 'date-object' | 'yyyy-mm-dd' | 'yyyy/mm/dd' | 'mm/dd/yyyy';
};
```

---

### `ParsedTimeValue`

Parsed clock-time value with the visible input format needed for output.

```ts
/**
 * Parsed clock-time value with the visible input format needed for output.
 */
export type ParsedTimeValue = {
  /** Seconds elapsed since midnight. */
  seconds: number;

  /** Original visible input format. */
  format: 'hh:mm' | 'hh:mm:ss';
};
```

---

### `linearNumericSequenceStrategy`

The `linearNumericSequenceStrategy` is an autofill strategy for RevoGrid's
AutoFillPlugin designed to generate numeric sequences with a constant interval.
This strategy is ideal for filling grid cells with linear numeric progressions.

 **Features**:
- Validates that all selected data elements are numeric, filtering out non-numeric
  sequences to prevent errors.
- Computes the common difference between numbers in the sequence to establish a
  consistent interval.
- Extends the numeric sequence across the specified range, maintaining the calculated
  interval throughout the grid.
- Supports dynamic autofill in both horizontal and vertical directions.

**Usage**:
- Import `linearNumericSequenceStrategy` and register it with the AutoFillPlugin
  for use in RevoGrid to enable linear numeric autofill functionality.

### Example
```typescript
import { linearNumericSequenceStrategy } from '@revolist/revogrid-pro'

const grid = document.createElement('revo-grid');
grid.plugins = [AutoFillPlugin];
AutoFillPlugin.registerStrategy(linearNumericSequenceStrategy); // Register strategy
```

This strategy is particularly suited for applications requiring predictable numeric
data entry, such as financial models, inventory lists, or any scenario where
arithmetic progression is needed.

```ts
linearNumericSequenceStrategy: AutoFillStrategy;
```

---

### `dateSequenceStrategy`

The `dateSequenceStrategy` is an autofill strategy designed for RevoGrid's
AutoFillPlugin, which facilitates the automatic generation of consistent date
sequences within grid cells. This strategy is used to extend a selected range
of date values either as Date objects or ISO date strings.

 **Features**:
- Validates that all selected data elements are either Date objects or valid
  ISO date strings, ensuring consistency in input types.
- Computes the common difference between consecutive dates to determine the
  sequence's interval.
- Generates a new date sequence extending the original, maintaining the identified
  interval across the target range specified.
- Supports output as either Date objects or 'YYYY-MM-DD' formatted strings,
  depending on the input type.

**Usage**:
- Import `dateSequenceStrategy` and register it with the AutoFillPlugin for use
  in RevoGrid to enable date autofill functionality.

### Example
```typescript
import { dateSequenceStrategy } from '@revolist/revogrid-pro'

const grid = document.createElement('revo-grid');
grid.plugins = [AutoFillPlugin];
AutoFillPlugin.registerStrategy(dateSequenceStrategy); // Register date sequence strategy
```

This strategy is ideal for applications dealing with chronological data entry,
where users benefit from automatic date progression, such as scheduling tools
or timeline management systems.

```ts
dateSequenceStrategy: AutoFillStrategy;
```

---

### `dateSequenceWithIntervalStrategy`

The `dateSequenceWithIntervalStrategy` is an advanced autofill strategy for
RevoGrid's AutoFillPlugin that facilitates filling grids with date sequences
that maintain a consistent interval. It extends upon basic date sequence
strategies by using a defined interval between consecutive dates.

 **Features**:
- Validates that input data consists of either Date objects or ISO date strings.
- Ensures consistency in date intervals across the sequence, filtering out
  inconsistent sequences.
- Generates a date sequence extending beyond the initial selection, maintaining
  the calculated interval throughout the target range.
- Supports output in both Date objects and 'YYYY-MM-DD' strings, based on input type.

**Usage**:
- Import `dateSequenceWithIntervalStrategy` and register it with the AutoFillPlugin
  to enable interval-based date autofill in RevoGrid.

### Example
```typescript
import { dateSequenceWithIntervalStrategy } from '@revolist/revogrid-pro'

const grid = document.createElement('revo-grid');
grid.plugins = [AutoFillPlugin];
AutoFillPlugin.registerStrategy(dateSequenceWithIntervalStrategy); // Register strategy
```

This strategy is particularly useful for applications that require consistent
scheduling or timeline management, where maintaining a regular interval between
dates is essential for data accuracy and usability.

```ts
dateSequenceWithIntervalStrategy: AutoFillStrategy;
```

---

### `textSequenceStrategy`

```ts
textSequenceStrategy: AutoFillStrategy;
```

---

### `copyFallbackStrategy`

The `copyFallbackStrategy` is the final default autofill strategy for
RevoGrid's AutoFillPlugin. It repeats the selected source values when no
sequence-specific strategy can safely infer a smarter progression.

**Features**:
- Repeats the selected matrix in row-major order across the target range.
- Supports plain text, numbers, dates, booleans, objects, and mixed values.
- Avoids surprising inferred sequences for ambiguous input.
- Provides deterministic preview and final apply data for every non-empty
  selection.

**Usage**:
- Included by default as the last built-in strategy.
- Custom strategies registered through AutoFillPlugin are inserted before this
  fallback so they can override copy behavior.

### Example
```typescript
import { copyFallbackStrategy } from '@revolist/revogrid-pro';

AutoFillPlugin.registerStrategy(copyFallbackStrategy);
```

```ts
copyFallbackStrategy: AutoFillStrategy;
```

---

### `singleNumericStepStrategy`

The `singleNumericStepStrategy` is an autofill strategy for RevoGrid's
AutoFillPlugin that expands a single numeric source value into a simple
incrementing numeric sequence.

**Features**:
- Activates only when exactly one selected value is numeric.
- Uses a default step of `+1`.
- Supports numeric strings and number values.
- Falls through for mixed, empty, or multi-value selections so more specific
  strategies or the copy fallback can handle them.

**Usage**:
- Included by default before the copy fallback.
- Useful for spreadsheet-like fills such as `1` -> `1, 2, 3`.

### Example
```typescript
import { singleNumericStepStrategy } from '@revolist/revogrid-pro';

AutoFillPlugin.registerStrategy(singleNumericStepStrategy);
```

```ts
singleNumericStepStrategy: AutoFillStrategy;
```

---

### `textNumberSequenceStrategy`

The `textNumberSequenceStrategy` is an autofill strategy for RevoGrid's
AutoFillPlugin that continues strings containing an embedded number.

**Features**:
- Supports numeric suffixes, prefixes, and middle-number patterns.
- Preserves leading zero width, for example `INV-099` -> `INV-100`.
- Supports ordinal text such as `1st Floor`, `2nd Floor`, `3rd Floor`.
- Requires a consistent prefix/suffix shape and numeric interval.
- Falls through for ambiguous mixed text patterns.

**Usage**:
- Included by default before the legacy text suffix strategy.
- Use it for identifiers, labels, invoice numbers, and numbered locations.

### Example
```typescript
import { textNumberSequenceStrategy } from '@revolist/revogrid-pro';

AutoFillPlugin.registerStrategy(textNumberSequenceStrategy);
```

```ts
textNumberSequenceStrategy: AutoFillStrategy;
```

---

### `weekdayMonthNameStrategy`

The `weekdayMonthNameStrategy` is an autofill strategy for RevoGrid's
AutoFillPlugin that continues English weekday and month name sequences.

**Features**:
- Supports full names such as `Monday` and `January`.
- Supports three-letter names such as `Mon` and `Jan`.
- Preserves the selected full-name or short-name format.
- Wraps around calendar boundaries, for example `Sat, Sun` -> `Mon`.
- Falls through when weekday and month labels are mixed or ambiguous.

**Usage**:
- Included by default before generic text and copy strategies.
- Use it for spreadsheet-like calendar labels in planning grids.

### Example
```typescript
import { weekdayMonthNameStrategy } from '@revolist/revogrid-pro';

AutoFillPlugin.registerStrategy(weekdayMonthNameStrategy);
```

```ts
weekdayMonthNameStrategy: AutoFillStrategy;
```

---

### `dateUnitSequenceStrategy`

The `dateUnitSequenceStrategy` is an autofill strategy for RevoGrid's
AutoFillPlugin that continues date sequences using calendar-aware day and
month units.

**Features**:
- Supports Date objects and common date strings: `YYYY-MM-DD`, `YYYY/MM/DD`,
  and `MM/DD/YYYY`.
- Preserves the selected input format in generated values.
- Infers daily, weekly, monthly, quarterly, and yearly progressions through
  consistent day or month steps.
- Uses a one-day step for a single selected date.
- Falls through for invalid, mixed-format, or irregular date selections.

**Usage**:
- Included by default before legacy date strategies.
- Use it for scheduling, planning, and timeline grids where visible date
  formatting should remain stable.

### Example
```typescript
import { dateUnitSequenceStrategy } from '@revolist/revogrid-pro';

AutoFillPlugin.registerStrategy(dateUnitSequenceStrategy);
```

```ts
dateUnitSequenceStrategy: AutoFillStrategy;
```

---

### `timeSequenceStrategy`

The `timeSequenceStrategy` is an autofill strategy for RevoGrid's
AutoFillPlugin that continues clock-time strings.

**Features**:
- Supports `HH:mm` and `HH:mm:ss` formats.
- Preserves the selected time format in generated values.
- Infers a consistent interval from multiple selected times.
- Uses a one-hour step for a single selected time.
- Wraps around 24-hour boundaries.

**Usage**:
- Included by default before generic text and copy strategies.
- Use it for scheduling grids, time slots, and recurring interval data.

### Example
```typescript
import { timeSequenceStrategy } from '@revolist/revogrid-pro';

AutoFillPlugin.registerStrategy(timeSequenceStrategy);
```

```ts
timeSequenceStrategy: AutoFillStrategy;
```

---

### `booleanCycleStrategy`

The `booleanCycleStrategy` is an autofill strategy for RevoGrid's
AutoFillPlugin that repeats boolean-like toggle values.

**Features**:
- Supports boolean values: `true` and `false`.
- Supports common string pairs: `true/false`, `yes/no`, and `on/off`.
- Preserves the original selected values while repeating the selected cycle.
- Requires both string pair values to be present before string cycling.
- Falls through for single string values so plain copy fallback can handle them.

**Usage**:
- Included by default before the generic copy fallback.
- Use it for toggles, status columns, and simple alternating flags.

### Example
```typescript
import { booleanCycleStrategy } from '@revolist/revogrid-pro';

AutoFillPlugin.registerStrategy(booleanCycleStrategy);
```

```ts
booleanCycleStrategy: AutoFillStrategy;
```
