@c-time/simple-ex-grid 1.0.0

package/dist/types.d.ts

@@ -0,0 +1,84 @@
+export type GridMode = 'readonly' | 'edit' | 'select';
+export type ColumnWidth = number | `${number}%` | 'fit-content';
+export type RowHeight = 'fit-content' | 'single-line';
+export type SortMark = 'asc' | 'desc' | null;
+export interface ColumnDef<Row> {
+    key: keyof Row & string;
+    header: string;
+    width?: ColumnWidth;
+    hidden?: boolean;
+    editable?: boolean;
+    formatter?: (value: unknown, row: Row) => string;
+    render?: (value: unknown, row: Row, rowIndex: number) => React.ReactNode;
+    parser?: (input: string) => unknown;
+    validator?: (value: unknown) => string | null;
+    sortMark?: SortMark;
+    align?: 'left' | 'center' | 'right';
+    headerAlign?: 'left' | 'center' | 'right';
+}
+export interface CellRange {
+    start: {
+        row: number;
+        col: number;
+    };
+    end: {
+        row: number;
+        col: number;
+    };
+}
+export interface CellChange {
+    row: number;
+    col: number;
+    before: unknown;
+    after: unknown;
+}
+export interface HistoryApi<Row> {
+    pushHistory: (beforeRows: Row[], afterRows: Row[]) => void;
+    undo: () => void;
+    redo: () => void;
+    canUndo: boolean;
+    canRedo: boolean;
+}
+export interface SimpleExGridProps<Row> {
+    rows: Row[];
+    columns: ColumnDef<Row>[];
+    onChange?: (next: Row[], changes: CellChange[]) => void;
+    mode?: GridMode;
+    showRowGripHeader?: boolean;
+    showColumnGripHeader?: boolean;
+    gripHeaderDragSelect?: boolean;
+    pinnedLeftCount?: number;
+    pinnedTopCount?: number;
+    pagination?: boolean;
+    pageSize?: number;
+    page?: number;
+    onPageChange?: (page: number) => void;
+    onPageSizeChange?: (pageSize: number) => void;
+    clipboard?: {
+        enabled?: boolean;
+        format?: 'tsv' | 'html' | 'both';
+    };
+    selection?: CellRange | null;
+    onSelectionChange?: (range: CellRange | null) => void;
+    onActiveCellChange?: (row: number, col: number) => void;
+    onEditStart?: (row: number, col: number) => boolean | void;
+    onEditCommit?: (row: number, col: number, before: unknown, after: unknown) => boolean | void;
+    onEditCancel?: (row: number, col: number) => void;
+    onRowsAdd?: (startRow: number, count: number) => void;
+    onRowsDelete?: (startRow: number, count: number) => void;
+    rowHeight?: RowHeight;
+    allowRowAdd?: boolean;
+    allowRowDelete?: boolean;
+    maxHistory?: number;
+    shouldRecordHistory?: (changes: CellChange[], rowEvent?: {
+        kind: 'add' | 'delete';
+        startRow: number;
+        count: number;
+    }) => boolean;
+    historyApiRef?: React.MutableRefObject<HistoryApi<Row> | null>;
+    colSpan?: (row: number, col: number) => number;
+    cellAlign?: (row: number, col: number) => 'left' | 'center' | 'right' | undefined;
+    virtualized?: boolean;
+    minRows?: number;
+    minCols?: number;
+}

package/dist/utils/colspan.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Utility functions for resolving column spans.
+ *
+ * The `ColSpanGetter` callback is only invoked on "owner" columns — the leftmost
+ * column of each span group.  Covered columns (those absorbed by a previous
+ * cell's span) are skipped during the left-to-right scan.
+ */
+export type ColSpanGetter = (row: number, col: number) => number;
+/**
+ * Find the owner (leftmost) column for a given (row, col) position.
+ * If `col` is inside a span that started at an earlier column, this returns
+ * that earlier column index.
+ */
+export declare function findOwnerCol(row: number, col: number, colCount: number, getColSpan: ColSpanGetter): number;
+/**
+ * Get the effective span width for the cell at (row, col).
+ * Always resolves from the owner column first.
+ */
+export declare function getEffectiveSpan(row: number, col: number, colCount: number, getColSpan: ColSpanGetter): number;
+/**
+ * Return the next visible (owner) column after `col` in a given row.
+ * Returns `colCount` if there is no next column (i.e. we're at the end).
+ */
+export declare function nextOwnerCol(row: number, col: number, colCount: number, getColSpan: ColSpanGetter): number;
+/**
+ * Return the previous visible (owner) column before `col` in a given row.
+ * Returns -1 if there is no previous column.
+ */
+export declare function prevOwnerCol(row: number, col: number, colCount: number, getColSpan: ColSpanGetter): number;
+/**
+ * Return the last owner column in a given row.
+ */
+export declare function lastOwnerCol(row: number, colCount: number, getColSpan: ColSpanGetter): number;

package/dist/utils/html.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Encode grid data as an HTML <table> for clipboard (Excel/Sheets interop).
+ */
+export interface HtmlEncodeOptions {
+    colSpan?: (row: number, col: number) => number;
+    startRow?: number;
+    startCol?: number;
+}
+export declare function encodeHtml(grid: string[][], options?: HtmlEncodeOptions): string;

package/dist/utils/tsv.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Excel-compliant TSV encoder/decoder.
+ * - Row delimiter: \r\n
+ * - Cell delimiter: \t
+ * - Cells containing \t, \n, \r, or " are wrapped in double quotes with " escaped as ""
+ */
+export declare function encodeTsv(grid: string[][]): string;
+export declare function decodeTsv(tsv: string): string[][];

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "@c-time/simple-ex-grid",
+  "version": "1.0.0",
+  "description": "Excel-like grid component for React with clipboard, touch support, and cell selection",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "keywords": [
+    "react",
+    "grid",
+    "excel",
+    "spreadsheet",
+    "clipboard",
+    "touch"
+  ],
+  "author": "c-time",
+  "license": "MIT",
+  "peerDependencies": {
+    "react": "^18.0.0 || ^19.0.0",
+    "react-dom": "^18.0.0 || ^19.0.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@storybook/react": "^10.3.5",
+    "@storybook/react-vite": "^10.3.5",
+    "@testing-library/jest-dom": "^6.9.1",
+    "@testing-library/react": "^16.3.2",
+    "@types/react": "^19.2.14",
+    "@types/react-dom": "^19.2.3",
+    "@vitejs/plugin-react": "^6.0.1",
+    "eslint": "^10.2.0",
+    "eslint-plugin-react-hooks": "^7.0.1",
+    "eslint-plugin-react-refresh": "^0.5.2",
+    "jsdom": "^29.0.2",
+    "prettier": "^3.8.2",
+    "react": "^19.2.5",
+    "react-dom": "^19.2.5",
+    "storybook": "^10.3.5",
+    "typescript": "^6.0.2",
+    "typescript-eslint": "^8.58.1",
+    "vite": "^8.0.8",
+    "vitest": "^4.1.4"
+  },
+  "scripts": {
+    "dev": "storybook dev -p 6006",
+    "build": "vite build && tsc --emitDeclarationOnly",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "eslint src/",
+    "format": "prettier --write \"src/**/*.{ts,tsx}\"",
+    "format:check": "prettier --check \"src/**/*.{ts,tsx}\"",
+    "storybook:build": "storybook build",
+    "typecheck": "tsc --noEmit"
+  }
+}