@taskctrl/canvas-grid 0.1.0

package/dist/capture.d.ts

@@ -0,0 +1,17 @@
+import { TreeEngine } from './core/TreeEngine';
+import { ColumnEngine } from './core/ColumnEngine';
+import { SelectionEngine } from './core/SelectionEngine';
+import { ColumnGroup, CaptureOptions } from './types';
+import { GridLayerConfig } from './layers/GridLayer';
+import { CellLayerConfig } from './layers/CellLayer';
+export interface CaptureGridOptions extends CaptureOptions {
+    treeEngine: TreeEngine;
+    columnEngine: ColumnEngine;
+    selectionEngine: SelectionEngine;
+    columnGroups?: ColumnGroup[];
+    rowHeight: number;
+    sidebarWidth: number;
+    gridLayerConfig: GridLayerConfig;
+    cellLayerConfig: CellLayerConfig;
+}
+export declare function captureGrid(options: CaptureGridOptions): HTMLCanvasElement;

package/dist/core/ColumnEngine.d.ts

@@ -0,0 +1,43 @@
+import { Column } from '../types';
+export declare class ColumnEngine {
+    private readonly _columns;
+    constructor(columns: Column[]);
+    getVisibleColumns(): Column[];
+    /** Returns visible pinned-left columns, preserving order. */
+    getPinnedColumns(): Column[];
+    /** Returns visible non-pinned columns, preserving order. */
+    getScrollableColumns(): Column[];
+    /** Total width of all pinned-left columns. */
+    getPinnedWidth(): number;
+    getAllColumns(): Column[];
+    getTotalWidth(): number;
+    /**
+     * Returns X offset of a column in the logical layout:
+     * pinned columns come first (at offsets 0..pinnedWidth),
+     * scrollable columns follow (at offsets pinnedWidth..).
+     */
+    getColumnX(colId: string): number;
+    /**
+     * Given an absolute X (i.e. accounting for scroll in scrollable region),
+     * returns the column id at that position. Pinned columns are checked first
+     * since they overlay scrollable content.
+     */
+    getColumnAtX(x: number): string | null;
+    /**
+     * Returns the visible range of SCROLLABLE columns only (pinned are always visible).
+     * scrollX is applied only to the scrollable portion (offset relative to pinnedWidth).
+     */
+    getVisibleRange(scrollX: number, viewportWidth: number): {
+        startIndex: number;
+        endIndex: number;
+    };
+    /** Returns the range of pinned columns (always all of them). */
+    getPinnedRange(): {
+        startIndex: number;
+        endIndex: number;
+    };
+    resize(colId: string, newWidth: number): ColumnEngine;
+    reorder(colId: string, newIndex: number): ColumnEngine;
+    hide(colId: string): ColumnEngine;
+    show(colId: string): ColumnEngine;
+}

package/dist/core/HitTest.d.ts

@@ -0,0 +1,8 @@
+import { ViewState } from './ViewState';
+import { TreeEngine } from './TreeEngine';
+import { ColumnEngine } from './ColumnEngine';
+export declare function hitTest(x: number, y: number, viewState: ViewState, treeEngine: TreeEngine, columnEngine: ColumnEngine): {
+    rowId: string | number;
+    colId: string;
+} | null;
+export declare function detectEdge(localX: number, colId: string, columnEngine: ColumnEngine): 'left' | 'right' | 'body';

package/dist/core/RenderScheduler.d.ts

@@ -0,0 +1,11 @@
+import { LayerName } from '../types';
+export declare class RenderScheduler {
+    private readonly _drawFn;
+    private _dirty;
+    private _rafId;
+    constructor(drawFn: (layer: LayerName) => void);
+    markDirty(layer: LayerName): void;
+    markAllDirty(): void;
+    destroy(): void;
+    private _flush;
+}

package/dist/core/SelectionEngine.d.ts

