@particle-academy/fancy-sheets 0.6.3 → 0.7.0

package/docs/Spreadsheet.md

@@ -61,6 +61,8 @@ Takes `SheetData` directly — no workbook wrapper, no tabs, no toolbar:
 | rowHeight | `number` | `28` | Row height in px |
 | readOnly | `boolean` | `false` | Disable editing |
 | contextMenuItems | `ContextMenuItem[] \| (addr) => ContextMenuItem[]` | - | Custom right-click items |
+| highlights | `CellHighlightMap` | - | Consumer-driven cell highlights (address → color/label) |
+| onActiveCellChange | `(addr, cell?) => void` | - | Fires when the active cell changes |
 | className | `string` | - | Additional CSS classes |
 
 ### Spreadsheet.Toolbar
@@ -69,6 +71,7 @@ Takes `SheetData` directly — no workbook wrapper, no tabs, no toolbar:
 |------|------|-------------|
 | children | `ReactNode` | Replace default toolbar entirely |
 | extra | `ReactNode` | Append content after default buttons (before formula bar) |
+| buttons | `ToolbarButton[]` | Which built-in groups to show (default: all). Pass `[]` for only custom `extra`. |
 | className | `string` | Additional CSS classes |
 
 ### SheetWorkbook
@@ -80,6 +83,7 @@ All `Spreadsheet` props plus:
 | hideToolbar | `boolean` | `false` | Hide the toolbar |
 | hideTabs | `boolean` | `false` | Hide the sheet tabs |
 | toolbarExtra | `ReactNode` | - | Extra toolbar content |
+| toolbarButtons | `ToolbarButton[]` | all | Which built-in toolbar groups to show |
 
 ### Sheet
 
@@ -127,6 +131,7 @@ interface CellData {
   computedValue?: CellValue;
   format?: CellFormat;
   comment?: CellComment;
+  meta?: Record<string, unknown>;  // consumer-defined metadata
 }
 ```
 
@@ -146,6 +151,7 @@ interface CellFormat {
   borderRight?: string;
   borderBottom?: string;
   borderLeft?: string;
+  className?: string;          // custom CSS class(es) on the cell element
 }
 ```
 
@@ -166,51 +172,350 @@ Comments render as:
 - A 1px border around the cell in the comment color
 - A hover tooltip showing author + text
 
-### Context Menu Items
+### SpreadsheetContextMenuItem
 
 ```ts
 interface SpreadsheetContextMenuItem {
   label: string;
-  onClick: (address: string) => void;
+  onClick?: (address: string) => void;
   disabled?: boolean | ((address: string) => boolean);
   danger?: boolean;
+  items?: SpreadsheetContextMenuItem[];  // nested submenu
 }
 ```
 
