# Range Selection Limit
URL: https://pro.rv-grid.com/api/range-selection-limit/
Source: src/content/docs/api/range-selection-limit.md
## Module Extensions

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

```ts
interface HTMLRevoGridElement {
  /**
       * Direct range selection limit configuration.
       */
      rangeSelectionLimit?: RangeSelectionLimitConfig
}
```

---

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

```ts
interface AdditionalData {
  /**
       * Additional data property for range selection limiting.
       * @deprecated Use `grid.rangeSelectionLimit` instead.
       */
      rangeSelectionLimit?: RangeSelectionLimitConfig
}
```

## Plugin API

### `RangeSelectionLimitPlugin`

Constrains interactive range selection to a single row or column.

The plugin intercepts `beforeapplyrange`, normalizes the pending range, and
lets the regular RevoGrid `setrange` flow continue. It does not change data,
create a render layer, or block single-cell focus.

### Example
```ts
import { RangeSelectionLimitPlugin } from '@revolist/revogrid-pro';

const grid = document.createElement('revo-grid');
grid.range = true;
grid.plugins = [RangeSelectionLimitPlugin];
grid.rangeSelectionLimit = { mode: 'column' };
```

### Row-only selection
```ts
grid.rangeSelectionLimit = { mode: 'row' };
```

### Boolean shorthand
```ts
grid.rangeSelectionLimit = true; // same as { mode: 'column' }
grid.rangeSelectionLimit = false; // disabled
```

#### Dependencies

- **Config integration** `additionalData.rangeSelectionLimit`: Reads legacy range selection limit configuration from additionalData.rangeSelectionLimit.

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

---

### `limitRangeSelection`

Normalizes a pending RevoGrid range to match the configured range limit mode.

`column` mode pins `x` and `x1` to the focused column so the range can only
expand vertically. `row` mode pins `y` and `y1` to the focused row so the
range can only expand horizontally. Disabled config returns a cloned range.

**@param** range Pending range emitted by `beforeapplyrange`.
 *
**@param** focus Current focused cell used as the range anchor.
 *
**@param** config Normalized range selection limit configuration.
 *
**@returns** A range constrained to the configured mode.
 *
 *
**Example:**
```typescript
* ```ts
 * limitRangeSelection(
 *   { x: 0, y: 0, x1: 5, y1: 8 },
 *   { x: 2, y: 1 },
 *   { mode: 'column' },
 * );
 * // { x: 2, y: 0, x1: 2, y1: 8 }
 * ```
 *
 *
```
**Example:**
```typescript
* ```ts
 * limitRangeSelection(
 *   { x: 0, y: 0, x1: 5, y1: 8 },
 *   { x: 2, y: 1 },
 *   { mode: 'row' },
 * );
 * // { x: 0, y: 1, x1: 5, y1: 1 }
 * ```
```

```ts
export function limitRangeSelection(
  range: RangeArea,
  focus: Cell | null | undefined,
  config: NormalizedRangeSelectionLimitConfig,
): RangeArea;
```

---

### `normalizeRangeSelectionLimitConfig`

Converts public `rangeSelectionLimit` shorthand into the internal plugin shape.

**@param** config Public grid or `additionalData` configuration.
 *
**@returns** Normalized configuration with `mode: null` when disabled.
 *
 *
**Example:**
```typescript
* ```ts
 * normalizeRangeSelectionLimitConfig(true);
 * // { mode: 'column' }
 *
 * normalizeRangeSelectionLimitConfig('row');
 * // { mode: 'row' }
 * ```
```

```ts
export function normalizeRangeSelectionLimitConfig(
  config?: RangeSelectionLimitConfig,
): NormalizedRangeSelectionLimitConfig;
```

---

### `RangeSelectionLimitMode`

Built-in range selection limit modes.

**Example:**
```typescript
* ```ts
 * grid.rangeSelectionLimit = 'column';
 * grid.rangeSelectionLimit = 'row';
 * ```
```

```ts
/**
 * Built-in range selection limit modes.
 *
 * @example
 * ```ts
 * grid.rangeSelectionLimit = 'column';
 * grid.rangeSelectionLimit = 'row';
 * ```
 */
export type RangeSelectionLimitMode = 'column' | 'row';
```

---

### `RangeSelectionLimitOptions`

Object form for range selection limit configuration.

Use the object form when you want a stable extension point for future options,
such as validator-backed shapes.

**Example:**
```typescript
* ```ts
 * grid.rangeSelectionLimit = {
 *   mode: 'column',
 * };
 * ```
```

```ts
/**
 * Object form for range selection limit configuration.
 *
 * Use the object form when you want a stable extension point for future options,
 * such as validator-backed shapes.
 *
 * @example
 * ```ts
 * grid.rangeSelectionLimit = {
 *   mode: 'column',
 * };
 * ```
 */
export type RangeSelectionLimitOptions = {
  /**
   * Selection shape limit.
   * - `column` keeps the focused column fixed and allows row expansion.
   * - `row` keeps the focused row fixed and allows column expansion.
   */
  mode: RangeSelectionLimitMode;
};
```

---

### `RangeSelectionLimitConfig`

Public plugin configuration for `RangeSelectionLimitPlugin`.

Supported shorthand:
- `true` enables the default `column` mode.
- `false` disables the plugin behavior.
- `'column'` or `'row'` enables the matching built-in mode.

**Example:**
```typescript
* ```ts
 * import { RangeSelectionLimitPlugin } from '@revolist/revogrid-pro';
 *
 * grid.range = true;
 * grid.plugins = [RangeSelectionLimitPlugin];
 * grid.rangeSelectionLimit = { mode: 'row' };
 * ```
 *
 *
```
**Example:**
```typescript
* ```ts
 * grid.rangeSelectionLimit = true; // same as { mode: 'column' }
 * grid.rangeSelectionLimit = false; // disabled
 * ```
```

```ts
/**
 * Public plugin configuration for `RangeSelectionLimitPlugin`.
 *
 * Supported shorthand:
 * - `true` enables the default `column` mode.
 * - `false` disables the plugin behavior.
 * - `'column'` or `'row'` enables the matching built-in mode.
 *
 * @example
 * ```ts
 * import { RangeSelectionLimitPlugin } from '@revolist/revogrid-pro';
 *
 * grid.range = true;
 * grid.plugins = [RangeSelectionLimitPlugin];
 * grid.rangeSelectionLimit = { mode: 'row' };
 * ```
 *
 * @example
 * ```ts
 * grid.rangeSelectionLimit = true; // same as { mode: 'column' }
 * grid.rangeSelectionLimit = false; // disabled
 * ```
 */
export type RangeSelectionLimitConfig =
  | boolean
  | RangeSelectionLimitMode
  | RangeSelectionLimitOptions;
```

---

### `NormalizedRangeSelectionLimitConfig`

```ts
export type NormalizedRangeSelectionLimitConfig = {
  mode: RangeSelectionLimitMode | null;
};
```