@@ -0,0 +1,15 @@
+import { Selection } from '../types';
+export declare class SelectionEngine {
+    private _selection;
+    constructor(initial?: Selection);
+    click(rowId: string | number, colId: string, allRowIds: Array<string | number>, allColIds: string[]): void;
+    ctrlClick(rowId: string | number, colId: string): void;
+    shiftClick(rowId: string | number, colId: string, allRowIds: Array<string | number>, allColIds: string[]): void;
+    selectRow(rowId: string | number, allColIds: string[]): void;
+    selectColumn(colId: string, allRowIds: Array<string | number>): void;
+    clear(): void;
+    isSelected(rowId: string | number, colId: string): boolean;
+    isRowSelected(rowId: string | number): boolean;
+    isColumnSelected(colId: string): boolean;
+    getSelection(): Selection;
+}

package/dist/core/TreeEngine.d.ts

@@ -0,0 +1,20 @@
+import { Row } from '../types';
+export declare class TreeEngine {
+    private readonly _rows;
+    private readonly _expandedRows;
+    private readonly _flattenedRows;
+    private readonly _depthMap;
+    private readonly _childrenMap;
+    constructor(rows: Row[], expandedRows: Set<string | number>);
+    private _buildMaps;
+    private _buildFlattenedRows;
+    get flattenedRows(): readonly Row[];
+    getDepth(rowId: string | number): number;
+    hasChildren(rowId: string | number): boolean;
+    isExpanded(rowId: string | number): boolean;
+    toggle(rowId: string | number): Set<string | number>;
+    getVisibleRange(scrollTop: number, viewportHeight: number, rowHeight: number): {
+        startIndex: number;
+        endIndex: number;
+    };
+}

package/dist/core/ViewState.d.ts

@@ -0,0 +1,48 @@
+interface ViewStateProps {
+    scrollX?: number;
+    scrollY?: number;
+    canvasWidth?: number;
+    canvasHeight?: number;
+    rowHeight?: number;
+}
+export declare class ViewState {
+    scrollX: number;
+    scrollY: number;
+    canvasWidth: number;
+    canvasHeight: number;
+    rowHeight: number;
+    pinnedWidth: number;
+    private _columnOffsets;
+    private _columnWidths;
+    private _pinnedOffsets;
+    private _pinnedWidths;
+    private _scrollableOffsets;
+    private _scrollableWidths;
+    constructor(initial?: ViewStateProps);
+    update(partial: ViewStateProps): void;
+    setColumnOffsets(offsets: number[]): void;
+    setColumnWidths(widths: number[]): void;
+    setPinnedOffsets(offsets: number[], widths: number[]): void;
+    setScrollableOffsets(offsets: number[], widths: number[]): void;
+    rowToY(index: number): number;
+    yToRow(y: number): number;
+    /**
+     * Column index → canvas X pixel.
+     * When pinned param is provided, uses the separate pinned/scrollable arrays.
+     * - pinned columns: offset directly (no scrollX applied)
+     * - scrollable columns: offset - scrollX + pinnedWidth
+     * When pinned param is omitted, falls back to legacy behavior (single array).
+     */
+    colToX(index: number, pinned?: boolean): number;
+    /**
+     * Canvas X pixel → column index (-1 if not found).
+     * When usePinnedLayout is true, checks pinned columns first, then scrollable.
+     * Returns { index, pinned } to distinguish which array was hit.
+     */
+    xToColPinned(x: number): {
+        index: number;
+        pinned: boolean;
+    } | null;
+    xToCol(x: number): number;
+}
+export {};

package/dist/dom/AriaLiveRegion.d.ts

@@ -0,0 +1,9 @@
+import { default as React } from 'react';
+export interface AriaLiveRegionProps {
+    message: string;
+}
+/**
+ * Visually hidden live region for screen reader announcements.
+ * Updates whenever `message` changes, which triggers aria-live to read it aloud.
+ */
+export declare function AriaLiveRegion({ message }: AriaLiveRegionProps): React.ReactElement;

package/dist/dom/ColumnHeaders.d.ts

