@particle-academy/fancy-sheets 0.4.5 → 0.4.6

package/dist/styles.css.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/styles.css"],"sourcesContent":["/* @particle-academy/fancy-sheets — spreadsheet styles */\r\n\r\n/* Grid cell borders */\r\n[data-fancy-sheets-grid] {\r\n  font-family: -apple-system, BlinkMacSystemFont, \"Segoe UI\", Roboto, sans-serif;\r\n}\r\n\r\n/* Cell editor positioning */\r\n[data-fancy-sheets-cell-editor] {\r\n  box-sizing: border-box;\r\n}\r\n\r\n/* Scrollbar styling */\r\n[data-fancy-sheets-grid]::-webkit-scrollbar {\r\n  width: 10px;\r\n  height: 10px;\r\n}\r\n\r\n[data-fancy-sheets-grid]::-webkit-scrollbar-track {\r\n  background: transparent;\r\n}\r\n\r\n[data-fancy-sheets-grid]::-webkit-scrollbar-thumb {\r\n  background: #a1a1aa;\r\n  border-radius: 5px;\r\n}\r\n\r\n.dark [data-fancy-sheets-grid]::-webkit-scrollbar-thumb {\r\n  background: #52525b;\r\n}\r\n"],"mappings":";AAGA,CAAC;AACC;AAAA,IAAa,aAAa;AAAA,IAAE,kBAAkB;AAAA,IAAE,UAAU;AAAA,IAAE,MAAM;AAAA,IAAE;AACtE;AAGA,CAAC;AACC,cAAY;AACd;AAGA,CAAC,uBAAuB;AACtB,SAAO;AACP,UAAQ;AACV;AAEA,CAAC,uBAAuB;AACtB,cAAY;AACd;AAEA,CAAC,uBAAuB;AACtB,cAAY;AACZ,iBAAe;AACjB;AAEA,CAAC,KAAK,CAAC,uBAAuB;AAC5B,cAAY;AACd;","names":[]}
+{"version":3,"sources":["../src/styles.css"],"sourcesContent":["/* @particle-academy/fancy-sheets — spreadsheet styles */\n\n/* Grid cell borders */\n[data-fancy-sheets-grid] {\n  font-family: -apple-system, BlinkMacSystemFont, \"Segoe UI\", Roboto, sans-serif;\n}\n\n/* Cell editor positioning */\n[data-fancy-sheets-cell-editor] {\n  box-sizing: border-box;\n}\n\n/* Scrollbar styling */\n[data-fancy-sheets-grid]::-webkit-scrollbar {\n  width: 10px;\n  height: 10px;\n}\n\n[data-fancy-sheets-grid]::-webkit-scrollbar-track {\n  background: transparent;\n}\n\n[data-fancy-sheets-grid]::-webkit-scrollbar-thumb {\n  background: #a1a1aa;\n  border-radius: 5px;\n}\n\n.dark [data-fancy-sheets-grid]::-webkit-scrollbar-thumb {\n  background: #52525b;\n}\n"],"mappings":";AAGA,CAAC;AACC;AAAA,IAAa,aAAa;AAAA,IAAE,kBAAkB;AAAA,IAAE,UAAU;AAAA,IAAE,MAAM;AAAA,IAAE;AACtE;AAGA,CAAC;AACC,cAAY;AACd;AAGA,CAAC,uBAAuB;AACtB,SAAO;AACP,UAAQ;AACV;AAEA,CAAC,uBAAuB;AACtB,cAAY;AACd;AAEA,CAAC,uBAAuB;AACtB,cAAY;AACZ,iBAAe;AACjB;AAEA,CAAC,KAAK,CAAC,uBAAuB;AAC5B,cAAY;AACd;","names":[]}

package/docs/Spreadsheet.md