-Pass as array (static) or callback (dynamic per cell):
+---
+
+## Custom Toolbar Buttons
+
+Use the `extra` prop on `Spreadsheet.Toolbar` (or `toolbarExtra` on `SheetWorkbook`) to inject your own buttons alongside the built-in ones. They appear after a divider at the end of the button bar.
+
+```tsx
+<Spreadsheet data={data} onChange={setData}>
+  <Spreadsheet.Toolbar
+    extra={
+      <>
+        <button
+          className="rounded bg-green-600 px-2 py-0.5 text-xs text-white"
+          onClick={() => addRow("income")}
+        >
+          + Income
+        </button>
+        <button
+          className="rounded bg-red-500 px-2 py-0.5 text-xs text-white ml-1"
+          onClick={() => addRow("expense")}
+        >
+          + Expense
+        </button>
+      </>
+    }
+  />
+  <Spreadsheet.Grid />
+</Spreadsheet>
+```
+
+Or via `SheetWorkbook`:
+
+```tsx
+<SheetWorkbook
+  data={data}
+  onChange={setData}
+  toolbarExtra={<button onClick={exportCSV}>Export</button>}
+/>
+```
+
+## Controlling the Toolbar
+
+The `buttons` prop on `Spreadsheet.Toolbar` (or `toolbarButtons` on `SheetWorkbook`) controls which built-in button groups are visible.
+
+```ts
+type ToolbarButton = "undo" | "bold" | "align" | "freeze" | "format" | "decimals" | "formulaBar";
+```
+
+### Show all (default)
+
+```tsx
+<Spreadsheet.Toolbar />
+```
+
+### Show specific groups only
+
+```tsx
+<Spreadsheet.Toolbar buttons={["undo", "bold", "formulaBar"]} />
+```
+
+### Show only custom buttons (hide all built-in)
+
+```tsx
+<Spreadsheet.Toolbar buttons={[]} extra={<MyCustomToolbar />} />
+```
+
+### Via SheetWorkbook
+
+```tsx
+<SheetWorkbook
+  toolbarButtons={["undo", "bold", "format", "formulaBar"]}
+  toolbarExtra={<button>Custom</button>}
+/>
+```
+
+### Replace the toolbar entirely
+
+Pass `children` to `Spreadsheet.Toolbar` to replace the default UI completely. Use `useSpreadsheet()` inside your custom toolbar to access state and actions.
+
+```tsx
+function MyToolbar() {
+  const { undo, redo, canUndo, canRedo, selection } = useSpreadsheet();
+  return (
+    <div className="flex gap-2 p-2 border-b">
+      <button onClick={undo} disabled={!canUndo}>Undo</button>
+      <button onClick={redo} disabled={!canRedo}>Redo</button>
+      <span>Cell: {selection.activeCell}</span>
+    </div>
+  );
+}
+
+<Spreadsheet data={data} onChange={setData}>
+  <Spreadsheet.Toolbar>
+    <MyToolbar />
+  </Spreadsheet.Toolbar>
+  <Spreadsheet.Grid />
+</Spreadsheet>
+```
+
+## Custom Context Menus
+
+The `contextMenuItems` prop adds items to the right-click menu after the built-in items (Copy, Paste, Clear, Freeze), separated by a divider.
+
+### Static items
+
+```tsx
+<Spreadsheet
+  data={data}
+  onChange={setData}
+  contextMenuItems={[
+    { label: "Highlight yellow", onClick: (addr) => highlight(addr, "#fef08a") },
+    { label: "Clear formatting", onClick: (addr) => clearFormat(addr) },
+  ]}
+>
+```
+
+### Dynamic items (context-aware)
+
+Pass a callback to return different items based on the active cell:
+
+```tsx
+<Spreadsheet
+  data={data}
+  onChange={setData}
+  contextMenuItems={(addr) => {
+    const cell = activeSheet.cells[addr];
+    const row = parseInt(addr.replace(/[A-Z]+/, ""), 10);
+
+    const items: SpreadsheetContextMenuItem[] = [];
+
+    // Comment actions depend on whether cell has a comment
+    if (cell?.comment) {
+      items.push({ label: "Edit Comment", onClick: (a) => openEditor(a) });
+      items.push({ label: "Delete Comment", danger: true, onClick: (a) => deleteComment(a) });
+    } else {
+      items.push({ label: "Add Comment", onClick: (a) => openEditor(a) });
+    }
+
+    // Row actions only for data rows
+    if (row >= 2) {
+      items.push({ label: "Delete Row", danger: true, onClick: (a) => deleteRow(a) });
+    }
+
+    return items;
+  }}
+>
+```
+
+### Nested submenus
+
+Add an `items` array to group actions into submenus:
+
+```tsx
+contextMenuItems={(addr) => [
+  {
+    label: "Comments",
+    items: [
+      { label: "Add Comment", onClick: (a) => openEditor(a) },
+    ],
+  },
+  {
+    label: "Row Actions",
+    items: [
+      { label: "Mark as Paid", onClick: (a) => markPaid(a) },
+      { label: "Duplicate Row", onClick: (a) => duplicateRow(a) },
+      { label: "Delete Row", danger: true, onClick: (a) => deleteRow(a) },
+    ],
+  },
+]}
+```
+
+Submenus nest arbitrarily deep — each item with `items` renders as a hover-to-open submenu with a chevron indicator.
+
+## Cell Metadata
+
+The `meta` field on `CellData` stores arbitrary consumer-defined data. The package preserves it through edits but never reads it — consumers use it to build domain-specific features like grouping, tagging, or variable bindings.
+
+```tsx
+s.cells = {
+  A1: { value: "Revenue",  meta: { group: "rev", role: "label" } },
+  B1: { value: 50000,      meta: { group: "rev", role: "variable" } },
+};
+```
+
+## Custom CSS Classes
+
+The `className` field on `CellFormat` applies custom CSS classes to individual cell elements. Use it for Tailwind utilities, conditional styling, animations, or any CSS your app needs.
+
+```tsx
+s.cells = {
+  A1: { value: "Header", format: { className: "font-semibold tracking-wide" } },
+  B1: { value: 42,       format: { className: "tabular-nums text-right" } },
+  C1: { value: "Alert",  format: { className: "animate-pulse bg-red-100" } },
+};
+```
+
+Classes are merged after the built-in cell classes via `cn()`, so Tailwind utilities work and can override defaults.
+
+## Cell Highlights
+
+The `highlights` prop renders visual overlays on cells independent of selection and formatting — colored outlines, background tints, and optional label badges.
+
+```ts
+interface CellHighlight {
+  color: string;            // outline color (CSS)
+  backgroundColor?: string; // tint (auto-derived at 10% opacity from hex if omitted)
+  label?: string;           // small badge in top-left corner
+}
+
+type CellHighlightMap = Record<string, CellHighlight>;
+```
+
+### Static highlights
 
 ```tsx
-// Static
-<Spreadsheet contextMenuItems={[
-  { label: "Highlight", onClick: (addr) => highlight(addr) },
-]}>
+<Sheet
+  data={sheet}
+  onChange={setSheet}
+  highlights={{
+    A1: { color: "#8b5cf6", label: "src" },
+    B1: { color: "#8b5cf6", label: "dst" },
+  }}
+/>
+```
+
+### Reactive highlights (grouping pattern)
+
+Use `onActiveCellChange` + `meta` to highlight related cells when the user clicks:
 