@@ -0,0 +1,14 @@
+import { default as React } from 'react';
+import { ColumnEngine } from '../core/ColumnEngine';
+import { ColumnGroup, HeaderOrientation } from '../types';
+export interface ColumnHeadersProps {
+    columnEngine: ColumnEngine;
+    columnGroups?: ColumnGroup[];
+    scrollX: number;
+    orientation?: HeaderOrientation;
+    onColumnClick?: (colId: string, e: React.PointerEvent) => void;
+    onColumnResize?: (colId: string, newWidth: number) => void;
+    onColumnReorder?: (colId: string, newIndex: number) => void;
+    columnHeaderRenderer?: (colId: string, title: string) => React.ReactNode;
+}
+export declare function ColumnHeaders({ columnEngine, columnGroups, scrollX, orientation, onColumnClick, onColumnResize, onColumnReorder, columnHeaderRenderer, }: ColumnHeadersProps): React.ReactElement;

package/dist/dom/ColumnVisibilityMenu.d.ts

@@ -0,0 +1,7 @@
+import { default as React } from 'react';
+import { ColumnEngine } from '../core/ColumnEngine';
+export interface ColumnVisibilityMenuProps {
+    columnEngine: ColumnEngine;
+    onColumnVisibilityChange: (colId: string, visible: boolean) => void;
+}
+export declare function ColumnVisibilityMenu({ columnEngine, onColumnVisibilityChange, }: ColumnVisibilityMenuProps): React.ReactElement;

package/dist/dom/HoverPortal.d.ts

@@ -0,0 +1,9 @@
+import { default as React } from 'react';
+export interface HoverPortalProps {
+    content: React.ReactNode;
+    position: {
+        left: number;
+        top: number;
+    };
+}
+export declare function HoverPortal({ content, position }: HoverPortalProps): React.ReactPortal;

package/dist/dom/RowSidebar.d.ts

@@ -0,0 +1,16 @@
+import { default as React } from 'react';
+import { TreeEngine } from '../core/TreeEngine';
+import { SidebarRenderer } from '../types';
+export interface RowSidebarProps {
+    treeEngine: TreeEngine;
+    width: number;
+    rowHeight: number;
+    scrollTop: number;
+    viewportHeight: number;
+    sidebarRenderer?: SidebarRenderer;
+    onToggle: (rowId: string | number) => void;
+    onRowClick?: (rowId: string | number, e: React.PointerEvent) => void;
+    hoveredRowId?: string | number | null;
+    onRowHover?: (rowId: string | number | null) => void;
+}
+export declare function RowSidebar({ treeEngine, width, rowHeight, scrollTop, viewportHeight, sidebarRenderer, onToggle, onRowClick, hoveredRowId, onRowHover, }: RowSidebarProps): React.ReactElement;

package/dist/helpers/DrawHelpers.d.ts

@@ -0,0 +1,2 @@
+import { DrawHelpers } from '../types';
+export declare function createDrawHelpers(ctx: CanvasRenderingContext2D): DrawHelpers;

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export { CanvasGrid } from './CanvasGrid';
+export { createDrawHelpers } from './helpers/DrawHelpers';
+export { TreeEngine } from './core/TreeEngine';
+export { ColumnEngine } from './core/ColumnEngine';
+export { SelectionEngine } from './core/SelectionEngine';
+export { ViewState } from './core/ViewState';
+export type { Row, Column, ColumnGroup, CellBounds, CellState, CellData, CellRenderer, SidebarRenderer, DrawHelpers, HeaderOrientation, Selection, CanvasGridProps, LayerName, CaptureOptions, CanvasGridRef, } from './types';

package/dist/layers/CellLayer.d.ts

@@ -0,0 +1,14 @@
+import { ViewState } from '../core/ViewState';
+import { TreeEngine } from '../core/TreeEngine';
+import { ColumnEngine } from '../core/ColumnEngine';
+import { SelectionEngine } from '../core/SelectionEngine';
+import { CellRenderer } from '../types';
+export interface CellLayerConfig {
+    cellRenderer: CellRenderer;
+    getCellData: (rowId: string | number, colId: string) => unknown;
+    hoveredCell?: {
+        rowId: string | number;
+        colId: string;
+    } | null;
+}
+export declare function drawCellLayer(ctx: CanvasRenderingContext2D, viewState: ViewState, treeEngine: TreeEngine, columnEngine: ColumnEngine, selectionEngine: SelectionEngine, config: CellLayerConfig): void;

