# ClipboardPlugin

> _Since v0.1.1_

Clipboard Plugin for tbw-grid

Brings familiar copy/cut/paste functionality with full keyboard shortcut support
(Ctrl+C, Ctrl+X, Ctrl+V). Handles single cells, multi-cell selections, and integrates
seamlessly with Excel and other spreadsheet applications via tab-delimited output.

> **Optional Dependency:** Works best with SelectionPlugin for copying/pasting selected
> cells. Without SelectionPlugin, copies the entire grid and pastes at row 0, column 0.

## Installation

```ts
import { ClipboardPlugin } from '@toolbox-web/grid/plugins/clipboard';
```

## Keyboard Shortcuts

| Shortcut | Action |
|----------|--------|
| `Ctrl+C` / `Cmd+C` | Copy selected cells |
| `Ctrl+V` / `Cmd+V` | Paste into selected cells |
| `Ctrl+X` / `Cmd+X` | Cut selected cells |

## Paste Behavior by Selection Type

| Selection Type | Paste Behavior |
|----------------|----------------|
| Single cell | Paste expands freely from that cell |
| Range selection | Paste is clipped to fit within the selected range |
| Row selection | Paste is clipped to the selected rows |
| No selection | Paste starts at row 0, column 0 |

## [Configuration Options](/grid/plugins/clipboard/interfaces/clipboardconfig.md)

| Option | Type | Description |
| ------ | ---- | ----------- |
| `includeHeaders?` | <code>boolean</code> | Include column headers in copied text (default: false) |
| `delimiter?` | <code>string</code> | Column delimiter character (default: '\\t' for tab) |
| `newline?` | <code>string</code> | Row delimiter/newline character (default: '\\n') |
| `quoteStrings?` | <code>boolean</code> | Wrap string values with quotes (default: false) |
| `processCell?` | <code>(value: unknown, field: string, row: unknown) =&gt; string</code> | Custom cell value processor for copy operations |
| `pasteHandler?` | <code><a href="/grid/plugins/clipboard/types/pastehandler/">PasteHandler</a> &#124; unknown</code> | Custom paste handler. By default, the plugin applies pasted data to `grid.rows` starting at the target cell. |

## Examples

### Basic Usage with Excel Compatibility

```ts
import '@toolbox-web/grid';
import { ClipboardPlugin } from '@toolbox-web/grid/plugins/clipboard';
import { SelectionPlugin } from '@toolbox-web/grid/plugins/selection';

grid.gridConfig = {
  columns: [
    { field: 'name', header: 'Name' },
    { field: 'email', header: 'Email' },
  ],
  plugins: [
    new SelectionPlugin({ mode: 'range' }),
    new ClipboardPlugin({
      includeHeaders: true,
      delimiter: '\t', // Tab for Excel
    }),
  ],
};
```

### Custom Paste Handler

```ts
new ClipboardPlugin({
  pasteHandler: (grid, target, data) => {
    // Validate or transform data before applying
    console.log('Pasting', data.length, 'rows');
    return defaultPasteHandler(grid, target, data);
  },
})
```

## See Also

- [`ClipboardConfig`](/grid/plugins/clipboard/interfaces/clipboardconfig.md) for all configuration options
- SelectionPlugin for enhanced copy/paste with selection

> **Extends** [BaseGridPlugin](/docs/grid-api-plugin-development-classes-basegridplugin--docs)
>
> Inherited methods like `attach()`, `detach()`, `afterRender()`, etc. are documented in the base class.

## Methods

### getSelectionAsText()

Get the text representation of the current selection (or specified data)
without writing to the system clipboard.

Useful for previewing what would be copied, or for feeding the text into
a custom UI (e.g., a "copy with column picker" dialog).

```ts
getSelectionAsText(options: CopyOptions): string
```

#### Parameters

| Name | Type | Description |
| ---- | ---- | ----------- |
| `options` | <code><a href="/grid/plugins/clipboard/interfaces/copyoptions/">CopyOptions</a></code> | Control which columns/rows to include |

#### Returns

`string` - Delimited text, or empty string if nothing to copy

#### Example

```ts
const clipboard = grid.getPluginByName('clipboard');
const text = clipboard.getSelectionAsText({
  columns: ['name', 'email'],
  includeHeaders: true,
});
console.log(text);
// "Name\tEmail\nAlice\talice@example.com\n..."
```

***

### copy()

Copy data to the system clipboard.

Without options, copies the current selection (or entire grid if no selection).
With options, copies exactly the specified columns and/or rows — ideal for
"copy with column picker" workflows where the user selects rows first,
then chooses which columns to include via a dialog.

```ts
copy(options: CopyOptions): Promise<string>
```

#### Parameters

| Name | Type | Description |
| ---- | ---- | ----------- |
| `options` | <code><a href="/grid/plugins/clipboard/interfaces/copyoptions/">CopyOptions</a></code> | Control which columns/rows to include |

#### Returns

`Promise<string>` - The copied text

#### Example

```ts
const clipboard = grid.getPluginByName('clipboard');
await clipboard.copy();
```

***

### copyRows()

Copy specific rows by index to clipboard.

Convenience wrapper around copy for row-based workflows.
Supports non-contiguous row indices (e.g., `[0, 3, 7]`).

```ts
copyRows(indices: number[], options: Omit<CopyOptions, "rowIndices">): Promise<string>
```

#### Parameters

| Name | Type | Description |
| ---- | ---- | ----------- |
| `indices` | <code>number[]</code> | Array of row indices to copy |
| `options` | <code>Omit&lt;<a href="/grid/plugins/clipboard/interfaces/copyoptions/">CopyOptions</a>, rowIndices&gt;</code> | Additional copy options (columns, headers, etc.) |

#### Returns

`Promise<string>` - The copied text

#### Example

```ts
const clipboard = grid.getPluginByName('clipboard');
// Copy only rows 0 and 5, including just name and email columns
await clipboard.copyRows([0, 5], { columns: ['name', 'email'] });
```

***

### paste()

Read and parse clipboard content.

```ts
paste(): Promise<string[][] | null>
```

#### Returns

`Promise<string[][] | null>` - Parsed 2D array of cell values, or null if clipboard is empty

***

### getLastCopied()

Get the last copied text and timestamp.

```ts
getLastCopied(): object | null
```

#### Returns

`object | null` - The last copied info or null

***