Oatear Longtable

A feature-rich spreadsheet component built for Angular

Live Demo / Documentation

Longtable is a feature-rich, standalone spreadsheet component built for modern, zoneless Angular applications. It provides a powerful and familiar spreadsheet experience with a simple and declarative API.

This library was designed to be highly interactive and performant, leveraging Angular signals for state management.

---

Features

• Rich Data Editing: Double-click or type to edit cells.
• Data Types: Support for text, numeric, checkbox, and dropdown cells.
• Multi-Select: Click and drag to select ranges of cells.
• Copy & Paste: Seamlessly copy/paste data to and from external applications like Excel or Google Sheets.
• Drag-to-Fill: Easily fill data down or across a range.
• Column Operations: Resize, reorder, and configure columns.
• Row Operations: Insert and delete single or multiple rows.
• Undo/Redo: Full history tracking for data changes.
• Sorting & Filtering: Built-in UI for sorting and filtering columns.
• Context Menu: Intuitive right-click menu for common actions.
• Data Analysis: An integrated statistics modal for data distribution and correlation analysis.
• Theming: Includes light and dark mode support.

Installation

Since this library is not yet published to the npm registry, you must build it locally and install it as a file dependency.

Method 1: Install via Tarball (Recommended)

This method "packages" the library with your project, ensuring stability.

1. Clone and Build:

   git clone https://github.com/oatear/longtable.git
   cd longtable
   npm install
   npm run build:lib

2. Create Package:

   cd dist/longtable
   npm pack

   This creates a file like oatear-longtable-1.0.0.tgz.

3. Install in Your Project: Move the .tgz file to your project (e.g., into a libs/ folder) and install it:

   npm install ./libs/oatear-longtable-1.0.0.tgz

Method 2: Install via Local Path

Useful if you want to keep the library source separate on your machine.

npm install /path/to/longtable/dist/longtable

Method 3: npm link (Active Development)

Use this if you are actively modifying the library and want changes to reflect immediately in your app.

1. Link Library:

   cd dist/longtable
   npm link

2. Link in App:

   cd my-app
   npm link oatear-longtable

Setup

After installing the library, you need to configure your project to support the library's styling and icons.

Import Styles

Add the prebuilt styles to your global stylesheet (e.g., src/styles.css or src/styles.scss):

@import 'oatear-longtable/longtable-styles.css';

Alternatively, include it directly in your angular.json build configuration under the styles array:

"styles": [
  "src/styles.css",
  "node_modules/oatear-longtable/longtable-styles.css"
]

Basic Usage

To use the Longtable spreadsheet, you need to provide two main inputs: data and columnConfig, both as Angular WritableSignals. You can also listen for changes using the onDataChange and onColumnChange outputs.

app.component.ts

import { Component, signal, WritableSignal } from '@angular/core';
import { CommonModule } from '@angular/common';
import { SpreadsheetComponent, Cell, ColumnConfig } from './longtable';

@Component({
  selector: 'app-root',
  standalone: true,
  imports: [CommonModule, SpreadsheetComponent],
  template: `
    <main class="p-4">
      <h1 class="text-2xl font-bold mb-4">My Longtable Spreadsheet</h1>
      <long-spreadsheet 
        [data]="initialData" 
        [columnConfig]="columnConfig"
        (onDataChange)="onDataChanged($event)"
        (onColumnChange)="onColumnConfigChanged($event)">
      </long-spreadsheet>
    </main>
  `,
})
export class AppComponent {

  // The core data for the spreadsheet grid. Does not include headers.
  initialData: WritableSignal<Cell[][]> = signal([
    [{ value: 'Jane Doe' }, { value: 'Developer' }, { value: true }],
    [{ value: 'John Smith' }, { value: 'Designer' }, { value: false }],
  ]);

  // Configuration for each column, including header names.
  columnConfig: WritableSignal<ColumnConfig[]> = signal([
    { name: 'Name', field: 'name', width: 200 },
    { name: 'Role', field: 'role', width: 150 },
    { name: 'Active', field: 'active', width: 80, editor: 'checkbox' },
  ]);

  onDataChanged(data: Cell[][]) {
    console.log('Spreadsheet data has changed:', data);
  }

  onColumnConfigChanged(config: ColumnConfig[]) {
    console.log('Column configuration has changed:', config);
  }
}

API

Inputs

Input	Type	Description
data	WritableSignal<Cell[][]>	Required. The 2D array of Cell objects that represents the spreadsheet grid's data rows.
columnConfig	WritableSignal<ColumnConfig[]>	Required. An array of configuration objects, one for each column, controlling properties like headers, width, and cell editors.
height	string | number	Optional. Sets the height of the spreadsheet container. Supports 'auto' (height of content), '100%'/'full' (fill parent), or specific pixel values (number or string like '500px'). Defaults to '60vh'.

Outputs

Output	Payload Type	Description
onDataChange	Cell[][]	Emits the entire data grid whenever a change to the data occurs.
onColumnChange	ColumnConfig[]	Emits the entire column configuration whenever it is changed.

Data Models

Cell Interface

The Cell object defines the content and behavior of a single cell.

interface Cell {
  value: string | number | boolean;
  readOnly?: boolean;
}

ColumnConfig Interface

The ColumnConfig object defines metadata for an entire column.

interface ColumnConfig {
  name: string;
  field: string;
  readOnly?: boolean;
  width?: number | 'auto';
  description?: string;
  editor?: 'text' | 'dropdown' | 'checkbox' | 'numeric';
  options?: (string | DropdownOption)[];
  lockSettings?: boolean;
}

interface DropdownOption {
  value: string;
  color: string; // Hex color string
}

Development

This project involves two main parts:

• longtable: The Angular library.
• docs: The demonstration and documentation application.

Library

To build the library:

npm run build:lib

Artifacts will be generated in dist/longtable.

Documentation / Demo

To run the documentation site locally:

npm run start

This serves the application at http://localhost:4200/.

To build the documentation site:

npm run build:demo

Artifacts will be generated in dist/docs.

Releasing

To publish a new release using the automated GitHub Actions workflow:

1. Update the version number in longtable/package.json and commit the change.
2. Create and push a new git tag that matches your version (starting with v, e.g., v1.0.0):

   git tag v1.0.0
   git push origin v1.0.0

The "Release Library" GitHub Actions workflow will automatically trigger. It will check out the codebase, build the library, and create a new GitHub release containing the oatear-longtable-1.0.0.tgz asset.

Alternatively, you can manually trigger the "Release Library" workflow from the Actions tab in GitHub.