@koeroesi86/canvas-grid 1.0.15 → 26.11.1

package/README.md

@@ -1,3 +1,241 @@
 # Canvas Grid
 
 [![CI](https://github.com/Koeroesi86/canvas-grid/actions/workflows/ci.yml/badge.svg)](https://github.com/Koeroesi86/canvas-grid/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/@koeroesi86/canvas-grid)](https://www.npmjs.com/package/@koeroesi86/canvas-grid)
+
+A fast data grid rendered on `<canvas>`, shipped as a framework-agnostic custom element (`<canvas-grid>`). It virtualises rows and columns, flashes cells when their values change, and is built for streams of frequent updates.
+
+- Plain web component: no framework required, works with React, Vue, Angular or vanilla JS
+- Written in TypeScript, types included
+- Optional AG Grid-style adapter (`agApi`) for `setRowData` / `updateRowData` / `setColumnDefs`
+
+## Install
+
+```sh
+npm install @koeroesi86/canvas-grid
+```
+
+Importing the package registers the `<canvas-grid>` element:
+
+```ts
+import '@koeroesi86/canvas-grid';
+```
+
+Or use the UMD build from a script tag (exposes `window.CanvasGrid`):
+
+```html
+<script src="https://unpkg.com/@koeroesi86/canvas-grid/build/web-component.js"></script>
+```
+
+## Usage
+
+The element draws into its own box, so give it a size:
+
+```html
+<style>
+  canvas-grid { display: block; width: 100%; height: 400px; }
+</style>
+<canvas-grid></canvas-grid>
+```
+
+```ts
+import '@koeroesi86/canvas-grid';
+
+const grid = document.querySelector('canvas-grid')!; // typed as CanvasGridComponent
+
+grid.font = '12px "Roboto", sans-serif';
+
+grid.setColumns([
+  'name',                                        // shorthand: id and header text
+  { id: 'price', displayName: 'Price', width: 80, valueFormatter: v => Number(v).toFixed(2) },
+]);
+
+grid.setValues([
+  { id: 1, name: 'Apple', price: 1.2 },
+  { id: 2, name: 'Pear', price: 0.9 },
+]);
+
+// later: update single rows (batched and throttled internally)
+grid.queueUpdate({ id: 2, price: 1.0 });
+```
+
+Before `setColumns` is called, the grid shows 50 numeric placeholder columns.
+
+## API
+
+### Data model
+
+| Concept | Shape |
+| --- | --- |
+| Row | `{ id: string \| number, [column: string]: unknown }`. `id` identifies the row (see `getRowId`) |
+| Column | `string \| number` (used as both id and header text), or an object (below) |
+
+Column object fields (`ColumnDefinition`):
+
+| Field | Default | Description |
+| --- | --- | --- |
+| `id` | required | Key of the row property shown in this column |
+| `displayName` | – | Header text. Not derived from `id` for object columns |
+| `width` | `100` | Column width in px |
+| `valueFormatter` | `String(value)` | Converts the raw value to the displayed string. Runs lazily, only for cells being drawn, and again only when the cell's value changes |
+| `renderers` | grid's `cellRenderers` | Renderers drawing a cell of this column, in order. Names of [registered renderers](#custom-renderers-and-layers) or renderer objects |
+| `headerRenderer` | `'header'` | Renderer drawing this column's header (name or object) |
+
+### Methods
+
+| Method | Description |
+| --- | --- |
+| `setColumns(columns)` | Replaces the column set |
+| `setValues(rows)` | Replaces all rows. Pending updates are discarded |
+| `queueUpdate(row)` | Adds or updates a row (merged by `id`); only the given columns change |
+| `queueRemove(row)` | Removes the row with the same `id` |
+| `transaction({ add, update, remove })` | Batch form of the above |
+| `getRowData(id)` | `{ id, index, height, values }` for a row (`index` is its displayed position, `values` the raw values by column id), or `undefined` |
+| `setSortModel(keys)` / `getSortModel()` | Orders the rows, see [Sorting](#sorting). An empty list restores the original order |
+| `forceDraw()` | Clears and redraws everything |
+| `registerRenderer(name, renderer)` | Makes a [renderer](#custom-renderers-and-layers) available to columns by name; an existing name is replaced |
+| `unregisterRenderer(name)` | Removes a registered renderer |
+| `addLayer(name, { alpha, before })` | Adds a canvas on top of the others (or below the layer named in `before`) |
+| `removeLayer(name)` / `getLayer(name)` | Removes / looks up a layer (`{ name, canvas, ctx }`) |
+
+Updates are throttled (50 ms) and changed cells flash for `flashInDuration + flashOutDuration`.
+
+### Properties
+
+| Property | Default | Description |
+| --- | --- | --- |
+| `font` | `'12px monospace'` | Cell font (CSS font shorthand) |
+| `headerFont` | `'13px monospace'` | Header font |
+| `getRowId` | `(row) => row.id` | Derives the row id; assign your own to key rows differently |
+| `showHeaders` | `true` | Show the header row |
+| `showRowNumbers` | `true` | Show the row-number column |
+| `rowNumbersWidth` | `30` | Width of the row-number column |
+| `headerHeight` | `30` | Header row height |
+| `cellHeight` | `20` | Row height. Set it before `setValues`, it applies to rows as they are created |
+| `fps` | `30` | Maximum redraw rate |
+| `cellRenderers` | `['background', 'value']` | Renderers used by columns without their own `renderers` |
+| `flashInDuration` | `200` | Fade-in of the update flash in ms |
+| `flashOutDuration` | `400` | Fade-out of the update flash in ms |
+
+### Sorting
+
+```js
+grid.setSortModel([
+  { columnId: 'price', direction: 'desc' },
+  { columnId: 'name' },
+]);
+```
+
+Keys apply in priority order; rows equal on every key keep their original order. By default numbers compare numerically, text with `Intl.Collator`, and empty values come last; a key can bring its own `compare(a, b)`. Row numbers follow the displayed order. The order is kept as rows are added or updated: new rows are placed by the model, and an update to a sorted column moves the row (re-sorting runs with the throttled updates, so it costs O(n log n) per batch). `setSortModel` works on raw values, so it does not depend on `valueFormatter`.
+
+### Custom renderers and layers
+
+The grid draws onto stacked canvases called layers: `background`, `content` and `header` out of the box. A renderer draws into one layer and is registered under a name; columns select renderers by name. The built-in ones are `'background'` (fill, borders and the update flash), `'value'` (the text) and `'header'`.
+
+```ts
+grid.addLayer('badges'); // on top of the existing layers
+
+grid.registerRenderer('badge', {
+  layer: 'badges',
+  draw({ ctx, x, y, width, formatted }) {
+    ctx.fillStyle = formatted === 'sold out' ? '#c33' : '#3a3';
+    ctx.fillRect(x + width - 8, y + 4, 4, 4);
+  },
+});
+
+grid.setColumns([
+  { id: 'status', renderers: ['background', 'value', 'badge'] },
+]);
+```
+
+A renderer is an object:
+
+| Member | Description |
+| --- | --- |
+| `layer` | Name of the layer its `ctx` belongs to |
+| `draw(cell)` | Draws one cell, header or row number |
+| `isAnimating?(cell)` | Return `true` while the cell is animating. Cells are only redrawn when something changed (value, scroll, resize) or while a renderer reports animation, plus once after it stops |
+| `clearCache?()` | Called when web fonts finish loading |
+
+`cell` (`CellContext`) is one object reused for every cell, so read what you need while drawing and do not keep a reference to it:
+
+| Field | Description |
+| --- | --- |
+| `ctx` | Context of the renderer's layer |
+| `x`, `y`, `width`, `height` | Cell rectangle in canvas pixels |
+| `row`, `column` | `{ id, index }` of the row and the column header; `row` is undefined for headers, `column` for row numbers |
+| `value`, `formatted` | Raw value and the string after the column's `valueFormatter` |
+| `updatedAt`, `age` | When the value last changed, and ms since then (`Infinity` if it never did) |
+| `now`, `dt` | Frame timestamp and ms since the previous draw (the grid only draws when something changed, so this can be long) |
+| `valueChanged` | The formatted value differs from what was drawn last time |
+| `forced` | Everything is being redrawn (first draw, resize, scrolling) |
+| `isScrolling` | The grid is being scrolled |
+| `state` | Object that persists per cell between frames, for your own bookkeeping. Kept for the 2048 most recently drawn rows, so it resets for a row that was scrolled far away |
+
+A renderer that animates, for example a pulse that lasts one second after a change:
+
+```ts
+grid.registerRenderer('pulse', {
+  layer: 'badges',
+  isAnimating: ({ age }) => age < 1000,
+  draw({ ctx, x, y, width, height, age }) {
+    ctx.clearRect(x, y, width, height);
+    if (age >= 1000) return;
+    ctx.globalAlpha = 1 - age / 1000;
+    ctx.fillStyle = '#39f';
+    ctx.fillRect(x, y, width, height);
+    ctx.globalAlpha = 1;
+  },
+});
+```
+
+> `cellRenderer(value, x, y, ...)` and `headerRenderer(header, x)` with positional arguments were replaced by the renderer objects above.
+
+### AG Grid-style adapter
+
+`grid.agApi` mirrors a small part of AG Grid's API for easier migration:
+
+```ts
+grid.agApi.setColumnDefs(columns);
+grid.agApi.setRowData(rows);
+grid.agApi.updateRowData({ add: [], update: [], remove: [] });
+grid.agApi.getRowNodeId = row => row.key;
+```
+
+### TypeScript
+
+Types ship with the package. Besides the element class (default export) it exports `ColumnHeader`, `ColumnDefinition`, `Transaction`, `CellRenderer`, `CellContext`, `CellState`, `RendererRef`, `LayerOptions`, `SortKey` and `SortDirection`, and registers `canvas-grid` in `HTMLElementTagNameMap`, so `document.querySelector('canvas-grid')` is typed.
+
+> The declarations are single-format. Bundler-style resolution (`moduleResolution: "bundler"`) works; strict Node16 ESM resolution may report the types as CommonJS.
+
+## Browser support
+
+Modern evergreen browsers with Custom Elements v1 and Canvas 2D.
+
+## Development
+
+Requires Node.js 22.18+ (the Node-side scripts are TypeScript run through Node's native type stripping).
+
+```sh
+npm ci
+npm run dev          # Vite dev server with a random-data websocket source, http://localhost:3000
+npm run build        # type-check, then bundle (UMD + ESM) and emit declarations into build/
+npm test             # type-check, release-script tests and data store unit tests
+npm run bench        # data store benchmarks (BENCH_ROWS=1000,1000000 to change sizes)
+npm run bench:scroll # scroll FPS and frame-time p95 in headless Chromium (needs `npx playwright install chromium`)
+npm run serve-local  # run only the example data server
+```
+
+`DEV_PORT` (env or `.env`) changes the dev port.
+
+Releases are published to npm from CI when a `vX.Y.Z` tag is pushed (see `.github/workflows/publish.yml`).
+
+Pull requests also run the scroll benchmark against the base commit in CI (`.github/workflows/benchmark.yml`): base and head alternate three times on the same runner, and the job summary shows the median change. It fails on a regression of more than 30% in FPS or p95 frame time. Locally: `node scripts/compare-benchmarks.mts <path-to-base-checkout>`.
+
+## Security
+
+See [SECURITY.md](.github/SECURITY.md).
+
+## License
+
+[MIT](LICENSE)

package/build/types/cell-background/index.d.ts

@@ -0,0 +1,25 @@
+import Renderer from '../utils/renderer';
+import type { CellContext, CellRenderer } from '../types';
+export interface CellBackgroundOptions {
+    layer: string;
+    enableFlashing: boolean;
+    background: string;
+    flashInDuration: number;
+    flashOutDuration: number;
+    flashRGB: string;
+    borderRightWidth: number;
+    borderRightColor: string;
+    borderBottomWidth: number;
+    borderBottomColor: string;
+}
+declare class CellBackground extends Renderer<CellBackgroundOptions> implements CellRenderer {
+    static readonly defaultOptions: CellBackgroundOptions;
+    constructor(options?: Partial<CellBackgroundOptions>);
+    get layer(): string;
+    /** Cells flash after their value changed, until the flash has faded out. */
+    isAnimating({ age }: Readonly<CellContext>): boolean;
+    /** Flash opacity for a cell updated `age` ms ago: fades in, then out, then 0. */
+    private getFlashAlpha;
+    draw({ ctx, x, y, width, height, age }: Readonly<CellContext>): void;
+}
+export default CellBackground;

package/build/types/cell-value/index.d.ts

@@ -0,0 +1,21 @@
+import Renderer from '../utils/renderer';
+import type { CellContext, CellRenderer } from '../types';
+export interface CellValueOptions {
+    layer: string;
+    font: string;
+    color: string;
+}
+export default class CellValueRenderer extends Renderer<CellValueOptions> implements CellRenderer {
+    static readonly defaultOptions: CellValueOptions;
+    private readonly renderer;
+    constructor(options?: Partial<CellValueOptions>);
+    get layer(): string;
+    set font(font: string);
+    get font(): string;
+    set color(color: string);
+    get color(): string;
+    set pixelRatio(pixelRatio: number);
+    get pixelRatio(): number;
+    clearCache(): void;
+    draw({ ctx, x, y, width, height, formatted, valueChanged, forced }: Readonly<CellContext>): void;
+}

package/build/types/character/index.d.ts

@@ -0,0 +1,21 @@
+import { CanvasRenderer } from '../utils/renderer';
+import type { RenderProps } from '../types';
+export interface CharacterOptions {
+    font: string;
+    color: string;
+    alpha: boolean;
+    clearBeforeRender: boolean;
+}
+export default class CharacterRenderer extends CanvasRenderer<CharacterOptions> {
+    static readonly defaultOptions: CharacterOptions;
+    private readonly charWidthCache;
+    private readonly canvas;
+    private readonly ctx;
+    constructor(options?: Partial<CharacterOptions>);
+    set font(font: string);
+    set color(color: string);
+    clearCache(): void;
+    protected cacheKey({ value, height }: RenderProps): string;
+    getCharacterWidth(character?: string): number;
+    render({ value, height }: RenderProps): HTMLCanvasElement;
+}

package/build/types/header/index.d.ts

@@ -0,0 +1,25 @@
+import Renderer from '../utils/renderer';
+import type { CellContext, CellRenderer } from '../types';
+export interface HeaderOptions {
+    layer: string;
+    background: string;
+    font: string;
+    color: string;
+    borderRightWidth: number;
+    borderRightColor: string;
+    borderBottomWidth: number;
+    borderBottomColor: string;
+}
+declare class HeaderRenderer extends Renderer<HeaderOptions> implements CellRenderer {
+    static readonly defaultOptions: HeaderOptions;
+    private readonly textRenderer;
+    constructor(options?: Partial<HeaderOptions>);
+    get layer(): string;
+    set font(font: string);
+    get font(): string;
+    set pixelRatio(pixelRatio: number);
+    get pixelRatio(): number;
+    clearCache(): void;
+    draw({ ctx, x, y, width, height, formatted }: Readonly<CellContext>): void;
+}
+export default HeaderRenderer;

package/build/types/rectangle/index.d.ts

@@ -0,0 +1,12 @@
+export interface RectProps {
+    x?: number;
+    y?: number;
+    width: number;
+    height: number;
+    color: string;
+    /** Opacity from 0 to 1, applied on top of the color. */
+    alpha?: number;
+}
+/** Solid rectangle, filled straight onto the target context. */
+declare const Rect: import("../utils/jsx").Component<RectProps>;
+export default Rect;

package/build/types/text/index.d.ts

@@ -0,0 +1,31 @@
+import Renderer from '../utils/renderer';
+import type { RenderProps } from '../types';
+export interface TextOptions {
+    ellipsis: string;
+    cellPadding: {
+        top: number;
+        right: number;
+        bottom: number;
+        left: number;
+    };
+    font: string;
+    color: string;
+    isEllipsisRight: boolean;
+}
+declare class TextRenderer extends Renderer<TextOptions> {
+    static readonly defaultOptions: TextOptions;
+    private readonly characterRenderer;
+    constructor(options?: Partial<TextOptions>);
+    set font(font: string);
+    get font(): string;
+    set color(color: string);
+    get color(): string;
+    set pixelRatio(pixelRatio: number);
+    get pixelRatio(): number;
+    clearCache(): void;
+    getTextWidth(text: string): number;
+    /** Draws the text clipped with an ellipsis; `(x, y)` is the offset of the text box from `(originX, originY)`. */
+    paint(ctx: CanvasRenderingContext2D, { value, x, y, width, height }: RenderProps, originX: number, originY: number): void;
+    readonly element: import("../utils/jsx").Component<RenderProps>;
+}
+export default TextRenderer;

package/build/types/types.d.ts

@@ -0,0 +1,87 @@
+export type Key = string | number;
+export type RowId = Key;
+export interface RowInput {
+    id: RowId;
+    [column: string]: unknown;
+}
+/** A row's position and size; its values live in the column stores, addressed by `slot`. */
+export interface RowData {
+    id: RowId;
+    /** Position in the displayed (sorted) order. */
+    index: number;
+    /** Position in the column stores; stable until rows are removed. */
+    slot: number;
+    height: number;
+}
+export type SortDirection = 'asc' | 'desc';
+export interface SortKey {
+    columnId: Key;
+    direction?: SortDirection;
+    /** Orders two values of the column; defaults to numbers numerically, then text, with empty values last. */
+    compare?: (a: unknown, b: unknown) => number;
+}
+/** Props of a drawable element (see utils/jsx); positions are relative to the draw origin. */
+export interface RenderProps {
+    value?: string;
+    x?: number;
+    y?: number;
+    width?: number;
+    height?: number;
+}
+/** Free-form storage a renderer can keep per cell; it survives between frames. */
+export type CellState = Record<string, unknown>;
+export interface CellRow {
+    id: RowId;
+    index: number;
+}
+export interface CellColumn {
+    id: Key;
+    index: number;
+    displayName?: string;
+}
+/**
+ * Everything a renderer needs to draw one cell, header or row number.
+ *
+ * One object is reused for every cell, so read what you need while drawing and never keep a reference to it.
+ */
+export interface CellContext {
+    /** Context of the layer the renderer is registered for. */
+    ctx: CanvasRenderingContext2D;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    /** Undefined for headers and placeholder cells. */
+    row: CellRow | undefined;
+    /** Undefined for row numbers. */
+    column: CellColumn | undefined;
+    /** Raw value as stored. */
+    value: unknown;
+    /** Value after the column's `valueFormatter`; this is what the built-in renderers draw. */
+    formatted: string;
+    /** When the value last changed, in ms since the epoch. */
+    updatedAt: number | undefined;
+    /** Milliseconds since `updatedAt`; Infinity when the value never changed. */
+    age: number;
+    /** Timestamp of the current frame. */
+    now: number;
+    /** Milliseconds since the previous frame. */
+    dt: number;
+    /** The formatted value differs from what was drawn last time. */
+    valueChanged: boolean;
+    /** Everything has to be redrawn: first draw, resize or scrolling. */
+    forced: boolean;
+    isScrolling: boolean;
+    state: CellState;
+}
+/** Draws into one named layer. Register it with `grid.registerRenderer` and select it per column. */
+export interface CellRenderer {
+    /** Name of the layer `ctx` belongs to. */
+    readonly layer: string;
+    draw(cell: Readonly<CellContext>): void;
+    /** Return true while the cell is animating; it is redrawn every frame, plus once more after it stops. */
+    isAnimating?(cell: Readonly<CellContext>): boolean;
+    clearCache?(): void;
+}
+/** A renderer, or the name it was registered under. */
+export type RendererRef = string | CellRenderer;

package/build/types/utils/canvas.d.ts

@@ -0,0 +1 @@
+export declare const getContext2d: (canvas: HTMLCanvasElement, options?: CanvasRenderingContext2DSettings) => CanvasRenderingContext2D;

package/build/types/utils/collection.d.ts

@@ -0,0 +1,18 @@
+import type { Key } from '../types';
+/**
+ * Insertion-ordered map. Keys are compared as strings (1 and '1' are the same entry),
+ * and every operation is O(1) apart from iteration.
+ */
+declare class Collection<T> {
+    private entries;
+    constructor();
+    get keys(): Key[];
+    get(key: Key): T | undefined;
+    set(key: Key, value: T): void;
+    add(value: T): void;
+    delete(key: Key): void;
+    clear(matcher?: (item: T, key: Key) => boolean): void;
+    forEach(fn: (item: T, key: Key) => void): void;
+    get length(): number;
+}
+export default Collection;

package/build/types/utils/column-store.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Values of one column for all rows, indexed by row slot. Two flat arrays instead of an object per cell.
+ * `undefined` means the row has no value in this column.
+ */
+declare class ColumnStore {
+    values: unknown[];
+    /** When each value last changed, 0 when unknown; only allocated once a value changes after loading. */
+    private updatedAt;
+    constructor(length?: number);
+    get(slot: number): unknown;
+    getUpdatedAt(slot: number): number | undefined;
+    set(slot: number, value: unknown, updatedAt?: number): void;
+    /** Drops the values of the given slots (ascending) and shifts the following ones down. */
+    removeSlots(slots: readonly number[]): void;
+}
+export default ColumnStore;

package/build/types/utils/data-store.d.ts

@@ -0,0 +1,49 @@
+import ColumnStore from './column-store';
+import RowStore from './row-store';
+import type { Key, RowId, RowInput, SortKey } from '../types';
+export type RowIdGetter = (row: RowInput, index?: number) => RowId;
+export interface DataStoreEnvironment {
+    getRowId: RowIdGetter;
+    getCellHeight: () => number;
+}
+/** Numbers numerically, then text, then anything else as text; empty values sort last. */
+export declare const compareValues: (a: unknown, b: unknown) => number;
+/**
+ * Cell values stored by column (one array per column, addressed by the row's slot) plus the row order,
+ * with the queued add/update/remove handling and the sort model. Independent of the DOM.
+ */
+declare class DataStore {
+    rows: RowStore;
+    columns: Map<string, ColumnStore>;
+    /** Queued changes, applied in the order they were made. */
+    private pending;
+    private sortModel;
+    private sortDirty;
+    private environment;
+    constructor(environment: DataStoreEnvironment);
+    get hasPending(): boolean;
+    getSortModel(): readonly SortKey[];
+    /** Orders the rows by the given columns, in priority order; an empty model restores the insertion order. */
+    setSortModel(model: readonly SortKey[]): void;
+    /** Value of a cell, `undefined` when the row has none. */
+    getValue(rowId: RowId, columnKey: Key): unknown;
+    getUpdatedAt(rowId: RowId, columnKey: Key): number | undefined;
+    queueUpdate(row: RowInput): void;
+    queueRemove(row: RowInput): void;
+    clear(): void;
+    /** Replaces everything, dropping any queued changes. */
+    setRows(data: RowInput[]): void;
+    /**
+     * Applies the queued changes in the order they were queued; consecutive removals are applied together.
+     * Returns whether rows changed position (removed or re-sorted), which needs the whole grid to be redrawn.
+     */
+    flush(now?: number): boolean;
+    private column;
+    private addRow;
+    private removeRows;
+    private applyUpdate;
+    private applyValue;
+    private markSortDirty;
+    private sort;
+}
+export default DataStore;

package/build/types/utils/jsx.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Minimal declarative layer over the canvas 2D API.
+ *
+ * `<Group>` and friends do not draw when evaluated. They build a light tree of nodes, and calling
+ * `node.draw(ctx, x, y)` paints it, with `(x, y)` as the origin that child positions are relative to.
+ * Nothing is rasterized to an intermediate canvas unless a component opts into bitmap caching.
+ */
+export interface VNode {
+    draw(ctx: CanvasRenderingContext2D, x: number, y: number): void;
+}
+/** `false`, `null` and `undefined` are skipped, so `{condition && <Rect />}` works. */
+export type Child = VNode | false | null | undefined;
+export type Children = Child | readonly Child[];
+export interface ChildrenProps {
+    /** A single child, an array of them, or the mix of both that JSX produces for several children. */
+    children?: Children | readonly Children[];
+}
+export type Component<Props extends object> = (props: Props) => VNode;
+declare global {
+    namespace JSX {
+        type Element = VNode;
+        interface ElementChildrenAttribute {
+            children: unknown;
+        }
+        interface IntrinsicElements {
+        }
+    }
+}
+/** Wraps a paint function into a leaf component; positions in `props` are relative to the draw origin. */
+export declare const primitive: <Props extends object>(paint: (ctx: CanvasRenderingContext2D, props: Props, x: number, y: number) => void) => Component<Props>;
+export interface GroupProps extends ChildrenProps {
+    x?: number;
+    y?: number;
+}
+/** Draws its children relative to its own offset. */
+export declare const Group: Component<GroupProps>;
+declare const React: {
+    createElement<Props extends object>(component: Component<Props & ChildrenProps>, props: Props | null, ...children: Children[]): VNode;
+};
+export default React;

package/build/types/utils/layer.d.ts

@@ -0,0 +1,24 @@
+export interface LayerOptions {
+    /** Transparent canvas. Opaque layers (`false`) draw faster; keep the bottom layer opaque. */
+    alpha?: boolean;
+    /** Name of an existing layer to stack this one below; defaults to the top. */
+    before?: string;
+}
+/** A named canvas stacked in the grid; renderers draw into its context. */
+declare class Layer {
+    readonly name: string;
+    readonly canvas: HTMLCanvasElement;
+    readonly ctx: CanvasRenderingContext2D;
+    constructor(name: string, { alpha }?: Pick<LayerOptions, 'alpha'>);
+    /** Size in CSS pixels; the backing store is `pixelRatio` times larger. */
+    width: number;
+    height: number;
+    pixelRatio: number;
+    /**
+     * Resizes the canvas, scaling the context so renderers keep drawing in CSS pixels.
+     * Returns false, leaving the canvas untouched, when nothing changed (assigning a size clears the canvas).
+     */
+    resize(width: number, height: number, pixelRatio?: number): boolean;
+    clear(): void;
+}
+export default Layer;

package/build/types/utils/loading.d.ts

@@ -0,0 +1,17 @@
+import Renderer from './renderer';
+interface LoadingOptions {
+    ctx: CanvasRenderingContext2D;
+}
+declare class Loading extends Renderer<LoadingOptions> {
+    private readonly ctx;
+    private readonly offCanvas;
+    private readonly offCtx;
+    private rotation;
+    private readonly speed;
+    private readonly count;
+    constructor(options: LoadingOptions);
+    updateLoader(): void;
+    renderLoader(): void;
+    render(): HTMLCanvasElement;
+}
+export default Loading;

package/build/types/utils/lru-cache.d.ts

@@ -0,0 +1,11 @@
+/** Size-bounded map that evicts the least recently used entry first. */
+declare class LruCache<T> {
+    private readonly entries;
+    private readonly limit;
+    constructor(limit: number);
+    get(key: string): T | undefined;
+    set(key: string, value: T): void;
+    clear(): void;
+    get size(): number;
+}
+export default LruCache;

package/build/types/utils/renderer-registry.d.ts

@@ -0,0 +1,13 @@
+import type { CellRenderer, RendererRef } from '../types';
+/** Named renderers; columns refer to them by name or hand over a renderer directly. */
+declare class RendererRegistry {
+    private readonly renderers;
+    private readonly warned;
+    register(name: string, renderer: CellRenderer): void;
+    unregister(name: string): void;
+    get(name: string): CellRenderer | undefined;
+    /** Resolves a reference without allocating; unknown names are reported once and yield undefined. */
+    resolve(ref: RendererRef): CellRenderer | undefined;
+    clearCaches(): void;
+}
+export default RendererRegistry;