Grid-Sight

A lightweight library for enriching HTML tables with data visualization and analysis tools. The published IIFE bundle ships standalone — it works offline (file:// and air-gapped servers) and reaches the page with no network requests at runtime.

Two npm packages are pulled in at build time only: simple-statistics (used by the heatmap / outlier paths) and shepherd.js (used by the onboarding tour). Both are tree-shaken into the IIFE; the published artefact requires nothing from the network.

Features

• Automatic table detection on web pages
• Heatmap visualization for numeric data
• Z-score outlier detection
• Per-table configuration
• Dynamic sliders with linear / bilinear interpolation, cross-table sync, and URL-fragment persistence (see specs/001-dynamic-sliders/)
• Heatmap position marker + threshold slider
• Row sort (three-state asc / desc / off) and row filter (numeric range + categorical inclusion), with multi-column AND composition, a clear-all chip, and shareable URL state (see specs/002-003-row-visibility/)
• Virtual columns: cumulative running-sum (Σ), inline sparkline trend (⌇), and pairwise column compare (Δ), with shareable URL state (see specs/012-virtual-columns/)
• Self-contained IIFE bundle — no network requests at runtime
• Accessibility-focused design
• Works with or without a build system

Installation

Via CDN (Recommended for simple use cases)

<script src="https://cdn.jsdelivr.net/npm/@deepbluec/grid-sight/dist/grid-sight.iife.js"></script>

Via npm/yarn

# Using npm
npm install @deepbluec/grid-sight

# Or using yarn
yarn add @deepbluec/grid-sight

Manual Installation

1. Download the latest release from the releases page
2. Include the script in your HTML:

<script src="path/to/grid-sight.iife.js"></script>

Usage

Basic Usage

Include the script and let Grid-Sight automatically process all valid tables on the page:

<!-- Your HTML -->
<table id="my-table">
  <!-- Table content -->
</table>

<!-- Include Grid-Sight -->
<script src="path/to/grid-sight.iife.js"></script>

Programmatic Usage

// Process a specific table
const table = document.getElementById('my-table');
window.gridSight.processTable(table);

// Process all tables on the page
window.gridSight.init();

Demo

A demo is included in the public/demo directory. You can view it by:

1. Cloning the repository
2. Running yarn install and yarn build
3. Opening dist/demo/index.html in your browser

Or by using the development server:

yarn dev

Then navigate to http://localhost:5173/demo/

Building from Source

Prerequisites

• Node.js 16+ (LTS recommended)
• Yarn 1.22+ or npm 8+

Build Commands

# Install dependencies
yarn install

# Build the library
yarn build

# Start development server
yarn dev

# Run tests
yarn test

# Run end-to-end tests
yarn test:e2e

# Build and preview production build
yarn build
yarn preview

API Reference

window.gridSight.init()

Scans the document for tables and processes all valid ones.

window.gridSight.processTable(table: HTMLTableElement, options?: object): HTMLTableElement

Processes a single table.

Parameters:

• table: The HTML table element to process
• options: Optional configuration object
  • id: Custom ID for the table (auto-generated if not provided)
  • applyStyles: Whether to apply default styles (default: true)
  • onComplete: Callback function when processing is complete

Returns: The processed table element

window.gridSight.isValidTable(table: HTMLTableElement): boolean

Checks if a table is valid for processing.

Parameters:

• table: The HTML table element to validate

Returns: true if the table is valid, false otherwise

Browser Support

Grid-Sight works in all modern browsers, including:

• Chrome (latest 2 versions)
• Firefox (latest 2 versions)
• Safari (latest 2 versions)
• Edge (latest 2 versions)

Contributing

Contributions are welcome! Please read our Contributing Guidelines for details.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Grid-Sight will automatically detect and enhance tables on your page.

License

MIT