package/dist/layers/GridLayer.d.ts

@@ -0,0 +1,10 @@
+import { ViewState } from '../core/ViewState';
+import { TreeEngine } from '../core/TreeEngine';
+import { ColumnEngine } from '../core/ColumnEngine';
+import { Row } from '../types';
+export interface GridLayerConfig {
+    rowStyle?: (row: Row, depth: number) => {
+        backgroundColor?: string;
+    } | null;
+}
+export declare function drawGridLayer(ctx: CanvasRenderingContext2D, viewState: ViewState, treeEngine: TreeEngine, columnEngine: ColumnEngine, config?: GridLayerConfig): void;

package/dist/layers/OverlayLayer.d.ts

@@ -0,0 +1,22 @@
+import { ViewState } from '../core/ViewState';
+import { TreeEngine } from '../core/TreeEngine';
+import { ColumnEngine } from '../core/ColumnEngine';
+import { SelectionEngine } from '../core/SelectionEngine';
+export interface OverlayLayerConfig {
+    hoveredCell?: {
+        rowId: string | number;
+        colId: string;
+    } | null;
+    hoveredRowId?: string | number | null;
+    /** When set, draws crosshair (full row + col highlight) for the selected cell */
+    selectedCell?: {
+        rowId: string | number;
+        colId: string;
+    } | null;
+    resizingColumn?: {
+        colId: string;
+        x: number;
+    };
+    loading?: boolean;
+}
+export declare function drawOverlayLayer(ctx: CanvasRenderingContext2D, viewState: ViewState, treeEngine: TreeEngine, columnEngine: ColumnEngine, selectionEngine: SelectionEngine, config?: OverlayLayerConfig): void;

package/dist/setupCanvas.d.ts

@@ -0,0 +1 @@
+export declare function setupCanvas(canvas: HTMLCanvasElement, width: number, height: number): CanvasRenderingContext2D;

package/dist/types.d.ts

