@particle-academy/fancy-sheets 0.4.5 → 0.5.0

package/README.md

@@ -1,23 +1,18 @@
 # @particle-academy/fancy-sheets
 
-Spreadsheet editor with formula engine, multi-sheet tabs, and full cell editing. Part of the `@particle-academy` component ecosystem.
+A full-featured spreadsheet component with formulas, formatting, selection, multi-sheet workbooks, clipboard, CSV import/export, and undo/redo. Custom engine — no third-party dependency.
 
 ## Installation
 
 ```bash
-# npm
 npm install @particle-academy/fancy-sheets
-
-# pnpm
-pnpm add @particle-academy/fancy-sheets
-
-# yarn
-yarn add @particle-academy/fancy-sheets
+# or: pnpm add @particle-academy/fancy-sheets
+# or: yarn add @particle-academy/fancy-sheets
 ```
 
 **Peer dependencies:** `react >= 18`, `react-dom >= 18`, `@particle-academy/react-fancy >= 1.5`
 
-## Usage
+## Setup
 
 ```css
 @import "tailwindcss";
@@ -25,16 +20,15 @@ yarn add @particle-academy/fancy-sheets
 @source "../node_modules/@particle-academy/fancy-sheets/dist/**/*.js";
 ```
 
+## Quick Start
+
 ```tsx
-import { Spreadsheet, createEmptyWorkbook } from "@particle-academy/fancy-sheets";
-import "@particle-academy/fancy-sheets/styles.css";
+import { Spreadsheet } from "@particle-academy/fancy-sheets";
 
 function App() {
-  const [data, setData] = useState(createEmptyWorkbook());
-
   return (
-    <div style={{ height: 500 }}>
-      <Spreadsheet data={data} onChange={setData}>
+    <div style={{ height: 600 }}>
+      <Spreadsheet>
         <Spreadsheet.Toolbar />
         <Spreadsheet.Grid />
         <Spreadsheet.SheetTabs />
@@ -44,7 +38,15 @@ function App() {
 }
 ```
 
-The spreadsheet fills its container — set a fixed height on the parent element.
+The component fills its container — wrap it in a sized element (height is required).
+
+## Documentation
+
+| Topic | Doc |
+|-------|-----|
+| Full component API (props, sub-components, `useSpreadsheet` hook, data model, keyboard shortcuts) | [docs/Spreadsheet.md](./docs/Spreadsheet.md) |
+| 80+ built-in formula functions + custom function registration | [docs/formulas.md](./docs/formulas.md) |
+| CSV import / export utilities | [docs/csv.md](./docs/csv.md) |
 
 ## Commands
 
