range

Lets the user take a block of cells, and copy, cut, paste or empty it.

Import	import { range } from '@dzgrid/dom/range';
Signature	range(o?: RangeOptions): RangeFeature
Texts	import { EN_RANGE } from '@dzgrid/dom/locales/en-range'; languages: en, fr, ar
Style sheet	import '@dzgrid/theme/range.css';
Declared in	packages/dom/src/range/index.ts

Options	Type
drag	boolean
canCopy	(c: CopyAsk) => boolean
guard	boolean
raw	boolean
maxPaste	number
clearOnOutside	boolean

What it does

range() adds blocks of cells. Shift+arrows grow a block from the focused cell, a drag of the mouse or a pen draws one, Shift+click stretches it, Ctrl+A takes every cell shown and Shift+Space the focused row. The block is tinted, and its size is said to a screen reader after a pause. It is dropped, and that is said once, when the sort or the rows shown change.

Ctrl+C copies the block as tab-separated text that spreadsheets read (numbers in the locale’s form, formula starts guarded), with an HTML table beside it. Ctrl+X cuts, Ctrl+V pastes into editable cells, Delete empties them: these three need edit, and a paste or a cut is one save request and one undo. The rangeCopied event tells how many cells were copied.

api(grid) gives the block to your code: get(), set(range), clear(), box(), copy(), cut(), paste(text), erase(). A block over rows not loaded yet (a server’s) is refused with a rows-not-loaded warning; a maxPaste that is not a whole number is replaced by the default, with an invalid-setting warning.

Options

• drag: a press and a drag of the mouse or a pen makes a block. Default true; false leaves the keys, Shift+click and the API.
• canCopy(ask): may refuse a copy or a cut. It sees the block’s column ids and its counts, never the values; false or a throw refuses.
• guard: the formula guard on copy, so a spreadsheet does not run a copied text. Default true.
• raw: numbers copied with a point whatever the locale. Default false.
• maxPaste: above this many cells a paste writes nothing. Default 100 000.
• clearOnOutside: a press outside the grid clears the block, and says so — not inside an element marked data-dzg-keep-range, nor on the page’s scrollbar. Default true; with false the block stays (Escape clears it).

Example

import { createGrid } from '@dzgrid/dom';
import { range } from '@dzgrid/dom/range';
import { EN } from '@dzgrid/dom/locales/en';
import { EN_RANGE } from '@dzgrid/dom/locales/en-range';

type Book = { id: string; title: string; pages: number };

const blocks = range({ maxPaste: 5000, canCopy: (ask) => ask.cells <= 1000 });

const grid = createGrid<Book>(document.getElementById('books')!, {
  rows: [{ id: 'b1', title: 'The salt road', pages: 212 }, { id: 'b2', title: 'Owls at noon', pages: 96 }],
  columns: [
    { id: 'title', header: 'Title' },
    { id: 'pages', header: 'Pages', type: 'number' },
  ],
  getRowId: (b) => b.id,
  messages: { ...EN, text: { ...EN.text, ...EN_RANGE.text } },
  features: [blocks],
  onEvent: (e) => {
    if (e.type === 'rangeCopied') console.log(e.cells);
  },
});

console.log(blocks.api(grid)?.copy({ headers: true })?.text);

Live demo

Shift+arrows or a drag take a block; Ctrl+C copies it; a press outside the grid clears it.

See also

• fill: the handle at the block’s corner, and Ctrl+D / Ctrl+R.
• statusBar: the block’s count, sum and mean under the rows.
• Selection and ranges: rows and blocks, side by side.