@particle-academy/fancy-sheets 0.4.6 → 0.5.0

package/dist/index.d.cts

@@ -18,6 +18,20 @@ interface CellFormat {
     displayFormat?: CellDisplayFormat;
     /** Number of decimal places to display (for number/currency/percentage) */
     decimals?: number;
+    /** Background color (any CSS color value) */
+    backgroundColor?: string;
+    /** Font color (any CSS color value) */
+    color?: string;
+    /** Font size in pixels */
+    fontSize?: number;
+    /** Top border color (renders 1px solid) */
+    borderTop?: string;
+    /** Right border color */
+    borderRight?: string;
+    /** Bottom border color */
+    borderBottom?: string;
+    /** Left border color (renders 1px solid) */
+    borderLeft?: string;
 }
 /** A single cell's complete data */
 interface CellData {
@@ -76,6 +90,17 @@ interface SelectionState {
     ranges: CellRange[];
 }
 
+/** Custom context menu item for right-click menus */
+interface SpreadsheetContextMenuItem {
+    /** Display label */
+    label: string;
+    /** Called with the active cell address when the item is clicked */
+    onClick: (address: string) => void;
+    /** Whether the item is disabled — static or per-cell function */
+    disabled?: boolean | ((address: string) => boolean);
+    /** Render with danger styling */
+    danger?: boolean;
+}
 interface SpreadsheetProps {
     children: ReactNode;
     className?: string;
@@ -95,6 +120,8 @@ interface SpreadsheetProps {
     rowHeight?: number;
     /** Read-only mode */
     readOnly?: boolean;
+    /** Custom context menu items appended after built-in items */
+    contextMenuItems?: SpreadsheetContextMenuItem[] | ((address: string) => SpreadsheetContextMenuItem[]);
 }
 interface SpreadsheetContextValue {
     workbook: WorkbookData;
@@ -132,6 +159,8 @@ interface SpreadsheetContextValue {
     getColumnWidth: (col: number) => number;
     isCellSelected: (address: string) => boolean;
     isCellActive: (address: string) => boolean;
+    /** Custom context menu items from consumer */
+    contextMenuItems?: SpreadsheetContextMenuItem[] | ((address: string) => SpreadsheetContextMenuItem[]);
     /** @internal drag-to-select state */
     _isDragging: React.RefObject<boolean>;
 }
@@ -147,8 +176,10 @@ declare namespace SpreadsheetGrid {
 interface SpreadsheetToolbarProps {
     children?: React.ReactNode;
     className?: string;
+    /** Additional toolbar content appended after default buttons */
+    extra?: React.ReactNode;
 }
-declare function SpreadsheetToolbar({ children, className }: SpreadsheetToolbarProps): react_jsx_runtime.JSX.Element;
+declare function SpreadsheetToolbar({ children, className, extra }: SpreadsheetToolbarProps): react_jsx_runtime.JSX.Element;
 declare namespace SpreadsheetToolbar {
     var displayName: string;
 }
@@ -161,7 +192,7 @@ declare namespace SpreadsheetSheetTabs {
     var displayName: string;
 }
 
-declare function SpreadsheetRoot({ children, className, data, defaultData, onChange, columnCount, rowCount, defaultColumnWidth, rowHeight, readOnly, }: SpreadsheetProps): react_jsx_runtime.JSX.Element;
+declare function SpreadsheetRoot({ children, className, data, defaultData, onChange, columnCount, rowCount, defaultColumnWidth, rowHeight, readOnly, contextMenuItems, }: SpreadsheetProps): react_jsx_runtime.JSX.Element;
 declare namespace SpreadsheetRoot {
     var displayName: string;
 }
@@ -173,6 +204,62 @@ declare const Spreadsheet: typeof SpreadsheetRoot & {
 
 declare function useSpreadsheet(): SpreadsheetContextValue;
 
+interface SheetProps {
+    /** Single sheet data (controlled) */
+    data?: SheetData;
+    /** Called when sheet data changes */
+    onChange?: (data: SheetData) => void;
+    className?: string;
+    /** Number of columns (default: 26) */
+    columnCount?: number;
+    /** Number of rows (default: 100) */
+    rowCount?: number;
+    /** Default column width in px (default: 100) */
+    defaultColumnWidth?: number;
+    /** Row height in px (default: 28) */
+    rowHeight?: number;
+    /** Read-only mode */
+    readOnly?: boolean;
+    /** Custom context menu items */
+    contextMenuItems?: SpreadsheetContextMenuItem[] | ((address: string) => SpreadsheetContextMenuItem[]);
+}
+declare function Sheet({ data, onChange, contextMenuItems, ...props }: SheetProps): react_jsx_runtime.JSX.Element;
+declare namespace Sheet {
+    var displayName: string;
+}
+
+interface SheetWorkbookProps {
+    /** Controlled workbook data */
+    data?: WorkbookData;
+    /** Default data (uncontrolled) */
+    defaultData?: WorkbookData;
+    /** Called on any data change */
+    onChange?: (data: WorkbookData) => void;
+    className?: string;
+    /** Number of columns (default: 26) */
+    columnCount?: number;
+    /** Number of rows (default: 100) */
+    rowCount?: number;
+    /** Default column width in px (default: 100) */
+    defaultColumnWidth?: number;
+    /** Row height in px (default: 28) */
+    rowHeight?: number;
+    /** Read-only mode */
+    readOnly?: boolean;
+    /** Hide the toolbar (default: false) */
+    hideToolbar?: boolean;
+    /** Hide the sheet tabs (default: false) */
+    hideTabs?: boolean;
+    /** Extra content appended to the default toolbar */
+    toolbarExtra?: ReactNode;
+    /** Custom context menu items */
+    contextMenuItems?: SpreadsheetContextMenuItem[] | ((address: string) => SpreadsheetContextMenuItem[]);
+}
+declare function SheetWorkbook({ hideToolbar, hideTabs, toolbarExtra, contextMenuItems, ...props }: SheetWorkbookProps): react_jsx_runtime.JSX.Element;
+declare namespace SheetWorkbook {
+    var displayName: string;
+}
+
 /** Convert 0-based column index to letter(s): 0="A", 25="Z", 26="AA" */
 declare function columnToLetter(col: number): string;
 /** Convert column letter(s) to 0-based index: "A"=0, "Z"=25, "AA"=26 */
@@ -197,4 +284,4 @@ declare function workbookToCSV(workbook: WorkbookData, sheetId?: string): string
 type FormulaRangeFunction = (args: CellValue[][]) => CellValue;
 declare function registerFunction(name: string, fn: FormulaRangeFunction): void;
 
-export { type CellAddress, type CellData, type CellFormat, type CellMap, type CellRange, type CellValue, type ColumnWidths, type MergedRegion, type SelectionState, type SheetData, Spreadsheet, type SpreadsheetContextValue, type SpreadsheetProps, type TextAlign, type WorkbookData, columnToLetter, createEmptySheet, createEmptyWorkbook, csvToWorkbook, letterToColumn, parseAddress, parseCSV, registerFunction, stringifyCSV, toAddress, useSpreadsheet, workbookToCSV };
+export { type CellAddress, type CellData, type CellFormat, type CellMap, type CellRange, type CellValue, type ColumnWidths, type FormulaRangeFunction, type MergedRegion, type SelectionState, Sheet, type SheetData, type SheetProps, SheetWorkbook, type SheetWorkbookProps, Spreadsheet, type SpreadsheetContextMenuItem, type SpreadsheetContextValue, type SpreadsheetProps, type TextAlign, type WorkbookData, columnToLetter, createEmptySheet, createEmptyWorkbook, csvToWorkbook, letterToColumn, parseAddress, parseCSV, registerFunction, stringifyCSV, toAddress, useSpreadsheet, workbookToCSV };

package/dist/index.d.ts

@@ -18,6 +18,20 @@ interface CellFormat {
     displayFormat?: CellDisplayFormat;
     /** Number of decimal places to display (for number/currency/percentage) */
     decimals?: number;
+    /** Background color (any CSS color value) */
+    backgroundColor?: string;
+    /** Font color (any CSS color value) */
+    color?: string;
+    /** Font size in pixels */
+    fontSize?: number;
+    /** Top border color (renders 1px solid) */
+    borderTop?: string;
+    /** Right border color */
+    borderRight?: string;
+    /** Bottom border color */
+    borderBottom?: string;
+    /** Left border color (renders 1px solid) */
+    borderLeft?: string;
 }
 /** A single cell's complete data */
 interface CellData {
@@ -76,6 +90,17 @@ interface SelectionState {
     ranges: CellRange[];
 }
 
+/** Custom context menu item for right-click menus */
+interface SpreadsheetContextMenuItem {
+    /** Display label */
+    label: string;
+    /** Called with the active cell address when the item is clicked */
+    onClick: (address: string) => void;
+    /** Whether the item is disabled — static or per-cell function */
+    disabled?: boolean | ((address: string) => boolean);
+    /** Render with danger styling */
+    danger?: boolean;
+}
 interface SpreadsheetProps {
     children: ReactNode;
     className?: string;
@@ -95,6 +120,8 @@ interface SpreadsheetProps {
     rowHeight?: number;
     /** Read-only mode */
     readOnly?: boolean;
+    /** Custom context menu items appended after built-in items */
+    contextMenuItems?: SpreadsheetContextMenuItem[] | ((address: string) => SpreadsheetContextMenuItem[]);
 }
 interface SpreadsheetContextValue {
     workbook: WorkbookData;
@@ -132,6 +159,8 @@ interface SpreadsheetContextValue {
     getColumnWidth: (col: number) => number;
     isCellSelected: (address: string) => boolean;
     isCellActive: (address: string) => boolean;
+    /** Custom context menu items from consumer */
+    contextMenuItems?: SpreadsheetContextMenuItem[] | ((address: string) => SpreadsheetContextMenuItem[]);
     /** @internal drag-to-select state */
     _isDragging: React.RefObject<boolean>;
 }
@@ -147,8 +176,10 @@ declare namespace SpreadsheetGrid {
 interface SpreadsheetToolbarProps {
     children?: React.ReactNode;
     className?: string;
+    /** Additional toolbar content appended after default buttons */
+    extra?: React.ReactNode;
 }
-declare function SpreadsheetToolbar({ children, className }: SpreadsheetToolbarProps): react_jsx_runtime.JSX.Element;
+declare function SpreadsheetToolbar({ children, className, extra }: SpreadsheetToolbarProps): react_jsx_runtime.JSX.Element;
 declare namespace SpreadsheetToolbar {
     var displayName: string;
 }
@@ -161,7 +192,7 @@ declare namespace SpreadsheetSheetTabs {
     var displayName: string;
 }
 
-declare function SpreadsheetRoot({ children, className, data, defaultData, onChange, columnCount, rowCount, defaultColumnWidth, rowHeight, readOnly, }: SpreadsheetProps): react_jsx_runtime.JSX.Element;
+declare function SpreadsheetRoot({ children, className, data, defaultData, onChange, columnCount, rowCount, defaultColumnWidth, rowHeight, readOnly, contextMenuItems, }: SpreadsheetProps): react_jsx_runtime.JSX.Element;
 declare namespace SpreadsheetRoot {
     var displayName: string;
 }
@@ -173,6 +204,62 @@ declare const Spreadsheet: typeof SpreadsheetRoot & {
 
 declare function useSpreadsheet(): SpreadsheetContextValue;
 
+interface SheetProps {
+    /** Single sheet data (controlled) */
+    data?: SheetData;
+    /** Called when sheet data changes */
+    onChange?: (data: SheetData) => void;
+    className?: string;
+    /** Number of columns (default: 26) */
+    columnCount?: number;
+    /** Number of rows (default: 100) */
+    rowCount?: number;
+    /** Default column width in px (default: 100) */
+    defaultColumnWidth?: number;
+    /** Row height in px (default: 28) */
+    rowHeight?: number;
+    /** Read-only mode */
+    readOnly?: boolean;
+    /** Custom context menu items */
+    contextMenuItems?: SpreadsheetContextMenuItem[] | ((address: string) => SpreadsheetContextMenuItem[]);
+}
+declare function Sheet({ data, onChange, contextMenuItems, ...props }: SheetProps): react_jsx_runtime.JSX.Element;
+declare namespace Sheet {
+    var displayName: string;
+}
+
+interface SheetWorkbookProps {
+    /** Controlled workbook data */
+    data?: WorkbookData;
+    /** Default data (uncontrolled) */
+    defaultData?: WorkbookData;
+    /** Called on any data change */
+    onChange?: (data: WorkbookData) => void;
+    className?: string;
+    /** Number of columns (default: 26) */
+    columnCount?: number;
+    /** Number of rows (default: 100) */
+    rowCount?: number;
+    /** Default column width in px (default: 100) */
+    defaultColumnWidth?: number;
+    /** Row height in px (default: 28) */
+    rowHeight?: number;
+    /** Read-only mode */
+    readOnly?: boolean;
+    /** Hide the toolbar (default: false) */
+    hideToolbar?: boolean;
+    /** Hide the sheet tabs (default: false) */
+    hideTabs?: boolean;
+    /** Extra content appended to the default toolbar */
+    toolbarExtra?: ReactNode;
+    /** Custom context menu items */
+    contextMenuItems?: SpreadsheetContextMenuItem[] | ((address: string) => SpreadsheetContextMenuItem[]);
+}
+declare function SheetWorkbook({ hideToolbar, hideTabs, toolbarExtra, contextMenuItems, ...props }: SheetWorkbookProps): react_jsx_runtime.JSX.Element;
+declare namespace SheetWorkbook {
+    var displayName: string;
+}
+
 /** Convert 0-based column index to letter(s): 0="A", 25="Z", 26="AA" */
 declare function columnToLetter(col: number): string;
 /** Convert column letter(s) to 0-based index: "A"=0, "Z"=25, "AA"=26 */
@@ -197,4 +284,4 @@ declare function workbookToCSV(workbook: WorkbookData, sheetId?: string): string
 type FormulaRangeFunction = (args: CellValue[][]) => CellValue;
 declare function registerFunction(name: string, fn: FormulaRangeFunction): void;
 
-export { type CellAddress, type CellData, type CellFormat, type CellMap, type CellRange, type CellValue, type ColumnWidths, type MergedRegion, type SelectionState, type SheetData, Spreadsheet, type SpreadsheetContextValue, type SpreadsheetProps, type TextAlign, type WorkbookData, columnToLetter, createEmptySheet, createEmptyWorkbook, csvToWorkbook, letterToColumn, parseAddress, parseCSV, registerFunction, stringifyCSV, toAddress, useSpreadsheet, workbookToCSV };
+export { type CellAddress, type CellData, type CellFormat, type CellMap, type CellRange, type CellValue, type ColumnWidths, type FormulaRangeFunction, type MergedRegion, type SelectionState, Sheet, type SheetData, type SheetProps, SheetWorkbook, type SheetWorkbookProps, Spreadsheet, type SpreadsheetContextMenuItem, type SpreadsheetContextValue, type SpreadsheetProps, type TextAlign, type WorkbookData, columnToLetter, createEmptySheet, createEmptyWorkbook, csvToWorkbook, letterToColumn, parseAddress, parseCSV, registerFunction, stringifyCSV, toAddress, useSpreadsheet, workbookToCSV };

package/dist/index.js

@@ -1836,6 +1836,21 @@ var Cell = 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__ */ jsx(
     "div",
     {
@@ -1995,7 +2010,8 @@ function SpreadsheetGrid({ className }) {
     setFrozenCols,
     extendSelection,
     undo,
-    redo
+    redo,
+    contextMenuItems
   } = useSpreadsheet();
   const containerRef = useRef(null);
   const handleKeyDown = useCallback(
@@ -2188,14 +2204,31 @@ function SpreadsheetGrid({ className }) {
       /* @__PURE__ */ jsx(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__ */ jsxs(Fragment, { children: [
+          /* @__PURE__ */ jsx(ContextMenu.Separator, {}),
+          items.map((item, i) => /* @__PURE__ */ jsx(
+            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,
@@ -2387,7 +2420,11 @@ function DefaultToolbar() {
             /* @__PURE__ */ jsx("span", { className: "text-[8px]", children: "\u2192" })
           ]
         }
-      )
+      ),
+      extra && /* @__PURE__ */ jsxs(Fragment, { children: [
+        /* @__PURE__ */ jsx("div", { className: "mx-1 h-4 w-px bg-zinc-200 dark:bg-zinc-700" }),
+        extra
+      ] })
     ] }),
     /* @__PURE__ */ 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__ */ jsx("span", { className: "w-12 shrink-0 text-center text-[11px] font-medium text-zinc-500 dark:text-zinc-400", children: selection.activeCell }),
@@ -2406,8 +2443,8 @@ function DefaultToolbar() {
     ] })
   ] });
 }
-function SpreadsheetToolbar({ children, className }) {
-  return /* @__PURE__ */ jsx("div", { "data-fancy-sheets-toolbar": "", className: cn("", className), children: children ?? /* @__PURE__ */ jsx(DefaultToolbar, {}) });
+function SpreadsheetToolbar({ children, className, extra }) {
+  return /* @__PURE__ */ jsx("div", { "data-fancy-sheets-toolbar": "", className: cn("", className), children: children ?? /* @__PURE__ */ jsx(DefaultToolbar, { extra }) });
 }
 SpreadsheetToolbar.displayName = "SpreadsheetToolbar";
 function SpreadsheetSheetTabs({ className }) {
@@ -2504,7 +2541,8 @@ function SpreadsheetRoot({
   rowCount = 100,
   defaultColumnWidth = 100,
   rowHeight = 28,
-  readOnly = false
+  readOnly = false,
+  contextMenuItems
 }) {
   const { state, actions } = useSpreadsheetStore(data ?? defaultData);
   const onChangeRef = useRef(onChange);
@@ -2569,9 +2607,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__ */ jsx(SpreadsheetContext.Provider, { value: ctx, children: /* @__PURE__ */ jsx(
     "div",
@@ -2588,6 +2627,32 @@ var Spreadsheet = Object.assign(SpreadsheetRoot, {
   Grid: SpreadsheetGrid,
   SheetTabs: SpreadsheetSheetTabs
 });
+function Sheet({ data, onChange, contextMenuItems, ...props }) {
+  const workbook = useMemo(
+    () => data ? { sheets: [data], activeSheetId: data.id } : void 0,
+    [data]
+  );
+  const handleChange = useMemo(() => {
+    if (!onChange) return void 0;
+    return (wb) => onChange(wb.sheets[0]);
+  }, [onChange]);
+  return /* @__PURE__ */ jsx(Spreadsheet, { data: workbook, onChange: handleChange, contextMenuItems, ...props, children: /* @__PURE__ */ jsx(Spreadsheet.Grid, {}) });
+}
+Sheet.displayName = "Sheet";
+function SheetWorkbook({
+  hideToolbar = false,
+  hideTabs = false,
+  toolbarExtra,
+  contextMenuItems,
+  ...props
+}) {
+  return /* @__PURE__ */ jsxs(Spreadsheet, { ...props, contextMenuItems, children: [
+    !hideToolbar && /* @__PURE__ */ jsx(Spreadsheet.Toolbar, { extra: toolbarExtra }),
+    /* @__PURE__ */ jsx(Spreadsheet.Grid, {}),
+    !hideTabs && /* @__PURE__ */ jsx(Spreadsheet.SheetTabs, {})
+  ] });
+}
+SheetWorkbook.displayName = "SheetWorkbook";
 
 // src/engine/csv.ts
 function parseCSV(text) {
@@ -2685,6 +2750,6 @@ function workbookToCSV(workbook, sheetId) {
   return stringifyCSV(data);
 }
 
-export { Spreadsheet, columnToLetter, createEmptySheet, createEmptyWorkbook, csvToWorkbook, letterToColumn, parseAddress, parseCSV, registerFunction, stringifyCSV, toAddress, useSpreadsheet, workbookToCSV };
+export { Sheet, SheetWorkbook, Spreadsheet, columnToLetter, createEmptySheet, createEmptyWorkbook, csvToWorkbook, letterToColumn, parseAddress, parseCSV, registerFunction, stringifyCSV, toAddress, useSpreadsheet, workbookToCSV };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map