# Column Stretch
URL: https://pro.rv-grid.com/api/column-stretch/
Source: src/content/docs/api/column-stretch.md
## Module Extensions

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

```ts
interface HTMLRevoGridElement {
  /**
       * Direct column stretch configuration.
       */
      stretch?: StretchConfig
}
```

---

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

Additional data property for column stretch configuration

```ts
interface AdditionalData {
  /**
       *
       * Additional data property for column stretch configuration
       * @deprecated Use `grid.stretch` instead.
       * @example
       * grid.additionalData = {
       *   // Stretch all columns to utilize available space
       *   stretch: 'all',
       *   // Stretch the first column to utilize available space
       *   stretch: 1,
       *   // Stretch the last column to utilize available space
       *   stretch: 'last',
       *   // Stretch the last column and preserve column sizes when columns are replaced
       *   stretch: {
       *     mode: 'last',
       *     preserveSizesOnColumnChange: true,
       *   },
       * }
       */
      stretch?: StretchConfig
}
```

## Plugin API

### `ColumnStretchPlugin`

The ColumnStretchPlugin is a RevoGrid plugin designed to dynamically adjust column
widths based on available space within the grid. It ensures that extra space is
efficiently utilized by increasing the width of specified columns, enhancing the
presentation of data without manual resizing.

**Key Features**:
- Automatically stretches the width of columns to fill any remaining space in the grid.
- Supports configurations for stretching all columns, a specific column by index,
  or only the last column.
- Observes direct `grid.stretch` and legacy `additionalData.stretch` config
  updates, then adjusts column sizes based on grid dimensions or configuration changes.
- Utilizes `ResizeObserver` and a debounced `applyStretch` function to efficiently
  manage size recalculations during viewport size changes.

**Usage**:
- Integrate the plugin into a RevoGrid instance by adding it to the grid's plugin array.
- Configure the stretching behavior through direct `grid.stretch` or legacy
  `additionalData.stretch`, specifying modes like 'none', 'all', or a specific index.

### Example
```typescript
import { ColumnStretchPlugin } from './column-stretch';

const grid = document.createElement('revo-grid');
grid.plugins = [ColumnStretchPlugin];

grid.stretch = 'last'; // Stretch the last column to fit available space
```

By using this plugin, developers can enhance the adaptability and visual layout
of their RevoGrid, ensuring optimal use of grid space and improving data display
without manual intervention.

#### Dependencies

- **Config integration** `auto-size-column`: Skips columns marked with autoSize when applying stretch sizing.
- **Config integration** `additionalData.stretch`: Reads legacy stretch configuration from additionalData.stretch.

```ts
class ColumnStretchPlugin {}
```

---

### `StretchMode`

The `StretchConfig` type
specifies how extra space in the grid should be utilized by adjusting the width
of columns.

**Usage**:
- Import the `StretchConfig` type to define stretching behavior in RevoGrid components.
- Assign the desired stretching configuration to the grid's `additionalData.stretch`
  property to control how columns adjust to available space.

**Example:**
```typescript
:
 * ```typescript
 * import { ColumnStretchPlugin } from '@revolist/revogrid-pro';
 *
 * const grid = document.createElement('revo-grid');
 * grid.plugins = [ColumnStretchPlugin];
 *
 * grid.additionalData = {
 *   stretch: 'all', // Stretch all columns to utilize available space
 * };
 * ```
 *
 * This configuration type allows developers to customize how columns adapt to
 * changes in grid size, ensuring optimal data presentation and grid layout.
```

```ts
// column-stretch/stretch.types.ts

/**
 * The `StretchConfig` type
 * specifies how extra space in the grid should be utilized by adjusting the width
 * of columns.
 *
 * **Usage**:
 * - Import the `StretchConfig` type to define stretching behavior in RevoGrid components.
 * - Assign the desired stretching configuration to the grid's `additionalData.stretch`
 *   property to control how columns adjust to available space.
 *
 * @example:
 * ```typescript
 * import { ColumnStretchPlugin } from '@revolist/revogrid-pro';
 *
 * const grid = document.createElement('revo-grid');
 * grid.plugins = [ColumnStretchPlugin];
 *
 * grid.additionalData = {
 *   stretch: 'all', // Stretch all columns to utilize available space
 * };
 * ```
 *
 * This configuration type allows developers to customize how columns adapt to
 * changes in grid size, ensuring optimal data presentation and grid layout.
 */

export type StretchMode = 'none' | 'last' | 'all' | number;
```

---

### `StretchOptions`

```ts
export type StretchOptions = {
  /**
   * Stretch mode.
   */
  mode: StretchMode;
  /**
   * Preserve rendered column sizes for matching column props when columns are replaced.
   * Matching uses the column dimension type and `prop`, so reordered columns keep their
   * previous width while new columns use their configured/default width.
   */
  preserveSizesOnColumnChange?: boolean;
};
```

---

### `StretchConfig`

```ts
export type StretchConfig = false | StretchMode | StretchOptions;
```

---

### `ColumnStretchSizePreserve`

```ts
class ColumnStretchSizePreserve {
  snapshot();

  restore(columns: ColumnCollection['columns']);
}
```