@@ -0,0 +1,216 @@
+# Spreadsheet
+
+A full-featured spreadsheet component with formulas, formatting, selection, multi-sheet workbooks, clipboard, CSV import/export, and undo/redo. Compound API.
+
+## Import
+
+```tsx
+import { Spreadsheet, useSpreadsheet } from "@particle-academy/fancy-sheets";
+import "@particle-academy/fancy-sheets/styles.css";
+```
+
+## Basic Usage
+
+```tsx
+<div style={{ height: 600 }}>
+  <Spreadsheet>
+    <Spreadsheet.Toolbar />
+    <Spreadsheet.Grid />
+    <Spreadsheet.SheetTabs />
+  </Spreadsheet>
+</div>
+```
+
+The component fills its container — wrap it in a sized element (height is required).
+
+## Props
+
+### Spreadsheet (root)
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| data | `WorkbookData` | - | Controlled workbook |
+| defaultData | `WorkbookData` | empty workbook | Initial workbook (uncontrolled) |
+| onChange | `(data: WorkbookData) => void` | - | Called on any data change |
+| columnCount | `number` | `26` | Number of columns |
+| rowCount | `number` | `100` | Number of rows |
+| defaultColumnWidth | `number` | `100` | Default column width in px |
+| rowHeight | `number` | `28` | Row height in px |
+| readOnly | `boolean` | `false` | Disable editing, formatting, and structural changes |
+| className | `string` | - | Additional CSS classes |
+
+### Spreadsheet.Toolbar
+
+Default toolbar with format buttons (bold, italic, align), undo/redo, and freeze controls. Pass `children` to replace entirely.
+
+| Prop | Type | Description |
+|------|------|-------------|
+| children | `ReactNode` | Replace defaults |
+| className | `string` | Additional CSS classes |
+
+### Spreadsheet.Grid
+
+The main editable cell grid. Handles navigation, selection, editing, keyboard shortcuts, and clipboard.
+
+| Prop | Type | Description |
+|------|------|-------------|
+| className | `string` | Additional CSS classes |
+
+### Spreadsheet.SheetTabs
+
+Bottom tab bar for multi-sheet workbooks. Supports add/rename/delete/switch.
+
+| Prop | Type | Description |
+|------|------|-------------|
+| className | `string` | Additional CSS classes |
+
+## Data Model
+
+### WorkbookData
+
+```ts
+interface WorkbookData {
+  sheets: SheetData[];
+  activeSheetId: string;
+}
+```
+
+### SheetData
+
+```ts
+interface SheetData {
+  id: string;
+  name: string;
+  cells: Record<CellAddress, CellData>;   // sparse — only non-empty cells
+  columnWidths: Record<number, number>;   // sparse overrides
+  mergedRegions: MergedRegion[];
+  columnFilters: Record<number, string>;
+  sortColumn?: number;
+  sortDirection?: "asc" | "desc";
+  frozenRows: number;
+  frozenCols: number;
+}
+```
+
+### CellData
+
+```ts
+type CellAddress = string; // "A1", "AA99", ...
+type CellValue = string | number | boolean | null;
+
+interface CellData {
+  value: CellValue;           // raw entered value
+  formula?: string;           // original formula string (e.g. "=SUM(A1:A10)")
+  computedValue?: CellValue;  // evaluated result
+  format?: CellFormat;
+}
+```
+
+### CellFormat
+
+```ts
+interface CellFormat {
+  bold?: boolean;
+  italic?: boolean;
+  textAlign?: "left" | "center" | "right";
+  displayFormat?: "auto" | "date" | "datetime" | "number" | "percent";
+  decimals?: number;
+}
+```
+
+## Helpers
+
+```ts
+import { createEmptyWorkbook, createEmptySheet } from "@particle-academy/fancy-sheets";
+
+const workbook = createEmptyWorkbook();
+const newSheet = createEmptySheet("sheet-2", "Summary");
+```
+
+## useSpreadsheet Hook
+
+Access full workbook state and actions from any child of `<Spreadsheet>`.
+
+```tsx
+import { useSpreadsheet } from "@particle-academy/fancy-sheets";
+
+function ExportButton() {
+  const { workbook } = useSpreadsheet();
+  return (
+    <button onClick={() => download(workbookToCSV(workbook))}>
+      Export CSV
+    </button>
+  );
+}
+```
+
+See `SpreadsheetContextValue` in source for the full shape — key properties:
+
+| Property | Description |
+|----------|-------------|
+| `workbook` | Current WorkbookData |
+| `activeSheet` | Currently displayed SheetData |
+| `selection` | `{ activeCell, ranges }` |
+| `setCellValue(addr, val)` | Update a single cell |
+| `setCellFormat(addrs[], fmt)` | Apply formatting to a list of cells |
+| `navigate(dir, extend?)` | Move active cell (arrow-key equivalent) |
+| `startEdit(val?) / confirmEdit() / cancelEdit()` | Edit lifecycle |
+| `addSheet() / renameSheet() / deleteSheet() / setActiveSheet()` | Sheet management |
+| `setFrozenRows(n) / setFrozenCols(n)` | Freeze controls |
+| `undo() / redo()` | History navigation (50-step stack) |
+| `canUndo / canRedo` | Booleans |
+
+## Controlled Usage
+
+```tsx
+const [data, setData] = useState<WorkbookData>(createEmptyWorkbook());
+
+<Spreadsheet data={data} onChange={setData}>
+  <Spreadsheet.Toolbar />
+  <Spreadsheet.Grid />
+  <Spreadsheet.SheetTabs />
+</Spreadsheet>
+```
+
+## Read-Only Display
+
+```tsx
+<Spreadsheet defaultData={reportData} readOnly>
+  <Spreadsheet.Grid />
+</Spreadsheet>
+```
+
+## Keyboard Shortcuts
+
+| Keys | Action |
+|------|--------|
+| Arrow keys | Move active cell |
+| Shift + arrows | Extend selection |
+| Ctrl/Cmd + arrows | Jump to edge |
+| Enter / F2 | Start editing |
+| Esc | Cancel edit |
+| Tab / Shift+Tab | Move right/left |
+| Ctrl/Cmd + C / X / V | Copy / Cut / Paste |
+| Ctrl/Cmd + Z / Y | Undo / Redo |
+| Ctrl/Cmd + B / I | Bold / Italic |
+
+## Data Attributes
+
+| Attribute | Element |
+|-----------|---------|
+| `data-fancy-sheets` | Root container |
+| `data-fancy-sheets-toolbar` | Toolbar |
+| `data-fancy-sheets-formula-bar` | Formula bar |
+| `data-fancy-sheets-grid` | Grid container |
+| `data-fancy-sheets-column-headers` | Column header row |
+| `data-fancy-sheets-row-header` | Row header cell |
+| `data-fancy-sheets-cell` | Individual cell |
+| `data-fancy-sheets-cell-editor` | Active edit input |
+| `data-fancy-sheets-selection` | Selection overlay |
+| `data-fancy-sheets-resize-handle` | Column resize handle |
+| `data-fancy-sheets-tabs` | Sheet tabs |
+
+## See Also
+
+- [Formulas](./formulas.md) — all 80+ built-in functions and how to register custom ones
+- [CSV Import/Export](./csv.md) — `csvToWorkbook`, `workbookToCSV`, `parseCSV`, `stringifyCSV`

