@particle-academy/fancy-sheets 0.6.3 → 0.7.0

package/dist/index.d.cts

@@ -32,6 +32,8 @@ interface CellFormat {
     borderBottom?: string;
     /** Left border color (renders 1px solid) */
     borderLeft?: string;
+    /** Custom CSS class(es) applied to the cell element */
+    className?: string;
 }
 /** Cell comment */
 interface CellComment {
@@ -42,6 +44,17 @@ interface CellComment {
     /** Comment color — used for the corner triangle indicator and cell border (default: #f59e0b / amber-500) */
     color?: string;
 }
+/** Consumer-driven cell highlight — rendered as a visual overlay, independent of selection and format */
+interface CellHighlight {
+    /** Border/outline color (any CSS color value) */
+    color: string;
+    /** Background tint — if omitted and color is hex, auto-derived at 10% opacity */
+    backgroundColor?: string;
+    /** Small label badge in the cell's top-left corner (e.g., "var", "lbl") */
+    label?: string;
+}
+/** Map of cell addresses to their highlights */
+type CellHighlightMap = Record<string, CellHighlight>;
 /** A single cell's complete data */
 interface CellData {
     /** The raw value (what the user typed) */
@@ -54,6 +67,8 @@ interface CellData {
     format?: CellFormat;
     /** Cell comment — shows a triangle indicator in the corner */
     comment?: CellComment;
+    /** Consumer-defined metadata — the package stores but never reads this */
+    meta?: Record<string, unknown>;
 }
 
 /** Sparse cell map — only stores cells that have data */
@@ -135,6 +150,10 @@ interface SpreadsheetProps {
     readOnly?: boolean;
     /** Custom context menu items appended after built-in items */
     contextMenuItems?: SpreadsheetContextMenuItem[] | ((address: string) => SpreadsheetContextMenuItem[]);
+    /** Consumer-driven cell highlights — rendered as visual overlays, independent of selection */
+    highlights?: CellHighlightMap;
+    /** Fires when the active cell changes */
+    onActiveCellChange?: (address: string, cell: CellData | undefined) => void;
 }
 interface SpreadsheetContextValue {
     workbook: WorkbookData;
@@ -174,6 +193,8 @@ interface SpreadsheetContextValue {
     isCellActive: (address: string) => boolean;
     /** Custom context menu items from consumer */
     contextMenuItems?: SpreadsheetContextMenuItem[] | ((address: string) => SpreadsheetContextMenuItem[]);
+    /** Consumer-provided cell highlights */
+    highlights: CellHighlightMap;
     /** @internal drag-to-select state */
     _isDragging: React.RefObject<boolean>;
 }
@@ -209,7 +230,7 @@ declare namespace SpreadsheetSheetTabs {
     var displayName: string;
 }
 
-declare function SpreadsheetRoot({ children, className, data, defaultData, onChange, columnCount, rowCount, defaultColumnWidth, rowHeight, readOnly, contextMenuItems, }: SpreadsheetProps): react_jsx_runtime.JSX.Element;
+declare function SpreadsheetRoot({ children, className, data, defaultData, onChange, columnCount, rowCount, defaultColumnWidth, rowHeight, readOnly, contextMenuItems, highlights, onActiveCellChange, }: SpreadsheetProps): react_jsx_runtime.JSX.Element;
 declare namespace SpreadsheetRoot {
     var displayName: string;
 }
@@ -239,8 +260,12 @@ interface SheetProps {
     readOnly?: boolean;
     /** Custom context menu items */
     contextMenuItems?: SpreadsheetContextMenuItem[] | ((address: string) => SpreadsheetContextMenuItem[]);
+    /** Consumer-driven cell highlights */
+    highlights?: CellHighlightMap;
+    /** Fires when the active cell changes */
+    onActiveCellChange?: (address: string, cell: CellData | undefined) => void;
 }
-declare function Sheet({ data, onChange, contextMenuItems, ...props }: SheetProps): react_jsx_runtime.JSX.Element;
+declare function Sheet({ data, onChange, contextMenuItems, highlights, onActiveCellChange, ...props }: SheetProps): react_jsx_runtime.JSX.Element;
 declare namespace Sheet {
     var displayName: string;
 }
@@ -273,8 +298,12 @@ interface SheetWorkbookProps {
     toolbarButtons?: ToolbarButton[];
     /** Custom context menu items */
     contextMenuItems?: SpreadsheetContextMenuItem[] | ((address: string) => SpreadsheetContextMenuItem[]);
+    /** Consumer-driven cell highlights */
+    highlights?: CellHighlightMap;
+    /** Fires when the active cell changes */
+    onActiveCellChange?: (address: string, cell: CellData | undefined) => void;
 }
-declare function SheetWorkbook({ hideToolbar, hideTabs, toolbarExtra, toolbarButtons, contextMenuItems, ...props }: SheetWorkbookProps): react_jsx_runtime.JSX.Element;
+declare function SheetWorkbook({ hideToolbar, hideTabs, toolbarExtra, toolbarButtons, contextMenuItems, highlights, onActiveCellChange, ...props }: SheetWorkbookProps): react_jsx_runtime.JSX.Element;
 declare namespace SheetWorkbook {
     var displayName: string;
 }
@@ -303,4 +332,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 CellComment, 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 ToolbarButton, type WorkbookData, columnToLetter, createEmptySheet, createEmptyWorkbook, csvToWorkbook, letterToColumn, parseAddress, parseCSV, registerFunction, stringifyCSV, toAddress, useSpreadsheet, workbookToCSV };
+export { type CellAddress, type CellComment, type CellData, type CellFormat, type CellHighlight, type CellHighlightMap, 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 ToolbarButton, type WorkbookData, columnToLetter, createEmptySheet, createEmptyWorkbook, csvToWorkbook, letterToColumn, parseAddress, parseCSV, registerFunction, stringifyCSV, toAddress, useSpreadsheet, workbookToCSV };

package/dist/index.d.ts

@@ -32,6 +32,8 @@ interface CellFormat {
     borderBottom?: string;
     /** Left border color (renders 1px solid) */
     borderLeft?: string;
+    /** Custom CSS class(es) applied to the cell element */
+    className?: string;
 }
 /** Cell comment */
 interface CellComment {
@@ -42,6 +44,17 @@ interface CellComment {
     /** Comment color — used for the corner triangle indicator and cell border (default: #f59e0b / amber-500) */
     color?: string;
 }
+/** Consumer-driven cell highlight — rendered as a visual overlay, independent of selection and format */
+interface CellHighlight {
+    /** Border/outline color (any CSS color value) */
+    color: string;
+    /** Background tint — if omitted and color is hex, auto-derived at 10% opacity */
+    backgroundColor?: string;
+    /** Small label badge in the cell's top-left corner (e.g., "var", "lbl") */
+    label?: string;
+}
+/** Map of cell addresses to their highlights */
+type CellHighlightMap = Record<string, CellHighlight>;
 /** A single cell's complete data */
 interface CellData {
     /** The raw value (what the user typed) */
@@ -54,6 +67,8 @@ interface CellData {
     format?: CellFormat;
     /** Cell comment — shows a triangle indicator in the corner */
     comment?: CellComment;
+    /** Consumer-defined metadata — the package stores but never reads this */
+    meta?: Record<string, unknown>;
 }
 
 /** Sparse cell map — only stores cells that have data */
@@ -135,6 +150,10 @@ interface SpreadsheetProps {
     readOnly?: boolean;
     /** Custom context menu items appended after built-in items */
     contextMenuItems?: SpreadsheetContextMenuItem[] | ((address: string) => SpreadsheetContextMenuItem[]);
+    /** Consumer-driven cell highlights — rendered as visual overlays, independent of selection */
+    highlights?: CellHighlightMap;
+    /** Fires when the active cell changes */
+    onActiveCellChange?: (address: string, cell: CellData | undefined) => void;
 }
 interface SpreadsheetContextValue {
     workbook: WorkbookData;
@@ -174,6 +193,8 @@ interface SpreadsheetContextValue {
     isCellActive: (address: string) => boolean;
     /** Custom context menu items from consumer */
     contextMenuItems?: SpreadsheetContextMenuItem[] | ((address: string) => SpreadsheetContextMenuItem[]);
+    /** Consumer-provided cell highlights */
+    highlights: CellHighlightMap;
     /** @internal drag-to-select state */
     _isDragging: React.RefObject<boolean>;
 }
@@ -209,7 +230,7 @@ declare namespace SpreadsheetSheetTabs {
     var displayName: string;
 }
 
-declare function SpreadsheetRoot({ children, className, data, defaultData, onChange, columnCount, rowCount, defaultColumnWidth, rowHeight, readOnly, contextMenuItems, }: SpreadsheetProps): react_jsx_runtime.JSX.Element;
+declare function SpreadsheetRoot({ children, className, data, defaultData, onChange, columnCount, rowCount, defaultColumnWidth, rowHeight, readOnly, contextMenuItems, highlights, onActiveCellChange, }: SpreadsheetProps): react_jsx_runtime.JSX.Element;
 declare namespace SpreadsheetRoot {
     var displayName: string;
 }
@@ -239,8 +260,12 @@ interface SheetProps {
     readOnly?: boolean;
     /** Custom context menu items */
     contextMenuItems?: SpreadsheetContextMenuItem[] | ((address: string) => SpreadsheetContextMenuItem[]);
+    /** Consumer-driven cell highlights */
+    highlights?: CellHighlightMap;
+    /** Fires when the active cell changes */
+    onActiveCellChange?: (address: string, cell: CellData | undefined) => void;
 }
-declare function Sheet({ data, onChange, contextMenuItems, ...props }: SheetProps): react_jsx_runtime.JSX.Element;
+declare function Sheet({ data, onChange, contextMenuItems, highlights, onActiveCellChange, ...props }: SheetProps): react_jsx_runtime.JSX.Element;
 declare namespace Sheet {
     var displayName: string;
 }
@@ -273,8 +298,12 @@ interface SheetWorkbookProps {
     toolbarButtons?: ToolbarButton[];
     /** Custom context menu items */
     contextMenuItems?: SpreadsheetContextMenuItem[] | ((address: string) => SpreadsheetContextMenuItem[]);
+    /** Consumer-driven cell highlights */
+    highlights?: CellHighlightMap;
+    /** Fires when the active cell changes */
+    onActiveCellChange?: (address: string, cell: CellData | undefined) => void;
 }
-declare function SheetWorkbook({ hideToolbar, hideTabs, toolbarExtra, toolbarButtons, contextMenuItems, ...props }: SheetWorkbookProps): react_jsx_runtime.JSX.Element;
+declare function SheetWorkbook({ hideToolbar, hideTabs, toolbarExtra, toolbarButtons, contextMenuItems, highlights, onActiveCellChange, ...props }: SheetWorkbookProps): react_jsx_runtime.JSX.Element;
 declare namespace SheetWorkbook {
     var displayName: string;
 }
@@ -303,4 +332,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 CellComment, 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 ToolbarButton, type WorkbookData, columnToLetter, createEmptySheet, createEmptyWorkbook, csvToWorkbook, letterToColumn, parseAddress, parseCSV, registerFunction, stringifyCSV, toAddress, useSpreadsheet, workbookToCSV };
+export { type CellAddress, type CellComment, type CellData, type CellFormat, type CellHighlight, type CellHighlightMap, 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 ToolbarButton, type WorkbookData, columnToLetter, createEmptySheet, createEmptyWorkbook, csvToWorkbook, letterToColumn, parseAddress, parseCSV, registerFunction, stringifyCSV, toAddress, useSpreadsheet, workbookToCSV };

package/dist/index.js

@@ -1343,6 +1343,8 @@ function reducer(state, action) {
       const sheet = getActiveSheet(state);
       const existing = sheet.cells[action.address];
       if (existing?.format) cellData.format = existing.format;
+      if (existing?.meta) cellData.meta = existing.meta;
+      if (existing?.comment) cellData.comment = existing.comment;
       const updatedWorkbook = updateActiveSheet(state, (s) => ({
         ...s,
         cells: { ...s.cells, [action.address]: cellData }
@@ -1799,9 +1801,11 @@ var Cell = memo(function Cell2({ address, row, col }) {
     getColumnWidth,
     isCellSelected,
     isCellActive,
+    highlights,
     _isDragging
   } = useSpreadsheet();
   const cell = activeSheet.cells[address];
+  const highlight = highlights[address];
   const isActive = isCellActive(address);
   const isSelected = isCellSelected(address);
   const isEditing = editingCell === address;
@@ -1869,11 +1873,13 @@ var Cell = memo(function Cell2({ address, row, col }) {
       "data-fancy-sheets-cell": "",
       "data-selected": isSelected || void 0,
       "data-active": isActive || void 0,
+      "data-highlighted": !!highlight || void 0,
       role: "gridcell",
       className: cn(
         "relative flex items-center truncate border-r border-b border-zinc-200 bg-white px-1.5 text-[13px] select-none dark:border-zinc-700 dark:bg-zinc-900",
         isActive && "ring-2 ring-inset ring-blue-500",
-        isSelected && !isActive && "bg-blue-50 dark:bg-blue-950/40"
+        isSelected && !isActive && "bg-blue-50 dark:bg-blue-950/40",
+        cell?.format?.className
       ),
       style: { width, minWidth: width, height: rowHeight, ...formatStyle },
       onMouseDown: handleMouseDown,
@@ -1887,6 +1893,27 @@ var Cell = memo(function Cell2({ address, row, col }) {
       },
       onDoubleClick: handleDoubleClick,
       children: [
+        highlight && /* @__PURE__ */ jsx(
+          "div",
+          {
+            className: "pointer-events-none absolute inset-0",
+            style: {
+              outline: `2px solid ${highlight.color}`,
+              outlineOffset: "-2px",
+              backgroundColor: highlight.backgroundColor ?? (highlight.color.startsWith("#") ? `${highlight.color}1A` : void 0)
+            },
+            "aria-hidden": true
+          }
+        ),
+        highlight?.label && /* @__PURE__ */ jsx(
+          "span",
+          {
+            className: "pointer-events-none absolute top-0 left-0 z-[1] px-0.5 text-[8px] font-bold leading-none text-white",
+            style: { backgroundColor: highlight.color },
+            "aria-hidden": true,
+            children: highlight.label
+          }
+        ),
         !isEditing && /* @__PURE__ */ jsx("span", { className: "truncate", children: displayValue }),
         comment && /* @__PURE__ */ jsx(
           "div",
@@ -2582,7 +2609,9 @@ function SpreadsheetRoot({
   defaultColumnWidth = 100,
   rowHeight = 28,
   readOnly = false,
-  contextMenuItems
+  contextMenuItems,
+  highlights,
+  onActiveCellChange
 }) {
   const { state, actions } = useSpreadsheetStore(data ?? defaultData);
   const onChangeRef = useRef(onChange);
@@ -2628,7 +2657,15 @@ function SpreadsheetRoot({
     (address) => state.selection.activeCell === address,
     [state.selection.activeCell]
   );
+  const onActiveCellChangeRef = useRef(onActiveCellChange);
+  onActiveCellChangeRef.current = onActiveCellChange;
+  useEffect(() => {
+    const addr = state.selection.activeCell;
+    const cell = activeSheet.cells[addr];
+    onActiveCellChangeRef.current?.(addr, cell);
+  }, [state.selection.activeCell, activeSheet]);
   const isDraggingRef = useRef(false);
+  const highlightsResolved = highlights ?? {};
   const ctx = useMemo(
     () => ({
       workbook: state.workbook,
@@ -2648,9 +2685,10 @@ function SpreadsheetRoot({
       isCellSelected,
       isCellActive,
       contextMenuItems,
+      highlights: highlightsResolved,
       _isDragging: isDraggingRef
     }),
-    [state, activeSheet, columnCount, rowCount, defaultColumnWidth, rowHeight, readOnly, actions, getColumnWidth, isCellSelected, isCellActive, contextMenuItems]
+    [state, activeSheet, columnCount, rowCount, defaultColumnWidth, rowHeight, readOnly, actions, getColumnWidth, isCellSelected, isCellActive, contextMenuItems, highlightsResolved]
   );
   return /* @__PURE__ */ jsx(SpreadsheetContext.Provider, { value: ctx, children: /* @__PURE__ */ jsx(
     "div",
@@ -2667,7 +2705,7 @@ var Spreadsheet = Object.assign(SpreadsheetRoot, {
   Grid: SpreadsheetGrid,
   SheetTabs: SpreadsheetSheetTabs
 });
-function Sheet({ data, onChange, contextMenuItems, ...props }) {
+function Sheet({ data, onChange, contextMenuItems, highlights, onActiveCellChange, ...props }) {
   const workbook = useMemo(
     () => data ? { sheets: [data], activeSheetId: data.id } : void 0,
     [data]
@@ -2676,7 +2714,7 @@ function Sheet({ data, onChange, contextMenuItems, ...props }) {
     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, {}) });
+  return /* @__PURE__ */ jsx(Spreadsheet, { data: workbook, onChange: handleChange, contextMenuItems, highlights, onActiveCellChange, ...props, children: /* @__PURE__ */ jsx(Spreadsheet.Grid, {}) });
 }
 Sheet.displayName = "Sheet";
 function SheetWorkbook({
@@ -2685,9 +2723,11 @@ function SheetWorkbook({
   toolbarExtra,
   toolbarButtons,
   contextMenuItems,
+  highlights,
+  onActiveCellChange,
   ...props
 }) {
-  return /* @__PURE__ */ jsxs(Spreadsheet, { ...props, contextMenuItems, children: [
+  return /* @__PURE__ */ jsxs(Spreadsheet, { ...props, contextMenuItems, highlights, onActiveCellChange, children: [
     !hideToolbar && /* @__PURE__ */ jsx(Spreadsheet.Toolbar, { extra: toolbarExtra, buttons: toolbarButtons }),
     /* @__PURE__ */ jsx(Spreadsheet.Grid, {}),
     !hideTabs && /* @__PURE__ */ jsx(Spreadsheet.SheetTabs, {})