@@ -55,428 +57,15 @@ pnpm --filter @particle-academy/fancy-sheets lint     # Type-check (tsc --noEmit
 pnpm --filter @particle-academy/fancy-sheets clean    # Remove dist/
 ```
 
-## Component API
-
-### Compound Components
-
-| Component | Description |
-|-----------|-------------|
-| `Spreadsheet` | Root wrapper — state management, context provider |
-| `Spreadsheet.Toolbar` | Undo/redo, bold/italic/align buttons, formula bar |
-| `Spreadsheet.Grid` | Editable cell grid with headers, selection, editing |
-| `Spreadsheet.SheetTabs` | Multi-sheet tab bar with add/rename/delete |
-
-### Spreadsheet Props
-
-```ts
-interface SpreadsheetProps {
-  children: ReactNode;
-  className?: string;
-  data?: WorkbookData;             // Controlled workbook data
-  defaultData?: WorkbookData;      // Uncontrolled initial data
-  onChange?: (data: WorkbookData) => void;
-  columnCount?: number;            // Default: 26 (A-Z)
-  rowCount?: number;               // Default: 100
-  defaultColumnWidth?: number;     // Default: 100px
-  rowHeight?: number;              // Default: 28px
-  readOnly?: boolean;              // Default: false
-}
-```
-
-### useSpreadsheet Hook
-
-Access the spreadsheet context from custom components:
-
-```tsx
-import { useSpreadsheet } from "@particle-academy/fancy-sheets";
-
-function CustomToolbar() {
-  const { selection, setCellValue, setCellFormat, undo, redo } = useSpreadsheet();
-  // Build custom toolbar buttons
-}
-```
-
-**Context value:**
-
-| Property / Method | Description |
-|-------------------|-------------|
-| `workbook` | Current WorkbookData |
-| `activeSheet` | The currently active SheetData |
-| `selection` | Current SelectionState (activeCell, ranges) |
-| `editingCell` | Address of cell being edited (null if not editing) |
-| `editValue` | Current value in the cell editor |
-| `setCellValue(addr, value)` | Set a cell's value (triggers formula recalc) |
-| `setCellFormat(addrs, format)` | Apply formatting to cells |
-| `setSelection(cell)` | Select a single cell |
-| `extendSelection(cell)` | Extend selection range (shift+click) |
-| `addSelection(cell)` | Add to selection (ctrl+click) |
-| `navigate(direction, extend?)` | Move active cell (arrow keys) |
-| `startEdit(value?)` | Enter edit mode |
-| `confirmEdit()` | Confirm edit and move down |
-| `cancelEdit()` | Cancel edit (Escape) |
-| `resizeColumn(col, width)` | Set column width |
-| `addSheet()` | Add a new sheet |
-| `renameSheet(id, name)` | Rename a sheet |
-| `deleteSheet(id)` | Delete a sheet |
-| `setActiveSheet(id)` | Switch active sheet |
-| `undo()` / `redo()` | Undo/redo (50-step history) |
-| `canUndo` / `canRedo` | Whether undo/redo is available |
-| `getColumnWidth(col)` | Get column width in px |
-| `isCellSelected(addr)` | Check if cell is in selection |
-| `isCellActive(addr)` | Check if cell is the active cell |
-
-## Data Model
-
-### WorkbookData
-
-```ts
-interface WorkbookData {
-  sheets: SheetData[];
-  activeSheetId: string;
-}
-```
-
-### SheetData
-
-```ts
-interface SheetData {
-  id: string;
-  name: string;
-  cells: CellMap;                              // Record<CellAddress, CellData>
-  columnWidths: Record<number, number>;        // Column width overrides
-  mergedRegions: MergedRegion[];
-  columnFilters: Record<number, string>;
-  sortColumn?: number;
-  sortDirection?: "asc" | "desc";
-  frozenRows: number;
-  frozenCols: number;
-}
-```
-
-### CellData
-
-```ts
-interface CellData {
-  value: CellValue;             // string | number | boolean | null
-  formula?: string;             // Without leading "=", e.g. "SUM(A1:A5)"
-  computedValue?: CellValue;    // Result of formula evaluation
-  format?: CellFormat;          // { bold?, italic?, textAlign? }
-}
-```
-
-### Helpers
-
-```tsx
-import { createEmptyWorkbook, createEmptySheet } from "@particle-academy/fancy-sheets";
-
-const workbook = createEmptyWorkbook();              // One empty sheet
-const sheet = createEmptySheet("my-id", "My Sheet"); // Custom sheet
-```
-
-## Formula Engine
-
-Type `=` in any cell to enter a formula. The engine supports cell references, ranges, operators, and functions.
-
-### Cell References
-
-| Syntax | Example | Description |
-|--------|---------|-------------|
-| Cell ref | `=A1` | Single cell reference |
-| Range | `=A1:B5` | Rectangular range |
-| Arithmetic | `=A1+B1*2` | Operators: `+`, `-`, `*`, `/`, `^` |
-| Comparison | `=A1>10` | Operators: `=`, `<>`, `<`, `>`, `<=`, `>=` |
-| Concatenation | `=A1&" "&B1` | String join with `&` |
-
-### Built-in Functions (80+)
-
-**Math (25):**
-
-| Function | Example | Description |
-|----------|---------|-------------|
-| `SUM` | `=SUM(A1:A10)` | Sum of values |
-| `AVERAGE` | `=AVERAGE(B1:B5)` | Mean of values |
-| `MEDIAN` | `=MEDIAN(A1:A10)` | Median value |
-| `MIN` | `=MIN(C1:C10)` | Minimum value |
-| `MAX` | `=MAX(C1:C10)` | Maximum value |
-| `COUNT` | `=COUNT(A1:A20)` | Count of numeric values |
-| `PRODUCT` | `=PRODUCT(A1:A5)` | Multiply all values |
-| `ROUND` | `=ROUND(A1, 2)` | Round to N decimals |
-| `ABS` | `=ABS(A1)` | Absolute value |
-| `SQRT` | `=SQRT(A1)` | Square root |
-| `POWER` | `=POWER(2,10)` | Exponentiation |
-| `MOD` | `=MOD(10,3)` | Remainder |
-| `INT` | `=INT(3.7)` | Round down to integer |
-| `TRUNC` | `=TRUNC(3.789,1)` | Truncate decimals |
-| `FLOOR` | `=FLOOR(2.7,1)` | Round down to multiple |
-| `CEILING` | `=CEILING(2.1,1)` | Round up to multiple |
-| `SIGN` | `=SIGN(-5)` | Returns -1, 0, or 1 |
-| `FACT` | `=FACT(5)` | Factorial (120) |
-| `PI` | `=PI()` | 3.14159... |
-| `EXP` | `=EXP(1)` | e^n |
-| `LN` | `=LN(10)` | Natural logarithm |
-| `LOG` | `=LOG(100,10)` | Logarithm (default base 10) |
-| `LOG10` | `=LOG10(1000)` | Base-10 logarithm |
-| `RAND` | `=RAND()` | Random 0-1 |
-| `RANDBETWEEN` | `=RANDBETWEEN(1,100)` | Random integer |
-
-**Text (19):**
-
-| Function | Example | Description |
-|----------|---------|-------------|
-| `UPPER` | `=UPPER(A1)` | Uppercase |
-| `LOWER` | `=LOWER(A1)` | Lowercase |
-| `PROPER` | `=PROPER("hello world")` | Title Case |
-| `LEN` | `=LEN(A1)` | String length |
-| `TRIM` | `=TRIM(A1)` | Remove whitespace |
-| `LEFT` | `=LEFT(A1,3)` | First N characters |
-| `RIGHT` | `=RIGHT(A1,3)` | Last N characters |
-| `MID` | `=MID(A1,2,3)` | Substring from position |
-| `FIND` | `=FIND("x",A1)` | Case-sensitive position |
-| `SEARCH` | `=SEARCH("x",A1)` | Case-insensitive position |
-| `SUBSTITUTE` | `=SUBSTITUTE(A1,"old","new")` | Replace text |
-| `REPLACE` | `=REPLACE(A1,2,3,"xyz")` | Replace by position |
-| `CONCAT` | `=CONCAT(A1,B1)` | Join values |
-| `REPT` | `=REPT("*",5)` | Repeat string |
-| `EXACT` | `=EXACT(A1,B1)` | Case-sensitive compare |
-| `VALUE` | `=VALUE("42")` | Text to number |
-| `TEXT` | `=TEXT(0.5,"0%")` | Format number as text |
-| `CHAR` | `=CHAR(65)` | Character from code |
-| `CODE` | `=CODE("A")` | Code of first character |
-
-**Logic (8):**
-
-| Function | Example | Description |
-|----------|---------|-------------|
-| `IF` | `=IF(A1>10,"High","Low")` | Conditional value |
-| `AND` | `=AND(A1>0,B1>0)` | All conditions true |
-| `OR` | `=OR(A1>0,B1>0)` | Any condition true |
-| `NOT` | `=NOT(A1)` | Negate boolean |
-| `IFERROR` | `=IFERROR(A1/B1,0)` | Fallback on error |
-| `IFBLANK` | `=IFBLANK(A1,"N/A")` | Fallback if empty |
-| `SWITCH` | `=SWITCH(A1,1,"One",2,"Two")` | Multi-case conditional |
-| `CHOOSE` | `=CHOOSE(2,"a","b","c")` | Select by index |
-
-**Conditional Aggregates (8):**
-
-| Function | Example | Description |
-|----------|---------|-------------|
-| `SUMIF` | `=SUMIF(A1:A10,">5",B1:B10)` | Conditional sum |
-| `SUMIFS` | `=SUMIFS(C1:C10,A1:A10,">5",B1:B10,"<10")` | Multi-criteria sum |
-| `COUNTIF` | `=COUNTIF(A1:A10,"Yes")` | Conditional count |
-| `COUNTIFS` | `=COUNTIFS(A1:A10,">5",B1:B10,"<10")` | Multi-criteria count |
-| `AVERAGEIF` | `=AVERAGEIF(A1:A10,">0")` | Conditional average |
-| `AVERAGEIFS` | `=AVERAGEIFS(C1:C10,A1:A10,">5")` | Multi-criteria average |
-| `MINIFS` | `=MINIFS(C1:C10,A1:A10,">5")` | Conditional min |
-| `MAXIFS` | `=MAXIFS(C1:C10,A1:A10,">5")` | Conditional max |
-
-**Lookup (8):**
-
-| Function | Example | Description |
-|----------|---------|-------------|
-| `VLOOKUP` | `=VLOOKUP(key,A1:C10,3)` | Vertical lookup |
-| `HLOOKUP` | `=HLOOKUP(key,A1:Z3,2)` | Horizontal lookup |
-| `INDEX` | `=INDEX(A1:A10,3)` | Value at position |
-| `MATCH` | `=MATCH("x",A1:A10)` | Find position of value |
-| `ROWS` | `=ROWS(A1:A10)` | Count rows in range |
-| `COLUMNS` | `=COLUMNS(A1:C1)` | Count columns in range |
-| `ROW` | `=ROW(A5)` | Row number |
-| `COLUMN` | `=COLUMN(C1)` | Column number |
-
-**Date/Time (12):**
-
-| Function | Example | Description |
-|----------|---------|-------------|
-| `TODAY` | `=TODAY()` | Current date (serial) |
-| `NOW` | `=NOW()` | Current date+time (serial) |
-| `DATE` | `=DATE(2024,6,15)` | Create date |
-| `YEAR` | `=YEAR(A1)` | Extract year |
-| `MONTH` | `=MONTH(A1)` | Extract month |
-| `DAY` | `=DAY(A1)` | Extract day |
-| `HOUR` | `=HOUR(A1)` | Extract hour |
-| `MINUTE` | `=MINUTE(A1)` | Extract minute |
-| `SECOND` | `=SECOND(A1)` | Extract second |
-| `WEEKDAY` | `=WEEKDAY(A1)` | Day of week (1-7) |
-| `DATEDIF` | `=DATEDIF(A1,B1,"M")` | Date difference |
-| `EDATE` | `=EDATE(A1,3)` | Date + N months |
-
-**Info (6):**
-
-| Function | Example | Description |
-|----------|---------|-------------|
-| `ISBLANK` | `=ISBLANK(A1)` | Is empty |
-| `ISNUMBER` | `=ISNUMBER(A1)` | Is numeric |
-| `ISTEXT` | `=ISTEXT(A1)` | Is text |
-| `ISERROR` | `=ISERROR(A1)` | Is error value |
-| `ISLOGICAL` | `=ISLOGICAL(A1)` | Is boolean |
-| `TYPE` | `=TYPE(A1)` | Type code (1=num, 2=text, 4=bool, 16=error) |
-
-### Custom Functions
-
-Register custom formula functions:
-
-```tsx
-import { registerFunction } from "@particle-academy/fancy-sheets";
-
-registerFunction("DOUBLE", (args) => {
-  const val = args.flat()[0];
-  return typeof val === "number" ? val * 2 : "#VALUE!";
-});
-// Now use =DOUBLE(A1) in any cell
-```
-
-### Error Values
-
-| Error | Cause |
-|-------|-------|
-| `#ERROR!` | Invalid formula syntax |
-| `#VALUE!` | Wrong value type for operation |
-| `#DIV/0!` | Division by zero |
-| `#NAME?` | Unknown function name |
-| `#CIRC!` | Circular reference detected |
-
-### Dependency Tracking
-
-The formula engine builds a dependency graph and recalculates in topological order. When cell A1 changes, all cells that reference A1 (directly or transitively) are automatically recalculated. Circular references are detected and marked with `#CIRC!`.
-
-## Features
-
-### Editing
-- Click to select, double-click or type to start editing
-- Enter confirms and moves down, Tab moves right
-- Escape cancels edit
-- Delete/Backspace clears cell
-- Formula bar shows formula for selected cell
-
-### Navigation
-- Arrow keys move between cells
-- Shift+Arrow extends selection range
-- Tab/Shift+Tab moves right/left
-- Ctrl+Z undo, Ctrl+Y redo
-
-### Selection
-- Click to select single cell
-- Shift+Click to select range
-- Ctrl+Click for multi-select
-- Visual blue overlay on selected ranges
-
-### Formatting
-- Bold (B), Italic (I) toggle buttons
-- Text align: left, center, right
-- Applied via toolbar or programmatically
-
-### Clipboard
-- Ctrl+C copies selected range as TSV
-- Ctrl+V pastes TSV data starting at active cell
-- Works with external data from Excel/Google Sheets
-
-### CSV Support
-
-```tsx
-import { parseCSV, csvToWorkbook, workbookToCSV } from "@particle-academy/fancy-sheets";
-
-// Import
-const workbook = csvToWorkbook(csvString, "Imported Data");
-
-// Export
-const csv = workbookToCSV(workbook);
-```
-
-### Multi-Sheet
-- Tab bar at bottom shows all sheets
-- Click to switch, double-click to rename
-- "+" button adds new sheet
-- Delete button removes active sheet (minimum 1)
-
-### Column Resize
-- Drag column header borders to resize
-- Minimum width: 30px
-
-### Undo/Redo
-- 50-step history
-- Every cell edit, format change pushes to undo stack
-- Ctrl+Z / Ctrl+Y keyboard shortcuts
-
-## Customization
-
-All components render `data-fancy-sheets-*` attributes:
-
-| Attribute | Element |
-|-----------|---------|
-| `data-fancy-sheets` | Root container |
-| `data-fancy-sheets-toolbar` | Toolbar area |
-| `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 number cell |
-| `data-fancy-sheets-cell` | Individual cell |
-| `data-fancy-sheets-cell-editor` | Inline edit input |
-| `data-fancy-sheets-selection` | Selection overlay |
-| `data-fancy-sheets-resize-handle` | Column resize handle |
-| `data-fancy-sheets-tabs` | Sheet tab bar |
-
-## Architecture
-
-```
-src/
-├── types/
-│   ├── cell.ts                  # CellValue, CellData, CellFormat
-│   ├── sheet.ts                 # SheetData, WorkbookData, helpers
-│   ├── selection.ts             # CellRange, SelectionState
-│   └── formula.ts               # FormulaToken, FormulaASTNode
-├── engine/
-│   ├── cell-utils.ts            # Address parsing (A1 <-> row/col)
-│   ├── clipboard.ts             # TSV serialize/parse
-│   ├── csv.ts                   # CSV import/export
-│   ├── sorting.ts               # Column sort
-│   ├── history.ts               # Undo/redo stack
-│   └── formula/
-│       ├── lexer.ts             # Tokenize formula strings
-│       ├── parser.ts            # Recursive descent -> AST
-│       ├── evaluator.ts         # Evaluate AST with cell lookups
-│       ├── references.ts        # Extract cell refs from AST
-│       ├── dependency-graph.ts  # Dep tracking, circular detection
-│       └── functions/
-│           ├── registry.ts      # Function registry
-│           ├── math.ts          # SUM, AVERAGE, MIN, MAX, etc.
-│           ├── text.ts          # UPPER, LOWER, LEN, TRIM, CONCAT
-│           └── logic.ts         # IF, AND, OR, NOT
-├── hooks/
-│   └── use-spreadsheet-store.ts # Central reducer + actions
-├── components/
-│   ├── Spreadsheet/             # Root compound component
-│   ├── Toolbar/                 # Format buttons + formula bar
-│   ├── Grid/                    # Cell grid, editor, selection, resize
-│   └── SheetTabs/               # Multi-sheet tab bar
-├── index.ts                     # Public API
-└── styles.css                   # Base styles
-```
-
-## Demo
-
-Demo page at `/react-demos/spreadsheet` in the monorepo with pre-populated product catalog data and formulas.
-
----
-
-## Agent Guidelines
-
-### Component Pattern
-- Same compound component pattern as react-fancy: `Object.assign(Root, { Toolbar, Grid, SheetTabs })`
-- Context via `SpreadsheetContext` + `useSpreadsheet()` hook
-- State managed by `useReducer` with action-based mutations
+## At a Glance
 
-### Formula Engine
-- Pure functions in `engine/formula/` — no React imports
-- Lexer → Parser → Evaluator pipeline
-- Dependency graph rebuilt on cell changes, topological sort for recalc order
-- Functions registered via side-effect imports (listed in `sideEffects` in package.json)
+- **Compound component API** — `Spreadsheet` + `Toolbar` / `Grid` / `SheetTabs`
+- **`useSpreadsheet` hook** — full workbook state and actions accessible from any child
+- **80+ built-in formulas** — Math, Text, Logic, Conditional aggregates, Lookup, Date/Time, Info
+- **Multi-sheet workbooks** — cross-sheet references via `Sheet2!A1` syntax
+- **Features** — editing, navigation, selection (single, range, multi-range), formatting (bold/italic/align), clipboard (copy/cut/paste with TSV), column resize, freeze rows/cols, undo/redo (50 steps), drag-to-select
+- **Zero third-party dependencies** — custom lexer, parser, evaluator, and dependency graph
 
-### Data Model
-- Sparse cell map (`Record<CellAddress, CellData>`) — only stores non-empty cells
-- Formulas stored as strings, computed values cached in `computedValue`
-- Undo/redo via workbook snapshot stack (max 50)
+## License
 
-### Build
-- tsup: ESM, CJS, DTS
-- External: react, react-dom, @particle-academy/react-fancy
-- Zero other dependencies
-- Verify with `npm run build` from monorepo root
+MIT

package/dist/index.cjs

@@ -1838,6 +1838,21 @@ var Cell = react.memo(function Cell2({ address, row, col }) {
   if (cell?.format?.bold) formatStyle.fontWeight = "bold";
   if (cell?.format?.italic) formatStyle.fontStyle = "italic";
   if (cell?.format?.textAlign) formatStyle.textAlign = cell.format.textAlign;
+  if (cell?.format?.backgroundColor) formatStyle.backgroundColor = cell.format.backgroundColor;
+  if (cell?.format?.color) formatStyle.color = cell.format.color;
+  if (cell?.format?.fontSize) formatStyle.fontSize = cell.format.fontSize;
+  if (cell?.format?.borderTop) {
+    formatStyle.borderTopWidth = 1;
+    formatStyle.borderTopStyle = "solid";
+    formatStyle.borderTopColor = cell.format.borderTop;
+  }
+  if (cell?.format?.borderRight) formatStyle.borderRightColor = cell.format.borderRight;
+  if (cell?.format?.borderBottom) formatStyle.borderBottomColor = cell.format.borderBottom;
+  if (cell?.format?.borderLeft) {
+    formatStyle.borderLeftWidth = 1;
+    formatStyle.borderLeftStyle = "solid";
+    formatStyle.borderLeftColor = cell.format.borderLeft;
+  }
   return /* @__PURE__ */ jsxRuntime.jsx(
     "div",
     {
@@ -1997,7 +2012,8 @@ function SpreadsheetGrid({ className }) {
     setFrozenCols,
     extendSelection,
     undo,
-    redo
+    redo,
+    contextMenuItems
   } = useSpreadsheet();
   const containerRef = react.useRef(null);
   const handleKeyDown = react.useCallback(
@@ -2190,14 +2206,31 @@ function SpreadsheetGrid({ className }) {
       /* @__PURE__ */ jsxRuntime.jsx(reactFancy.ContextMenu.Item, { onClick: () => {
         const col = parseAddress(selection.activeCell).col;
         setFrozenCols(activeSheet.frozenCols > 0 ? 0 : col);
-      }, disabled: readOnly, children: activeSheet.frozenCols > 0 ? "Unfreeze columns" : "Freeze columns left" })
+      }, disabled: readOnly, children: activeSheet.frozenCols > 0 ? "Unfreeze columns" : "Freeze columns left" }),
+      (() => {
+        const items = typeof contextMenuItems === "function" ? contextMenuItems(selection.activeCell) : contextMenuItems;
+        if (!items || items.length === 0) return null;
+        return /* @__PURE__ */ jsxRuntime.jsxs(jsxRuntime.Fragment, { children: [
+          /* @__PURE__ */ jsxRuntime.jsx(reactFancy.ContextMenu.Separator, {}),
+          items.map((item, i) => /* @__PURE__ */ jsxRuntime.jsx(
+            reactFancy.ContextMenu.Item,
+            {
+              onClick: () => item.onClick(selection.activeCell),
+              disabled: typeof item.disabled === "function" ? item.disabled(selection.activeCell) : item.disabled,
+              danger: item.danger,
+              children: item.label
+            },
+            i
+          ))
+        ] });
+      })()
     ] })
   ] });
 }
 SpreadsheetGrid.displayName = "SpreadsheetGrid";
 var btnClass = "inline-flex items-center justify-center rounded px-2 py-1 text-[12px] font-medium text-zinc-600 transition-colors hover:bg-zinc-100 disabled:opacity-40 dark:text-zinc-300 dark:hover:bg-zinc-800";
 var activeBtnClass = "bg-zinc-200 dark:bg-zinc-700";
-function DefaultToolbar() {
+function DefaultToolbar({ extra }) {
   const {
     selection,
     activeSheet,
@@ -2389,7 +2422,11 @@ function DefaultToolbar() {
             /* @__PURE__ */ jsxRuntime.jsx("span", { className: "text-[8px]", children: "\u2192" })
           ]
         }
-      )
+      ),
+      extra && /* @__PURE__ */ jsxRuntime.jsxs(jsxRuntime.Fragment, { children: [
+        /* @__PURE__ */ jsxRuntime.jsx("div", { className: "mx-1 h-4 w-px bg-zinc-200 dark:bg-zinc-700" }),
+        extra
+      ] })
     ] }),
     /* @__PURE__ */ jsxRuntime.jsxs("div", { "data-fancy-sheets-formula-bar": "", className: "flex items-center gap-2 border-b border-zinc-200 px-2 py-1 dark:border-zinc-700", children: [
       /* @__PURE__ */ jsxRuntime.jsx("span", { className: "w-12 shrink-0 text-center text-[11px] font-medium text-zinc-500 dark:text-zinc-400", children: selection.activeCell }),
@@ -2408,8 +2445,8 @@ function DefaultToolbar() {
     ] })
   ] });
 }
-function SpreadsheetToolbar({ children, className }) {
-  return /* @__PURE__ */ jsxRuntime.jsx("div", { "data-fancy-sheets-toolbar": "", className: reactFancy.cn("", className), children: children ?? /* @__PURE__ */ jsxRuntime.jsx(DefaultToolbar, {}) });
+function SpreadsheetToolbar({ children, className, extra }) {
+  return /* @__PURE__ */ jsxRuntime.jsx("div", { "data-fancy-sheets-toolbar": "", className: reactFancy.cn("", className), children: children ?? /* @__PURE__ */ jsxRuntime.jsx(DefaultToolbar, { extra }) });
 }
 SpreadsheetToolbar.displayName = "SpreadsheetToolbar";
 function SpreadsheetSheetTabs({ className }) {
@@ -2506,7 +2543,8 @@ function SpreadsheetRoot({
   rowCount = 100,
   defaultColumnWidth = 100,
   rowHeight = 28,
-  readOnly = false
+  readOnly = false,
+  contextMenuItems
 }) {
   const { state, actions } = useSpreadsheetStore(data ?? defaultData);
   const onChangeRef = react.useRef(onChange);
@@ -2571,9 +2609,10 @@ function SpreadsheetRoot({
       getColumnWidth,
       isCellSelected,
       isCellActive,
+      contextMenuItems,
       _isDragging: isDraggingRef
     }),
-    [state, activeSheet, columnCount, rowCount, defaultColumnWidth, rowHeight, readOnly, actions, getColumnWidth, isCellSelected, isCellActive]
+    [state, activeSheet, columnCount, rowCount, defaultColumnWidth, rowHeight, readOnly, actions, getColumnWidth, isCellSelected, isCellActive, contextMenuItems]
   );
   return /* @__PURE__ */ jsxRuntime.jsx(SpreadsheetContext.Provider, { value: ctx, children: /* @__PURE__ */ jsxRuntime.jsx(
     "div",
@@ -2590,6 +2629,32 @@ var Spreadsheet = Object.assign(SpreadsheetRoot, {
   Grid: SpreadsheetGrid,
   SheetTabs: SpreadsheetSheetTabs
 });
+function Sheet({ data, onChange, contextMenuItems, ...props }) {
+  const workbook = react.useMemo(
+    () => data ? { sheets: [data], activeSheetId: data.id } : void 0,
+    [data]
+  );
+  const handleChange = react.useMemo(() => {
+    if (!onChange) return void 0;
+    return (wb) => onChange(wb.sheets[0]);
+  }, [onChange]);
+  return /* @__PURE__ */ jsxRuntime.jsx(Spreadsheet, { data: workbook, onChange: handleChange, contextMenuItems, ...props, children: /* @__PURE__ */ jsxRuntime.jsx(Spreadsheet.Grid, {}) });
+}
+Sheet.displayName = "Sheet";
+function SheetWorkbook({
+  hideToolbar = false,
+  hideTabs = false,
+  toolbarExtra,
+  contextMenuItems,
+  ...props
+}) {
+  return /* @__PURE__ */ jsxRuntime.jsxs(Spreadsheet, { ...props, contextMenuItems, children: [
+    !hideToolbar && /* @__PURE__ */ jsxRuntime.jsx(Spreadsheet.Toolbar, { extra: toolbarExtra }),
+    /* @__PURE__ */ jsxRuntime.jsx(Spreadsheet.Grid, {}),
+    !hideTabs && /* @__PURE__ */ jsxRuntime.jsx(Spreadsheet.SheetTabs, {})
+  ] });
+}
+SheetWorkbook.displayName = "SheetWorkbook";
 
 // src/engine/csv.ts
 function parseCSV(text) {
@@ -2687,6 +2752,8 @@ function workbookToCSV(workbook, sheetId) {
   return stringifyCSV(data);
 }
 
+exports.Sheet = Sheet;
+exports.SheetWorkbook = SheetWorkbook;
 exports.Spreadsheet = Spreadsheet;
 exports.columnToLetter = columnToLetter;
 exports.createEmptySheet = createEmptySheet;