package/docs/csv.md

@@ -0,0 +1,75 @@
+# CSV Import / Export
+
+Four utility functions for moving data between CSV strings and workbook/sheet structures. Handles quoted fields, escaped quotes, and newlines inside quoted values.
+
+## Import
+
+```tsx
+import {
+  parseCSV,
+  stringifyCSV,
+  csvToWorkbook,
+  workbookToCSV,
+} from "@particle-academy/fancy-sheets";
+```
+
+## Low-Level: parseCSV / stringifyCSV
+
+```ts
+function parseCSV(csv: string): string[][];
+function stringifyCSV(rows: string[][]): string;
+```
+
+```tsx
+const rows = parseCSV(`name,age\nAlice,30\nBob,25`);
+// [["name", "age"], ["Alice", "30"], ["Bob", "25"]]
+
+const csv = stringifyCSV(rows);
+// "name,age\nAlice,30\nBob,25"
+```
+
+Quoted strings are preserved, embedded commas/newlines survive the round-trip, and `""` is decoded as a literal `"`.
+
+## High-Level: csvToWorkbook / workbookToCSV
+
+```ts
+function csvToWorkbook(csv: string, sheetName?: string): WorkbookData;
+function workbookToCSV(workbook: WorkbookData): string;
+```
+
+Use these for full workbook ↔ file conversions:
+
+```tsx
+// Load a CSV file into the editor
+const text = await file.text();
+const workbook = csvToWorkbook(text, file.name.replace(/\.csv$/i, ""));
+setData(workbook);
+
+// Export current workbook to CSV
+const csv = workbookToCSV(workbook);
+downloadFile(csv, "export.csv", "text/csv");
+```
+
+`workbookToCSV` concatenates all sheets separated by a blank line and `# <sheet name>` header lines. For single-sheet export, slice the returned string or pre-filter the workbook to one sheet.
+
+## Example: File Upload
+
+```tsx
+function Importer() {
+  const { workbook } = useSpreadsheet();
+
+  const handleFile = async (e: ChangeEvent<HTMLInputElement>) => {
+    const file = e.target.files?.[0];
+    if (!file) return;
+    const text = await file.text();
+    const imported = csvToWorkbook(text, file.name);
+    // merge into existing workbook or replace...
+  };
+
+  return <input type="file" accept=".csv" onChange={handleFile} />;
+}
+```
+
+## Clipboard
+
+Clipboard paste into the grid already uses TSV (tab-separated) internally — paste a CSV from Excel / Sheets and it lands in the cells correctly. Use the CSV helpers for file-based import/export, not clipboard.

