tessl/npm-tabulator-tables

Interactive table generation JavaScript library with sorting, filtering, editing, formatting, and extensive customization capabilities

—

Pending

Overview

Eval results

Files

Range Selection

Name: tessl/npm-tabulator-tables
Author: tessl

Advanced spreadsheet-like range selection functionality enabling users to select rectangular areas of cells, rows, or columns with keyboard and mouse interactions.

Capabilities

Range Management

Core functions for managing cell ranges and retrieving range data.

/**
 * Get data from all active ranges
 * @returns Array of data arrays for each range
 */
getRangesData(): any[][];

/**
 * Get all active range components
 * @returns Array of RangeComponent objects
 */
getRanges(): RangeComponent[];

/**
 * Add a new range selection
 * @param start - Starting cell, row, or column component
 * @param end - Ending cell, row, or column component (optional)
 * @returns RangeComponent representing the new range
 */
addRange(
  start: CellComponent | RowComponent | ColumnComponent, 
  end?: CellComponent | RowComponent | ColumnComponent
): RangeComponent;

Range Configuration:

interface RangeSelectionOptions {
  selectableRange?: boolean | number;
  selectableRangeColumns?: boolean;
  selectableRangeRows?: boolean;
  selectableRangeClearCells?: boolean;
  selectableRangeClearCellsValue?: any;
  selectableRangeAutoFocus?: boolean;
}

Component Range Access

Access range information from table components.

// Added to CellComponent by SelectRange module
/**
 * Get all ranges that include this cell
 * @returns Array of RangeComponent objects
 */
getRanges(): RangeComponent[];

// Added to RowComponent by SelectRange module  
/**
 * Get all ranges that include this row
 * @returns Array of RangeComponent objects
 */
getRanges(): RangeComponent[];

// Added to ColumnComponent by SelectRange module
/**
 * Get all ranges that include this column
 * @returns Array of RangeComponent objects
 */
getRanges(): RangeComponent[];

Usage Examples:

import { Tabulator } from "tabulator-tables";

// Enable range selection
const table = new Tabulator("#table", {
  data: [
    { id: 1, name: "Alice", age: 25, department: "Engineering", salary: 75000 },
    { id: 2, name: "Bob", age: 30, department: "Engineering", salary: 85000 },
    { id: 3, name: "Charlie", age: 28, department: "Sales", salary: 65000 },
    { id: 4, name: "Diana", age: 32, department: "Sales", salary: 70000 }
  ],
  columns: [
    { title: "ID", field: "id" },
    { title: "Name", field: "name" },
    { title: "Age", field: "age" },
    { title: "Department", field: "department" },
    { title: "Salary", field: "salary", formatter: "money" }
  ],
  selectableRange: 5, // Allow up to 5 simultaneous ranges
  selectableRangeColumns: true, // Enable column range selection
  selectableRangeRows: true, // Enable row range selection
  selectableRangeClearCells: true, // Allow clearing selected cells
  selectableRangeClearCellsValue: "", // Value to use when clearing
  selectableRangeAutoFocus: true // Auto-focus after range operations
});

// Programmatically create ranges
const startCell = table.getRow(0).getCell("name");
const endCell = table.getRow(2).getCell("age");
const range = table.addRange(startCell, endCell);

// Get range data
const rangesData = table.getRangesData();
console.log("Range data:", rangesData);

// Get all active ranges
const activeRanges = table.getRanges();
activeRanges.forEach((range, index) => {
  console.log(`Range ${index}:`, range.getData());
});

// Check which ranges include a specific cell
const cell = table.getRow(1).getCell("department");
const cellRanges = cell.getRanges();
console.log(`Cell is in ${cellRanges.length} ranges`);

RangeComponent Class

Component class representing a selected range with methods for data access and manipulation.

class RangeComponent {
  /**
   * Get the DOM element representing this range
   * @returns Range overlay element
   */
  getElement(): HTMLElement;
  
  /**
   * Get data from all cells in this range
   * @returns Array of arrays representing range data
   */
  getData(): any[][];
  
  /**
   * Get all cell components in this range
   * @returns Array of CellComponent objects
   */
  getCells(): CellComponent[];
  
  /**
   * Get cells organized by row and column structure
   * @returns Object with structured cell data
   */
  getStructuredCells(): { [row: number]: { [col: number]: CellComponent } };
  
  /**
   * Get all row components that intersect this range
   * @returns Array of RowComponent objects
   */
  getRows(): RowComponent[];
  
  /**
   * Get all column components that intersect this range
   * @returns Array of ColumnComponent objects
   */
  getColumns(): ColumnComponent[];
  
  /**
   * Get range boundary coordinates
   * @returns Object with start/end row/column indices
   */
  getBounds(): RangeBounds;
  
  /**
   * Get top edge row index
   * @returns Top row index
   */
  getTopEdge(): number;
  
  /**
   * Get bottom edge row index  
   * @returns Bottom row index
   */
  getBottomEdge(): number;
  
  /**
   * Get left edge column index
   * @returns Left column index
   */
  getLeftEdge(): number;
  