@@ -0,0 +1,110 @@
+import { default as React } from 'react';
+export interface Row {
+    id: string | number;
+    parentId?: string | number;
+    [key: string]: unknown;
+}
+export interface Column {
+    id: string;
+    title: string;
+    group?: string;
+    width: number;
+    minWidth?: number;
+    hidden?: boolean;
+    pinned?: 'left';
+    [key: string]: unknown;
+}
+export interface ColumnGroup {
+    id: string;
+    title: string;
+    color?: string;
+}
+export interface CellBounds {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+export interface CellState {
+    selected: boolean;
+    hovered: boolean;
+    rowSelected: boolean;
+    colSelected: boolean;
+    filtered: boolean;
+    /** Tree info for the row this cell belongs to */
+    depth: number;
+    hasChildren: boolean;
+    expanded: boolean;
+}
+export interface CellData {
+    rowId: string | number;
+    colId: string;
+    data: unknown;
+}
+export interface DrawHelpers {
+    roundRect(x: number, y: number, w: number, h: number, r: number, fill: string): void;
+    fillText(text: string, x: number, y: number, maxWidth?: number): void;
+    truncateText(text: string, maxWidth: number): string;
+    badge(x: number, y: number, text: string, bg: string, fg: string): number;
+    progressBar(x: number, y: number, w: number, h: number, percent: number, color: string): void;
+}
+export type CellRenderer = (ctx: CanvasRenderingContext2D, cell: CellData, bounds: CellBounds, state: CellState, helpers: DrawHelpers) => void;
+export type SidebarRenderer = (row: Row, depth: number, expanded: boolean, hasChildren: boolean) => React.ReactNode;
+export type HeaderOrientation = 'horizontal' | 'vertical';
+export interface Selection {
+    cells: Set<string>;
+    rows: Set<string | number>;
+    columns: Set<string>;
+    anchor?: {
+        rowId: string | number;
+        colId: string;
+    };
+}
+export type LayerName = 'grid' | 'cells' | 'overlay';
+export interface CaptureOptions {
+    scale?: number;
+}
+export interface CanvasGridRef {
+    captureToCanvas(options?: CaptureOptions): HTMLCanvasElement;
+}
+export interface CanvasGridProps {
+    rows: Row[];
+    columns: Column[];
+    columnGroups?: ColumnGroup[];
+    getCellData: (rowId: string | number, colId: string) => unknown;
+    cellRenderer: CellRenderer;
+    sidebarRenderer?: SidebarRenderer;
+    sidebarHeaderRenderer?: () => React.ReactNode;
+    sidebarWidth?: number;
+    rowHeight?: number;
+    headerOrientation?: HeaderOrientation;
+    rowStyle?: (row: Row, depth: number) => {
+        backgroundColor?: string;
+    } | null;
+    selection?: Selection;
+    onSelectionChange?: (selection: Selection) => void;
+    onCellClick?: (rowId: string | number, colId: string, e: PointerEvent) => void;
+    onCellDoubleClick?: (rowId: string | number, colId: string, e: PointerEvent) => void;
+    onCellContextMenu?: (rowId: string | number, colId: string, e: PointerEvent) => void;
+    onCellHover?: (rowId: string | number | null, colId: string | null, e: PointerEvent) => void;
+    onRowHeaderClick?: (rowId: string | number, e: PointerEvent) => void;
+    onColumnHeaderClick?: (colId: string, e: PointerEvent) => void;
+    /** Custom React content to render inside a column header cell (e.g. filter icons) */
+    columnHeaderRenderer?: (colId: string, title: string) => React.ReactNode;
+    defaultExpandedRows?: (string | number)[];
+    onExpandChange?: (expandedRows: (string | number)[]) => void;
+    onColumnResize?: (colId: string, width: number) => void;
+    onColumnReorder?: (colId: string, newIndex: number) => void;
+    onColumnVisibilityChange?: (colId: string, visible: boolean) => void;
+    onTreeToggle?: (rowId: string | number) => void;
+    onLoadMore?: () => void;
+    hasMore?: boolean;
+    loading?: boolean;
+    showColumnVisibilityMenu?: boolean;
+    hoverContent?: React.ReactNode;
+    hoverPosition?: {
+        left: number;
+        top: number;
+    };
+    ariaLabel?: string;
+}

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@taskctrl/canvas-grid",
+  "version": "0.1.0",
+  "description": "Tree-structured, virtualized data grid rendered on stacked HTML canvas layers for React",
+  "type": "module",
+  "author": "TaskCtrl AS",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/TaskCtrl-As/canvas-grid.git"
+  },
+  "main": "dist/canvas-grid.cjs.js",
+  "module": "dist/canvas-grid.es.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/canvas-grid.es.js",
+      "require": "./dist/canvas-grid.cjs.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "react": ">=17.0.0",
+    "react-dom": ">=17.0.0"
+  },
+  "devDependencies": {
+    "@storybook/react": "^10.4.1",
+    "@storybook/react-vite": "^10.4.1",
+    "@types/react": "^18.3.0",
+    "@types/react-dom": "^18.3.0",
+    "@vitejs/plugin-react": "^4.0.0",
+    "jsdom": "^26.0.0",
+    "react": "^18.3.0",
+    "react-dom": "^18.3.0",
+    "storybook": "^10.4.1",
+    "typescript": "^5.5.0",
+    "vite": "^6.0.0",
+    "vite-plugin-dts": "^5.0.1",
+    "vitest": "^3.0.0"
+  },
+  "scripts": {
+    "build": "vite build",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "local": "yarn build && npx -y yalc push --sig",
+    "local:watch": "LOCAL_DEV=1 vite build --watch",
+    "prepublishOnly": "yarn build",
+    "release": "yarn release:patch",
+    "release:patch": "npm version patch -m \"chore: release v%s\" && git push origin HEAD --follow-tags",
+    "release:minor": "npm version minor -m \"chore: release v%s\" && git push origin HEAD --follow-tags",
+    "release:major": "npm version major -m \"chore: release v%s\" && git push origin HEAD --follow-tags",
+    "release:beta": "npm version prerelease --preid=beta -m \"chore: release v%s\" && git push origin HEAD --follow-tags"
+  }
+}