package/docs/formulas.md

@@ -0,0 +1,161 @@
+# Formulas
+
+The engine evaluates Excel/Sheets-style formulas entered with a leading `=`. Parser and evaluator are custom — no third-party dependency.
+
+## Basics
+
+```
+=A1+B1              addition
+=SUM(A1:A10)        range aggregate
+=IF(A1>100, "hi", "lo")   logic
+=Sheet2!B3          cross-sheet reference
+=A1 & " " & B1      string concatenation
+```
+
+## Operators
+
+| Operator | Meaning |
+|----------|---------|
+| `+` `-` `*` `/` `^` | Arithmetic (`^` = power) |
+| `=` `<>` `<` `<=` `>` `>=` | Comparison |
+| `&` | String concatenation |
+| `%` | Percentage (`50%` = 0.5) |
+| `()` | Grouping |
+
+## Error Values
+
+| Value | Cause |
+|-------|-------|
+| `#ERROR!` | Syntax error in formula |
+| `#VALUE!` | Wrong argument type |
+| `#DIV/0!` | Division by zero |
+| `#NAME?` | Unknown function |
+| `#CIRC!` | Circular reference |
+
+## Reference Forms
+
+- `A1` — single cell
+- `A1:B5` — range
+- `Sheet2!A1` — cell on another sheet
+- `Sheet2!A1:B5` — range on another sheet
+
+## Built-in Functions (80+)
+
+### Math (25)
+
+| Function | Purpose |
+|----------|---------|
+| `SUM(range)` | Sum of numbers |
+| `AVERAGE(range)` | Arithmetic mean |
+| `MEDIAN(range)` | Median value |
+| `MIN(range)` / `MAX(range)` | Min / max |
+| `COUNT(range)` | Count of numeric cells |
+| `PRODUCT(range)` | Product of numbers |
+| `ROUND(n, digits)` | Round to `digits` decimals |
+| `ABS(n)` | Absolute value |
+| `SQRT(n)` | Square root |
+| `POWER(base, exp)` | `base^exp` |
+| `MOD(a, b)` | Remainder |
+| `INT(n)` / `TRUNC(n)` | Truncate to int |
+| `FLOOR(n)` / `CEILING(n)` | Round down / up |
+| `SIGN(n)` | `-1`, `0`, or `1` |
+| `FACT(n)` | Factorial |
+| `PI()` | 3.14159… |
+| `EXP(n)` | `e^n` |
+| `LN(n)` / `LOG(n, base?)` / `LOG10(n)` | Logarithms |
+| `RAND()` | 0 ≤ x < 1 |
+| `RANDBETWEEN(lo, hi)` | Integer in range |
+
+### Text (19)
+
+| Function | Purpose |
+|----------|---------|
+| `UPPER(s)` / `LOWER(s)` / `PROPER(s)` | Case conversion |
+| `LEN(s)` | String length |
+| `TRIM(s)` | Strip leading/trailing whitespace |
+| `LEFT(s, n)` / `RIGHT(s, n)` / `MID(s, start, n)` | Substrings |
+| `FIND(needle, haystack, start?)` | Case-sensitive position |
+| `SEARCH(needle, haystack, start?)` | Case-insensitive position |
+| `SUBSTITUTE(s, old, new, occurrence?)` | Replace |
+| `REPLACE(s, start, count, new)` | Positional replace |
+| `CONCAT(...args)` | Join strings |
+| `REPT(s, n)` | Repeat |
+| `EXACT(a, b)` | Case-sensitive equality |
+| `VALUE(s)` | String → number |
+| `TEXT(n, fmt)` | Number → formatted string |
+| `CHAR(code)` / `CODE(s)` | Code ↔ character |
+
+### Logic (8)
+
+| Function | Purpose |
+|----------|---------|
+| `IF(cond, then, else)` | Conditional |
+| `AND(...args)` / `OR(...args)` / `NOT(a)` | Boolean |
+| `IFERROR(val, fallback)` | Catch errors |
+| `IFBLANK(val, fallback)` | Blank-cell fallback |
+| `SWITCH(expr, case1, val1, ..., default?)` | Multi-branch |
+| `CHOOSE(index, v1, v2, ...)` | Pick by 1-based index |
+
+### Conditional Aggregates (8)
+
+| Function | Purpose |
+|----------|---------|
+| `SUMIF(range, criterion, sumRange?)` | Sum matching |
+| `SUMIFS(sumRange, r1, c1, ...)` | Multi-criteria sum |
+| `COUNTIF(range, criterion)` | Count matching |
+| `COUNTIFS(r1, c1, ...)` | Multi-criteria count |
+| `AVERAGEIF(range, criterion, avgRange?)` | Average matching |
+| `AVERAGEIFS(avgRange, r1, c1, ...)` | Multi-criteria average |
+| `MINIFS(minRange, r1, c1, ...)` | Min matching |
+| `MAXIFS(maxRange, r1, c1, ...)` | Max matching |
+
+Criteria support operators as strings: `">100"`, `"<=50"`, `"<>"`, `"=apple"`.
+
+### Lookup (8)
+
+| Function | Purpose |
+|----------|---------|
+| `VLOOKUP(value, range, colIndex, exact?)` | Vertical lookup |
+| `HLOOKUP(value, range, rowIndex, exact?)` | Horizontal lookup |
+| `INDEX(range, row, col?)` | Index into a range |
+| `MATCH(value, range, type?)` | Find position |
+| `ROWS(range)` / `COLUMNS(range)` | Dimensions |
+| `ROW(ref?)` / `COLUMN(ref?)` | Position of a ref |
+
+### Date / Time (12)
+
+| Function | Purpose |
+|----------|---------|
+| `TODAY()` | Current date |
+| `NOW()` | Current date + time |
+| `DATE(y, m, d)` | Build a date |
+| `YEAR(date)` / `MONTH(date)` / `DAY(date)` | Extract parts |
+| `HOUR(t)` / `MINUTE(t)` / `SECOND(t)` | Extract time parts |
+| `WEEKDAY(date, type?)` | Day of week |
+| `DATEDIF(start, end, unit)` | Difference (`"Y"`, `"M"`, `"D"`) |
+| `EDATE(start, months)` | Offset by months |
+
+### Info (6)
+
+| Function | Purpose |
+|----------|---------|
+| `ISBLANK(ref)` | Cell is empty |
+| `ISNUMBER(val)` / `ISTEXT(val)` / `ISLOGICAL(val)` | Type checks |
+| `ISERROR(val)` | Is an error value |
+| `TYPE(val)` | Type code (1=number, 2=text, 4=logical, 16=error) |
+
+## Registering Custom Functions
+
+```tsx
+import { registerFunction } from "@particle-academy/fancy-sheets";
+
+registerFunction("GREET", (name: string) => `Hello, ${name}`);
+
+// In a cell: =GREET("world")  →  "Hello, world"
+```
+
+Custom functions are called with resolved arguments (cell values, not tokens). Return any `CellValue`. Throwing is allowed — the value becomes `#ERROR!` in the grid.
+
+## Dependency Tracking
+
+The evaluator builds a dependency graph between cells. When a cell changes, only transitively dependent cells are re-evaluated, in topological order. Circular references are detected and reported as `#CIRC!`.