-// Dynamic (context-aware)
-<Spreadsheet contextMenuItems={(addr) => {
-  const cell = sheet.cells[addr];
-  return cell?.comment
-    ? [{ label: "Edit Comment", onClick: ... }, { label: "Delete Comment", danger: true, onClick: ... }]
-    : [{ label: "Add Comment", onClick: ... }];
-}}>
+```tsx
+const [activeAddr, setActiveAddr] = useState("A1");
+
+const highlights = useMemo<CellHighlightMap>(() => {
+  const group = (sheet.cells[activeAddr]?.meta as any)?.group;
+  if (!group) return {};
+  const map: CellHighlightMap = {};
+  for (const [addr, cell] of Object.entries(sheet.cells)) {
+    if ((cell.meta as any)?.group === group) {
+      map[addr] = {
+        color: "#8b5cf6",
+        label: (cell.meta as any)?.role,
+      };
+    }
+  }
+  return map;
+}, [activeAddr, sheet.cells]);
+
+<Sheet
+  data={sheet}
+  onChange={setSheet}
+  highlights={highlights}
+  onActiveCellChange={(addr) => setActiveAddr(addr)}
+/>
 ```
 
-Items appear after a separator below the built-in items (Copy, Paste, Clear, Freeze).
+Click a cell tagged with `meta: { group: "rev" }` and all cells in that group highlight with a purple outline, tinted background, and role badges ("var", "lbl").
 
 ## Custom Formulas
 
+Register custom functions that users can call in cell formulas with `=FUNCTION_NAME(...)`.
+
 ```tsx
 import { registerFunction } from "@particle-academy/fancy-sheets";
 import type { FormulaRangeFunction } from "@particle-academy/fancy-sheets";
+```
+
+### Basic function
 
-const myFormula: FormulaRangeFunction = (args) => {
+```tsx
+registerFunction("PRIORITY", (args) => {
   const value = Number(args[0]?.[0] ?? 0);
   return value > 100 ? "High" : "Low";
-};
+});
+
+// In a cell: =PRIORITY(A1)
+```
+
+### Function with multiple arguments
 
-registerFunction("PRIORITY", myFormula);
-// Usage in cells: =PRIORITY(A1)
+`args` is a 2D array — each argument may be a single value or a range of values:
+
+```tsx
+registerFunction("BUDGET_STATUS", (args) => {
+  const spent = Number(args[0]?.[0] ?? 0);    // first arg: single cell
+  const budget = Number(args[1]?.[0] ?? 0);   // second arg: single cell
+  if (!budget) return "N/A";
+  const ratio = spent / budget;
+  if (ratio > 1) return "Over Budget";
+  if (ratio > 0.9) return "Near Limit";
+  return "On Track";
+});
+
+// In a cell: =BUDGET_STATUS(C4, B4)
+```
+
+### Function that operates on ranges
+
+When a range like `A1:A10` is passed, `args[n]` contains all values in the range as a flat array:
+
+```tsx
+registerFunction("WEIGHTED_AVG", (args) => {
+  const values = args[0] ?? [];   // =WEIGHTED_AVG(B2:B10, C2:C10)
+  const weights = args[1] ?? [];
+  let sumProduct = 0, sumWeights = 0;
+  for (let i = 0; i < values.length; i++) {
+    const v = Number(values[i] ?? 0);
+    const w = Number(weights[i] ?? 0);
+    sumProduct += v * w;
+    sumWeights += w;
+  }
+  return sumWeights === 0 ? 0 : sumProduct / sumWeights;
+});
+
+// In a cell: =WEIGHTED_AVG(B2:B10, C2:C10)
 ```
 
+### Type signature
+
+```ts
+type FormulaRangeFunction = (args: CellValue[][]) => CellValue;
+// CellValue = string | number | boolean | null
+```
+
+- `args[0]` = first argument's values, `args[1]` = second, etc.
+- Single-cell arguments are `[value]` (array of one). Ranges are flat arrays.
+- Return a `CellValue`. Return a string starting with `#` for errors (e.g., `"#VALUE!"`).
+- Call `registerFunction` at module scope (before render). It's a global side-effect.
+
+### Built-in functions (80+)
+
+See [Formulas](./formulas.md) for the complete list: SUM, AVERAGE, IF, VLOOKUP, SUMIF, TODAY, CONCAT, and more.
+
 ## Helpers
 
 ```ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@particle-academy/fancy-sheets",
-  "version": "0.6.3",
+  "version": "0.7.0",
   "description": "Spreadsheet editor with formula engine, multi-sheet tabs, and full cell editing",
   "repository": {
     "type": "git",