  /**
   * Get right edge column index
   * @returns Right column index
   */
  getRightEdge(): number;
  
  /**
   * Remove this range from selection
   */
  remove(): void;
}

Advanced Usage Examples:

// Multi-range selection
const table = new Tabulator("#table", {
  selectableRange: 3, // Allow up to 3 ranges
  selectableRangeColumns: true,
  selectableRangeRows: true
});

// Create multiple ranges programmatically
const range1 = table.addRange(
  table.getRow(0).getCell("name"),
  table.getRow(2).getCell("age")
);

const range2 = table.addRange(
  table.getRow(3).getCell("department"),
  table.getRow(4).getCell("salary")
);

// Analyze range contents
const ranges = table.getRanges();
ranges.forEach((range, index) => {
  const bounds = range.getBounds();
  const data = range.getData();
  const cells = range.getCells();
  
  console.log(`Range ${index + 1}:`);
  console.log(`  Bounds: rows ${bounds.start.row}-${bounds.end.row}, cols ${bounds.start.col}-${bounds.end.col}`);
  console.log(`  Contains ${cells.length} cells`);
  console.log(`  Data:`, data);
  
  // Get unique columns in range
  const columns = range.getColumns();
  console.log(`  Spans ${columns.length} columns:`, columns.map(col => col.getField()));
  
  // Get rows in range
  const rows = range.getRows();
  console.log(`  Spans ${rows.length} rows`);
});

// Work with structured cell data
const structuredCells = range1.getStructuredCells();
Object.keys(structuredCells).forEach(rowIndex => {
  Object.keys(structuredCells[rowIndex]).forEach(colIndex => {
    const cell = structuredCells[rowIndex][colIndex];
    console.log(`Cell [${rowIndex},${colIndex}]: ${cell.getValue()}`);
  });
});

Range Selection Modes

Configure different selection behaviors for various use cases.

Cell Range Selection:

const table = new Tabulator("#table", {
  selectableRange: true, // Enable basic cell range selection
  selectableRangeColumns: false,
  selectableRangeRows: false
});

Column Range Selection:

const table = new Tabulator("#table", {
  selectableRange: true,
  selectableRangeColumns: true, // Enable column selection
  selectableRangeRows: false
});

Row Range Selection:

const table = new Tabulator("#table", {
  selectableRange: true,  
  selectableRangeColumns: false,
  selectableRangeRows: true // Enable row selection
});

**Mixed Range Selection:**
```javascript
const table = new Tabulator("#table", {
  selectableRange: 10, // Allow up to 10 ranges
  selectableRangeColumns: true, // Enable all selection types
  selectableRangeRows: true
});

Keyboard Interactions

Range selection supports standard spreadsheet keyboard shortcuts:

Arrow Keys: Move active cell within table
Shift + Arrow Keys: Extend selection range
Ctrl/Cmd + A: Select all cells
Ctrl/Cmd + Click: Add new range to selection
Delete: Clear contents of selected cells (if enabled)
Escape: Clear all selections

Clear Cell Functionality

Configure cell clearing behavior within selected ranges.

const table = new Tabulator("#table", {
  selectableRange: true,
  selectableRangeClearCells: true, // Enable cell clearing
  selectableRangeClearCellsValue: null, // Value to use when clearing
  // ... other options
});

// Programmatically clear selected ranges
document.getElementById("clear-btn").addEventListener("click", () => {
  const ranges = table.getRanges();
  ranges.forEach(range => {
    const cells = range.getCells();
    cells.forEach(cell => {
      cell.setValue(""); // Clear each cell
    });
  });
});

Events

Range selection provides events for tracking selection changes.

// Range selection events
table.on("rangeAdded", function(range) {
  console.log("Range added:", range.getData());
});

table.on("rangeRemoved", function(range) {
  console.log("Range removed");
});

table.on("rangeChanged", function(ranges) {
  console.log(`Selection changed: ${ranges.length} ranges active`);
});

Integration with Other Features

Range selection integrates with other Tabulator features:

// Copy/paste with clipboard module
table.on("rangeAdded", function(range) {
  // Enable custom copy functionality
  document.addEventListener("keydown", function(e) {
    if ((e.ctrlKey || e.metaKey) && e.key === "c") {
      const data = range.getData();
      // Copy data to clipboard
      navigator.clipboard.writeText(JSON.stringify(data));
    }
  });
});

// Export selected ranges
document.getElementById("export-btn").addEventListener("click", () => {
  const ranges = table.getRanges();
  if (ranges.length > 0) {
    const rangeData = ranges[0].getData();
    table.download("csv", "selected-range.csv", {data: rangeData});
  }
});

Types

interface RangeBounds {
  start: {
    row: number;
    col: number;
  };
  end: {
    row: number;
    col: number;
  };
}

interface RangeSelectionOptions {
  selectableRange?: boolean | number;
  selectableRangeColumns?: boolean;
  selectableRangeRows?: boolean;
  selectableRangeClearCells?: boolean;
  selectableRangeClearCellsValue?: any;
  selectableRangeAutoFocus?: boolean;
}

Install with Tessl CLI