package/package.json

@@ -1,56 +1,63 @@
-{
-  "name": "@particle-academy/fancy-sheets",
-  "version": "0.4.5",
-  "description": "Spreadsheet editor with formula engine, multi-sheet tabs, and full cell editing",
-  "type": "module",
-  "main": "./dist/index.cjs",
-  "module": "./dist/index.js",
-  "types": "./dist/index.d.ts",
-  "exports": {
-    ".": {
-      "import": {
-        "types": "./dist/index.d.ts",
-        "default": "./dist/index.js"
-      },
-      "require": {
-        "types": "./dist/index.d.cts",
-        "default": "./dist/index.cjs"
-      }
-    },
-    "./styles.css": "./dist/styles.css"
-  },
-  "files": [
-    "dist",
-    "README.md"
-  ],
-  "scripts": {
-    "build": "tsup",
-    "dev": "tsup --watch",
-    "lint": "tsc --noEmit",
-    "clean": "rm -rf dist",
-    "prepublishOnly": "tsup"
-  },
-  "peerDependencies": {
-    "react": "^18.0.0 || ^19.0.0",
-    "react-dom": "^18.0.0 || ^19.0.0",
-    "@particle-academy/react-fancy": "^1.5.0"
-  },
-  "dependencies": {},
-  "devDependencies": {
-    "@particle-academy/react-fancy": "workspace:*",
-    "@types/react": "^19.0.0",
-    "@types/react-dom": "^19.0.0",
-    "react": "^19.0.0",
-    "react-dom": "^19.0.0",
-    "tsup": "^8.5.0",
-    "typescript": "^5.8.0"
-  },
-  "publishConfig": {
-    "access": "public"
-  },
-  "license": "MIT",
-  "sideEffects": [
-    "**/*.css",
-    "src/engine/formula/functions/*.ts"
-  ]
-}
+{
+  "name": "@particle-academy/fancy-sheets",
+  "version": "0.4.6",
+  "description": "Spreadsheet editor with formula engine, multi-sheet tabs, and full cell editing",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Particle-Academy/fancy-sheets.git"
+  },
+  "homepage": "https://github.com/Particle-Academy/fancy-sheets#readme",
+  "bugs": "https://github.com/Particle-Academy/fancy-sheets/issues",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    },
+    "./styles.css": "./dist/styles.css"
+  },
+  "files": [
+    "dist",
+    "docs",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "lint": "tsc --noEmit",
+    "clean": "rm -rf dist",
+    "prepublishOnly": "tsup"
+  },
+  "peerDependencies": {
+    "react": "^18.0.0 || ^19.0.0",
+    "react-dom": "^18.0.0 || ^19.0.0",
+    "@particle-academy/react-fancy": "^1.5.0"
+  },
+  "dependencies": {},
+  "devDependencies": {
+    "@particle-academy/react-fancy": "*",
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "tsup": "^8.5.0",
+    "typescript": "^5.8.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT",
+  "sideEffects": [
+    "**/*.css",
+    "src/engine/formula/functions/*.ts"
+  ]
+}