
Solo/Trial license	If you are a solo developer working on a single application.	Not for commercial use
Professional license	If you are a developer looking for a full featured spreadsheet for commercial usage
Enterprise license	If you are deploying the Spreadsheet inside your organization. Commercial use with no limit on number of applications

Add Notes

setNotes(e.target.value)}
        placeholder="Enter your notes here..."
      />
      <button
        className="bg-blue-500 text-white px-4 py-2 rounded hover:bg-blue-600"
        onClick={() => console.log("Save notes:", notes)}
      >
        Save
      </button>
    </div>
  );
};
```

#### Data Visualization

```tsx
import { Chart } from "react-chartjs-2";

const getCellExpandContent = () => {
  const chartData = {
    labels: ["Jan", "Feb", "Mar", "Apr", "May"],
    datasets: [
      {
        label: "Sales",
        data: [12, 19, 3, 5, 2],
        backgroundColor: "rgba(75, 192, 192, 0.2)",
        borderColor: "rgba(75, 192, 192, 1)",
      },
    ],
  };

return (
    <div className="p-4 max-w-2xl">
      <h3 className="font-bold mb-4">Sales Trend</h3>
      <Chart type="line" data={chartData} />
    </div>
  );
};
```

## Cell-Specific Content

Customize content based on the cell being expanded:

```tsx
import { useSpreadsheet } from "@rowsncolumns/spreadsheet";

function SpreadsheetWithDynamicContent() {
  const { activeCell } = useSpreadsheet();

const getCellExpandContent = useCallback(() => {
    const cellData = getCellData(
      activeSheetId,
      activeCell.rowIndex,
      activeCell.columnIndex
    );

// Different content based on cell value
    if (cellData?.fv?.includes("Task")) {
      return <TaskDetailsPanel cellData={cellData} />;
    }

if (cellData?.fv?.includes("User")) {
      return <UserProfilePanel cellData={cellData} />;
    }

// Default content
    return (
      <div className="p-4">
        <p>No additional information available</p>
      </div>
    );
  }, [activeCell, activeSheetId]);

return (
    <CanvasGrid
      getCellExpandContent={getCellExpandContent}
      // ... other props
    />
  );
}
```

## Complete Example

```tsx
import React, { useState, useCallback } from "react";
import {
  SpreadsheetProvider,
  CanvasGrid,
  Sheet,
} from "@rowsncolumns/spreadsheet";
import {
  useSpreadsheetState,
  SheetData,
  CellData,
} from "@rowsncolumns/spreadsheet-state";
import { cellToAddress } from "@rowsncolumns/utils";

function EnhancedSpreadsheet() {
  const [sheets, setSheets] = useState<Sheet[]>([
    { sheetId: 1, rowCount: 100, columnCount: 26, title: "Data" }
  ]);
  const [sheetData, setSheetData] = useState<SheetData<CellData>>({});

const {
    activeCell,
    activeSheetId,
    selections,
    getCellData,
    onChangeActiveCell,
    onChangeSelections,
  } = useSpreadsheetState({
    sheets,
    sheetData,
    onChangeSheets: setSheets,
    onChangeSheetData: setSheetData,
  });

// Tooltip handler
  const getTooltipContent = useCallback(
    (sheetId: number, rowIndex: number, columnIndex: number) => {
      // Skip headers
      if (rowIndex === 0 || columnIndex === 0) return undefined;

const cellData = getCellData(sheetId, rowIndex, columnIndex);

if (!cellData) return undefined;

const address = cellToAddress({ rowIndex, columnIndex });

return (
        <div className="p-3 bg-white shadow-lg rounded-lg border">
          <div className="text-xs text-gray-500 mb-1">{address}</div>
          {cellData.note && (
            <div className="text-sm border-t pt-2 mt-2">
              <strong className="text-gray-700">Note:</strong>
              <div className="text-gray-600 mt-1">{cellData.note}</div>
            </div>
          )}
          {cellData.hyperlink && (
            <div className="text-sm border-t pt-2 mt-2">
              <strong className="text-blue-700">Link:</strong>
              <a
                href={cellData.hyperlink}
                className="text-blue-600 hover:underline ml-1"
              >
                {cellData.hyperlink}
              </a>
            </div>
          )}
        </div>
      );
    },
    [getCellData]
  );

// Expandable content handler
  const getCellExpandContent = useCallback(() => {
    const cellData = getCellData(
      activeSheetId,
      activeCell.rowIndex,
      activeCell.columnIndex
    );

return (
      <div className="overflow-auto max-h-96 max-w-2xl p-6 bg-white rounded-lg">
        <h2 className="text-xl font-bold mb-4">Cell Details</h2>

<div className="space-y-4">
          <div>
            <strong className="text-gray-700">Location:</strong>
            <span className="ml-2">
              {cellToAddress({
                rowIndex: activeCell.rowIndex,
                columnIndex: activeCell.columnIndex,
              })}
            </span>
          </div>

{cellData?.fv && (
            <div>
              <strong className="text-gray-700">Value:</strong>
              <div className="mt-1 p-3 bg-gray-50 rounded font-mono text-sm">
                {cellData.fv}
              </div>
            </div>
          )}

{cellData?.ue?.fv && (
            <div>
              <strong className="text-gray-700">Formula:</strong>
              <div className="mt-1 p-3 bg-blue-50 rounded font-mono text-sm">
                {cellData.ue.fv}
              </div>
            </div>
          )}

<div className="border-t pt-4">
            <button className="bg-blue-500 text-white px-4 py-2 rounded hover:bg-blue-600">
              Edit Cell
            </button>
          </div>
        </div>
      </div>
    );
  }, [activeCell, activeSheetId, getCellData]);

return (
    <SpreadsheetProvider>
      <CanvasGrid
        sheetId={activeSheetId}
        activeCell={activeCell}
        selections={selections}
        getCellData={getCellData}
        onChangeActiveCell={onChangeActiveCell}
        onChangeSelections={onChangeSelections}
        getTooltipContent={getTooltipContent}
        getCellExpandContent={getCellExpandContent}
      />
    </SpreadsheetProvider>
  );
}

export default EnhancedSpreadsheet;
```

## Styling

### Tooltip Styling

Tooltips automatically position themselves to avoid going off-screen. Style them using standard CSS classes:

```tsx
const getTooltipContent = () => (
  <div className="p-3 bg-gray-900 text-white rounded-lg shadow-xl max-w-xs">
    <div className="text-sm">Your tooltip content</div>
  </div>
);
```

### Popover Styling

Expandable content appears in a popover with scrolling support:

```tsx
const getCellExpandContent = () => (
  <div className="overflow-auto max-h-96 max-w-4xl p-6">
    {/* Scrollable content */}
  </div>
);
```

## Use Cases

### Data Annotations

Show additional context or metadata for cells containing important data.

### Error Explanations

Display helpful error messages and suggestions when formulas fail.

### Rich Content Preview

Preview images, charts, or formatted text without cluttering the grid.

### Interactive Dialogs

Provide forms or interactive elements for complex data entry.

### Audit Information

Display who last edited a cell and when.

## Performance Considerations

1. **Memoize Callbacks**: Use `useCallback` to prevent unnecessary re-renders
2. **Conditional Rendering**: Return `undefined` when no tooltip is needed
3. **Lazy Loading**: Load heavy content only when the popover is opened
4. **Limit Complexity**: Keep tooltip content simple for smooth hover interactions

## Best Practices

1. **Keep Tooltips Concise**: Display only essential information in tooltips
2. **Use Popovers for Rich Content**: Save complex content for expandable popovers
3. **Avoid Heavy Computations**: Don't perform expensive calculations in tooltip callbacks
4. **Accessibility**: Ensure tooltips and popovers work with keyboard navigation
5. **Consistent Styling**: Match your application's design system

## Troubleshooting

### Tooltips Not Showing

* Verify `getTooltipContent` returns valid JSX or undefined (not null)
* Check that the function is properly passed to CanvasGrid
* Ensure there are no JavaScript errors in the console

### Popovers Not Opening

* Confirm `getCellExpandContent` is defined
* Check that the cell expansion trigger is working (usually double-click or icon)
* Verify the content isn't too large or causing layout issues

### Performance Issues

* Use `React.memo` for complex tooltip components
* Implement lazy loading for heavy content
* Consider debouncing tooltip display

# Multi-Instance Spreadsheets

Run multiple spreadsheet instances in the same application

The `SpreadsheetMultiInstanceProvider` component allows you to render multiple spreadsheet instances within the same application while maintaining isolated state and preventing conflicts between instances.

## Overview

By default, each spreadsheet instance shares global context through `SpreadsheetProvider`. When you need to render multiple spreadsheets simultaneously (e.g., side-by-side comparison, multi-document interface), you need to wrap them in `SpreadsheetMultiInstanceProvider` to ensure proper isolation.

## Basic Usage

```tsx
import {
  SpreadsheetProvider,
  SpreadsheetMultiInstanceProvider,
  CanvasGrid,
} from "@rowsncolumns/spreadsheet";
import { useSpreadsheetState } from "@rowsncolumns/spreadsheet-state";

function MultiSpreadsheetApp() {
  return (
    <SpreadsheetMultiInstanceProvider>
      <SpreadsheetProvider>
        <SpreadsheetInstance instanceId="spreadsheet-1" />
      </SpreadsheetProvider>

<SpreadsheetProvider>
        <SpreadsheetInstance instanceId="spreadsheet-2" />
      </SpreadsheetProvider>
    </SpreadsheetMultiInstanceProvider>
  );
}

function SpreadsheetInstance({ instanceId }: { instanceId: string }) {
  const {
    activeCell,
    activeSheetId,
    selections,
    // ... other state
  } = useSpreadsheetState({
    // configuration
  });

return (
    <CanvasGrid
      instanceId={instanceId}
      sheetId={activeSheetId}
      activeCell={activeCell}
      selections={selections}
      // ... other props
    />
  );
}
```

## Instance ID

Each `CanvasGrid` instance should have a unique `instanceId` prop when rendered within `SpreadsheetMultiInstanceProvider`:

```tsx
<CanvasGrid
  instanceId="spreadsheet-a"  // Unique identifier
  sheetId={activeSheetId}
  // ... other props
/>
```

### Why Instance IDs Matter

Instance IDs ensure that:

* Keyboard events are routed to the correct spreadsheet
* Editor state is isolated between instances
* Context menus and dialogs appear in the correct location
* Formula evaluation doesn't cross instance boundaries

## Use Cases

### Side-by-Side Comparison

Compare two spreadsheets side by side:

```tsx
function SpreadsheetComparison() {
  return (
    <SpreadsheetMultiInstanceProvider>
      <div className="flex gap-4">
        <div className="flex-1">
          <h2>Version 1</h2>
          <SpreadsheetProvider>
            <SpreadsheetView instanceId="version-1" />
          </SpreadsheetProvider>
        </div>

<div className="flex-1">
          <h2>Version 2</h2>
          <SpreadsheetProvider>
            <SpreadsheetView instanceId="version-2" />
          </SpreadsheetProvider>
        </div>
      </div>
    </SpreadsheetMultiInstanceProvider>
  );
}
```

### Multi-Document Interface

Create a tabbed or windowed interface with multiple spreadsheet documents:

```tsx
function MultiDocumentInterface() {
  const [documents] = useState([
    { id: "doc-1", name: "Budget 2024" },
    { id: "doc-2", name: "Sales Report" },
    { id: "doc-3", name: "Inventory" },
  ]);

return (
    <SpreadsheetMultiInstanceProvider>
      {documents.map((doc) => (
        <SpreadsheetProvider key={doc.id}>
          <div className="document-window">
            <h3>{doc.name}</h3>
            <SpreadsheetView instanceId={doc.id} />
          </div>
        </SpreadsheetProvider>
      ))}
    </SpreadsheetMultiInstanceProvider>
  );
}
```

### Master-Detail View

Display a master spreadsheet with a detail view:

```tsx
function MasterDetailView() {
  const [selectedRow, setSelectedRow] = useState<number | null>(null);

return (
    <SpreadsheetMultiInstanceProvider>
      <div className="grid grid-cols-2 gap-4">
        {/* Master spreadsheet */}
        <SpreadsheetProvider>
          <h2>Sales Overview</h2>
          <SpreadsheetView
            instanceId="master"
            onRowSelect={setSelectedRow}
          />
        </SpreadsheetProvider>

{/* Detail spreadsheet */}
        {selectedRow && (
          <SpreadsheetProvider>
            <h2>Row Details</h2>
            <SpreadsheetView
              instanceId="detail"
              rowData={selectedRow}
            />
          </SpreadsheetProvider>
        )}
      </div>
    </SpreadsheetMultiInstanceProvider>
  );
}
```

## Complete Example

```tsx
import React, { useState } from "react";
import {
  SpreadsheetProvider,
  SpreadsheetMultiInstanceProvider,
  CanvasGrid,
  Sheet,
} from "@rowsncolumns/spreadsheet";
import {
  useSpreadsheetState,
  SheetData,
  CellData,
} from "@rowsncolumns/spreadsheet-state";

function App() {
  return (
    <SpreadsheetMultiInstanceProvider>
      <div className="flex gap-5 h-screen p-5">
        <div className="flex-1">
          <SpreadsheetProvider>
            <SpreadsheetA />
          </SpreadsheetProvider>
        </div>

<div className="flex-1">
          <SpreadsheetProvider>
            <SpreadsheetB />
          </SpreadsheetProvider>
        </div>
      </div>
    </SpreadsheetMultiInstanceProvider>
  );
}

function SpreadsheetA() {
  const [sheets, setSheets] = useState<Sheet[]>([
    { sheetId: 1, rowCount: 100, columnCount: 26, title: "Sheet A" }
  ]);
  const [sheetData, setSheetData] = useState<SheetData<CellData>>({});

const {
    activeCell,
    activeSheetId,
    selections,
    getCellData,
    onChangeActiveCell,
    onChangeSelections,
    onChange,
  } = useSpreadsheetState({
    sheets,
    sheetData,
    onChangeSheets: setSheets,
    onChangeSheetData: setSheetData,
  });

return (
    <CanvasGrid
      instanceId="spreadsheet-a"
      sheetId={activeSheetId}
      activeCell={activeCell}
      selections={selections}
      getCellData={getCellData}
      onChangeActiveCell={onChangeActiveCell}
      onChangeSelections={onChangeSelections}
      onChange={onChange}
    />
  );
}

function SpreadsheetB() {
  // Similar implementation with different instance ID
  // ...

return (
    <CanvasGrid
      instanceId="spreadsheet-b"
      // ... props
    />
  );
}
```

## Best Practices

1. **Always Use Unique Instance IDs**: Ensure each spreadsheet has a unique `instanceId` to prevent conflicts
2. **Wrap Each Instance**: Each spreadsheet should have its own `SpreadsheetProvider` wrapper
3. **Isolate State**: Use separate state management for each spreadsheet instance
4. **Performance Considerations**: Be mindful of rendering multiple large spreadsheets simultaneously - consider lazy loading or virtualization
5. **Memory Management**: Clean up instances when they're no longer needed to free up resources

## Limitations

* Each instance maintains its own calculation engine and state
* Cross-instance formulas are not supported (formulas cannot reference cells from other instances)
* Each instance requires separate data management

## Performance Tips

When rendering multiple instances:

```tsx
// Use React.memo to prevent unnecessary re-renders
const SpreadsheetInstance = React.memo(({ instanceId, data }) => {
  // ... implementation
});

// Lazy load instances that aren't immediately visible
const LazySpreadsheet = lazy(() => import('./SpreadsheetInstance'));

function MultiInstance() {
  return (
    <SpreadsheetMultiInstanceProvider>
      <Suspense fallback={<div>Loading...</div>}>
        <LazySpreadsheet instanceId="lazy-1" />
      </Suspense>
    </SpreadsheetMultiInstanceProvider>
  );
}
```

## Troubleshooting

### Keyboard Events Not Working

If keyboard events aren't working properly, ensure:

* Each `CanvasGrid` has a unique `instanceId`
* The `SpreadsheetMultiInstanceProvider` wraps all instances
* Only one spreadsheet has focus at a time

### State Conflicts

If you experience state conflicts between instances:

* Verify each instance has its own `SpreadsheetProvider`
* Check that state management is properly isolated
* Ensure instance IDs are unique and don't change during component lifecycle

# User-Defined Colors

Create custom color palettes for your spreadsheet

User-defined colors allow you to extend the default color palette with custom colors that persist across your application. Users can add their own colors to color pickers for text, backgrounds, and borders.

## Overview

By default, color selectors in the toolbar (background color, text color, border color) provide a standard palette. User-defined colors extend this palette with:

* **Custom brand colors**: Add your organization's brand colors
* **Project-specific palettes**: Create color schemes for different projects
* **User preferences**: Allow users to save frequently used colors
* **Persistent colors**: Colors that persist across sessions

To replace the picker UI itself rather than extend its palette, see [Custom Color Picker](/configuration/features/custom-color-picker).

## Basic Usage

```tsx
import React, { useState } from "react";
import {
  SpreadsheetProvider,
  CanvasGrid,
  Toolbar,
  BackgroundColorSelector,
  TextColorSelector,
  BorderSelector,
} from "@rowsncolumns/spreadsheet";

function SpreadsheetWithCustomColors() {
  const [userDefinedColors, setUserDefinedColors] = useState<string[]>([
    "#FF6B6B", // Coral Red
    "#4ECDC4", // Turquoise
    "#45B7D1", // Sky Blue
    "#FFA07A", // Light Salmon
  ]);

const handleAddColor = (color: string) => {
    setUserDefinedColors((prev) => [...prev, color]);
  };

return (
    <SpreadsheetProvider>
      <Toolbar>
        <BackgroundColorSelector
          color={currentCellFormat?.backgroundColor}
          theme={theme}
          userDefinedColors={userDefinedColors}
          onAddUserDefinedColor={handleAddColor}
          onChange={onChangeBackgroundColor}
        />

<CanvasGrid
        // ... props
      />
    </SpreadsheetProvider>
  );
}
```

## State Management

### Simple State

Use React state for basic color management:

```tsx
function MySpreadsheet() {
  const [userDefinedColors, setUserDefinedColors] = useState<string[]>([]);

const addColor = (color: string) => {
    setUserDefinedColors((prev) => [...prev, color]);
  };

return (
    <BackgroundColorSelector
      userDefinedColors={userDefinedColors}
      onAddUserDefinedColor={addColor}
      // ... other props
    />
  );
}
```

### Persistent Storage

Save colors to localStorage for persistence:

```tsx
function MySpreadsheet() {
  const [userDefinedColors, setUserDefinedColors] = useState<string[]>(() => {
    // Load from localStorage on mount
    const saved = localStorage.getItem("spreadsheet-custom-colors");
    return saved ? JSON.parse(saved) : [];
  });

const addColor = (color: string) => {
    setUserDefinedColors((prev) => {
      const updated = [...prev, color];
      // Save to localStorage
      localStorage.setItem(
        "spreadsheet-custom-colors",
        JSON.stringify(updated)
      );
      return updated;
    });
  };

return (
    <BackgroundColorSelector
      userDefinedColors={userDefinedColors}
      onAddUserDefinedColor={addColor}
      // ... other props
    />
  );
}
```

### Server-Side Persistence

Save colors to your backend:

```tsx
function MySpreadsheet() {
  const [userDefinedColors, setUserDefinedColors] = useState<string[]>([]);

// Load colors from server
  useEffect(() => {
    async function loadColors() {
      const response = await fetch("/api/user/colors");
      const colors = await response.json();
      setUserDefinedColors(colors);
    }
    loadColors();
  }, []);

const addColor = async (color: string) => {
    // Optimistically update UI
    setUserDefinedColors((prev) => [...prev, color]);

// Save to server
    try {
      await fetch("/api/user/colors", {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({ color }),
      });
    } catch (error) {
      console.error("Failed to save color:", error);
      // Revert on error
      setUserDefinedColors((prev) => prev.filter((c) => c !== color));
    }
  };

return (
    <BackgroundColorSelector
      userDefinedColors={userDefinedColors}
      onAddUserDefinedColor={addColor}
      // ... other props
    />
  );
}
```

## Color Format

User-defined colors support various formats:

```tsx
const [userDefinedColors, setUserDefinedColors] = useState([
  "#FF6B6B",           // Hex
  "rgb(78, 205, 196)", // RGB
  "rgba(78, 205, 196, 0.8)", // RGBA
  "hsl(180, 60%, 55%)", // HSL
]);
```

## Complete Example

```tsx
import React, { useState, useEffect } from "react";
import {
  SpreadsheetProvider,
  CanvasGrid,
  Toolbar,
  BackgroundColorSelector,
  TextColorSelector,
  BorderSelector,
  Sheet,
  SpreadsheetTheme,
  defaultSpreadsheetTheme,
} from "@rowsncolumns/spreadsheet";
import {
  useSpreadsheetState,
  SheetData,
  CellData,
} from "@rowsncolumns/spreadsheet-state";

// Default custom colors
const DEFAULT_CUSTOM_COLORS = [
  "#FF6B6B", // Coral Red
  "#4ECDC4", // Turquoise
  "#45B7D1", // Sky Blue
  "#FFA07A", // Light Salmon
  "#96CEB4", // Sage Green
  "#FFEAA7", // Warm Yellow
  "#DFE6E9", // Light Gray
  "#74B9FF", // Soft Blue
];

function SpreadsheetWithColors() {
  const [sheets, setSheets] = useState<Sheet[]>([
    { sheetId: 1, rowCount: 100, columnCount: 26, title: "Sheet 1" }
  ]);
  const [sheetData, setSheetData] = useState<SheetData<CellData>>({});
  const [theme] = useState<SpreadsheetTheme>(defaultSpreadsheetTheme);

// Load user-defined colors from localStorage
  const [userDefinedColors, setUserDefinedColors] = useState<string[]>(() => {
    const saved = localStorage.getItem("user-colors");
    return saved ? JSON.parse(saved) : DEFAULT_CUSTOM_COLORS;
  });

const {
    activeCell,
    activeSheetId,
    selections,
    getCellData,
    getEffectiveFormat,
    onChangeActiveCell,
    onChangeSelections,
    onChange,
    onChangeFormatting,
    onChangeBorder,
    isDarkMode,
  } = useSpreadsheetState({
    sheets,
    sheetData,
    onChangeSheets: setSheets,
    onChangeSheetData: setSheetData,
  });

// Get current cell format
  const currentCellFormat = getEffectiveFormat(
    activeSheetId,
    activeCell.rowIndex,
    activeCell.columnIndex
  );

// Handle adding new color
  const handleAddColor = (color: string) => {
    setUserDefinedColors((prev) => {
      // Avoid duplicates
      if (prev.includes(color)) return prev;

const updated = [...prev, color];

// Save to localStorage
      localStorage.setItem("user-colors", JSON.stringify(updated));

return updated;
    });
  };

// Handle background color change
  const handleBackgroundColorChange = (color: any) => {
    onChangeFormatting(
      activeSheetId,
      activeCell,
      selections,
      "backgroundColor",
      color
    );
  };

// Handle text color change
  const handleTextColorChange = (color: any) => {
    onChangeFormatting(
      activeSheetId,
      activeCell,
      selections,
      "textFormat",
      { color }
    );
  };

return (
    <SpreadsheetProvider>
      <div className="flex flex-col h-screen">
        <Toolbar>
          <BackgroundColorSelector
            color={currentCellFormat?.backgroundColor}
            theme={theme}
            userDefinedColors={userDefinedColors}
            onAddUserDefinedColor={handleAddColor}
            onChange={handleBackgroundColorChange}
          />

<div className="flex-1">
          <CanvasGrid
            sheetId={activeSheetId}
            activeCell={activeCell}
            selections={selections}
            getCellData={getCellData}
            onChangeActiveCell={onChangeActiveCell}
            onChangeSelections={onChangeSelections}
            onChange={onChange}
            theme={theme}
          />
        </div>
      </div>
    </SpreadsheetProvider>
  );
}

export default SpreadsheetWithColors;
```

## Advanced Features

### Color Validation

Validate colors before adding them:

```tsx
function isValidColor(color: string): boolean {
  const style = new Option().style;
  style.color = color;
  return style.color !== "";
}

const addColor = (color: string) => {
  if (!isValidColor(color)) {
    console.error("Invalid color:", color);
    return;
  }

setUserDefinedColors((prev) => [...prev, color]);
};
```

### Color Limits

Limit the number of custom colors:

```tsx
const MAX_CUSTOM_COLORS = 20;

### Color Organization

Organize colors by category:

```tsx
const [colorCategories, setColorCategories] = useState({
  brand: ["#FF6B6B", "#4ECDC4"],
  pastels: ["#FFA07A", "#96CEB4"],
  vibrant: ["#45B7D1", "#FFEAA7"],
});

// Flatten for color selectors
const allColors = Object.values(colorCategories).flat();
```

### Remove Colors

Allow users to remove custom colors:

```tsx
function ColorManager() {
  const [userDefinedColors, setUserDefinedColors] = useState<string[]>([]);

const removeColor = (colorToRemove: string) => {
    setUserDefinedColors((prev) =>
      prev.filter((color) => color !== colorToRemove)
    );
  };

return (
    <div className="space-y-2">
      {userDefinedColors.map((color) => (
        <div key={color} className="flex items-center gap-2">
          <div
            className="w-8 h-8 rounded border"
            style={{ backgroundColor: color }}
          />
          <span className="flex-1">{color}</span>
          <button
            onClick={() => removeColor(color)}
            className="px-2 py-1 text-sm text-red-600"
          >
            Remove
          </button>
        </div>
      ))}
    </div>
  );
}
```

## Integration with Theme Colors

User-defined colors work alongside theme colors:

```tsx
import { SpreadsheetTheme } from "@rowsncolumns/spreadsheet";

const customTheme: SpreadsheetTheme = {
  ...defaultSpreadsheetTheme,
  colors: [
    "#000000", // Black
    "#FFFFFF", // White
    "#FF0000", // Red
    // ... theme colors
  ],
};

// User-defined colors appear separately from theme colors
const [userDefinedColors, setUserDefinedColors] = useState([
  "#FF6B6B",
  "#4ECDC4",
]);
```

## Use Cases

### Brand Colors

```tsx
const brandColors = [
  "#1E40AF", // Primary Blue
  "#F59E0B", // Accent Orange
  "#10B981", // Success Green
  "#EF4444", // Error Red
];

const [userDefinedColors, setUserDefinedColors] = useState(brandColors);
```

### Project-Specific Palettes

```tsx
const projectPalettes = {
  marketing: ["#FF6B6B", "#4ECDC4", "#FFA07A"],
  finance: ["#1E40AF", "#10B981", "#F59E0B"],
  design: ["#8B5CF6", "#EC4899", "#F59E0B"],
};

const [activeProject, setActiveProject] = useState("marketing");
const userDefinedColors = projectPalettes[activeProject];
```

### User Preferences

```tsx
// Load user's saved colors from profile
const { user } = useAuth();
const [userDefinedColors, setUserDefinedColors] = useState(
  user.preferences.customColors || []
);
```

## Best Practices

1. **Provide Defaults**: Start with a set of useful default colors
2. **Limit Count**: Cap custom colors at 10-20 to avoid clutter
3. **Validate Input**: Ensure colors are valid before adding
4. **Persist Data**: Save colors to localStorage or backend
5. **Avoid Duplicates**: Check for duplicate colors before adding
6. **Visual Feedback**: Show color swatches clearly in the UI
7. **Accessibility**: Ensure sufficient contrast for readability

## Troubleshooting

### Colors Not Appearing

* Verify the `userDefinedColors` array is properly formatted
* Check that color values are valid CSS colors
* Ensure the array is passed to all color selector components

### Colors Not Persisting

* Confirm localStorage save logic is working
* Check for browser storage limits
* Verify localStorage keys are consistent

### Duplicate Colors

* Implement duplicate checking before adding colors
* Use `Set` to ensure uniqueness if needed

```tsx
const addColor = (color: string) => {
  setUserDefinedColors((prev) => {
    if (prev.includes(color)) return prev;
    return [...prev, color];
  });
};
```

# Custom Color Picker

Replace the built-in color picker with your own component

Every surface that renders a color picker accepts an optional `ColorSelector` prop, letting you replace the built-in picker with your own component. Use this to match your design system, integrate a third-party picker library, or restrict the palette users can choose from.

## Overview

The built-in `ColorSelector` (theme colors, standard colors, user-defined colors, hex input and eye dropper) is the default everywhere. Passing your own component to the `ColorSelector` prop swaps it at that surface:

| Component                 | Where the picker appears               |
| ------------------------- | -------------------------------------- |
| `TextColorSelector`       | Toolbar text color dropdown            |
| `BackgroundColorSelector` | Toolbar fill color dropdown            |
| `BorderSelector`          | Border color inside the border menu    |
| `BorderColorSelector`     | Standalone border color dropdown       |
| `SheetTabs`               | "Change color" in the tab context menu |
| `FloatingCellEditor`      | Text and fill color pickers            |

Because it is a plain prop, you can swap the picker on one surface and keep the default on the others.

## Writing a custom picker

Your component receives `ColorSelectorProps`:

```tsx
import type { ColorSelectorProps } from "@rowsncolumns/spreadsheet";

`ColorSelectorProps`:

| Prop                    | Type                                  | Description                                                                                    |
| ----------------------- | ------------------------------------- | ---------------------------------------------------------------------------------------------- |
| `color`                 | `Color \| null`                       | Currently selected color                                                                       |
| `onChange`              | `(color: Color \| undefined) => void` | Call with the new color; `undefined` resets to automatic                                       |
| `theme`                 | `SpreadsheetTheme`                    | Active theme, for rendering theme color swatches                                               |
| `resetButtonTitle`      | `string`                              | Label for the reset action ("Automatic", "No fill", "Reset")                                   |
| `userDefinedColors`     | `string[]`                            | Custom palette colors (see [User-Defined Colors](/configuration/features/user-defined-colors)) |
| `onAddUserDefinedColor` | `(color: string) => void`             | Add a color to the custom palette                                                              |

## Usage in the toolbar

```tsx
import {
  Toolbar,
  TextColorSelector,
  BackgroundColorSelector,
  BorderSelector,
} from "@rowsncolumns/spreadsheet";

<Toolbar>
  <TextColorSelector
    color={currentCellFormat?.textFormat?.color}
    theme={theme}
    onChange={handleTextColorChange}
    ColorSelector={BrandColorSelector}
  />
  <BackgroundColorSelector
    color={currentCellFormat?.backgroundColor}
    theme={theme}
    onChange={handleBackgroundColorChange}
    ColorSelector={BrandColorSelector}
  />
  <BorderSelector
    borders={currentCellFormat?.borders}
    theme={theme}
    onChange={onChangeBorder}
    ColorSelector={BrandColorSelector}
  />
</Toolbar>
```

`BorderSelector` forwards the component to the border color picker inside the borders menu.

## Sheet tab color picker

`SheetTabs` forwards the component to the "Change color" submenu of the tab context menu:

```tsx
import { SheetTabs } from "@rowsncolumns/spreadsheet";

<SheetTabs
  sheets={sheets}
  activeSheetId={activeSheetId}
  theme={theme}
  onChangeSheetTabColor={onChangeSheetTabColor}
  ColorSelector={BrandColorSelector}
/>
```

If you already supply a custom `ContextMenu` to `SheetTabs`, render your own picker inside it directly — the `ColorSelector` prop is forwarded to your context menu via `SheetTabContextMenuProps`.

## Floating cell editor

```tsx
import { FloatingCellEditor } from "@rowsncolumns/spreadsheet";

<FloatingCellEditor
  sheetId={activeSheetId}
  activeCell={activeCell}
  onChange={onChange}
  onChangeFormatting={onChangeFormatting}
  ColorSelector={BrandColorSelector}
/>
```

## Best practices

1. **Call `onChange` with `undefined`** for your reset action so "Automatic"/"No fill" behaves like the built-in picker
2. **Respect `resetButtonTitle`** — each surface passes the right label for its context
3. **Reuse one component** across surfaces for a consistent experience, or override only the surfaces you need
4. **Keep `userDefinedColors` support** if your app also uses the custom palette, so both features compose

# Version comparison

The version comparison feature allows users to compare two versions of a spreadsheet and visualize differences inline. Changes are highlighted with distinct colors for added, deleted, and modified cells.

<figure><img src="/files/MBrZ5cLx9fU83VPsQBjs" alt="Spreadsheet version comparison UI"><figcaption><p>Spreadsheet version comparison UI</p></figcaption></figure>

## Overview

Version comparison is useful for:

* Tracking changes between document revisions
* Reviewing edits before accepting them
* Understanding what changed between snapshots
* Collaboration workflows where multiple users edit the same document

## Visual Highlighting

| Change Type  | Background              | Text Color                 | Description                                                             |
| ------------ | ----------------------- | -------------------------- | ----------------------------------------------------------------------- |
| **Added**    | Light green (`#d0fae1`) | Dark green (`#046e38`)     | Cell exists in current version but not in previous                      |
| **Deleted**  | Light red (`#ffdbdb`)   | Dark red (`#b21313`)       | Cell exists in previous version but not in current (with strikethrough) |
| **Modified** | Both colors             | Red for old, green for new | Cell value or format changed                                            |

### Modified Cells

When a cell is modified, both the old and new values are displayed side by side within the cell:

* **Old value**: Red background with the previous formatting applied
* **New value**: Green background with the current formatting applied

This applies to both value changes and format-only changes (e.g., text becoming bold).

## Installation

```bash
npm install @rowsncolumns/version-comparison
```

## Basic Usage

```tsx
import { useState, useCallback, useMemo } from "react";
import { useVersionComparison } from "@rowsncolumns/version-comparison";
import { CanvasGrid, useSpreadsheetState } from "@rowsncolumns/spreadsheet";

const VersionComparisonDemo = () => {
  // Manage comparison mode yourself
  const [isComparing, setIsComparing] = useState(false);

// Your current spreadsheet data
  const [sheetData, setSheetData] = useState(currentData);

// Previous version snapshot
  const previousSheetData = useMemo(() => snapshotData, []);

const { getCellData } = useSpreadsheetState({
    sheetData,
    // ... other props
  });

// Function to get previous cell data
  const getPreviousCellData = useCallback(
    (sheetId: number, rowIndex: number, columnIndex: number) => {
      return previousSheetData[sheetId]?.[rowIndex]?.values?.[columnIndex] ?? null;
    },
    [previousSheetData]
  );

// Version comparison hook - pass null when not comparing
  const { getCellDiff } = useVersionComparison({
    getCellData,
    getPreviousCellData: isComparing ? getPreviousCellData : null,
  });

return (
    <div>
      {/* Comparison controls */}
      <div>
        {!isComparing ? (
          <button onClick={() => setIsComparing(true)}>Compare Versions</button>
        ) : (
          <button onClick={() => setIsComparing(false)}>Exit Comparison</button>
        )}
      </div>

{/* Grid with comparison highlighting */}
      <CanvasGrid
        // ... standard props
        isComparing={isComparing}
        getCellDiff={getCellDiff}
      />
    </div>
  );
};
```

## API Reference

### useVersionComparison Hook

```typescript
const { getCellDiff } = useVersionComparison(options);
```

#### Options

```typescript
type UseVersionComparisonOptions<T extends CellData = CellData> = {
  /** Function to get current cell data */
  getCellData: (sheetId: number, rowIndex: number, columnIndex: number) => T | null | undefined;
  /** Function to get previous cell data (null = not comparing) */
  getPreviousCellData: ((sheetId: number, rowIndex: number, columnIndex: number) => T | null | undefined) | null;
  /**
   * Resolved effective `CellFormat` for the current version. The caller owns
   * all resolution — inline `ef` / `uf`, sid → cellXfs lookup, cellStyleStore
   * overlays, conditional formatting, etc. If omitted, format changes are
   * not detected (only value changes contribute to the diff).
   */
  getEffectiveFormat?: (sheetId: number, rowIndex: number, columnIndex: number) => CellFormat | null | undefined;
  /**
   * Resolved effective `CellFormat` for the previous version. Defaults to
   * `getEffectiveFormat` if omitted (useful when both sides share a resolver).
   */
  getPreviousEffectiveFormat?: (sheetId: number, rowIndex: number, columnIndex: number) => CellFormat | null | undefined;
  /** Shared strings map for current version */
  sharedStrings?: Map<string, string> | null;
  /** Shared strings map for previous version (defaults to sharedStrings) */
  previousSharedStrings?: Map<string, string> | null;
};
```

#### Return Values

| Property      | Type                                                   | Description                  |
| ------------- | ------------------------------------------------------ | ---------------------------- |
| `getCellDiff` | `(sheetId, rowIndex, columnIndex) => CellDiff \| null` | Get diff for a specific cell |

### CellDiff Type

```typescript
type CellDiff = {
  sheetId: number;
  rowIndex: number;
  columnIndex: number;
  state: "added" | "deleted" | "modified";
  detail?: CellDiffDetail;
};

type CellDiffDetail = {
  valueChanged: boolean;
  formatChanged: boolean;
  oldValue?: ExtendedValue;
  newValue?: ExtendedValue;
  oldFormattedValue?: string;
  newFormattedValue?: string;
  oldFormat?: CellFormat;
  newFormat?: CellFormat;
};
```

## Detecting Different Types of Changes

### Value Changes

```typescript
const diff = getCellDiff(sheetId, rowIndex, columnIndex);
if (diff?.detail?.valueChanged) {
  console.log("Old value:", diff.detail.oldFormattedValue);
  console.log("New value:", diff.detail.newFormattedValue);
}
```

### Format Changes

```typescript
const diff = getCellDiff(sheetId, rowIndex, columnIndex);
if (diff?.detail?.formatChanged) {
  console.log("Old format:", diff.detail.oldFormat);
  console.log("New format:", diff.detail.newFormat);
}
```

### Format-Only Changes

When a cell's value stays the same but formatting changes (e.g., text becomes bold):

```typescript
const diff = getCellDiff(sheetId, rowIndex, columnIndex);
const isFormatOnlyChange = diff?.detail?.formatChanged && !diff?.detail?.valueChanged;
if (isFormatOnlyChange) {
  // Show both old and new side by side to display formatting difference
}
```

## Working with Shared Strings

If your cell data uses shared strings (`ss` property pointing to a shared strings map), pass the shared strings:

```typescript
const { getCellDiff } = useVersionComparison({
  getCellData,
  getPreviousCellData,
  sharedStrings, // Map<string, string>
});
```

Cell data with shared string:

```typescript
// Cell uses ss to reference a shared string
const cellData = {
  ss: "0",  // References sharedStrings.get("0")
  fv: "Hello",
};

const sharedStrings = new Map([["0", "Hello"], ["1", "World"]]);
```

If the previous version has a different shared strings map (e.g., from a snapshot):

```typescript
const { getCellDiff } = useVersionComparison({
  getCellData,
  getPreviousCellData,
  sharedStrings: currentSharedStrings,
  previousSharedStrings: snapshotSharedStrings,
});
```

## Resolving Effective Formats

Format resolution is **caller-driven**. The hook never inspects `ef.sid` / `uf.sid` style references and never touches a cellXfs registry — it just compares the `CellFormat` objects you hand back. That keeps the hook agnostic to whatever resolution chain your app uses (cellXfs sid lookup, runtime overlays from a cell style store, conditional formatting, derived formats, …).

Pass `getEffectiveFormat` / `getPreviousEffectiveFormat` to opt in to format comparison:

```typescript
const { getCellDiff } = useVersionComparison({
  getCellData,
  getPreviousCellData,
  // Current side: useSpreadsheetState's getEffectiveFormat already merges
  // cellStyleStore + cellXfs sid + inline + derived format and is a
  // drop-in fit.
  getEffectiveFormat,
  // Previous side: walk the snapshot yourself when there's no
  // spreadsheet-state instance attached to it.
  getPreviousEffectiveFormat: (sheetId, row, col) => {
    const cell = previousSheetData[sheetId]?.[row]?.values?.[col];
    if (!cell) return null;
    const fmt = cell.ef ?? cell.uf;
    if (!fmt) return null;
    if ("sid" in fmt && typeof fmt.sid === "string") {
      return previousCellXfs.get(fmt.sid) ?? null;
    }
    return fmt;
  },
});
```

If both sides share a resolver, pass only `getEffectiveFormat` — `getPreviousEffectiveFormat` defaults to it. If you omit both, format changes simply aren't detected — only value changes will show up in the diff.

Cell data with a style reference looks like:

```typescript
// Cell uses ef.sid to reference an entry in the cellXfs map
const cellData = {
  ue: { sv: "Hello" },
  fv: "Hello",
  ef: { sid: "5" },  // Caller resolves: cellXfs.get("5")
};
```

## Comparison Summary

To display a summary of all changes:

```tsx
const DiffSummary = ({ isComparing, getCellDiff }) => {
  const summary = useMemo(() => {
    if (!isComparing) return { added: 0, modified: 0, deleted: 0 };

let added = 0, modified = 0, deleted = 0;

// Scan your data range
    for (let row = 0; row < rowCount; row++) {
      for (let col = 0; col < columnCount; col++) {
        const diff = getCellDiff(sheetId, row, col);
        if (diff?.state === "added") added++;
        else if (diff?.state === "modified") modified++;
        else if (diff?.state === "deleted") deleted++;
      }
    }

return { added, modified, deleted };
  }, [isComparing, getCellDiff]);

return (
    <div>
      <span>+{summary.added} added</span>
      <span>~{summary.modified} modified</span>
      <span>-{summary.deleted} deleted</span>
    </div>
  );
};
```

## CanvasGrid Props

| Prop          | Type                                      | Description                      |
| ------------- | ----------------------------------------- | -------------------------------- |
| `isComparing` | `boolean`                                 | Enable comparison mode rendering |
| `getCellDiff` | `(sheetId, row, col) => CellDiff \| null` | Function to get cell diff        |

## Diff Engine Functions

For advanced use cases, you can use the diff engine functions directly:

```typescript
import { areCellValuesEqual, areCellFormatsEqual } from "@rowsncolumns/version-comparison";

// Compare values
const valuesEqual = areCellValuesEqual(
  { nv: 100 },
  { nv: 100 }
); // true

// Compare formats
const formatsEqual = areCellFormatsEqual(
  { textFormat: { bold: true } },
  { textFormat: { bold: false } }
); // false
```

## Best Practices

1. **Snapshot Management**: Store snapshots efficiently - consider only storing changed cells rather than the entire sheet.
2. **Performance**: For large spreadsheets, consider lazy-loading diffs only for visible cells.
3. **User Experience**:
   * Show a clear indicator when comparison mode is active
   * Provide a summary of changes
   * Allow users to navigate between changes
4. **Format Comparison**: Remember that format changes count as modifications even if the value is unchanged.

## Example: Full Implementation

```tsx
import React, { useCallback, useMemo, useState } from "react";
import {
  SpreadsheetProvider,
  CanvasGrid,
  useSpreadsheetState,
} from "@rowsncolumns/spreadsheet";
import { useVersionComparison } from "@rowsncolumns/version-comparison";

const VersionComparisonApp = () => {
  // Manage comparison mode yourself
  const [isComparing, setIsComparing] = useState(false);

const [sheetData, setSheetData] = useState(currentSheetData);
  const previousSheetData = useMemo(() => snapshotSheetData, []);

const { getCellData, getEffectiveFormat, activeSheetId, ...spreadsheetProps } = useSpreadsheetState({
    sheetData,
    onChangeSheetData: setSheetData,
    // ... other props
  });

const getPreviousCellData = useCallback(
    (sheetId, rowIndex, columnIndex) =>
      previousSheetData[sheetId]?.[rowIndex]?.values?.[columnIndex] ?? null,
    [previousSheetData]
  );

// Resolve effective format for the snapshot (sid → previousCellXfs).
  // There's no useSpreadsheetState instance attached to the snapshot, so
  // walk it ourselves.
  const getPreviousEffectiveFormat = useCallback(
    (sheetId, rowIndex, columnIndex) => {
      const cell = getPreviousCellData(sheetId, rowIndex, columnIndex);
      if (!cell) return null;
      const fmt = cell.ef ?? cell.uf;
      if (!fmt) return null;
      if ("sid" in fmt && typeof fmt.sid === "string") {
        return previousCellXfs.get(fmt.sid) ?? null;
      }
      return fmt;
    },
    [getPreviousCellData, previousCellXfs]
  );

// Pass null when not comparing to disable diffing
  const { getCellDiff } = useVersionComparison({
    getCellData,
    getPreviousCellData: isComparing ? getPreviousCellData : null,
    getEffectiveFormat,
    getPreviousEffectiveFormat,
  });

return (
    <SpreadsheetProvider>
      <div style={{ display: "flex", flexDirection: "column", height: "100vh" }}>
        {/* Comparison toolbar */}
        <div style={{ padding: 8, borderBottom: "1px solid #ddd" }}>
          {!isComparing ? (
            <button onClick={() => setIsComparing(true)}>Compare with Previous</button>
          ) : (
            <button onClick={() => setIsComparing(false)}>Exit Comparison</button>
          )}
        </div>

{/* Spreadsheet grid */}
        <CanvasGrid
          sheetId={activeSheetId}
          {...spreadsheetProps}
          getCellData={getCellData}
          isComparing={isComparing}
          getCellDiff={getCellDiff}
        />
      </div>
    </SpreadsheetProvider>
  );
};
```

## Related Features

* [Undo/Redo](/configuration/features/undo-redo) - Track and revert changes
* [Real-time Data](/configuration/features/real-time-data) - Collaborative editing
* [Cell Renderer](/configuration/features/cell-renderer) - Custom cell rendering

# Navigate to Sheet Range

Programmatically navigate and scroll to specific cell ranges

The `useNavigateToSheetRange` hook provides a programmatic way to navigate to specific cell ranges, change sheets, and scroll to particular locations in your spreadsheet. This is useful for implementing search functionality, jumping to errors, following links, and creating guided tours.

## Overview

Navigate to Sheet Range enables:

* **Sheet switching**: Change the active sheet programmatically
* **Cell navigation**: Jump to specific cells or ranges
* **Auto-scrolling**: Automatically scroll cells into view
* **Selection updates**: Update selections when navigating
* **Cross-sheet navigation**: Navigate across different sheets

## Basic Usage

```tsx
import { SpreadsheetProvider } from "@rowsncolumns/spreadsheet";
import { useNavigateToSheetRange } from "@rowsncolumns/spreadsheet";

function MySpreadsheet() {
  const navigateToSheetRange = useNavigateToSheetRange();

const handleNavigate = () => {
    navigateToSheetRange?.({
      sheetId: 2,
      startRowIndex: 10,
      startColumnIndex: 5,
      endRowIndex: 15,
      endColumnIndex: 10,
    });
  };

return (
    <button onClick={handleNavigate}>
      Go to Sheet 2, Range F11:K16
    </button>
  );
}
```

## Hook Usage

The hook must be used within a `SpreadsheetProvider`:

```tsx
import { SpreadsheetProvider } from "@rowsncolumns/spreadsheet";
import { useNavigateToSheetRange } from "@rowsncolumns/spreadsheet";

function NavigationComponent() {
  const navigateToSheetRange = useNavigateToSheetRange();

// navigateToSheetRange is available for use
  return <YourComponent navigate={navigateToSheetRange} />;
}

function App() {
  return (
    <SpreadsheetProvider>
      <NavigationComponent />
    </SpreadsheetProvider>
  );
}
```

## Function Signature

```typescript
type SheetRange = {
  sheetId: number;
  startRowIndex: number;
  startColumnIndex: number;
  endRowIndex: number;
  endColumnIndex: number;
};

type NavigateToSheetRange = (range: SheetRange) => void;
```

## Navigation Examples

### Navigate to Specific Cell

```tsx
const navigateToCell = (sheetId: number, rowIndex: number, columnIndex: number) => {
  navigateToSheetRange?.({
    sheetId,
    startRowIndex: rowIndex,
    startColumnIndex: columnIndex,
    endRowIndex: rowIndex,
    endColumnIndex: columnIndex,
  });
};

// Navigate to cell B5 on sheet 1
navigateToCell(1, 5, 2);
```

### Navigate to Range

```tsx
const navigateToRange = () => {
  // Navigate to range A1:E10 on sheet 3
  navigateToSheetRange?.({
    sheetId: 3,
    startRowIndex: 1,
    startColumnIndex: 1,
    endRowIndex: 10,
    endColumnIndex: 5,
  });
};
```

### Navigate to Named Range

```tsx
function navigateToNamedRange(namedRangeName: string, namedRanges: NamedRange[]) {
  const namedRange = namedRanges.find((nr) => nr.name === namedRangeName);

if (!namedRange || !namedRange.range) {
    console.error(`Named range "${namedRangeName}" not found`);
    return;
  }

navigateToSheetRange?.(namedRange.range);
}

// Navigate to named range "SalesData"
navigateToNamedRange("SalesData", namedRanges);
```

## Complete Example

```tsx
import React, { useState } from "react";
import {
  SpreadsheetProvider,
  CanvasGrid,
  Sheet,
  useNavigateToSheetRange,
} from "@rowsncolumns/spreadsheet";
import {
  useSpreadsheetState,
  SheetData,
  CellData,
} from "@rowsncolumns/spreadsheet-state";

function NavigationControls() {
  const navigateToSheetRange = useNavigateToSheetRange();

const quickJumps = [
    { label: "Go to A1", sheetId: 1, row: 1, col: 1 },
    { label: "Go to Z100", sheetId: 1, row: 100, col: 26 },
    { label: "Sheet 2 - F11:K16", sheetId: 2, row: 11, col: 6, endRow: 16, endCol: 11 },
  ];

const handleQuickJump = (jump: typeof quickJumps[0]) => {
    navigateToSheetRange?.({
      sheetId: jump.sheetId,
      startRowIndex: jump.row,
      startColumnIndex: jump.col,
      endRowIndex: jump.endRow || jump.row,
      endColumnIndex: jump.endCol || jump.col,
    });
  };

return (
    <div className="flex gap-2 p-2">
      {quickJumps.map((jump, index) => (
        <button
          key={index}
          onClick={() => handleQuickJump(jump)}
          className="px-3 py-1 bg-blue-500 text-white rounded"
        >
          {jump.label}
        </button>
      ))}
    </div>
  );
}

function SpreadsheetWithNavigation() {
  const [sheets, setSheets] = useState<Sheet[]>([
    { sheetId: 1, rowCount: 200, columnCount: 26, title: "Sheet 1" },
    { sheetId: 2, rowCount: 200, columnCount: 26, title: "Sheet 2" },
  ]);
  const [sheetData, setSheetData] = useState<SheetData<CellData>>({});

const {
    activeCell,
    activeSheetId,
    selections,
    getCellData,
    onChangeActiveCell,
    onChangeSelections,
    onChangeActiveSheet,
  } = useSpreadsheetState({
    sheets,
    sheetData,
    onChangeSheets: setSheets,
    onChangeSheetData: setSheetData,
  });

return (
    <SpreadsheetProvider>
      <div className="flex flex-col h-screen">
        <NavigationControls />

<div className="flex-1">
          <CanvasGrid
            sheetId={activeSheetId}
            activeCell={activeCell}
            selections={selections}
            getCellData={getCellData}
            onChangeActiveCell={onChangeActiveCell}
            onChangeSelections={onChangeSelections}
            onChangeActiveSheet={onChangeActiveSheet}
          />
        </div>
      </div>
    </SpreadsheetProvider>
  );
}

export default SpreadsheetWithNavigation;
```

## Use Cases

### Search Results Navigation

Navigate to cells matching search criteria:

```tsx
function SearchAndNavigate() {
  const navigateToSheetRange = useNavigateToSheetRange();
  const [searchResults, setSearchResults] = useState<SheetRange[]>([]);
  const [currentIndex, setCurrentIndex] = useState(0);

const handleNextResult = () => {
    if (searchResults.length === 0) return;

const nextIndex = (currentIndex + 1) % searchResults.length;
    setCurrentIndex(nextIndex);
    navigateToSheetRange?.(searchResults[nextIndex]);
  };

const handlePreviousResult = () => {
    if (searchResults.length === 0) return;

const prevIndex = currentIndex === 0 ? searchResults.length - 1 : currentIndex - 1;
    setCurrentIndex(prevIndex);
    navigateToSheetRange?.(searchResults[prevIndex]);
  };

return (
    <div>
      <button onClick={handlePreviousResult}>Previous</button>
      <span>{currentIndex + 1} / {searchResults.length}</span>
      <button onClick={handleNextResult}>Next</button>
    </div>
  );
}
```

### Error Navigation

Jump to cells with formula errors:

```tsx
function navigateToErrors(
  sheets: Sheet[],
  sheetData: SheetData<CellData>,
  navigateToSheetRange: NavigateToSheetRange
) {
  const errors: SheetRange[] = [];

sheets.forEach((sheet) => {
    const data = sheetData[sheet.sheetId];
    if (!data) return;

data.forEach((row, rowIndex) => {
      if (!row?.values) return;

row.values.forEach((cell, colIndex) => {
        if (cell?.ev?.ev) {
          errors.push({
            sheetId: sheet.sheetId,
            startRowIndex: rowIndex,
            startColumnIndex: colIndex,
            endRowIndex: rowIndex,
            endColumnIndex: colIndex,
          });
        }
      });
    });
  });

// Navigate to first error
  if (errors.length > 0) {
    navigateToSheetRange(errors[0]);
  }

return errors;
}
```

### Table Navigation

Navigate to different sections of a table:

```tsx
function navigateToTable(table: TableView, section: "header" | "data" | "total") {
  const range = { ...table.range };

switch (section) {
    case "header":
      range.endRowIndex = range.startRowIndex;
      break;
    case "data":
      range.startRowIndex = range.startRowIndex + 1;
      if (table.totalsRow) {
        range.endRowIndex = range.endRowIndex - 1;
      }
      break;
    case "total":
      if (table.totalsRow) {
        range.startRowIndex = range.endRowIndex;
      }
      break;
  }

navigateToSheetRange?.(range);
}
```

### Hyperlink Navigation

Navigate when clicking on cell references:

```tsx
function handleCellReferenceClick(cellReference: string) {
  // Parse cell reference like "Sheet2!A1" or "B5"
  const match = cellReference.match(/^(?:(.+)!)?([A-Z]+)(\d+)$/);

if (!match) return;

const [, sheetName, column, row] = match;
  const sheetId = sheetName ? getSheetIdByName(sheetName) : activeSheetId;
  const columnIndex = columnToIndex(column);
  const rowIndex = parseInt(row, 10);

navigateToSheetRange?.({
    sheetId,
    startRowIndex: rowIndex,
    startColumnIndex: columnIndex,
    endRowIndex: rowIndex,
    endColumnIndex: columnIndex,
  });
}
```

### Guided Tour

Create a step-by-step tour of your spreadsheet:

```tsx
function SpreadsheetTour() {
  const navigateToSheetRange = useNavigateToSheetRange();

const tourSteps = [
    {
      title: "Welcome",
      range: { sheetId: 1, startRowIndex: 1, startColumnIndex: 1, endRowIndex: 1, endColumnIndex: 1 },
      description: "This is cell A1, the starting point",
    },
    {
      title: "Sales Data",
      range: { sheetId: 1, startRowIndex: 5, startColumnIndex: 2, endRowIndex: 20, endColumnIndex: 5 },
      description: "Here is our sales data table",
    },
    {
      title: "Summary",
      range: { sheetId: 2, startRowIndex: 1, startColumnIndex: 1, endRowIndex: 10, endColumnIndex: 3 },
      description: "The summary is on Sheet 2",
    },
  ];

const [currentStep, setCurrentStep] = useState(0);

const goToStep = (stepIndex: number) => {
    if (stepIndex < 0 || stepIndex >= tourSteps.length) return;

setCurrentStep(stepIndex);
    navigateToSheetRange?.(tourSteps[stepIndex].range);
  };

return (
    <div className="p-4 border rounded">
      <h3 className="font-bold mb-2">{tourSteps[currentStep].title}</h3>
      <p className="text-sm mb-4">{tourSteps[currentStep].description}</p>

<div className="flex gap-2">
        <button
          onClick={() => goToStep(currentStep - 1)}
          disabled={currentStep === 0}
          className="px-3 py-1 bg-gray-500 text-white rounded disabled:opacity-50"
        >
          Previous
        </button>
        <button
          onClick={() => goToStep(currentStep + 1)}
          disabled={currentStep === tourSteps.length - 1}
          className="px-3 py-1 bg-blue-500 text-white rounded disabled:opacity-50"
        >
          Next
        </button>
      </div>

<div className="text-sm text-gray-500 mt-2">
        Step {currentStep + 1} of {tourSteps.length}
      </div>
    </div>
  );
}
```

## Advanced Features

### Smooth Scrolling

Implement smooth scrolling with animation:

```tsx
function smoothNavigate(range: SheetRange, duration: number = 300) {
  // Implementation would involve animating the scroll position
  // This is handled internally by the spreadsheet component
  navigateToSheetRange?.(range);
}
```

### Navigation History

Track navigation history for back/forward buttons:

```tsx
function useNavigationHistory() {
  const [history, setHistory] = useState<SheetRange[]>([]);
  const [currentIndex, setCurrentIndex] = useState(-1);
  const navigateToSheetRange = useNavigateToSheetRange();

const navigate = (range: SheetRange) => {
    const newHistory = history.slice(0, currentIndex + 1);
    newHistory.push(range);
    setHistory(newHistory);
    setCurrentIndex(newHistory.length - 1);
    navigateToSheetRange?.(range);
  };

const goBack = () => {
    if (currentIndex > 0) {
      const newIndex = currentIndex - 1;
      setCurrentIndex(newIndex);
      navigateToSheetRange?.(history[newIndex]);
    }
  };

const goForward = () => {
    if (currentIndex < history.length - 1) {
      const newIndex = currentIndex + 1;
      setCurrentIndex(newIndex);
      navigateToSheetRange?.(history[newIndex]);
    }
  };

return {
    navigate,
    goBack,
    goForward,
    canGoBack: currentIndex > 0,
    canGoForward: currentIndex < history.length - 1,
  };
}
```

## Helper Functions

### Cell Address to Range

Convert cell address notation to range:

```tsx
import { cellToAddress } from "@rowsncolumns/utils";

function addressToRange(address: string, sheetId: number): SheetRange | null {
  // Parse address like "A1" or "Sheet2!B5:C10"
  const match = address.match(/^(?:(.+)!)?([A-Z]+)(\d+)(?::([A-Z]+)(\d+))?$/);

if (!match) return null;

const [, sheetName, startCol, startRow, endCol, endRow] = match;
  const actualSheetId = sheetName ? getSheetIdByName(sheetName) : sheetId;

return {
    sheetId: actualSheetId,
    startRowIndex: parseInt(startRow, 10),
    startColumnIndex: columnToIndex(startCol),
    endRowIndex: parseInt(endRow || startRow, 10),
    endColumnIndex: columnToIndex(endCol || startCol),
  };
}
```

## Best Practices

1. **Validate Ranges**: Ensure row and column indices are within bounds
2. **Handle Edge Cases**: Check for undefined or null navigateToSheetRange
3. **User Feedback**: Provide visual indicators during navigation
4. **Accessibility**: Support keyboard shortcuts for navigation
5. **Performance**: Avoid excessive navigation calls in loops

## Troubleshooting

### Navigation Not Working

* Verify you're calling the hook within `SpreadsheetProvider`
* Check that sheet IDs and indices are valid
* Ensure the component is properly mounted

### Sheet Not Switching

* Confirm the target sheet exists in the sheets array
* Verify `onChangeActiveSheet` is properly connected
* Check that sheet IDs match

### Scroll Position Not Updating

* Ensure row and column indices are within the sheet bounds
* Verify the grid is properly rendered
* Check for conflicting scroll handlers

# Calculated columns

Add columns with formulas, join multiple tables

Add any formula on the far end of the table, to create a calculated column. Calculated columns are indicated with a `bolt` icon.

<figure><img src="/files/VOZor8QvhKDbbXb4kvg4" alt=""><figcaption><p>Calculated column</p></figcaption></figure>

When table expands, while user adds new row, calculated columns are automatically added.

# Structured references

Add structured data to Spreadsheet and reference them using semantic formulas

Spreadsheet allows you to convert any data in the sheet to an Excel Table. Select a dataset, or add a dataset using an Array formula such as `=IMPORTDATA`

<figure><img src="/files/TqD1AtA6WleLOcFLiT2f" alt=""><figcaption><p>Convert dataset to Structured table</p></figcaption></figure>

You can now add formulas in your table referencing to the column names

<figure><img src="/files/6RNh89TgUKYydO4L3ufN" alt=""><figcaption><p>Formulas referencing column names</p></figcaption></figure>

## Calculated Columns

Dynamic columns can be added just like Excel. Users can edit the table, add multiple columns and extend the table range to give the column additional features such as filtering, sorting etc

## Joining tables

You can join tables and create dynamic columns from multiple datasources. Structured formulas refer tables using `Table name` . For example, in the above table, you can add formulas like `=Table 2[@Region]`

# Schema based tables and columns

Convert any dataset to a schema driven table

Tables in Spreadsheet 2 gives you the same amount of control that you get in Excel/Google sheets. Users can add dynamic columns, calculated columns with a formula, create columns from another table etc.

## Column order

Column orders can be easily changed by selecting a column from the column header and moving them left or right.

All formulas and references are automatically updated.

<figure><img src="/files/aCU7nJr8NzdCBHM36QwY" alt=""><figcaption><p>Re-arranging columns</p></figcaption></figure>

# Drag and Drop

Drag and drop images and CSV/Excel files from your desktop

With drag and drop enabled, users can move files from their desktop directly to the sheets.

{% hint style="info" %}
Images are stored as base64 string while CSV files are converted to sheetData
{% endhint %}

{% hint style="warning" %}
Dropping an Excel file will replace all sheets, sheet data, tables, embeds, charts etc which is not undoable
{% endhint %}

# Text to Columns

Split text in cells into multiple columns

The Text to Columns feature allows users to split text content from cells into multiple columns based on delimiters or fixed widths. This is useful for importing data, cleaning up datasets, and reformatting text.

## Overview

Text to Columns functionality enables users to:

* Split comma-separated values (CSV) into columns
* Parse tab-delimited or space-delimited text
* Split by custom delimiters
* Break up formatted text (e.g., "First Last" � "First" | "Last")
* Clean and restructure imported data

## Basic Usage

The `onSplitTextToColumns` callback is provided by `useSpreadsheetState` and is triggered when users request to split text in cells.

```tsx
import {
  SpreadsheetProvider,
  CanvasGrid,
} from "@rowsncolumns/spreadsheet";
import { useSpreadsheetState } from "@rowsncolumns/spreadsheet-state";

function SpreadsheetWithTextSplit() {
  const {
    activeCell,
    activeSheetId,
    selections,
    onSplitTextToColumns,
    // ... other state
  } = useSpreadsheetState({
    // configuration
  });

return (
    <SpreadsheetProvider>
      <CanvasGrid
        sheetId={activeSheetId}
        activeCell={activeCell}
        selections={selections}
        onSplitTextToColumns={onSplitTextToColumns}
        // ... other props
      />
    </SpreadsheetProvider>
  );
}
```

## Function Signature

```typescript
type OnSplitTextToColumns = (
  sheetId: number,
  activeCell: CellInterface,
  selections: SelectionArea<SelectionAttributes>[]
) => void;
```

## How It Works

When `onSplitTextToColumns` is called:

1. The function analyzes the selected cells
2. Detects or prompts for a delimiter (comma, semicolon, tab, space, etc.)
3. Splits the text content based on the delimiter
4. Distributes the split values across adjacent columns
5. Preserves the original data structure

## Example Usage

### Manual Trigger

You can manually trigger text splitting from a button or menu:

```tsx
function SpreadsheetToolbar() {
  const {
    activeCell,
    activeSheetId,
    selections,
    onSplitTextToColumns,
  } = useSpreadsheetState({
    // configuration
  });

const handleSplitText = () => {
    onSplitTextToColumns?.(activeSheetId, activeCell, selections);
  };

return (
    <button
      onClick={handleSplitText}
      className="px-3 py-1 bg-blue-500 text-white rounded"
    >
      Split Text to Columns
    </button>
  );
}
```

### Context Menu Integration

Add Text to Columns to the context menu:

```tsx
import { DropdownMenu, DropdownMenuItem } from "@rowsncolumns/ui";

function CustomContextMenu({
  activeCell,
  activeSheetId,
  selections,
  onSplitTextToColumns,
}) {
  return (
    <DropdownMenu>
      <DropdownMenuItem
        onClick={() => onSplitTextToColumns?.(activeSheetId, activeCell, selections)}
      >
        Split Text to Columns
      </DropdownMenuItem>
      {/* Other menu items */}
    </DropdownMenu>
  );
}
```

## Common Use Cases

### Splitting Names

Split "First Last" into separate columns:

```tsx
// Before:
// | John Doe | Jane Smith |

### Parsing CSV Data

Split comma-separated values:

```tsx
// Before:
// | apple,banana,cherry |

// After splitting by comma:
// | apple | banana | cherry |
```

### Processing Addresses

Split full addresses into components:

```tsx
// Before:
// | 123 Main St, New York, NY 10001 |

// After splitting by comma:
// | 123 Main St | New York | NY 10001 |
```

## Complete Example

```tsx
import React, { useState } from "react";
import {
  SpreadsheetProvider,
  CanvasGrid,
  Toolbar,
  ToolbarIconButton,
  Sheet,
} from "@rowsncolumns/spreadsheet";
import {
  useSpreadsheetState,
  SheetData,
  CellData,
} from "@rowsncolumns/spreadsheet-state";

function SpreadsheetWithSplitText() {
  const [sheets, setSheets] = useState<Sheet[]>([
    { sheetId: 1, rowCount: 100, columnCount: 26, title: "Data" }
  ]);
  const [sheetData, setSheetData] = useState<SheetData<CellData>>({});

const {
    activeCell,
    activeSheetId,
    selections,
    getCellData,
    onChangeActiveCell,
    onChangeSelections,
    onChange,
    onSplitTextToColumns,
  } = useSpreadsheetState({
    sheets,
    sheetData,
    onChangeSheets: setSheets,
    onChangeSheetData: setSheetData,
  });

const handleSplitText = () => {
    if (!onSplitTextToColumns) {
      console.warn("Split text to columns is not available");
      return;
    }

onSplitTextToColumns(activeSheetId, activeCell, selections);
  };

return (
    <SpreadsheetProvider>
      <div className="flex flex-col h-screen">
        <Toolbar>
          <ToolbarIconButton
            onClick={handleSplitText}
            title="Split Text to Columns"
          >
            <SplitIcon />
          </ToolbarIconButton>
        </Toolbar>

<div className="flex-1">
          <CanvasGrid
            sheetId={activeSheetId}
            activeCell={activeCell}
            selections={selections}
            getCellData={getCellData}
            onChangeActiveCell={onChangeActiveCell}
            onChangeSelections={onChangeSelections}
            onChange={onChange}
            onSplitTextToColumns={onSplitTextToColumns}
          />
        </div>
      </div>
    </SpreadsheetProvider>
  );
}

export default SpreadsheetWithSplitText;
```

## Custom Implementation

If you need custom text splitting logic, you can implement your own:

```tsx
import { CellInterface, SelectionArea } from "@rowsncolumns/spreadsheet";

function customSplitTextToColumns(
  sheetId: number,
  activeCell: CellInterface,
  selections: SelectionArea<SelectionAttributes>[],
  delimiter: string = ","
) {
  // Get the selection range
  const selection = selections[0] || {
    range: {
      startRowIndex: activeCell.rowIndex,
      endRowIndex: activeCell.rowIndex,
      startColumnIndex: activeCell.columnIndex,
      endColumnIndex: activeCell.columnIndex,
    },
  };

// Process each row in the selection
  for (
    let rowIndex = selection.range.startRowIndex;
    rowIndex <= selection.range.endRowIndex;
    rowIndex++
  ) {
    // Get the cell value
    const cellData = getCellData(
      sheetId,
      rowIndex,
      selection.range.startColumnIndex
    );

if (!cellData?.formattedValue) continue;

// Split the text
    const parts = cellData.formattedValue.split(delimiter);

// Write parts to adjacent columns
    parts.forEach((part, index) => {
      const columnIndex = selection.range.startColumnIndex + index;

// Update cell with split value
      onChange?.(
        sheetId,
        { rowIndex, columnIndex },
        part.trim(),
        undefined,
        false
      );
    });
  }
}
```

## Delimiter Options

Common delimiters for text splitting:

```typescript
const delimiters = {
  comma: ",",
  semicolon: ";",
  tab: "\t",
  space: " ",
  pipe: "|",
  colon: ":",
  custom: "...", // User-defined
};
```

## Advanced Features

### Multiple Delimiters

Split by multiple delimiters at once:

```tsx
function splitByMultipleDelimiters(text: string, delimiters: string[]) {
  let result = [text];

delimiters.forEach((delimiter) => {
    result = result.flatMap((part) => part.split(delimiter));
  });

return result.map((part) => part.trim()).filter(Boolean);
}

// Example: Split by comma OR semicolon
const parts = splitByMultipleDelimiters("apple,banana;cherry", [",", ";"]);
// Result: ["apple", "banana", "cherry"]
```

### Fixed Width Splitting

Split text at fixed character positions:

```tsx
function splitFixedWidth(text: string, widths: number[]) {
  const parts: string[] = [];
  let position = 0;

widths.forEach((width) => {
    parts.push(text.slice(position, position + width).trim());
    position += width;
  });

// Add remaining text
  if (position < text.length) {
    parts.push(text.slice(position).trim());
  }

return parts;
}

// Example: Split "JohnDoe  25Engineer"
const parts = splitFixedWidth("JohnDoe  25Engineer", [8, 4]);
// Result: ["JohnDoe", "25", "Engineer"]
```

### Preserve Quoted Text

Don't split text within quotes:

```tsx
function splitWithQuotes(text: string, delimiter: string) {
  const regex = new RegExp(
    `${delimiter}(?=(?:[^"]*"[^"]*")*[^"]*$)`,
    "g"
  );
  return text.split(regex).map((part) => part.replace(/^"|"$/g, "").trim());
}

// Example: Split 'apple,"banana,cherry",grape'
const parts = splitWithQuotes('apple,"banana,cherry",grape', ",");
// Result: ["apple", "banana,cherry", "grape"]
```

## Keyboard Shortcuts

Add a keyboard shortcut for text splitting:

```tsx
function SpreadsheetWithShortcuts() {
  const { onSplitTextToColumns } = useSpreadsheetState({
    // configuration
  });

const handleKeyDown = (e: React.KeyboardEvent) => {
    // Ctrl/Cmd + Shift + T
    if ((e.ctrlKey || e.metaKey) && e.shiftKey && e.key === "T") {
      e.preventDefault();
      onSplitTextToColumns?.(activeSheetId, activeCell, selections);
    }
  };

return (
    <CanvasGrid
      onKeyDown={handleKeyDown}
      onSplitTextToColumns={onSplitTextToColumns}
      // ... other props
    />
  );
}
```

## Best Practices

1. **Backup Data**: Always preserve original data before splitting
2. **Check Column Space**: Ensure enough empty columns for split data
3. **Handle Edge Cases**: Account for empty cells and malformed data
4. **Trim Whitespace**: Remove leading/trailing spaces from split values
5. **Validate Output**: Verify the split operation produced expected results
6. **Undo Support**: Ensure split operations are undoable

## Error Handling

```tsx
function safeSplitTextToColumns(
  sheetId: number,
  activeCell: CellInterface,
  selections: SelectionArea<SelectionAttributes>[]
) {
  try {
    // Check if there's a selection
    if (!selections.length) {
      console.warn("No cells selected for splitting");
      return;
    }

// Check if there's enough space for split data
    const estimatedColumns = 5; // Estimate or calculate
    const maxColumn = getSheetColumnCount(sheetId);
    const startColumn = activeCell.columnIndex;

if (startColumn + estimatedColumns > maxColumn) {
      console.error("Not enough columns for split operation");
      return;
    }

// Perform split
    onSplitTextToColumns?.(sheetId, activeCell, selections);
  } catch (error) {
    console.error("Error splitting text to columns:", error);
  }
}
```

## Limitations

* The split operation requires adjacent empty columns
* Very long text may exceed column limits
* Complex delimiters may require custom parsing
* Large selections may impact performance

## Use Cases

### Data Import

Clean up imported CSV or TSV data:

```tsx
// Import raw data as single column, then split
```

### Name Parsing

Split full names into first and last names:

```tsx
// "John Doe" � "John" | "Doe"
```

### Email Processing

Extract username and domain from emails:

```tsx
// "user@example.com" � "user" | "example.com"
```

### Tag Parsing

Split tags or categories:

```tsx
// "tag1,tag2,tag3" � "tag1" | "tag2" | "tag3"
```

## Troubleshooting

### Split Not Working

* Verify `onSplitTextToColumns` is passed to CanvasGrid
* Check that cells contain text data
* Ensure there are empty columns for split data

### Unexpected Results

* Check delimiter selection
* Verify text format (quotes, escapes, etc.)
* Test with sample data first

### Performance Issues

* Limit selection size for large datasets
* Consider batch processing for many cells
* Use web workers for heavy split operations

# Conditional formatting

Change text or background colour of cells based on the value

CanvasGrid accepts array of `conditionalFormats` prop which can be used to inject formatting rules based on the value of a cell. Formula values are supported.

```tsx
import { SpreadsheetProvider, CanvasGrid } from "@rowsncolumns/spreadsheet";

const MySpreadsheet = () => {
  return (
    <CanvasGrid
      conditionalFormats={[
        {
          ranges: [
            {
              startRowIndex: 1,
              endRowIndex: 1000,
              startColumnIndex: 2,
              endColumnIndex: 2,
            },
          ],
          booleanRule: {
            condition: {
              type: "NUMBER_LESS",
              values: [
                {
                  userEnteredValue: "0",
                },
              ],
            },
            format: {
              backgroundColor: "red",
            },
          },
        },
      ]}
    />
  );
};

const App = () => (
  <SpreadsheetProvider>
    <MySpreadsheet />
  </SpreadsheetProvider>
);

```

### Gradient scale or heatmaps

```typescript
conditionalFormats: [
  {
    ranges: [
      {
        startRowIndex: 11,
        endRowIndex: 26,
        startColumnIndex: 7,
        endColumnIndex: 8,
      },
    ],
    gradientRule: {
      minpoint: {
        color: "#FFCF54",
        type: "MIN",
        // value: 10 Automatically calculated from range
      },
      midpoint: {
        color: "#FFE8A3",
        type: "MIN",
        // value: 12, Automatically calculated from range
      },
      maxpoint: {
        color: "#FFFFFF",
        type: "MAX",
        // value: 21, Automatically calculated from range
      },
    },
  },
],
```

### Data bars

Paint a horizontal bar inside each cell, scaled by the cell's value relative to the range min/max. Round-trips XLSX + ODS.

```typescript
conditionalFormats: [
  {
    ranges: [
      {
        startRowIndex: 1,
        endRowIndex: 20,
        startColumnIndex: 3,
        endColumnIndex: 3,
      },
    ],
    dataBarRule: {
      color: "#638EC6",
      minpoint: { type: "MIN" },
      maxpoint: { type: "MAX" },
      // Optional: separate color for negative values
      negativeColor: "#DC2626",
      // Optional: render direction ("leftToRight" / "rightToLeft")
      direction: "leftToRight",
      // Optional: hide the cell value, show only the bar
      showValue: true,
    },
  },
],
```

### Icon sets

Stamp an icon to the left of each cell based on which bucket the value falls in. Many built-in icon families ship: `3TrafficLights1`, `3TrafficLights2`, `3Arrows`, `3Symbols`, `4Rating`, `5Rating`, `5Arrows`, etc.

```typescript
conditionalFormats: [
  {
    ranges: [
      {
        startRowIndex: 1,
        endRowIndex: 20,
        startColumnIndex: 4,
        endColumnIndex: 4,
      },
    ],
    iconSetRule: {
      iconSet: "3TrafficLights1",
      // Thresholds split the value range into N buckets — for a 3-icon
      // set we need 2 thresholds (low/mid/high).
      thresholds: [
        { type: "PERCENT", value: 33 },
        { type: "PERCENT", value: 66 },
      ],
      // Optional: reverse the icon order (so red lights up on high
      // values instead of low).
      reverse: false,
      // Optional: show only the icon, hide the cell value
      showValue: true,
    },
  },
],
```

## Supported conditions

```typescript
// Supported condition types
export const CONDITION_TYPES = [
  "NUMBER_GREATER",
  "NUMBER_GREATER_THAN_EQ",
  "NUMBER_LESS",
  "NUMBER_LESS_THAN_EQ",
  "NUMBER_EQ",
  "NUMBER_NOT_EQ",
  "NUMBER_BETWEEN",
  "NUMBER_NOT_BETWEEN",
  "TEXT_CONTAINS",
  "TEXT_NOT_CONTAINS",
  "TEXT_STARTS_WITH",
  "TEXT_ENDS_WITH",
  "TEXT_EQ",
  "TEXT_IS_EMAIL",
  "TEXT_IS_URL",
  "DATE_EQ",
  "DATE_BEFORE",
  "DATE_AFTER",
  "DATE_ON_OR_BEFORE",
  "DATE_ON_OR_AFTER",
  "DATE_BETWEEN",
  "DATE_NOT_BETWEEN",
  "DATE_IS_VALID",
  "ONE_OF_RANGE",
  "ONE_OF_LIST",
  "BLANK",
  "NOT_BLANK",
  "CUSTOM_FORMULA",
  "BOOLEAN",
  "TEXT_NOT_EQ",
  "DATE_NOT_EQ",
] as const;
```

## Adding conditional format editor UI

Spreadsheet comes with a default conditional format editor.

Right click on any cell and select `Conditional format editor` . Or you can invoke the function `onRequestConditionalFormat` from useSpreadsheetState hook

<figure><img src="/files/1dASGN09BWrNJTQPAxMe" alt=""><figcaption><p>Conditional format editor</p></figcaption></figure>

```tsx
import { SpreadsheetProvider, CanvasGrid, defaultSpreadsheetTheme } from "@rowsncolumns/spreadsheet";
import { ConditionalFormatDialog, ConditionalFormatEditor } from "@rowsncolumns/spreadsheet-state"

const App = () => (
  <SpreadsheetProvider>
    <MySpreadsheet />
  </SpreadsheetProvider>
);

```

# Sparklines

Inline mini-charts inside cells — line, column, or win/loss

Sparklines are mini-charts rendered inside a single cell. They're authored as `SPARKLINE()` formulas, which means they live alongside the rest of the calculation graph — referenced cells recompute the sparkline on change, copy/paste duplicates the formula, and XLSX + ODS round-trip preserves every option.

## Basic usage

Type `=SPARKLINE(A1:A10)` into a cell. The cell's effective value becomes a `sparkline` structured value, the renderer paints the chart, and the formula bar still shows the source.

```
A1:A10 = numeric values
B1     = =SPARKLINE(A1:A10)        // line sparkline (default)
B2     = =SPARKLINE(A1:A10, {"charttype","column"})
B3     = =SPARKLINE(A1:A10, {"charttype","winloss"})
```

## Options

`SPARKLINE` takes an optional second argument — a flat array of `"key", value` pairs in Excel array literal syntax (`{…}`). All options round-trip both directions through XLSX (`<x14:sparklineGroup>` attributes) and via SPARKLINE formula text.

### Chart type + color

```
=SPARKLINE(A1:A10, {"charttype","line"})
=SPARKLINE(A1:A10, {"charttype","column"})
=SPARKLINE(A1:A10, {"charttype","winloss"})
=SPARKLINE(A1:A10, {"color","#638ec6"})
```

### Axis options

```
// Render an X-axis line
=SPARKLINE(A1:A10, {"axis",TRUE})

// Plot empty cells as zero (default: gap)
=SPARKLINE(A1:A10, {"emptycells","zero"})

// Or connect across blanks
=SPARKLINE(A1:A10, {"emptycells","span"})

// Treat the X axis as a date axis (when paired with a date series)
=SPARKLINE(A1:A10, {"dateaxis",TRUE})
```

### Point highlights

```
=SPARKLINE(A1:A10, {
  "markers",TRUE,           // line sparkline: diamond markers at every point
  "highpoint",TRUE,         // highlight the maximum
  "lowpoint",TRUE,          // highlight the minimum
  "firstpoint",TRUE,        // highlight the first point
  "lastpoint",TRUE,         // highlight the last point
  "negativepoints",TRUE     // column/winloss: color negative bars differently
})
```

### Axis bounds

By default each sparkline scales to its own min/max ("individual"). Switch to a group-wide or custom scale:

```
// Use a custom max + min instead of auto
=SPARKLINE(A1:A10, {"max",100, "min",-10})

// Scale to the group of sparklines in the same x14:sparklineGroup
=SPARKLINE(A1:A10, {"minaxistype","group", "maxaxistype","group"})

// Custom — exact values from max/min
=SPARKLINE(A1:A10, {"minaxistype","custom", "maxaxistype","custom"})
```

### Line weight

```
=SPARKLINE(A1:A10, {"lineweight",2.5})    // line sparkline only
```

### Composing options

Combine any of the above in a single options block:

```
=SPARKLINE(A1:A10, {
  "charttype","line",
  "color","#1d4ed8",
  "markers",TRUE,
  "highpoint",TRUE,
  "lowpoint",TRUE,
  "lineweight",2,
  "emptycells","span"
})
```

## XLSX round-trip

Sparklines export as `<x14:sparklineGroup>` blocks inside the worksheet's `extLst`. Two sparklines share a group when every axis option matches; distinct settings each get their own group block. The exporter follows Excel's grouping rule precisely so a saved-and-reopened file produces the same UI.

The legacy default highlight behavior (markers + high + low for line; high + low + negative for column / winloss) ships unchanged for bare `SPARKLINE(range)` formulas without explicit options.

## ODS round-trip

LibreOffice's `calcext:sparkline-groups` extension is parsed on import and emitted on export.

## Working with structured values

A sparkline cell's `ev.structuredValue` is a `SparkLineResult`:

```ts
type SparkLineResult = {
  kind: "sparkline";
  data: number[];
  options: Record<string, string | number | boolean>;
};
```

Custom renderers can read this directly and replace the default chart implementation.

# Comments

Legacy single-author cell notes with author + rich text + author color

Spreadsheet supports Excel's **legacy comments** model — single-author notes with rich text + author metadata, anchored to a single cell. These map to OOXML `comments.xml` on round-trip.

Excel 2016+ **threaded comments** (with replies and resolved state, stored in `commentsThreaded.xml`) are not yet supported.

## Authoring a comment

A comment lives on `CellData.note` as plain text, or as a richer pointer via `commentThreadId` (reserved for the future threaded model). For the legacy single-author case, `note` is the field:

```ts
const cellData: CellData = {
  ue: { sv: "Q3 revenue" },
  fv: "Q3 revenue",
  note: "Includes the Atlas-2 contract — see slack #revenue for context.",
};
```

The renderer paints a small triangle marker in the cell's corner. Hovering shows the note.

## Round-trip

* **XLSX**: parsed from `xl/comments<N>.xml`, emitted on the way out. Author + creation timestamp preserved.
* **ODS**: parsed from `office:annotation` children of the cell node.

## Threading

Excel 2016 introduced threaded comments stored in `xl/threadedComments/threadedComment<N>.xml` — different file, different schema. These carry replies, resolved state, person IDs, and @mentions in the thread body.

Threading is currently a Tier-1 round-trip gap. Files that use threaded comments will:

* Import: the legacy comment shim (`comments.xml`) is still read; threaded replies + resolved state are dropped.
* Export: written as a flat legacy comment.

Track it on `docs/getting-started/excel-google-sheet-compatibility.md` under "Comments (threaded with replies)".

## Mentions in comments

For `@user` mentions inside notes / comments, see [Mentions](/configuration/features/mentions). Mentions work on the live cell editor; persistence into the threaded-comments OOXML store is part of the same gap above.

# Gradient cell fills

Linear and radial gradient fills on individual cells — round-trips XLSX and renders on canvas

Set a gradient on any cell's `uf` (user-entered format) and the canvas renderer paints it directly. Supports both **linear** (with a rotation angle) and **path / radial** (with axis-of-radial insets), each with two or more color stops.

Mirrors OOXML's `<gradientFill>` element. XLSX round-trip is full; the canvas paint uses native `CanvasGradient` (`createLinearGradient` / `createRadialGradient`).

## Authoring

```ts
const cellData: CellData = {
  ue: { sv: "Header" },
  fv: "Header",
  uf: {
    gradient: {
      type: "linear",
      degree: 90,              // 0 = left→right, 90 = top→bottom, 180 = right→left, 270 = bottom→top
      stops: [
        { position: 0, color: "#fde68a" },
        { position: 1, color: "#dc2626" },
      ],
    },
  },
};
```

`position` is on `[0, 1]`. At least two stops are required; three+ stops give multi-stop ramps.

## Path / radial gradients

Use `type: "path"` with four optional inset values describing where the inner stop's "core" rectangle sits relative to the cell:

```ts
uf: {
  gradient: {
    type: "path",
    left: 0.5,
    right: 0.5,
    top: 0.5,
    bottom: 0.5,
    stops: [
      { position: 0, color: "#ffffff" },   // center
      { position: 1, color: "#7c3aed" },   // edges
    ],
  },
}
```

The example above produces a radial gradient centered in the cell. Shift the center off-axis by adjusting `left` / `right` / `top` / `bottom` (each 0..1 — the inset of the inner stop's core from that edge).

## Three-stop ramps

```ts
uf: {
  gradient: {
    type: "linear",
    degree: 45,
    stops: [
      { position: 0,   color: "#fef08a" },   // yellow at one end
      { position: 0.5, color: "#22c55e" },   // green in the middle
      { position: 1,   color: "#1e40af" },   // blue at the other end
    ],
  },
}
```

## Precedence over solid + pattern fills

When `gradient` is present on a cell's format, it takes precedence over `backgroundColor` and `fillPattern`. Excel's UI treats fills as mutually exclusive on a single cell, so the renderer matches that: pattern + solid are ignored.

The `cellXfsRegistry` deduplication hash includes the gradient stops, so two cells with the same gradient share a `sid` reference (same compression behavior as for regular fills).

## XLSX round-trip

Parser reads `<gradientFill>` from `xl/styles.xml` and hydrates the `gradient` field on `CellFormat`. Exporter emits the same element with `<stop position><color rgb="..."/></stop>` children. Both linear and path/radial round-trip. The OOXML attributes map 1:1 onto the type's fields:

| OOXML                                   | Field                             |
| --------------------------------------- | --------------------------------- |
| `type="linear"` + `degree`              | `type: "linear"`, `degree`        |
| `type="path"` + `left/right/top/bottom` | `type: "path"`, four inset fields |
| `<stop position><color rgb=…/></stop>`  | `stops` array                     |

## Canvas rendering

The renderer constructs a `CanvasGradient` for each cell:

* **Linear**: the gradient axis projects through the cell's centroid at the given angle; start/end points are where that axis exits the bounding box.
* **Path / radial**: a `createRadialGradient` anchored at the inset midpoint with radius = distance to the farthest corner.

`setLineDash` and stroke styles are preserved — gradient cells still get cell borders, conditional-format icons, etc.

## Storybook example

See the `compatShowcaseSheet` in the storybook (Sheet 1, row 12) for a side-by-side gallery: `linear 0°`, `linear 90°`, `linear 45° (3 stops)`, `path (radial)`, `linear 180°`, and a `linear vert 3-stop` example. The pattern-fill row (row 11) is positioned right above so you can compare the two paint paths.

# Linked data types

Cells that carry a structured entity (Stocks, Geography, custom) with refreshable fields accessed via dot notation

Linked data types are Excel's "Stocks" and "Geography" cells generalized into a framework. A cell holds an **entity** with named fields, and other cells reference those fields via dot notation (`=A1.price`). The library ships the entity model + a provider plug-in API; you wire your own data source.

This is how the storybook's "Insert stock at A1" button works — it writes an `entity` structured value into a cell, then `refreshDataTypes` walks every entity cell and calls the matching provider to refresh fields.

## The entity shape

A linked-data-type cell's `ev.structuredValue` is an entity:

```ts
type Entity = {
  kind: "entity";
  dataType: string;          // matches a DataTypeProvider.id
  externalId: string;        // the ticker / location / etc.
  status: "loading" | "loaded" | "stale" | "error";
  fields?: Record<string, string | number | boolean>;
  formattedValue?: string;
};
```

The cell renderer paints `formattedValue` (or `fv`) as the display text. Field-access formulas (`=A1.price`) resolve through `getEffectiveStructuredValue`.

## Wiring a provider

```ts
import type { DataTypeProvider } from "@rowsncolumns/spreadsheet-state";

const stockProvider: DataTypeProvider = {
  id: "stock",
  schema: () => [
    { field: "name", type: "string" },
    { field: "price", type: "number", numberFormat: '"$"#,##0.00' },
    { field: "currency", type: "string" },
    { field: "changePercent", type: "number", numberFormat: "0.00%" },
  ],
  async refresh(entity) {
    const ticker = (entity.externalId ?? "").toUpperCase();
    const row = await fetchStockQuote(ticker);
    return {
      fields: {
        name: row.name,
        price: row.price,
        currency: row.currency,
        changePercent: row.changePercent,
      },
      formattedValue: `${ticker}  $${row.price.toFixed(2)}`,
    };
  },
};
```

Pass providers to `useSpreadsheetState`:

```ts
const { refreshDataTypes } = useSpreadsheetState({
  dataTypeProviders: [stockProvider],
  getEffectiveStructuredValue: (structuredValue, property) => {
    if (property && structuredValue?.kind === "entity") {
      return resolveEntityField(structuredValue, property);
    }
    if (property) {
      const value = get(structuredValue, property);
      return value ?? "";
    }
    return structuredValue;
  },
});
```

`resolveEntityField` is exported from `@rowsncolumns/spreadsheet-state`; it reads `entity.fields[property]`.

## Inserting a linked data type

Write the entity shape into the cell's `ev.structuredValue`:

```ts
const tickers = ["AAPL", "MSFT", "GOOG"];
onChangeSheetData?.((prev) => {
  const next = { ...prev };
  const sheet = (next[activeSheetId] ?? []).slice();
  next[activeSheetId] = sheet;
  tickers.forEach((ticker, idx) => {
    const rowIndex = 1 + idx;
    const row = sheet[rowIndex] ?? {};
    const values = (row.values ?? []).slice();
    values[1] = {
      ev: {
        structuredValue: {
          kind: "entity",
          dataType: "stock",
          externalId: ticker,
          status: "stale",
          formattedValue: ticker,
        },
      },
      fv: ticker,
    };
    sheet[rowIndex] = { ...row, values };
  });
  return next;
});

// Now refresh so fields hydrate
await refreshDataTypes?.({ sheetId: activeSheetId });
```

After the refresh:

* `=A2.price` returns the numeric price.
* `=A2.changePercent` returns the percent (with format applied).
* `=SUM(A2:A4.price)` aggregates across multiple linked-data-type cells.

## Dot-notation field access

`=cellRef.field` resolves through the formula engine's structured-value branch. The field name matches a key in `entity.fields`. The library auto-applies the `numberFormat` declared in the provider's `schema()` to the result.

```
A2 entity {ticker: "AAPL", price: 182.50, currency: "USD"}

=A2                  → "AAPL  $182.50"   (cell's formattedValue)
=A2.price            → 182.50            (numeric)
=A2.currency         → "USD"             (string)
=A2.price * 100      → 18250
```

## Refresh model

`refreshDataTypes({sheetId})` walks every cell whose `structuredValue.kind === "entity"` and calls the matching provider's `refresh()`. Each refresh sets the cell's `status` to `"loading"` while in flight, then `"loaded"` (or `"error"`) when complete. Cells with downstream `=A1.field` formulas recompute automatically once the entity lands.

`status: "stale"` is the initial state for a freshly-inserted entity and triggers a refresh on the next `refreshDataTypes` call.

## What's not yet supported

* **OOXML `linkedDataType` round-trip** — Excel's native Stocks / Geography panels emit a specific element that's not yet parsed or emitted. Custom provider entities survive the export as plain JSON in `structuredValue` if the host writes them as such; Excel's native Stocks won't be recognized.

See [Excel compatibility](/getting-started/excel-google-sheet-compatibility) → "Phase 12 — linked data types" for the deferral notes.

# LAMBDA and higher-order functions

LAMBDA, LET, MAP/REDUCE/BYROW/BYCOL/SCAN/MAKEARRAY, and GROUPBY/PIVOTBY

The formula engine ships Excel's full LAMBDA family: `LAMBDA` as both an IIFE and a value, `LET` for named bindings, the six standard higher-order functions (`MAP`, `REDUCE`, `BYROW`, `BYCOL`, `SCAN`, `MAKEARRAY`), and `GROUPBY` / `PIVOTBY` built on the same infrastructure. Dependency tracking through lambda bodies is automatic.

## LAMBDA

Two shapes — both work:

**IIFE** (call inline):

```
=LAMBDA(x, x*x)(5)         → 25
=LAMBDA(a, b, a+b)(2, 3)   → 5
```

**As a value** (pass to a HOF or store on a named range):

```
=MAP(A1:A3, LAMBDA(v, v*2))
```

Internally a standalone `LAMBDA(...)` rewrites at compile time to `__RNC_LAMBDA__("params", "body source")`, which constructs a runtime lambda value `{__isLambda, params, body}`. HOFs unwrap that value and re-evaluate the body once per element with bindings substituted in.

A recursion guard caps depth at 256 to keep runaway lambdas from blowing the JS stack.

## LET

Bind names to values inside a formula. Source-level expansion: each binding's value is inlined into the body before parse.

```
=LET(n, 5, n*2)                  → 10
=LET(a, 3, b, 4, a+b)            → 7
=LET(name, "World", "Hello "&name) → "Hello World"
```

Nested LET works:

```
=LET(x, 10, LET(y, x*2, y+1))    → 21
```

A LET-bound LAMBDA can be called like a function — the engine substitutes Function-shaped occurrences of binding names with the lambda source, then the IIFE inliner collapses it:

```
=LET(double, LAMBDA(x, x*2), double(5))    → 10
=LET(add, LAMBDA(a, b, a+b), add(3, 4))    → 7
```

## Closures via LET capture

LET expands BEFORE LAMBDA, so any LET binding referenced inside a LAMBDA body is baked into the body source. This gives you closures for free:

```
=LET(n, 5, LAMBDA(x, x+n))
// becomes: __RNC_LAMBDA__("x", "x+(5)")
```

```
=LET(n, 10, LET(addn, LAMBDA(x, x+n), addn(5)))   → 15
```

## Higher-order functions

### MAP

Apply a lambda to each element of an array, returns a same-shape result:

```
=MAP(A1:A3, LAMBDA(v, v*2))
// [[1], [2], [3]] → [[2], [4], [6]]
```

Multiple input arrays of the same shape:

```
=MAP(A1:A3, B1:B3, LAMBDA(a, b, a+b))
```

### REDUCE

Left fold:

```
=REDUCE(0, A1:A3, LAMBDA(acc, v, acc+v))    // sum
=REDUCE(1, A1:A3, LAMBDA(acc, v, acc*v))    // product
```

### SCAN

Like REDUCE but returns intermediate accumulator values, same shape as input:

```
=SCAN(0, A1:A3, LAMBDA(acc, v, acc+v))      // running total
// [[1], [2], [3]] → [[1], [3], [6]]
```

### BYROW / BYCOL

Apply a lambda to each row (or column) as a 1D array:

```
=BYROW(A1:C3, LAMBDA(row, SUM(row)))
=BYCOL(A1:C3, LAMBDA(col, AVERAGE(col)))
```

### MAKEARRAY

Build an N×M array by invoking a lambda with `(r, c)` per cell (1-indexed per Excel):

```
=MAKEARRAY(2, 3, LAMBDA(r, c, r*10+c))
// [[11, 12, 13],
//  [21, 22, 23]]
```

## GROUPBY

Aggregate rows by row-field tuple, calling a lambda once per group on the group's value vector:

```
=GROUPBY(A1:A6, B1:B6, LAMBDA(v, SUM(v)))
```

Args:

| Arg               | Purpose                                                                           |
| ----------------- | --------------------------------------------------------------------------------- |
| `row_fields`      | column or 2D — each row defines a group key tuple                                 |
| `values`          | column or 2D — values to aggregate per group                                      |
| `function`        | LAMBDA receiving the group's value vector (1D array) and returning a scalar       |
| `[field_headers]` | 0 (default) / 1 — echo the leading header row in output                           |
| `[total_depth]`   | 0 (default) / 1 grand-total at top / -1 grand-total at bottom                     |
| `[sort_order]`    | 1 (default, asc) / -1 (desc) by the first row-field column                        |
| `[filter_array]`  | optional boolean column same length as row\_fields; rows where FALSE are excluded |

```
// Sum per category
=GROUPBY(A1:A6, B1:B6, LAMBDA(v, SUM(v)))

// Average per category, descending
=GROUPBY(A1:A6, B1:B6, LAMBDA(v, AVERAGE(v)), 0, 0, -1)

// With grand total at top
=GROUPBY(A1:A6, B1:B6, LAMBDA(v, SUM(v)), 0, 1)

// Count + filter
=GROUPBY(A1:A6, B1:B6, LAMBDA(v, COUNT(v)), 0, 0, 1, C1:C6)
```

The aggregation lambda receives the group's value vector as an Excel array literal (`{a, b, c}`) substituted into the body source — so any aggregator that accepts an array works (`SUM`, `AVERAGE`, `COUNT`, `MAX`, `MIN`, custom LAMBDAs, etc.).

## PIVOTBY

Two-axis cousin of GROUPBY — adds a column axis on top of the row grouping:

```
=PIVOTBY(rows, cols, values, function,
         [row_headers], [row_total_depth], [row_sort_order],
         [col_headers], [col_total_depth], [col_sort_order],
         [filter_array])
```

```
// Rows = regions, columns = quarters, values summed
=PIVOTBY(A1:A8, B1:B8, C1:C8, LAMBDA(v, SUM(v)))

// With row + column grand totals at top/left
=PIVOTBY(A1:A8, B1:B8, C1:C8, LAMBDA(v, SUM(v)), 0, 1, 1, 0, 1, 1)

// Totals at bottom/right
=PIVOTBY(A1:A8, B1:B8, C1:C8, LAMBDA(v, SUM(v)), 0, -1, 1, 0, -1, 1)

// Sort both axes descending
=PIVOTBY(A1:A8, B1:B8, C1:C8, LAMBDA(v, SUM(v)), 0, 0, -1, 0, 0, -1)
```

Output is a 2D spilled array — a header row of distinct column-tuples, then one row per distinct row-tuple prefixed by row labels.

## Dependency tracking through lambda bodies

When a lambda body references a cell, the dep parser walks the body string via a fresh inner parser instance and registers each ref as a precedent of the outer formula. Recalc propagates correctly:

```
=MAP(A1:A3, LAMBDA(v, v+B1))
// Both A1:A3 AND B1 are tracked as dependencies
```

```
=REDUCE(0, A1:A3, LAMBDA(acc, v, acc+v+C5))
// C5 is tracked
```

## Named LAMBDAs (workbook scope)

Define a named range whose value is a LAMBDA and call it like a function:

```
// In Name Manager:
Commission = =LAMBDA(sales, IF(sales > 1000, sales*0.1, sales*0.05))

// Anywhere in the workbook:
=Commission(500)    → 25
=Commission(5000)   → 500
=MAP(A1:A10, Commission)
```

See [Named ranges](/configuration/features/named-ranges) for the full story on workbook + sheet scoping.

## What's not yet supported

**Recursive LAMBDA** — `=LET(fact, LAMBDA(n, IF(n<=1, 1, n*fact(n-1))), fact(5))` doesn't work yet. Body-reparse at runtime loses the LET binding for `fact`. A runtime registry that survives per-call re-parse is the fix; deferred.

See `docs/getting-started/excel-google-sheet-compatibility.md` → "Phase 7" for the full status.

# Undo/Redo

All change history is preserved. Making versioning simple.

Change histories are stored as `immer` patches. But developers can choose their own state management modules, hence libraries like Redux or MobX can create state histories/patches.

`useSpreadsheetState` uses `immer` to product patches during state updates.

```tsx
import React, { useState } from "react";
import { CanvasGrid, CellData } from "@rowsncolumns/spreadsheet";
import { produceWithPatches } from "immer";
import {
  SheetData,
  useSpreadsheetState,
} from "@rowsncolumns/spreadsheet-state";

saveHistory({
            sheetData: { patches, inversePatches },
          });

return nextState;
        });
      }}
    />
  );
};
```

# Components

# Canvas Grid

The Canvas Grid that renders the spreadsheet

CanvasGrid is a controlled component that accepts a set of props and exposes callbacks for developers to hook into.

```tsx
import { SpreadsheetProvider, CanvasGrid } from "@rowsncolumns/spreadsheet";

const App = () => {
  return (
    <SpreadsheetProvider>
      <CanvasGrid
        rowCount={1000}
        columnCount={1000}
        sheetId={1}
      />
    </SpreadsheetProvider>
  );
};
```

## CanvasGrid options

The following options are supported by CanvasGrid component

```typescript
export type CanvasGridProps<T extends CellData = CellData> = {
  licenseKey?: string;
  /**
   * ID of the selected sheet
   */
  sheetId: number;
  /**
   * Initial active cell of the sheet
   */
  activeCell?: CellInterface;
  /**
   * Initial cell selections of the sheet
   */
  selections?: SelectionArea<SelectionAttributes>[];
  /**
   * Spreadsheet theme
   */
  theme?: SpreadsheetTheme;
  /**
   * Automatically focus on the Spreadsheet
   */
  autoFocus?: boolean;
  /**
   * Frozen row count
   */
  frozenRowCount?: number;
  /**
   * Frozen column count
   */
  frozenColumnCount?: number;
  /**
   * Total no of rows
   */
  rowCount?: number;
  /**
   * Total no of columns
   */
  columnCount?: number;
  /**
   * Scaling factor
   */
  scale?: number;
  /**
   * @deprecated basicFilter. Use tables instead
   */
  basicFilter?: FilterView;
  /**
   * Filter views
   */
  tables?: TableView[];
  /**
   * Named ranges
   */
  namedRanges?: NamedRange[];
  /**
   * Banded ranges
   */
  bandedRanges?: BandedRange[];
  /**
   * Collaborators of the sheetsActivecell + Selections of the
   * collaborator will be highlighted. Exclude current user
   */
  users?: Collaborator[];
  /**
   * Current user's userId
   */
  userId?: number | string;
  /**
   * Color of filter view border
   */
  tableBorderColor?: string;
  /**
   * Color of the filter icon
   */
  filterIconColor?: string;
  /**
   * Show filter icon in header cells
   */
  showFilterIcon?: boolean;
  /**
   * Show calculated column icon
   */
  showCalculatedColumnIcon?: boolean;
  /**
   * Conditional formatting
   */
  conditionalFormats?: ConditionalFormatRule[];
  /**
   * Embedded chart
   */
  charts?: EmbeddedChart[];
  /**
   * Pivot tables
   */
  pivotTables?: PivotTable[];
  /**
   * Embed any object on top of a sheet
   */
  embeds?: EmbeddedObject[];
  /**
   * Default row height
   */
  defaultRowHeight?: number;
  /**
   * Default column width
   */
  defaultColumnWidth?: number;
  /**
   * Default column header height
   */
  defaultColumnHeaderHeight?: number;
  /**
   * Default row header width
   */
  defaultRowHeaderWidth?: number;
  /**
   * Color of the sheet grid lines
   */
  gridLineColor?: string;
  /**
   * Default text color
   */
  cellColor?: string;
  /**
   * Header color of banded cell
   */
  bandedHeaderColor?: string;
  /**
   * Opacity of first band
   */
  bandedOpacity?: number;
  /**
   * Default background color of a cell
   */
  cellBackgroundColor?: string;
  /**
   * Border color of header cell
   */
  headerBorderColor?: string;
  /**
   * Background color of header cells
   */
  headerBackgroundColor?: string;
  /**
   * Header text color
   */
  headerColor?: string;
  /**
   * When a cell is selected
   */
  headerActiveBackgroundColor?: string;
  /**
   * Header background when an entire row or column is selected
   */
  headerSelectedBackgroundColor?: string;
  /**
   * Text color of header when an entire row or column is selected
   */
  headerSelectedColor?: string;
  /**
   * Header background for table cells
   */
  headerTableBackgroundColor?: string;
  /**
   * Header background when table cell is selected
   */
  headerTableActiveBackgroundColor?: string;
  /**
   * When an entire header row or column is selected
   */
  headerTableSelectedBackgroundColor?: string;
  /**
   * Selected border color for charts
   */
  chartSelectedColor?: string;
  /**
   * Background color of chips
   */
  chipBackgroundColor?: string;
  /**
   * Shadow color of frozen row
   */
  frozenShadowColor?: string;
  /**
   * Thickness of frozen shadow
   */
  frozenShadowThickness?: number;
  /**
   * Border color of selections
   */
  selectionBorderColor?: string;
  /**
   * Background selection color
   */
  selectionBackgroundColor?: string;
  /**
   * Border color when selection is dragged
   */
  selectionDragBorderColor?: string;
  /**
   * Merged cells
   */
  merges?: GridRange[];
  /**
   * Protected cell ranges
   */
  protectedRanges?: ProtectedRange[];
  /**
   * Additional bordered areas in the grid
   */
  borderStyles?: RangeBorderStyle[];
  /**
   * Meta data of a row
   */
  rowMetadata?: Sheet["columnMetadata"];
  /**
   * Meta data of a column
   */
  columnMetadata?: Sheet["columnMetadata"];
  /**
   * Enable sticky editor
   */
  stickyEditor?: boolean;
  /**
   * Scrollbar size
   */
  scrollbarSize?: number;
  /**
   * Show grid lines
   */
  showGridLines?: boolean;
  /**
   * Show frozen line separator for row and column
   */
  showFrozenSeparator?: boolean;
  /**
   * Show formulas in cells
   */
  showFormulas?: boolean;
  /**
   * Show spreadsheet row and column headers
   */
  showHeaders?: boolean;
  /**
   * Snaps to row or column while scrolling
   * Recommended for 60fps scrolling, Since canvas
   * does not need to redraw at each scroll frame
   */
  scrollSnap?: boolean;
  /**
   * How fast scroll should snap to row or column
   */
  scrollThrottleTimeout?: number;
  /**
   * Cell selection policy
   */
  selectionPolicy?: UseSelectionOptions["selectionPolicy"];
  /**
   * Enable enter key to edit a cell
   * When false, pressing enter will select the next cell
   */
  enableEditOnEnterKey?: boolean;
  /**
   * Show header menu button that invokes context menu
   */
  showHeaderMenuButton?: boolean;
  /**
   * Enable text overflow to neighbouring empty cells
   * Enabling it will have an performance impact
   */
  enableTextOverflow?: boolean;
  /**
   * Number of additional columns to
   * render on the left and right
   * Useful, when text overflows adjacent cells
   */
  overscanCount?: number;
  /**
   * Header renderer
   */
  HeaderCell?: ElementType<HeaderCellProps>;
  /**
   * Cell renderer
   */
  Cell?: ElementType<CellProps>;
  /**
   * Selection title component
   */
  SelectionTitleComponent?: ElementType<SelectionTitleProps>;
  /**
   * Cell Editor
   */
  CellEditor?: ElementType;
  /**
   * Tooltip
   */
  CellTooltip?: ElementType<CellTooltipProps>;
  /**
   * Custom Context menu component
   */
  ContextMenu?: ElementType;
  /**
   * Filterbox component
   */
  FilterBox?: ElementType | ReactElement;
  /**
   * Paste menu component, shown after a paste operation
   */
  PasteMenu?: React.ComponentType<PasteMenuProps>;
  /**
   * Agent suggestion action component
   */
  SuggestionAction?: React.ComponentType<SuggestionActionProps>;
  /**
   * Hidden row markers, shown in the row header for hidden rows
   */
  HiddenRowMarkers?: React.ComponentType<HiddenRowMarkersProps>;
  /**
   * Hidden column markers, shown in the column header for hidden columns
   */
  HiddenColumnMarkers?: React.ComponentType<HiddenColumnMarkersProps>;
  /**
   * Chart component
   */
  getChartComponent?(props: ChartComponentProps): React.ReactElement;
  /**
   * Chart component
   */
  getEmbedComponent?(props: EmbedComponentProps): React.ReactElement;
  /**
   * User scrolls the grid
   * @param scrollCoords
   */
  onScroll?(scrollCoords: ScrollCoords): void;
  /**
   * View port changes
   */
  onViewPortChange?(viewport: ViewPortProps): void;
  /**
   * Callback when user changes a cell value
   * @param sheetId
   * @param cell
   * @param value
   */
  onChange?(
    sheetId: number,
    cell: CellInterface,
    value: string | boolean,
    previousValue: string | boolean | undefined,
    isDirty?: boolean
  ): void;
  /**
   * User is deleting a cell or selections
   * @param sheetId
   * @param cell
   * @param selections
   */
  onDelete?(
    sheetId: number,
    cell: CellInterface,
    selections: SelectionArea<SelectionAttributes>[]
  ): void;
  /**
   * When user changes editor value
   * @param value
   * @param sheetId
   * @param cell
   */
  onChangeEditorValue?(
    value: string,
    sheetId: number,
    cell: CellInterface
  ): void;
  /**
   * For result preview panel in cell editor
   * @param value
   * @param sheetId
   * @param cell
   *
   * @returns FormulaResult
   */
  onRequestCalculate?(
    value: string,
    sheetId: number,
    rowIndex: number,
    columnIndex: number,
    isArray?: boolean
  ): Promise<
    | undefined
    | string
    | number
    | boolean
    | Date
    | (string | number | boolean | Date)[][]
  >;
  /**
   * Fill
   * @param cell
   * @param selections
   */
  onFill?(
    sheetId: number,
    cell: CellInterface,
    fillSelection: SelectionArea<SelectionAttributes>,
    selections: SelectionArea<SelectionAttributes>[]
  ): void;
  /**
   * Callback when user moves a selection
   * @param from
   * @param to
   */
  onMoveSelection?(
    sheetId: number,
    from: SelectionArea<SelectionAttributes>,
    to: SelectionArea<SelectionAttributes>
  ): void;
  /**
   * Callback when active cell changes
   */
  onChangeActiveCell?(cell: CellInterface): void;
  /**
   * Callback when selections cell changes
   */
  onChangeSelections?(
    selections: SelectionArea<SelectionAttributes>[],
    finishedSelection?: boolean
  ): void;
  /**
   * Formulas can trigger sheet change
   */
  onChangeActiveSheet?(sheetId: number): void;
  /**
   * Get data of a specific cell
   * @param rowIndex
   * @param columnIndex
   * @returns CellData
   */
  getCellData?(
    sheetId: number,
    rowIndex: number,
    columnIndex: number
  ): T | null | undefined;
  /**
   * Callback when user resizes a column or row
   * @param dimension
   * @param index
   * @param axis
   * @param autoFit
   */
  onResize?(
    sheetId: number,
    indexes: number[],
    dimension: number,
    axis: AXIS,
    autoFit?: boolean
  ): void;
  /**
   * Hide column
   * @param columnIndexes
   */
  onHideColumn?(sheetId: number, columnIndexes: number[]): void;
  /**
   * Hide row
   * @param rowIndexes
   */
  onHideRow?(sheetId: number, rowIndexes: number[]): void;
  /**
   * Show column
   * @param columnIndex
   */
  onShowColumn?(sheetId: number, columnIndexes: number[]): void;
  /**
   * Show row
   * @param rowIndex
   */
  onShowRow?(sheetId: number, rowIndexes: number[]): void;
  /**
   * Delete column
   * @param columnIndex
   */
  onDeleteColumn?(sheetId: number, columnIndexes: number[]): void;
  /**
   * Delete row
   * @param rowIndex
   */
  onDeleteRow?(sheetId: number, rowIndexes: number[]): void;
  /**
   * Insert column
   * @param columnIndex
   */
  onInsertColumn?(sheetId: number, columnIndex: number): void;
  /**
   * Insert row
   * @param rowIndex
   */
  onInsertRow?(sheetId: number, rowIndex: number): void;
  /**
   * When user inserts cell and shift down
   * @param cell
   */
  onInsertCellsShiftDown?(sheetId: number, cell: CellInterface): void;
  /**
   * When user inserts cell and shift right
   * @param cell
   */
  onInsertCellsShiftRight?(sheetId: number, cell: CellInterface): void;
  /**
   * Delete cells and shift left
   * @param cell
   */
  onDeleteCellsShiftLeft?(sheetId: number, cell: CellInterface): void;
  /**
   * Delete cells and shift up
   * @param cell
   */
  onDeleteCellsShiftUp?(sheetId: number, cell: CellInterface): void;
  /**
   * Callback when columns are moved
   * @param dims
   * @param toColumn
   */
  onMoveColumns?(sheetId: number, dims: number[], toColumn: number): void;
  /**
   * Callback when rows are moved
   * @param dims
   * @param toRow
   */
  onMoveRows?(sheetId: number, dims: number[], toRow: number): void;
  /**
   * User pressed a key to select previous sheet
   */
  onSelectPreviousSheet?(e?: React.KeyboardEvent<HTMLDivElement>): void;
  /**
   * User pressed a key to select previous sheet
   */
  onSelectNextSheet?(e?: React.KeyboardEvent<HTMLDivElement>): void;
  /**
   * Shift + Fn + F11
   * To insert a new sheet
   */
  onCreateNewSheet?(): void;
  /**
   * Keydown handler
   */
  onKeyDown?(e: React.KeyboardEvent<HTMLDivElement>): void;
  /**
   * When user changes formatting, Eg: bold, underline
   */
  onChangeFormatting?<T extends FormattingType>(
    sheetId: number,
    type: T,
    value: FormattingValue<T>
  ): void;
  /**
   * When user presses F4, we can replay the last formatting
   * on a new cell
   * @param sheetId
   */
  onRepeatFormatting?(sheetId: number): void;
  /**
   * User is trying to clear all formatting from
   * cells
   */
  onClearFormatting?(sheetId: number): void;
  /**
   * Callback when user clears contents
   */
  onClearContents?(sheetId: number, activeCell: CellInterface): void;
  /**
   * Called when user tries to edit a protected cell
   * @param cell
   */
  onEditProtectedCell?(sheetId: number, cell: CellInterface): void;
  /**
   * Return sheet name from sheetId
   * @param sheetId
   */
  getSheetName?(sheetId: number): string;
  /**
   * Callback when user resizes a chart
   * @param width
   * @param height
   */
  onResizeChart?(
    chartId: number,
    anchorCell: CellInterface,
    offsetXPixels: number,
    offsetYPixels: number,
    width: number,
    height: number
  ): void;
  /**
   * User is trying to delete an embed
   * @param chartId
   */
  onDeleteChart?(chartId: number): void;
  /**
   * Fired when user moves a chart
   * @param anchorCell
   * @param offsetXPixels
   * @param offsetYPixels
   */
  onMoveChart?(
    chartId: number,
    anchorCell: CellInterface,
    offsetXPixels: number,
    offsetYPixels: number
  ): void;
  /**
   * Callback when user resizes an embed
   * @param width
   * @param height
   */
  onResizeEmbed?(
    embedId: number,
    anchorCell: CellInterface,
    offsetXPixels: number,
    offsetYPixels: number,
    width: number,
    height: number
  ): void;
  /**
   * User is trying to delete an embed
   * @param embedId
   */
  onDeleteEmbed?(embedId: number): void;
  /**
   * Fired when user moves an embed
   * @param anchorCell
   * @param offsetXPixels
   * @param offsetYPixels
   */
  onMoveEmbed?(
    embedId: number,
    anchorCell: CellInterface,
    offsetXPixels: number,
    offsetYPixels: number
  ): void;
  /**
   * When user tries to fill range
   * @param activeCell
   * @param selections
   * @param direction
   *
   * Command + Enter => Fill range
   * Command + D => Fill down
   * Command + R => Fill right
   */
  onFillRange?(
    sheetId: number,
    activeCell: CellInterface,
    selections: SelectionArea<SelectionAttributes>[],
    direction?: Direction
  ): void;
  /**
   * On insert current time
   * @param activeCell
   * @param selections
   */
  onInsertTime?(
    sheetId: number,
    activeCell: CellInterface,
    selections: SelectionArea<SelectionAttributes>[]
  ): void;
  /**
   * On insert date
   * @param activeCell
   * @param selections
   */
  onInsertDate?(
    sheetId: number,
    activeCell: CellInterface,
    selections: SelectionArea<SelectionAttributes>[]
  ): void;
  /**
   * Freeze columns
   * @param sheetId
   * @param columnIndex
   */
  onFreezeColumn?(sheetId: number, columnIndex: number): void;
  /**
   * Freeze rows
   * @param sheetId
   * @param columnIndex
   */
  onFreezeRow?(sheetId: number, rowIndex: number): void;
  /**
   * User tries to undo an action
   */
  onUndo?(): void;
  /**
   * User tries to redo an action
   */
  onRedo?(): void;
  /**
   * Callback when user paste a set of cells
   * @param e Browser event
   * @param copiedSelections Selection that user copied
   * @param activeCell Current active cell
   * @param selections Current active selections
   * @param shouldDeleteSource If user has cut a selection, we should delete copiedSelections
   */
  onPaste?(
    e: ClipboardEvent | undefined,
    sourceSheetId: number | undefined,
    destinationSheetId: number,
    copiedSelections: SelectionArea<SelectionAttributes>[] | undefined,
    activeCell: CellInterface,
    selections: SelectionArea<SelectionAttributes>[] | undefined,
    finalSelections: SelectionArea<SelectionAttributes>[] | undefined,
    shouldDeleteSource: boolean
  ): void;
  /**
   * Callback when user copies a selection
   * useful to save copied selection till user
   * paste's the selection
   * @param e
   * @param copiedSelections Selections that user copied
   */
  onCopy?(
    e: ClipboardEvent | undefined,
    sheetId: number,
    copiedSelections: SelectionArea<SelectionAttributes>[]
  ): void;
  /**
   * Callback when user cuts a selection
   * @param e
   */
  onCut?(e: ClipboardEvent | undefined, sheetId: number): void;
  /**
   * Sort sheet by columnIndex
   * @param columnIndex
   * @param sortOrder
   */
  onSortColumn?(
    sheetId: number,
    columnIndex: number,
    sortOrder: SortOrder
  ): void;
  /**
   * Callback when user sorts a basicFilter or Table
   */
  onSortTable?(
    sheetId: number,
    filter: FilterView | TableView,
    columnIndex: number,
    direction: SortOrder
  ): void;
  /**
   * Callback when applies a filter
   * @param columnIndex
   * @param conditionType
   * @param conditionValue
   * @param hiddenValues
   */
  onFilterTable?(
    sheetId: number,
    filter: FilterView | TableView,
    columnIndex: number,
    conditionType: ConditionType | undefined,
    conditionValue: ConditionValue[] | undefined,
    hiddenValues: string[]
  ): void;
  /**
   * Callback when user resizes a table
   * @param sheetId
   * @param tableId
   * @param range
   */
  onResizeTable?(sheetId: number, table: TableView, range: GridRange): void;
  /**
   * Callback when user updates or adds a new note
   * @param sheetId
   * @param cell
   * @param notes
   */
  onUpdateNote?(sheetId: number, cell: CellInterface, notes?: string): void;
  /**
   * User wants to protect a range of cells or sheet
   * @param sheetId
   * @param cell
   * @param selections
   */
  onProtectRange?(
    sheetId: number,
    cell: CellInterface,
    selections: SelectionArea<SelectionAttributes>[] | undefined
  ): void;
  /**
   * Un protect range by Id
   * @param sheetId
   * @param protectedRangeId
   */
  onUnProtectRange?(sheetId: number, protectedRangeId: number): void;
  /**
   * Sort a selection range
   * @param sheetId
   * @param selection
   */
  onSortRange?(
    sheetId: number,
    selection: SelectionArea<SelectionAttributes>[],
    sortOrder: SortOrder
  ): void;
  /**
   * On Request edit a table
   * Developers can choose to show a modal dialog
   * @param table
   */
  onRequestEditTable?(table: TableView): void;
  /**
   * Handle keyboard shortcut to create a new table
   * Option + Command + T
   * Ctrl + Option + T
   */
  onCreateTable?(
    sheetId: number,
    activeCell: CellInterface,
    selections: SelectionArea<SelectionAttributes>[],
    headerRow?: boolean
  ): void;
  /**
   * Request to edit a pivot table configuration
   * @param pivotId
   */
  onRequestEditPivotTable?(pivotId: string): void;
  /**
   * Request to delete a pivot table
   * @param pivotId
   */
  onRequestDeletePivotTable?(pivotId: string): void;
  /**
   * Define a new or edit an existing named range
   */
  onRequestDefineNamedRange?(
    sheetId: number,
    activeCell: CellInterface,
    selections: SelectionArea<SelectionAttributes>[]
  ): void;
  /**
   * Get text for a row header
   * @param rowIndex
   */
  getRowHeaderText?(rowIndex: number): string;
  /**
   * Get text for a column header
   * @param columnIndex
   */
  getColumnHeaderText?(columnIndex: number): string;
  /**
   * Parses a text value to return tokens
   * @param value
   */
  tokenizer?(value: string | undefined, sheetName?: string): ParsedToken[];
  /**
   * All functions supported by the
   * calculator, used for suggestions
   * in the formula dropdown
   */
  functionDescriptions?: CalculatorFunction[];
};
```

# Toolbar

Toolbar component is a wrapper for all formatting buttons of the Spreadsheet

Toolbar component can be imported from spreadsheet module using the following code. You can compose your own toolbar or even use a third-party component to render the buttons.

[Radix icons](https://icons.radix-ui.com/) are used for the toolbar buttons, but this can be easily swapped to any icon set by using custom components.

<figure><img src="/files/KRZNH75lgVWUy3YrKya9" alt=""><figcaption><p>Toolbar</p></figcaption></figure>

<pre class="language-tsx"><code class="lang-tsx"><strong>import {
</strong>  Toolbar,
  ButtonDecreaseDecimal,
  ButtonFormatCurrency,
  ButtonFormatPercent,
  ButtonIncreaseDecimal,
  ButtonRedo,
  ButtonUndo,
  ScaleSelector,
  ToolbarSeparator,
  BackgroundColorSelector,
  BorderSelector,
  ButtonBold,
  ButtonItalic,
  ButtonStrikethrough,
  ButtonUnderline,
  ButtonInsertImage,
  ButtonInsertLink,
  ButtonSwitchColorMode,
  ThemeSelector,
  TableActions,
  FontFamilySelector,
  FontSizeSelector,
  MergeCellsSelector,
  TextColorSelector,
  TextFormatSelector,
  TextHorizontalAlignSelector,
  TextVerticalAlignSelector,
  TextWrapSelector
} from "@rowsncolumns/spreadsheet";
import { Separator } from "@rowsncolumns/ui";

const App = () => {
  return (
    <Toolbar>
      <ButtonUndo />
      <ButtonRedo />
      <ToolbarSeparator />
      <ScaleSelector />
      <ToolbarSeparator />
      <ButtonFormatCurrency />
      <ButtonFormatPercent />
      <ButtonDecreaseDecimal />
      <ButtonIncreaseDecimal />
      <TextFormatSelector />
      <ToolbarSeparator />
      <FontFamilySelector />
      <ToolbarSeparator />
      <FontSizeSelector />
      <ToolbarSeparator />
      <ButtonBold />
      <ButtonItalic />
      <ButtonUnderline />
      <ButtonStrikethrough />
      <TextColorSelector />
      <ToolbarSeparator />
      <BackgroundColorSelector />
      <BorderSelector />
      <MergeCellsSelector />
      <ToolbarSeparator />
      <TextHorizontalAlignSelector />
      <TextVerticalAlignSelector />
      <TextWrapSelector />
      
      <ButtonInsertImage />
      <ButtonInsertLink />
      <ButtonSwitchColorMode />
      <ThemeSelector />
      <TableAction />
    </Toolbar>
  );
};
</code></pre>

## BottomBar

BottomBar component is a container for the footer of the Spreadsheet, which houses Sheet Tabs, Sheet Switcher, Sheet Status and NewSheetButton component

# Formula Bar

Display and edit cell formulas and values

The Formula Bar is a compound component that displays the active cell reference and allows users to view and edit cell values and formulas. It consists of three main sub-components: `FormulaBar`, `FormulaBarLabel`, and `FormulaBarInput`.

## Overview

The Formula Bar provides:

* **Cell reference display**: Shows the active cell address (e.g., "A1", "Sheet2!B5")
* **Formula editing**: Edit cell formulas and values in a larger input area
* **Formula preview**: View complete formulas without cell width constraints
* **Function hints**: Display function syntax and autocomplete

## Components

### FormulaBar

The parent container that wraps the formula bar components.

```tsx
import { FormulaBar, FormulaBarLabel, FormulaBarInput } from "@rowsncolumns/spreadsheet";

<FormulaBar>
  <FormulaBarLabel>A1</FormulaBarLabel>
  <FormulaBarInput
    value="=SUM(A1:A10)"
    onChange={handleChange}
  />
</FormulaBar>
```

### FormulaBarLabel

Displays the active cell reference or range.

```tsx
import { FormulaBarLabel } from "@rowsncolumns/spreadsheet";
import { cellToAddress } from "@rowsncolumns/utils";

function MyFormulaBar() {
  const { activeCell, activeSheetId, selections } = useSpreadsheetState({});

const label = selections.length > 1
    ? selectionToAddress(selections[0])
    : cellToAddress(activeCell);

return (
    <FormulaBarLabel>
      {label}
    </FormulaBarLabel>
  );
}
```

### FormulaBarInput

Input field for editing cell values and formulas.

```tsx
import { FormulaBarInput } from "@rowsncolumns/spreadsheet";

<FormulaBarInput
  value={cellValue}
  onChange={(value) => onChange(activeSheetId, activeCell, value)}
  onKeyDown={handleKeyDown}
  functionDescriptions={functionDescriptions}
/>
```

## Complete Example

```tsx
import React, { useState } from "react";
import {
  SpreadsheetProvider,
  CanvasGrid,
  FormulaBar,
  FormulaBarLabel,
  FormulaBarInput,
  Sheet,
} from "@rowsncolumns/spreadsheet";
import {
  useSpreadsheetState,
  SheetData,
  CellData,
} from "@rowsncolumns/spreadsheet-state";
import { cellToAddress, selectionToAddress } from "@rowsncolumns/utils";
import { functionDescriptions } from "@rowsncolumns/functions";

function SpreadsheetWithFormulaBar() {
  const [sheets, setSheets] = useState<Sheet[]>([
    { sheetId: 1, rowCount: 100, columnCount: 26, title: "Sheet 1" }
  ]);
  const [sheetData, setSheetData] = useState<SheetData<CellData>>({});

const {
    activeCell,
    activeSheetId,
    selections,
    getCellData,
    getSheetName,
    onChangeActiveCell,
    onChangeSelections,
    onChange,
  } = useSpreadsheetState({
    sheets,
    sheetData,
    onChangeSheets: setSheets,
    onChangeSheetData: setSheetData,
  });

// Get current cell data
  const cellData = getCellData(
    activeSheetId,
    activeCell.rowIndex,
    activeCell.columnIndex
  );

// Determine label (cell reference or range)
  const formulaBarLabel = selections.length > 0 && selections[0]
    ? selectionToAddress(selections[0])
    : cellToAddress(activeCell);

// Get cell value (formula or formatted value)
  const cellValue = cellData?.ue?.fv
    || cellData?.fv
    || "";

return (
    <SpreadsheetProvider>
      <div className="flex flex-col h-screen">
        {/* Formula Bar */}
        <FormulaBar>
          <FormulaBarLabel>{formulaBarLabel}</FormulaBarLabel>
          <FormulaBarInput
            value={cellValue}
            onChange={(value) => {
              onChange?.(
                activeSheetId,
                activeCell,
                value,
                cellData?.fv
              );
            }}
            functionDescriptions={functionDescriptions}
            getSheetName={getSheetName}
          />
        </FormulaBar>

{/* Spreadsheet Grid */}
        <div className="flex-1">
          <CanvasGrid
            sheetId={activeSheetId}
            activeCell={activeCell}
            selections={selections}
            getCellData={getCellData}
            onChangeActiveCell={onChangeActiveCell}
            onChangeSelections={onChangeSelections}
            onChange={onChange}
            functionDescriptions={functionDescriptions}
          />
        </div>
      </div>
    </SpreadsheetProvider>
  );
}

export default SpreadsheetWithFormulaBar;
```

## Props

### FormulaBar

| Prop        | Type              | Description                                         |
| ----------- | ----------------- | --------------------------------------------------- |
| `children`  | `React.ReactNode` | Child components (FormulaBarLabel, FormulaBarInput) |
| `className` | `string`          | Optional CSS class name                             |

### FormulaBarLabel

| Prop        | Type              | Description                               |
| ----------- | ----------------- | ----------------------------------------- |
| `children`  | `React.ReactNode` | Cell reference text (e.g., "A1", "B2:D5") |
| `className` | `string`          | Optional CSS class name                   |

### FormulaBarInput

| Prop                   | Type                               | Description                           |
| ---------------------- | ---------------------------------- | ------------------------------------- |
| `value`                | `string`                           | Current cell value or formula         |
| `onChange`             | `(value: string) => void`          | Callback when value changes           |
| `onKeyDown`            | `(e: React.KeyboardEvent) => void` | Optional keyboard handler             |
| `functionDescriptions` | `CalculatorFunction[]`             | Function definitions for autocomplete |
| `getSheetName`         | `(sheetId: number) => string`      | Get sheet name by ID                  |
| `className`            | `string`                           | Optional CSS class name               |

## Features

### Formula Autocomplete

The FormulaBarInput supports autocomplete for functions when `functionDescriptions` is provided:

```tsx
import { functionDescriptions, functions } from "@rowsncolumns/functions";

<FormulaBarInput
  value={cellValue}
  onChange={onChange}
  functionDescriptions={functionDescriptions}
/>
```

When users type `=SUM(`, the input shows function hints and parameter information.

### Multi-Cell Selection Display

When multiple cells are selected, the label shows the range:

```tsx
const label = selections.length > 0 && selections[0]
  ? selectionToAddress(selections[0])  // "A1:E10"
  : cellToAddress(activeCell);         // "A1"

<FormulaBarLabel>{label}</FormulaBarLabel>
```

### Named Range Display

Show named range when applicable:

```tsx
const getFormulaBarLabel = () => {
  // Check if selection is a named range
  const selection = selections[0];
  const namedRange = namedRanges.find(nr =>
    rangesEqual(nr.range, selection?.range)
  );

if (namedRange) {
    return namedRange.name; // "SalesData"
  }

return selectionToAddress(selection) || cellToAddress(activeCell);
};
```

### Cross-Sheet References

Display sheet names in cross-sheet references:

```tsx
import { getSheetName } from "@rowsncolumns/spreadsheet-state";

const label = activeSheetId !== 1
  ? `${getSheetName(activeSheetId)}!${cellToAddress(activeCell)}`
  : cellToAddress(activeCell);

<FormulaBarLabel>{label}</FormulaBarLabel>
```

## Keyboard Shortcuts

The Formula Bar supports standard keyboard shortcuts:

* **Enter**: Confirm and move to next cell
* **Escape**: Cancel editing
* **Tab**: Autocomplete function name
* **F2**: Edit cell in formula bar
* **Ctrl/Cmd + A**: Select all text

## Styling

The Formula Bar can be styled using CSS classes:

```tsx
<FormulaBar className="border-b bg-white">
  <FormulaBarLabel className="font-mono text-sm px-3 py-2 border-r bg-gray-50" />
  <FormulaBarInput className="flex-1 px-3 py-2 font-mono text-sm" />
</FormulaBar>
```

## Integration with Toolbar

Combine with toolbar for a complete spreadsheet interface:

```tsx
import { Toolbar, FormulaBar } from "@rowsncolumns/spreadsheet";

<div className="flex flex-col h-screen">
  <Toolbar>
    {/* Toolbar buttons */}
  </Toolbar>

<FormulaBar>
    <FormulaBarLabel>{label}</FormulaBarLabel>
    <FormulaBarInput value={value} onChange={onChange} />
  </FormulaBar>

<div className="flex-1">
    <CanvasGrid {...props} />
  </div>
</div>
```

## Advanced Usage

### Custom Formula Validation

Validate formulas before applying:

```tsx
const handleFormulaChange = (value: string) => {
  if (value.startsWith("=")) {
    // Validate formula syntax
    try {
      validateFormula(value);
      onChange(activeSheetId, activeCell, value);
    } catch (error) {
      console.error("Invalid formula:", error);
    }
  } else {
    onChange(activeSheetId, activeCell, value);
  }
};

<FormulaBarInput
  value={cellValue}
  onChange={handleFormulaChange}
/>
```

### Formula Highlighting

Highlight cell references in formulas:

```tsx
const highlightedFormula = useMemo(() => {
  if (!cellValue.startsWith("=")) return cellValue;

// Highlight cell references (A1, B2:C5, etc.)
  return cellValue.replace(
    /([A-Z]+[0-9]+)(:[A-Z]+[0-9]+)?/g,
    '<span class="text-blue-600 font-semibold">$&</span>'
  );
}, [cellValue]);
```

### Read-Only Mode

Disable editing in read-only mode:

```tsx
<FormulaBarInput
  value={cellValue}
  onChange={readonly ? undefined : onChange}
  readOnly={readonly}
/>
```

## Best Practices

1. **Always Show Cell Reference**: Display the current cell or range reference in FormulaBarLabel
2. **Sync with Active Cell**: Update formula bar when active cell changes
3. **Handle Long Formulas**: Ensure the input can scroll for long formulas
4. **Provide Function Hints**: Include functionDescriptions for better UX
5. **Validate Input**: Check for formula errors before applying changes
6. **Support Keyboard Navigation**: Implement standard spreadsheet keyboard shortcuts

## Troubleshooting

### Formula Bar Not Updating

* Verify activeCell and selections are properly synced
* Check that getCellData returns the correct cell data
* Ensure onChange is called when cell values change

### Autocomplete Not Working

* Confirm functionDescriptions prop is provided
* Check that function definitions are properly formatted
* Verify the formula starts with "="

### Performance Issues

* Memoize cellValue calculation for large spreadsheets
* Use debouncing for onChange handler
* Consider lazy loading function descriptions

## See Also

* [Formula Input](/configuration/components/formula-input) - Standalone formula input component
* [Toolbar](/configuration/components/toolbar) - Toolbar component with formatting buttons
* [Canvas Grid](/configuration/components/canvas-grid) - Main spreadsheet grid component

# Font and Text Selectors

Font family, size, and text formatting selectors

A collection of toolbar components for font and text formatting including font family selection, font size adjustment, text alignment, and text wrapping options.

## Components Overview

* **FontFamilySelector**: Choose font family (Arial, Times New Roman, etc.)
* **FontSizeSelector**: Select font size in points
* **TextHorizontalAlignSelector**: Horizontal text alignment
* **TextVerticalAlignSelector**: Vertical text alignment
* **TextWrapSelector**: Text wrapping options
* **TextFormatSelector**: Additional text formatting options

## FontFamilySelector

Select the font family for cells.

### Basic Usage

```tsx
import { FontFamilySelector } from "@rowsncolumns/spreadsheet";

<FontFamilySelector
  value={currentCellFormat?.textFormat?.fontFamily}
  onChange={(value) => {
    onChangeFormatting(
      activeSheetId,
      activeCell,
      selections,
      "textFormat",
      { fontFamily: value }
    );
  }}
/>
```

### Complete Example

```tsx
import React, { useState } from "react";
import {
  SpreadsheetProvider,
  CanvasGrid,
  Toolbar,
  FontFamilySelector,
  Sheet,
} from "@rowsncolumns/spreadsheet";
import {
  useSpreadsheetState,
  SheetData,
  CellData,
} from "@rowsncolumns/spreadsheet-state";

function SpreadsheetWithFontSelector() {
  const [sheets, setSheets] = useState<Sheet[]>([
    { sheetId: 1, rowCount: 100, columnCount: 26, title: "Sheet 1" }
  ]);
  const [sheetData, setSheetData] = useState<SheetData<CellData>>({});

const {
    activeCell,
    activeSheetId,
    selections,
    getEffectiveFormat,
    onChangeFormatting,
  } = useSpreadsheetState({
    sheets,
    sheetData,
    onChangeSheets: setSheets,
    onChangeSheetData: setSheetData,
  });

const currentCellFormat = getEffectiveFormat(
    activeSheetId,
    activeCell.rowIndex,
    activeCell.columnIndex
  );

return (
    <SpreadsheetProvider>
      <Toolbar>
        <FontFamilySelector
          value={currentCellFormat?.textFormat?.fontFamily}
          onChange={(value) => {
            onChangeFormatting(
              activeSheetId,
              activeCell,
              selections,
              "textFormat",
              { fontFamily: value }
            );
          }}
        />
      </Toolbar>

<CanvasGrid
        sheetId={activeSheetId}
        activeCell={activeCell}
        selections={selections}
        // ... other props
      />
    </SpreadsheetProvider>
  );
}
```

### Props

| Prop        | Type                      | Description                                            |
| ----------- | ------------------------- | ------------------------------------------------------ |
| `value`     | `string`                  | Current font family (e.g., "Arial", "Times New Roman") |
| `onChange`  | `(value: string) => void` | Callback when font family changes                      |
| `className` | `string`                  | Optional CSS class name                                |

### Supported Fonts

Default supported fonts include:

* Arial
* Times New Roman
* Courier New
* Georgia
* Verdana
* Comic Sans MS
* Impact
* Trebuchet MS

## FontSizeSelector

Select font size in points.

### Basic Usage

```tsx
import { FontSizeSelector, DEFAULT_FONT_SIZE_PT } from "@rowsncolumns/spreadsheet";

<FontSizeSelector
  value={currentCellFormat?.textFormat?.fontSize ?? DEFAULT_FONT_SIZE_PT}
  onChange={(value) => {
    onChangeFormatting(
      activeSheetId,
      activeCell,
      selections,
      "textFormat",
      { fontSize: value }
    );
  }}
/>
```

### Props

| Prop        | Type                      | Description                               |
| ----------- | ------------------------- | ----------------------------------------- |
| `value`     | `number`                  | Current font size in points (default: 11) |
| `onChange`  | `(value: number) => void` | Callback when font size changes           |
| `className` | `string`                  | Optional CSS class name                   |

### Common Font Sizes

* 8pt (Very Small)
* 10pt (Small)
* 11pt (Default)
* 12pt (Normal)
* 14pt (Large)
* 18pt (Heading)
* 24pt (Large Heading)
* 36pt (Display)

## TextHorizontalAlignSelector

Horizontal text alignment selector.

### Basic Usage

```tsx
import { TextHorizontalAlignSelector } from "@rowsncolumns/spreadsheet";

<TextHorizontalAlignSelector
  value={currentCellFormat?.horizontalAlignment}
  onChange={(value) => {
    onChangeFormatting(
      activeSheetId,
      activeCell,
      selections,
      "horizontalAlignment",
      value
    );
  }}
/>
```

### Props

| Prop        | Type                            | Description                     |
| ----------- | ------------------------------- | ------------------------------- |
| `value`     | `"left" \| "center" \| "right"` | Current horizontal alignment    |
| `onChange`  | `(value) => void`               | Callback when alignment changes |
| `className` | `string`                        | Optional CSS class name         |

### Alignment Options

* **Left**: Align text to the left (default for text)
* **Center**: Center text horizontally
* **Right**: Align text to the right (default for numbers)

## TextVerticalAlignSelector

Vertical text alignment selector.

### Basic Usage

```tsx
import { TextVerticalAlignSelector } from "@rowsncolumns/spreadsheet";

### Props

| Prop        | Type                            | Description                     |
| ----------- | ------------------------------- | ------------------------------- |
| `value`     | `"top" \| "middle" \| "bottom"` | Current vertical alignment      |
| `onChange`  | `(value) => void`               | Callback when alignment changes |
| `className` | `string`                        | Optional CSS class name         |

### Alignment Options

* **Top**: Align text to top of cell
* **Middle**: Center text vertically (default)
* **Bottom**: Align text to bottom of cell

## TextWrapSelector

Text wrapping options.

### Basic Usage

```tsx
import { TextWrapSelector } from "@rowsncolumns/spreadsheet";

<TextWrapSelector
  value={currentCellFormat?.wrapStrategy}
  onChange={(value) => {
    onChangeFormatting(
      activeSheetId,
      activeCell,
      selections,
      "wrapStrategy",
      value
    );
  }}
/>
```

### Props

| Prop        | Type                             | Description                         |
| ----------- | -------------------------------- | ----------------------------------- |
| `value`     | `"overflow" \| "clip" \| "wrap"` | Current wrap strategy               |
| `onChange`  | `(value) => void`                | Callback when wrap strategy changes |
| `className` | `string`                         | Optional CSS class name             |

### Wrap Options

* **Overflow**: Text overflows into adjacent cells (default)
* **Clip**: Text is clipped at cell boundary
* **Wrap**: Text wraps within the cell

## TextFormatSelector

Additional text formatting options.

### Basic Usage

```tsx
import { TextFormatSelector } from "@rowsncolumns/spreadsheet";

<TextFormatSelector
  value={currentCellFormat?.textRotation}
  onChange={(value) => {
    onChangeFormatting(
      activeSheetId,
      activeCell,
      selections,
      "textRotation",
      value
    );
  }}
/>
```

### Props

| Prop        | Type                      | Description                             |
| ----------- | ------------------------- | --------------------------------------- |
| `value`     | `number`                  | Text rotation angle (-90 to 90 degrees) |
| `onChange`  | `(value: number) => void` | Callback when rotation changes          |
| `className` | `string`                  | Optional CSS class name                 |

## Complete Toolbar Example

```tsx
import React, { useState } from "react";
import {
  SpreadsheetProvider,
  CanvasGrid,
  Toolbar,
  ToolbarSeparator,
  FontFamilySelector,
  FontSizeSelector,
  TextHorizontalAlignSelector,
  TextVerticalAlignSelector,
  TextWrapSelector,
  ButtonBold,
  ButtonItalic,
  ButtonUnderline,
  DEFAULT_FONT_SIZE_PT,
  Sheet,
} from "@rowsncolumns/spreadsheet";
import {
  useSpreadsheetState,
  SheetData,
  CellData,
} from "@rowsncolumns/spreadsheet-state";

function SpreadsheetWithTextFormatting() {
  const [sheets, setSheets] = useState<Sheet[]>([
    { sheetId: 1, rowCount: 100, columnCount: 26, title: "Sheet 1" }
  ]);
  const [sheetData, setSheetData] = useState<SheetData<CellData>>({});

const {
    activeCell,
    activeSheetId,
    selections,
    getCellData,
    getEffectiveFormat,
    onChangeActiveCell,
    onChangeSelections,
    onChangeFormatting,
  } = useSpreadsheetState({
    sheets,
    sheetData,
    onChangeSheets: setSheets,
    onChangeSheetData: setSheetData,
  });

const currentCellFormat = getEffectiveFormat(
    activeSheetId,
    activeCell.rowIndex,
    activeCell.columnIndex
  );

return (
    <SpreadsheetProvider>
      <div className="flex flex-col h-screen">
        <Toolbar>
          {/* Font Family */}
          <FontFamilySelector
            value={currentCellFormat?.textFormat?.fontFamily}
            onChange={(value) => {
              onChangeFormatting(
                activeSheetId,
                activeCell,
                selections,
                "textFormat",
                { fontFamily: value }
              );
            }}
          />

{/* Font Size */}
          <FontSizeSelector
            value={currentCellFormat?.textFormat?.fontSize ?? DEFAULT_FONT_SIZE_PT}
            onChange={(value) => {
              onChangeFormatting(
                activeSheetId,
                activeCell,
                selections,
                "textFormat",
                { fontSize: value }
              );
            }}
          />

{/* Bold, Italic, Underline */}
          <ButtonBold
            active={currentCellFormat?.textFormat?.bold}
            onClick={() => {
              onChangeFormatting(
                activeSheetId,
                activeCell,
                selections,
                "textFormat",
                { bold: !currentCellFormat?.textFormat?.bold }
              );
            }}
          />

<ButtonItalic
            active={currentCellFormat?.textFormat?.italic}
            onClick={() => {
              onChangeFormatting(
                activeSheetId,
                activeCell,
                selections,
                "textFormat",
                { italic: !currentCellFormat?.textFormat?.italic }
              );
            }}
          />

<ButtonUnderline
            active={currentCellFormat?.textFormat?.underline}
            onClick={() => {
              onChangeFormatting(
                activeSheetId,
                activeCell,
                selections,
                "textFormat",
                { underline: !currentCellFormat?.textFormat?.underline }
              );
            }}
          />

{/* Text Alignment */}
          <TextHorizontalAlignSelector
            value={currentCellFormat?.horizontalAlignment}
            onChange={(value) => {
              onChangeFormatting(
                activeSheetId,
                activeCell,
                selections,
                "horizontalAlignment",
                value
              );
            }}
          />

<TextVerticalAlignSelector
            value={currentCellFormat?.verticalAlignment}
            onChange={(value) => {
              onChangeFormatting(
                activeSheetId,
                activeCell,
                selections,
                "verticalAlignment",
                value
              );
            }}
          />

{/* Text Wrapping */}
          <TextWrapSelector
            value={currentCellFormat?.wrapStrategy}
            onChange={(value) => {
              onChangeFormatting(
                activeSheetId,
                activeCell,
                selections,
                "wrapStrategy",
                value
              );
            }}
          />
        </Toolbar>

<div className="flex-1">
          <CanvasGrid
            sheetId={activeSheetId}
            activeCell={activeCell}
            selections={selections}
            getCellData={getCellData}
            onChangeActiveCell={onChangeActiveCell}
            onChangeSelections={onChangeSelections}
          />
        </div>
      </div>
    </SpreadsheetProvider>
  );
}

export default SpreadsheetWithTextFormatting;
```

## Keyboard Shortcuts

Common keyboard shortcuts for text formatting:

* **Ctrl/Cmd + B**: Toggle bold
* **Ctrl/Cmd + I**: Toggle italic
* **Ctrl/Cmd + U**: Toggle underline
* **Ctrl/Cmd + L**: Align left
* **Ctrl/Cmd + E**: Align center
* **Ctrl/Cmd + R**: Align right

## Styling

Customize selector appearance with CSS:

```tsx
<FontFamilySelector
  className="min-w-32 border rounded"
  value={fontFamily}
  onChange={onChange}
/>

<FontSizeSelector
  className="w-16"
  value={fontSize}
  onChange={onChange}
/>
```

## Best Practices

1. **Show Current Format**: Always display the current cell's formatting state
2. **Multi-Selection Support**: Apply formatting to all selected cells
3. **Use getEffectiveFormat**: Get the computed format including defaults
4. **Provide Visual Feedback**: Highlight active formatting buttons
5. **Group Related Controls**: Use ToolbarSeparator to organize formatting options

## Use Cases

### Custom Font Lists

Provide custom font families:

```tsx
const customFonts = [
  "Roboto",
  "Open Sans",
  "Lato",
  "Montserrat",
  "Raleway",
];

<FontFamilySelector
  fonts={customFonts}
  value={fontFamily}
  onChange={onChange}
/>
```

### Font Size Presets

Common font size presets:

```tsx
const fontSizePresets = [8, 9, 10, 11, 12, 14, 16, 18, 20, 24, 28, 32, 36];

<FontSizeSelector
  presets={fontSizePresets}
  value={fontSize}
  onChange={onChange}
/>
```

### Conditional Formatting

Apply different alignments based on data type:

```tsx
const handleAlignmentChange = (value) => {
  const cellData = getCellData(activeSheetId, activeCell.rowIndex, activeCell.columnIndex);

// Auto-align numbers to the right
  if (typeof cellData?.ev?.nv === "number") {
    value = "right";
  }

onChangeFormatting(activeSheetId, activeCell, selections, "horizontalAlignment", value);
};
```

## Troubleshooting

### Selectors Not Showing Current Value

* Ensure getEffectiveFormat returns the correct cell format
* Check that activeCell and selections are properly synced
* Verify formatting data is stored correctly in sheetData

### Font Changes Not Applying

* Confirm onChangeFormatting is called with correct parameters
* Check that the font family name matches exactly
* Ensure the font is loaded (use loadWebFont for custom fonts)

### Performance Issues

* Memoize currentCellFormat calculation
* Debounce onChange handlers for font size input
* Use React.memo for selector components

## See Also

* [Toolbar](/configuration/components/toolbar) - Main toolbar component
* [Text Color Selector](/configuration/components/toolbar#textcolorselector) - Text color picker
* [Background Color Selector](/configuration/components/toolbar#backgroundcolorselector) - Background color picker
* [Border Selector](/configuration/components/toolbar#borderselector) - Cell border formatting

# Sheet Tabs

Quickly switch between multiple sheets

Optional SheetTab component to select sheets, and change sheet attributes. You can choose to use your preferred Tab component

<figure><img src="/files/1Pzul4gWqSqRkBSVSgKZ" alt=""><figcaption><p>Sheet tabs</p></figcaption></figure>

```tsx
import { SheetTabs } from "@rowsncolumns/spreadsheet"

const App = () => {
  return (
    <SheetTabs
      sheets={sheets}
      activeSheetId={activeSheetId}
      onChangeActiveSheet={onChangeActiveSheet}
      onRenameSheet={onRenameSheet}
      onChangeSheetTabColor={onChangeSheetTabColor}
      onDeleteSheet={onRequestDeleteSheet}
      onHideSheet={onHideSheet}
      onMoveSheet={onMoveSheet}
      onProtectSheet={onProtectSheet}
      onUnProtectSheet={onUnProtectSheet}
      onDuplicateSheet={onDuplicateSheet}
    />
  )
}
```

## Custom context menu

Each sheet tab can display a custom context menu. Use the `ContextMenu` props to inject a react component

You can use the default menu as a template to build your own Context menu

<https://github.com/rowsncolumns/spreadsheet/blob/main/apps/spreadsheet/components/sheet-tabs/context-menu.tsx>

Contextmenu uses shadcn/radix-ui dropdown components internally.

```tsx
import type { SheetTabContextMenuProps } from "@rowsncolumns/spreadsheet"
import {
  DropdownMenuContent,
  DropdownMenuItem,
  DropdownMenuPortal,
  DropdownMenuSeparator,
  DropdownMenuSub,
  DropdownMenuSubContent,
  DropdownMenuSubTrigger,
  DropdownRightSlot,
} from "@rowsncolumns/ui";

const CustomContextMenu = ({ onDeleteSheet, canDelete, sheetId }: SheetTabContextMenuProps) => {
  return (
    <DropdownMenuPortal>
      <DropdownMenuContent align="start">
        <DropdownMenuItem
          onClick={() => onDeleteSheet?.(sheetId)}
          disabled={!canDelete}
        >
          Delete
        </DropdownMenuItem>
      </DropdownMenuContent>
    </DropdownMenuPortal>
  )
}
<SheetTabs ContextMenu={CustomContextMenu}>
```

# Sheet Switcher

Dropdown menu with a list of sheets, both hidden and visible

<figure><img src="/files/DZ6rD4lL2bgCsYQ5FoAg" alt=""><figcaption><p>Sheet Switcher</p></figcaption></figure>

```tsx
import { SheetSwitcher } from "@rowsncolumns/spreadsheet"

const App = () => {
  return (
    <SheetSwitcher
      sheets={sheets}
      activeSheetId={activeSheetId}
      onChangeActiveSheet={onChangeActiveSheet}
      onShowSheet={onShowSheet}
    />
  )
}
```

# Sheet Status

Show average, count and sum of numerical values

SheetStatus uses the calculator to find Average, Count and Sum value of selected numerical fields

<figure><img src="/files/soXLJzwjJpLNZQiZ9CzF" alt=""><figcaption><p>SheetStatus component</p></figcaption></figure>

```tsx
import { SheetStatus } from "@rowsncolumns/spreadsheet"

const App = () => {
  return (
    <SheetStatus
      sheetId={activeSheetId}
      activeCell={activeCell}
      selections={selections}
      onRequestCalculate={onRequestCalculate}
      rowCount={rowCount}
      columnCount={columnCount}
    />
  )
}
```

# Range Selector

Displays and let users quickly select a named range

RangeSelector displays the currently selected cell address and creates a dropdown menu to select named ranges and sheets.

<figure><img src="/files/9K6AGPBDtkOTE0yOEO51" alt=""><figcaption><p>Range Selector</p></figcaption></figure>

```tsx
import { RangeSelector } from "@rowsncolumns/spreadsheet"

const App = () => {
  return (
    <RangeSelector
      selections={selections}
      activeCell={activeCell}
      onChangeActiveCell={onChangeActiveCell}
      onChangeSelections={onChangeSelections}
      sheets={sheets}
      rowCount={rowCount}
      columnCount={columnCount}
      onChangeActiveSheet={onChangeActiveSheet}
      namedRanges={namedRanges}
    />
  )
}
```

# Formula Input

Use a formula input component outside the spreadsheet

Formula input component allows users to enter formulas, make cell selections from Spreadsheet.

<figure><img src="/files/ej8POatfrgXsqeadbGlz" alt=""><figcaption><p>Formula Input component</p></figcaption></figure>

It can be placed anywhere inside the SpreadsheetProvider and use it part of your custom interface.

```tsx
import { FormulaInput } from "@rowsncolumns/spreadsheet"

const App = () => {
  const [ value, onChange ] = useState("")
  return (
    <FormulaInput
      value={value}
      onChange={onChange}
    />
  )
}
```

# Selection Input

Get selections from Spreadsheet and display it in an input field

<figure><img src="/files/JV7EVO5CLz4mt9jvniTU" alt=""><figcaption><p>Display selections and let users make selection input</p></figcaption></figure>

```tsx
import { SelectionInput } from "@rowsncolumns/spreadsheet"

const App = () => {
  const [ value, onChange ] = useState("")
  return (
    <SelectionInput
      onChange={onChange}
      value={value}
      selections={selections}
      activeCell={activeCell}
    />
  )
}
```

# SheetSearch

Search within a sheet with this component

<figure><img src="/files/DIStnUGlacVU4PMSpbjc" alt=""><figcaption><p>Ctrl +F to display Sheet Search component</p></figcaption></figure>

{% code overflow="wrap" %}

```tsx
import { CanvasGrid, SheetSearch } from "@rowsncolumns/spreadsheet"
import { useSpreadsheetState, useSearch } from "@rowsncolumns/spreadsheet-state"

const App = () => {
  const activeSheetId = 1
  const { getCellData, getNonEmptyColumnCount, getNonEmptyRowCount } = useSpreadsheetState({
    ...
  })
  const {
      onSearch,
      onResetSearch,
      onFocusNextResult,
      onFocusPreviousResult,
      hasNextResult,
      hasPreviousResult,
      borderStyles,
      isSearchActive,
      onRequestSearch,
      totalResults,
      currentResult,
      searchQuery,
    } = useSearch({
      getCellData,
      sheetId: activeSheetId,
      getNonEmptyColumnCount,
      getNonEmptyRowCount,
    });
  return (
    <>
      <CanvasGrid
        borderStyles={borderStyles}
      />
      <SheetSearch
        isActive={isSearchActive}
        onSubmit={onSearch}
        onReset={onResetSearch}
        onNext={onFocusNextResult}
        onPrevious={onFocusPreviousResult}
        disableNext={!hasNextResult}
        disablePrevious={!hasPreviousResult}
        currentResult={currentResult}
        totalResults={totalResults}
        searchQuery={searchQuery}
      />
    </>
  )
}
```

{% endcode %}

# NamedRangeEditor

Create and edit named ranges

<figure><img src="/files/S3e0XSKoS4KDEDZXILXr" alt=""><figcaption><p>Create or edit named ranges</p></figcaption></figure>

<pre class="language-tsx" data-overflow="wrap"><code class="lang-tsx">import { CanvasGrid, NamedRangeEditor } from "@rowsncolumns/spreadsheet"
import { useSpreadsheetState } from "@rowsncolumns/spreadsheet-state"

const App = () => {
  const activeSheetId = 1
<strong>  const { getSheetName, onCreateNamedRange, onUpdateNamedRange } = useSpreadsheetState({
</strong>    ...
  })
  return (
    <>
      <CanvasGrid
      />
      <NamedRangeEditor
        sheetId={activeSheetId}
        rowCount={rowCount}
        columnCount={columnCount}
        getSheetName={getSheetName}
        onCreateNamedRange={onCreateNamedRange}
        onUpdateNamedRange={onUpdateNamedRange}
      />
    </>
  )
}
</code></pre>

# DeleteSheetConfirmation

A confirmation dialog that can be displayed before deleting a sheet

<figure><img src="/files/D71PVGOzQEaJp8IrbJaT" alt=""><figcaption><p>Delete sheet confirmation</p></figcaption></figure>

<pre class="language-tsx" data-overflow="wrap"><code class="lang-tsx">import { CanvasGrid, DeleteSheetConfirmation } from "@rowsncolumns/spreadsheet"
import { useSpreadsheetState } from "@rowsncolumns/spreadsheet-state"

const App = () => {
  const activeSheetId = 1
<strong>  const { onDeleteSheet, onRequestDeleteSheet } = useSpreadsheetState({
</strong>    ...
  })
  return (
    <>
      <button onClick={onRequestDeleteSheet}>Delete current sheet</button>
      <CanvasGrid />
      <DeleteSheetConfirmation
        sheetId={activeSheetId}
        onDeleteSheet={onDeleteSheet}
      />
    </>
  )
}
</code></pre>

# TableEditor

A table editor dialog to edit name, range and other options of a table

<figure><img src="/files/f6jBdIwkioi8QpseqndR" alt=""><figcaption><p>Brings up a table editor</p></figcaption></figure>

const App = () => {
  const activeSheetId = 1
<strong>  const { onUpdateTable, onRequestEditTable, getSheetName } = useSpreadsheetState({
</strong>    ...
  })
  return (
    <>
      <button onClick={() => {
        onRequestEditTable(table)
      }>Edit table</button>
      <CanvasGrid />
      <TableEditor
        sheetId={activeSheetId}
        rowCount={rowCount}
        columnCount={columnCount}
        getSheetName={getSheetName}
        onSubmit={onUpdateTable}
      />
    </>
  )
}
</code></pre>

# Cell Format Editor

Component to edit cell format. It can be shown in a modal dialog or embedded in your own component.

<figure><img src="/files/WaYgvq8tpXUID1J82VSC" alt=""><figcaption><p>Cmd + Option + 1 will bring up the cell format editor</p></figcaption></figure>

<pre class="language-tsx" data-overflow="wrap"><code class="lang-tsx">import { CanvasGrid, defaultSpreadsheetTheme } from "@rowsncolumns/spreadsheet"
import { useSpreadsheetState, CellFormatEditor, CellFormatEditorDialog } from "@rowsncolumns/spreadsheet-state"

const App = () => {
  const activeSheetId = 1
  const [theme, onChangeTheme] = useState<SpreadsheetTheme>(
    defaultSpreadsheetTheme
  );
<strong>  const {
</strong><strong>    activeCell,
</strong><strong>    selections,
</strong><strong>    theme,
</strong><strong>    onMergeCells,
</strong><strong>    onChangeFormatting,
</strong><strong>    onChangeBorder,
</strong><strong>    onRequestFormatCells,
</strong><strong>    getUserEnteredFormat,
</strong><strong>    getEffectiveValue
</strong><strong>  } = useSpreadsheetState({
</strong>    ...
  })
  
  const currentCellFormat = useMemo(
    () =>
      getUserEnteredFormat(
        activeSheetId,
        activeCell.rowIndex,
        activeCell.columnIndex
      ),
    [activeSheetId, activeCell, getUserEnteredFormat]
  );
  return (
    <>
      <CanvasGrid
        // Binds to keyboard shortcut and context menu
        onRequestFormatCells={onRequestFormatCells}
      />
      <CellFormatEditorDialog>
        <CellFormatEditor
          sheetId={activeSheetId}
          activeCell={activeCell}
          selections={selections}
          onChangeFormatting={onChangeFormatting}
          cellFormat={currentCellFormat}
          getEffectiveValue={getEffectiveValue}
          onMergeCells={onMergeCells}
          theme={theme}
          onChangeBorder={onChangeBorder}
        />
      </CellFormatEditorDialog>

</>
  )
}
</code></pre>

# Conditional Format Editor

Adds a Conditonal format editor component

<figure><img src="/files/R9FzzPpJp3fwWmc8AogL" alt=""><figcaption><p>Conditional Format Editor</p></figcaption></figure>

{% code overflow="wrap" %}

```tsx
import { CanvasGrid, SpreadsheetProvider, defaultSpreadsheetTheme } from "@rowsncolumns/spreadsheet"
import { useSpreadsheet, ConditionalFormatDialog, ConditionalFormatEditor } from "@rowsncolumns/spreadsheet-state"

const Spreadsheet = () => {
  const [conditionalFormats, onChangeConditionalFormats] = useState<
      ConditionalFormatRule[]>([]);
  const [theme, onChangeTheme] = useState<SpreadsheetTheme>(
    defaultSpreadsheetTheme
  );
  const {
    activeSheetId,
    rowCount,
    columnCount,
    getSheetName,
    getSheetId,
    onCreateConditionalFormattingRule,
    onDeleteConditionalFormattingRule,
    onUpdateConditionalFormattingRule,
    onPreviewConditionalFormattingRule
  } = useSpreadsheetState({
    conditionalFormats
  })
  
  return (
    <>
      <ConditionalFormatDialog>
        <ConditionalFormatEditor
          sheetId={activeSheetId}
          rowCount={rowCount}
          columnCount={columnCount}
          theme={theme}
          conditionalFormats={conditionalFormats}
          onCreateRule={onCreateConditionalFormattingRule}
          onDeleteRule={onDeleteConditionalFormattingRule}
          onUpdateRule={onUpdateConditionalFormattingRule}
          onPreviewRule={onPreviewConditionalFormattingRule}
        />
      </ConditionalFormatDialog>
    </>
  )
}

const App = () => (
  <SpreadsheetProvider>
    <Spreadsheet />
  </SpreadsheetProvider>
)
```

{% endcode %}

# Data Validation Editor

Allow users to edit data validation rules

<figure><img src="/files/LWMb0tFNfqIK5IvqP5GB" alt=""><figcaption><p>Data validations editor screenshot</p></figcaption></figure>

{% code overflow="wrap" %}

const Spreadsheet = () => {
  const [ dataValidations, onChangeDataValidations] = useState<
      DataValidationRuleRecord[]>([]);
      
  const {
    activeSheetId,
    rowCount,
    columnCount,
    onRequestDataValidation,
    onCreateDataValidationRule,
    onUpdateDataValidationRule,
    onDeleteDataValidationRule,
    onDeleteDataValidationRules
  } = useSpreadsheetState({
    dataValidations,
    onChangeDataValidations
  })
  
  return (
    <>
      <CanvasGrid
        // User is requesting to open editor
        onRequestDataValidation={onRequestDataValidation}
      />
      <DataValidationEditorDialog>
        <DataValidationEditor
          dataValidations={dataValidations}
          sheetId={activeSheetId}
          rowCount={rowCount}
          columnCount={columnCount}
          onDeleteRules={onDeleteDataValidationRules}
          onDeleteRule={onDeleteDataValidationRule}
          onCreateRule={onCreateDataValidationRule}
          onUpdateRule={onUpdateDataValidationRule}
        />
      </DataValidationEditorDialog>
    </>
  )
}

const App = () => (
  <SpreadsheetProvider>
    <Spreadsheet />
  </SpreadsheetProvider>
)
```

{% endcode %}

# Insert Link Editor

Add and remove hyperlinks in cells

<figure><img src="/files/y0qJnzxGEekNkLMLqDti" alt=""><figcaption><p>Insert Link editor</p></figcaption></figure>

## Inserting Links

{% code overflow="wrap" %}

```tsx
import { CanvasGrid, SpreadsheetProvider } from "@rowsncolumns/spreadsheet"
import { useSpreadsheet, InsertLinkDialog, InsertLinkEditor } from "@rowsncolumns/spreadsheet-state"

const Spreadsheet = () => {
  const {
    activeSheetId,
    activeCell,
    selections,
    onInsertLink,
    onRequestInsertLink
  } = useSpreadsheetState({})

return (
    <>
      <button onClick={() => onRequestInsertLink()}>Insert link</button>
      <InsertLinkDialog>
        <InsertLinkEditor
          sheetId={activeSheetId}
          activeCell={activeCell}
          selections={selections}
          onInsertLink={onInsertLink}
        />
      </InsertLinkDialog>
    </>
  )
}

const App = () => (
  <SpreadsheetProvider>
    <Spreadsheet />
  </SpreadsheetProvider>
)
```

{% endcode %}

## Removing Links

Use the `onRemoveLink` callback to remove hyperlinks from cells:

```tsx
import { CanvasGrid, SpreadsheetProvider } from "@rowsncolumns/spreadsheet"
import { useSpreadsheetState } from "@rowsncolumns/spreadsheet-state"

const Spreadsheet = () => {
  const {
    activeSheetId,
    activeCell,
    selections,
    onInsertLink,
    onRemoveLink,
    onRequestInsertLink
  } = useSpreadsheetState({})

const handleRemoveLink = () => {
    onRemoveLink?.(activeSheetId, activeCell, selections);
  };

return (
    <>
      <button onClick={() => onRequestInsertLink()}>Insert Link</button>
      <button onClick={handleRemoveLink}>Remove Link</button>

<CanvasGrid
        sheetId={activeSheetId}
        activeCell={activeCell}
        selections={selections}
        onRemoveLink={onRemoveLink}
        // ... other props
      />
    </>
  )
}
```

## Complete Example with Context Menu

```tsx
import React, { useState } from "react";
import {
  SpreadsheetProvider,
  CanvasGrid,
  Sheet,
} from "@rowsncolumns/spreadsheet";
import {
  useSpreadsheetState,
  SheetData,
  CellData,
  InsertLinkDialog,
  InsertLinkEditor,
} from "@rowsncolumns/spreadsheet-state";

function SpreadsheetWithLinks() {
  const [sheets, setSheets] = useState<Sheet[]>([
    { sheetId: 1, rowCount: 100, columnCount: 26, title: "Sheet 1" }
  ]);
  const [sheetData, setSheetData] = useState<SheetData<CellData>>({});

const {
    activeCell,
    activeSheetId,
    selections,
    getCellData,
    onChangeActiveCell,
    onChangeSelections,
    onInsertLink,
    onRemoveLink,
    onRequestInsertLink,
  } = useSpreadsheetState({
    sheets,
    sheetData,
    onChangeSheets: setSheets,
    onChangeSheetData: setSheetData,
  });

// Check if active cell has a link
  const cellData = getCellData(
    activeSheetId,
    activeCell.rowIndex,
    activeCell.columnIndex
  );
  const hasLink = !!cellData?.hyperlink;

return (
    <SpreadsheetProvider>
      <div className="flex flex-col h-screen">
        <div className="p-2 border-b">
          <button
            onClick={() => onRequestInsertLink()}
            className="px-3 py-1 bg-blue-500 text-white rounded mr-2"
          >
            Insert Link
          </button>
          <button
            onClick={() => onRemoveLink?.(activeSheetId, activeCell, selections)}
            disabled={!hasLink}
            className="px-3 py-1 bg-red-500 text-white rounded disabled:opacity-50"
          >
            Remove Link
          </button>
        </div>

<InsertLinkDialog>
          <InsertLinkEditor
            sheetId={activeSheetId}
            activeCell={activeCell}
            selections={selections}
            onInsertLink={onInsertLink}
          />
        </InsertLinkDialog>
      </div>
    </SpreadsheetProvider>
  );
}

export default SpreadsheetWithLinks;
```

## Function Signatures

### onInsertLink

```typescript
type OnInsertLink = (
  sheetId: number,
  activeCell: CellInterface,
  selections: SelectionArea<SelectionAttributes>[],
  url: string,
  text?: string
) => void;
```

### onRemoveLink

```typescript
type OnRemoveLink = (
  sheetId: number,
  activeCell: CellInterface,
  selections: SelectionArea<SelectionAttributes>[]
) => void;
```

## Use Cases

### Adding Links to External Resources

```tsx
// Link to documentation
onInsertLink(sheetId, activeCell, selections, "https://docs.example.com", "Docs");

// Link to related file
onInsertLink(sheetId, activeCell, selections, "/files/report.pdf", "View Report");
```

### Batch Link Removal

Remove links from multiple cells:

```tsx
const removeBatchLinks = () => {
  // Remove links from all selected cells
  selections.forEach((selection) => {
    onRemoveLink?.(activeSheetId, activeCell, [selection]);
  });
};
```

## Best Practices

1. **Validate URLs**: Ensure URLs are properly formatted before insertion
2. **Provide Feedback**: Show visual indicators for cells with links
3. **Handle Errors**: Gracefully handle invalid or broken links
4. **Keyboard Shortcuts**: Support Ctrl/Cmd+K for inserting links
5. **Context Menu**: Add link operations to the cell context menu

# Insert Image Editor

Adds a image editor

<figure><img src="/files/TMGCin8Mn8E7yF9lHTFl" alt=""><figcaption><p>Insert Image editor</p></figcaption></figure>

{% code overflow="wrap" %}

```tsx
import { CanvasGrid, SpreadsheetProvider } from "@rowsncolumns/spreadsheet"
import { useSpreadsheet, InsertImageDialog, InsertImageEditor } from "@rowsncolumns/spreadsheet-state"

const Spreadsheet = () => {
  const {
    activeSheetId,
    activeCell,
    selections,
    onInsertImage,
    onRequestInsertImage
  } = useSpreadsheetState({})
  
  return (
    <>
      <button onClick={() => onRequestInsertImage()}>Insert image</button>
      <InsertImageDialog>
        <InsertImageEditor
          sheetId={activeSheetId}
          activeCell={activeCell}
          selections={selections}
          onInsertImage={onInsertImage}
        />
      </InsertImageDialog>
    </>
  )
}

const App = () => (
  <SpreadsheetProvider>
    <Spreadsheet />
  </SpreadsheetProvider>
)
```

{% endcode %}

# Floating Cell Editor

Floating Cell Editor component can be used to create Mobile editors that resides out of the Spreadsheet container.

<figure><img src="/files/o2cLT13UhElrAoeioK66" alt=""><figcaption><p>Mobile or Floating Cell Editor</p></figcaption></figure>

To insert a mobile or floating cell editor

{% code overflow="wrap" %}

```tsx
import { FloatingCellEditor, defaultSpreadsheetTheme } from "@rowsncolumns/spreadsheet"
import { functionDescriptions } from "@rowsncolumns/functions";

const App = () => {
  const [theme, onChangeTheme] = useState<SpreadsheetTheme>(
      defaultSpreadsheetTheme
    );
  const {
    activeSheetId,
    activeCell,
    selections,
    getUserEnteredValue,
    getEffectiveFormat,
    onChange,
    onChangeFormatting,
    onInsertRow,
    onInsertColumn 
  } = useSpreadsheetState({ ... })

// Format of the current cell
  const currentCellFormat = useMemo(
    () =>
      getEffectiveFormat(
        activeSheetId,
        activeCell.rowIndex,
        activeCell.columnIndex
      ),
    [activeSheetId, activeCell, getEffectiveFormat]
  );

return (
    <FloatingCellEditor
      initialValue={getUserEnteredValue(
        activeSheetId,
        activeCell.rowIndex,
        activeCell.columnIndex
      )}
      theme={theme}
      sheetId={activeSheetId}
      activeCell={activeCell}
      selections={selections}
      onChange={onChange}
      cellFormat={currentCellFormat}
      onChangeFormatting={onChangeFormatting}
      onInsertRow={onInsertRow}
      onInsertColumn={onInsertColumn}
      functionDescriptions={functionDescriptions}
    />
  )
}
```

{% endcode %}

# Grid Footer

Footer component for adding rows dynamically at the bottom of the spreadsheet

The `GridFooter` component provides a customizable footer area at the bottom of the spreadsheet grid, allowing users to add additional rows dynamically.

## Overview

GridFooter displays at the bottom of the spreadsheet canvas and typically includes controls for adding new rows to the end of the sheet. It's useful for applications where users frequently add data at the bottom of their spreadsheet.

## Basic Usage

```tsx
import { SpreadsheetProvider, CanvasGrid, GridFooter } from "@rowsncolumns/spreadsheet";
import { useSpreadsheetState } from "@rowsncolumns/spreadsheet-state";

function MySpreadsheet() {
  const {
    activeSheetId,
    onRequestAddRows,
    // ... other hook values
  } = useSpreadsheetState({
    // ... configuration
  });

return (
    <SpreadsheetProvider>
      <CanvasGrid
        sheetId={activeSheetId}
        footerHeight={80}
        footerComponent={
          <GridFooter
            sheetId={activeSheetId}
            onRequestAddRows={onRequestAddRows}
          />
        }
        // ... other props
      />
    </SpreadsheetProvider>
  );
}
```

## Props

### GridFooter Props

| Prop               | Type                                                | Description                             |
| ------------------ | --------------------------------------------------- | --------------------------------------- |
| `sheetId`          | `number`                                            | The ID of the active sheet              |
| `onRequestAddRows` | `(sheetId: number, additionalRows: number) => void` | Callback when user requests to add rows |

### CanvasGrid Props (for footer)

| Prop              | Type              | Description                         |
| ----------------- | ----------------- | ----------------------------------- |
| `footerHeight`    | `number`          | Height of the footer area in pixels |
| `footerComponent` | `React.ReactNode` | The footer component to render      |

## Features

### Add Rows Functionality

The GridFooter includes:

* An input field for specifying the number of rows to add
* An "Add" button to execute the action
* Automatic scrolling to the bottom after adding rows

```tsx
const { onRequestAddRows } = useSpreadsheetState({
  sheets,
  sheetData,
  onChangeSheets: setSheets,
  onChangeSheetData: setSheetData,
});

// GridFooter will call this when user clicks "Add"
// It automatically scrolls to the bottom after adding rows
<GridFooter
  sheetId={activeSheetId}
  onRequestAddRows={(sheetId, numRows) => {
    console.log(`Adding ${numRows} rows to sheet ${sheetId}`);
    onRequestAddRows?.(sheetId, numRows);
  }}
/>
```

### Implementing onRequestAddRows

The `onRequestAddRows` callback is typically provided by `useSpreadsheetState`, but you can also implement custom logic:

```tsx
import { useState } from "react";
import type { Sheet } from "@rowsncolumns/spreadsheet";

const [sheets, setSheets] = useState<Sheet[]>([
  { sheetId: 1, rowCount: 100, columnCount: 26, title: "Sheet 1" }
]);

<GridFooter
  sheetId={activeSheetId}
  onRequestAddRows={handleAddRows}
/>
```

## Custom Footer Component

You can create your own custom footer component instead of using the default GridFooter:

```tsx
const CustomFooter = ({ sheetId }: { sheetId: number }) => {
  return (
    <div className="flex items-center justify-between p-4 bg-gray-100">
      <span>Sheet {sheetId}</span>
      <button onClick={() => console.log("Custom action")}>
        Custom Action
      </button>
    </div>
  );
};

<CanvasGrid
  footerHeight={60}
  footerComponent={<CustomFooter sheetId={activeSheetId} />}
/>
```

## Styling

The GridFooter component uses Tailwind CSS classes and can be customized through className props:

```tsx
// The default GridFooter styling includes:
// - Responsive padding
// - Border styling
// - Background color from theme
// - Proper alignment with row headers
```

## Layout Considerations

### Footer Height

The `footerHeight` prop determines the height of the footer area:

```tsx
<CanvasGrid
  footerHeight={80}  // 80 pixels for footer
  footerComponent={<GridFooter {...props} />}
/>
```

### Row Header Alignment

GridFooter automatically aligns with the row header column, ensuring consistent layout:

```tsx
// Internal padding matches ROW_HEADER_WIDTH constant
// Scrollbar space is automatically accounted for
```

## Complete Example

```tsx
import React, { useState } from "react";
import {
  SpreadsheetProvider,
  CanvasGrid,
  GridFooter,
  type Sheet,
} from "@rowsncolumns/spreadsheet";
import {
  useSpreadsheetState,
  type SheetData,
} from "@rowsncolumns/spreadsheet-state";

function SpreadsheetWithFooter() {
  const [sheets, setSheets] = useState<Sheet[]>([
    { sheetId: 1, rowCount: 100, columnCount: 26, title: "Sheet 1" }
  ]);
  const [sheetData, setSheetData] = useState<SheetData>({});

const {
    activeCell,
    activeSheetId,
    selections,
    getCellData,
    onChangeActiveCell,
    onChangeSelections,
    onRequestAddRows,
    // ... other state values
  } = useSpreadsheetState({
    sheets,
    sheetData,
    onChangeSheets: setSheets,
    onChangeSheetData: setSheetData,
  });

return (
    <SpreadsheetProvider>
      <CanvasGrid
        sheetId={activeSheetId}
        activeCell={activeCell}
        selections={selections}
        getCellData={getCellData}
        onChangeActiveCell={onChangeActiveCell}
        onChangeSelections={onChangeSelections}
        footerHeight={80}
        footerComponent={
          <GridFooter
            sheetId={activeSheetId}
            onRequestAddRows={onRequestAddRows}
          />
        }
      />
    </SpreadsheetProvider>
  );
}
```

## Best Practices

1. **Set appropriate footer height**: The default 80px works well for most cases, but adjust based on your content
2. **Validate row additions**: Consider limits on total row count to prevent performance issues
3. **Provide feedback**: Show loading states or success messages when adding rows
4. **Handle errors gracefully**: Validate the number input and handle edge cases

## Use Cases

* **Data entry applications**: Allow users to easily add more rows as they input data
* **Dynamic spreadsheets**: Support growing datasets without manual sheet configuration
* **Form-like interfaces**: Provide a way to add new records at the bottom of a list
* **Log viewers**: Allow users to append new log entries

## Performance

GridFooter is lightweight and doesn't impact spreadsheet performance. The component only re-renders when its props change, and adding rows is handled efficiently by the spreadsheet state management.

# API

Spreadsheet API in a nutshell

# Cell Data

Defines the data model for a cell

`CellData` is the per-cell record stored in the array/record that builds sheet data. It bundles everything we need to round-trip a cell: the user-entered value, the calculated value, formatting, hyperlinks, validation, comments, protection flags, pivot/expand state, plus a handful of fields the calc engine uses internally.

Most fields exist in both a **long form** (`userEnteredValue`, `effectiveValue`, `userEnteredFormat`, `formattedValue`) and a **short form** (`ue`, `ev`, `uf`, `fv`). The short form is preferred for new writes — it keeps serialized payloads compact and is what the toolkit emits on save. The long forms still load for backwards compatibility.

The same naming convention applies one level down inside `ExtendedValue` — use `nv` / `sv` / `bv` / `fv` / `ev` instead of `numberValue` / `stringValue` / `boolValue` / `formulaValue` / `errorValue`.

```typescript
export type CellData<
  T extends StructuredResult = StructuredResult,
  M extends Mention = Mention,
> = {
  /**
   * The value the user entered in the cell. e.g, 1234, "Hello", or
   * "=NOW()". Dates, times, and datetimes are represented as doubles
   * in serial format.
   */
  ue?: ExtendedValue;
  /**
   * The effective value of the cell. For formula cells this is the
   * calculated result; for literal cells it equals `ue`. Read-only —
   * the calculation engine writes this. Set only when hydrating from
   * a saved snapshot.
   */
  ev?: ExtendedValue & StructuredValue<T>;
  /**
   * The formatted display string (after the number format is
   * applied). Read-only.
   */
  fv?: string;
  /**
   * The user-entered format. New writes are merged onto any existing
   * format. Can be a full `CellFormat` or a `StyleReference` (a short
   * `{ sid }` ref into the workbook's cellXfs registry) — the registry
   * dedupes repeated formats.
   */
  uf?: CellFormat | StyleReference;
  /**
   * Shared-strings key for cells whose value is interned in the
   * workbook's shared-strings table. Always a string. Per-segment
   * rich-text formatting (bold / italic / color / `@mention` chips)
   * rides on the SharedStrings entry as `{ text, runs }`; see the
   * [Rich text formatting](../features/rich-text-formatting.md)
   * feature page.
   */
  ss?: string;
  /**
   * Hyperlink target. Either a plain URL string or a structured value
   * carrying the URL + display label + tooltip.
   */
  hyperlink?: string | HyperlinkValue;
  /**
   * Data-validation rule attached to the cell. Inline rule object or
   * an ID reference into the sheet-level validation registry.
   */
  dataValidation?: DataValidationRule | DataValidationRuleRecord["id"];
  /**
   * Plain-text note (Excel "comment" — single-author, not threaded).
   */
  note?: string;
  /**
   * Pointer into the threaded-comment store (Excel 2016+ replies and
   * resolved state).
   */
  commentThreadId?: string | number;
  /**
   * Citation reference (FILTER source attribution, etc.).
   */
  citationId?: Citation["id"];
  /**
   * Cell-level protection flags. Only take effect when sheet protection
   * is enabled. `locked` defaults to true in Excel, so this field is
   * usually set to `{ locked: false }` to opt a cell OUT of protection.
   */
  protection?: {
    locked?: boolean;
    hidden?: boolean;
  };
  /**
   * Image URL — for cells whose value is an embedded image.
   */
  imageUrl?: string;
  /**
   * Cell metadata marker — currently only "people" for mention chips.
   */
  metaType?: "people";
  /**
   * Array-formula spill range in A1 notation ("B5:B20"). Only set on
   * the anchor cell of an array formula; spilled cells in the range
   * carry no `af`. Round-trips to / from <f t="array" ref="..."/> in
   * xlsx.
   */
  af?: string;
  /**
   * Conditional-formatting results keyed by rule ID. Written by the
   * CF evaluator; consumers shouldn't set this directly.
   */
  conditionalFormattingResultById?: Record<string, CustomFormulaResult>;
  /**
   * Result of a formula-based data-validation rule.
   */
  dataValidationResult?: CustomFormulaResult;
  /**
   * Outline / pivot grouping markers used by the canvas to render
   * expand-collapse chevrons.
   */
  expandable?: boolean;
  expanded?: boolean;
  /**
   * Pivot grouping key tuple for the cell.
   */
  groupKeys?: string[];
  childrenCount?: number;
  /**
   * Pivot table this cell belongs to.
   */
  pivotId?: PivotTable["pivotId"];
  /**
   * Collaboration / sync metadata.
   */
  version?: number;
  updatedAt?: number;

// -------------------------------------------------------------------
  // Long-form aliases — kept for backwards compatibility with older
  // saved payloads. Prefer the short forms (`ue` / `ev` / `uf` / `fv`)
  // for new writes.
  // -------------------------------------------------------------------
  /** @deprecated use `ue` */
  userEnteredValue?: ExtendedValue;
  /** @deprecated use `ev` */
  effectiveValue?: ExtendedValue & StructuredValue<T>;
  /** @deprecated use `fv` */
  formattedValue?: string;
  /** @deprecated use `uf` */
  userEnteredFormat?: CellFormat | StyleReference;
};
```

{% hint style="info" %}
CellData is the source of truth of a cell. Spreadsheet does not mutate cellData — cells are rendered based on the properties on the record.
{% endhint %}

## ev and ue

`ev` (effective value) is derived from the value the user entered. If the user enters `"1000"`, Spreadsheet detects the type and classifies it as `nv` (number).

If the user enters `=SUM(4,4)`, `ev` is set when the calculation engine returns the result — `nv: 8` in this case.

Internally `ev` is used for calculations and `ue` is used for cell editing.

## uf and the effective format

All user-modified format changes are stored on `uf` (user-entered format). The effective format used at render time is **not** persisted on `CellData` — the renderer derives it on the fly from `uf`, the cell's effective value, and (for formula cells) precedent formats via `useSheetProperties.getEffectiveFormat`.

The legacy `effectiveFormat` / `ef` fields are accepted when loading older saved data but **should not be written**. New writes set `uf` only.

## Using your own CellData object

CanvasGrid accepts a custom CellData type that extends the core type:

```typescript
import {
  SpreadsheetProvider,
  CanvasGrid,
  CellData,
} from "@rowsncolumns/spreadsheet";

export type MyCustomCellData = CellData & {
  highlight?: boolean;
};

const App = () => {
  return (
    <SpreadsheetProvider>
      <CanvasGrid<MyCustomCellData>
        rowCount={1000}
        columnCount={1000}
        sheetId={1}
      />
    </SpreadsheetProvider>
  );
};
```

# Sheets

Supports multiple sheets with cross-references and tables

Developers can define any `Sheet` type, as CanvasGrid is agnostic of sheets. The sheet model used by `useSpreadsheetState` hook is

<https://github.com/rowsncolumns/spreadsheet/blob/main/apps/spreadsheet/types.ts#L6>

```typescript
export type Sheet = {
  title: string;
  sheetId: number;
  tabColor?: string;
  hidden?: boolean;
  rowCount?: number;
  columnCount?: number;
  frozenRowCount?: number;
  frozenColumnCount?: number;
  hideGridlines?: boolean;
  merges?: GridRange[];
  basicFilter?: FilterView;
  rowMetadata?: (DimensionProperties | null)[];
  columnMetadata?: (DimensionProperties | null)[];
};
```

## Sheet components

The following Sheet components are packaged with Spreadsheet

* NewSheetButton
* SheetSwitcher
* SheetTabs
* SheetStatus
* TableEditor
* DeleteSheetConfirmation

## Using your own Sheet type

You can extend from the core `Sheet` type and add your custom attributes

```typescript
import { SpreadsheetProvider, CanvasGrid, Sheet } from "@rowsncolumns/spreadsheet";
import { useSpreadsheetState } from "@rowsncolumns/spreadsheet-state"

type MyCustomSheet = Sheet & {
  owner: string;
  module: string
}

const Spreadsheet = () => {
  const [ sheets, onChangeSheets ] = useState<MyCustomSheet[]>([])
  const { } = useSpreadsheetState({
    sheets,
    onChangeSheets
  })
  return (
    <CanvasGrid
      rowCount={1000}
      columnCount={1000}
      sheetId={1}
    />
  );
};

export const App = () => (
  <SpreadsheetProvider>
    <Spreadsheet />
  <SpreadsheetProvider />
)
```

# SpreadsheetProvider

Context Provider that isolates Spreadsheet internal state

Each Spreadsheet instance should be wrapped in a SpreadsheetProvider component so that each instance will have its own set of props and internal state.

## useSpreadSheet hook

Children of SpreadsheetProvider will have access to `useSpreadsheet` hook that exposes several internal functions a developer can access.

```tsx
import {
  SpreadsheetProvider,
  CanvasGrid,
  useSpreadsheet,
} from "@rowsncolumns/spreadsheet";
import { tokenize as tokenizer } from "@rowsncolumns/calculator";

const MySpreadsheet = () => {

const {
    canEditCell,
    cancelEditor,
    focusSheet,
    getCellBounds,
    getCellDimensions,
    getNamedRanges,
    getNextFocusableCell,
    getRowHeight,
    getSelectionsFromFormula,
    getTableColumnNames,
    getTableNames,
    makeEditable,
    onEditorKeyDown,
    scrollToCell,
    setEditorValue,
    submitEditor,
    updateSelectionStartEndReference,
  } = useSpreadsheet();
  
  return (
    <CanvasGrid
      rowCount={1000}
      columnCount={1000}
      sheetId={1}
      tokenizer={tokenizer}
    />
  );
};

const App = () => (
  <SpreadsheetProvider>
    <MySpreadsheet />
  </SpreadsheetProvider>
);
```

## Multiple Spreadsheets

You can render multiple Spreadsheet UI's in a single page, each able to work independently or together. It is left to your imagination.

You can share `tables, charts, embeds` across multiple sheets or even sheets and sheetData.

Each Spreadsheet should be wrapped in `<SpreadsheetProvider />` to isolate internal state, such as `formulaMode`, cell editor states, cell selection states etc.

```tsx
import { SpreadsheetProvider, CanvasGrid } from "@rowsncolumns/spreadsheet"

const SpreadsheetA = () => {
  return (
    <SpreadsheetProvider>
      <CanvasGrid />
    </SpreadsheetProvider>
  )
}
const SpreadsheetB = () => {
  return (
    <SpreadsheetProvider>
      <CanvasGrid />
    </SpreadsheetProvider>
  )
}

const App = () => {
  return (
    <>
      <SpreadsheetA />
      <SpreadsheetB />
    </>
  )
}
```

# useSpreadsheet

useSpreadsheet exposes some of the internal API via hooks

{% hint style="info" %}
Wrap your app in `SpreadsheetProvider` to use `useSpreadsheet` hook
{% endhint %}

```tsx
import { SpreadsheetProvider, CanvasGrid, useSpreadsheet } from "@rowsncolumns/spreadsheet";

const MySpreadsheet = () => {
  const {
    makeEditable,
    canEditCell,
    cancelEditor,
    commit,
    focusSheet,
    getCellBounds,
    getCellDimensions,
    getContentfulGridRangeAroundCell,
    getNamedRanges,
    getNextFocusableCell,
    getRowHeight,
    getSelectionsFromFormula,
    getTableColumnNames,
    getTableNames,
    onEditorKeyDown,
    scrollToCell,
    setEditorValue,
    submitEditor,
    updateSelectionStartEndReference,
    tokenizer,
  } = useSpreadsheet();
  return (
    <CanvasGrid />
  );
};

const App = () => (
  <SpreadsheetProvider>
    <MySpreadsheet />
  </SpreadsheetProvider>
);
```

| API                                | Description                                                                                                                                             |
| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `makeEditable`                     | Manually trigger a cell to be in edit mode                                                                                                              |
| `canEditCell`                      | Verify if a cell is editable, respects protected ranges                                                                                                 |
| `cancelEditor`                     | Cancels edit mode                                                                                                                                       |
| `commit`                           | Commit the in-progress edit (submit if dirty, cancel if clean). Returns `true` if there was an edit to flush. Useful from a consumer-side blur handler. |
| `focusSheet`                       | Trigger focus on the Spreadsheet                                                                                                                        |
| `getCellBounds`                    | Get relative position of a cell relative to container                                                                                                   |
| `getCellDimensions`                | Get dimension (x, y, width, height) of a cell                                                                                                           |
| `getContentfulGridRangeAroundCell` | Get range around a specific cells that has content                                                                                                      |
| `getNamedRanges`                   | Get all named ranges of a sheet                                                                                                                         |
| `getNextFocusableCell`             | Get next available cell that can be focused. Skips hidden cells, rows and columns                                                                       |
| `getRowHeight`                     | Returns row height of a rowIndex                                                                                                                        |
| `getSelectionsFromFormula`         | Get all selections from text                                                                                                                            |
| `getTableColumnNames`              | Helper function to retrieve table column names                                                                                                          |
| `getTableNames`                    | Helper function to retrieve table names                                                                                                                 |
| `onEditorKeyDown`                  | Callback when user enters value in editor                                                                                                               |
| `scrollToCell`                     | Scroll to a cell                                                                                                                                        |
| `setEditorValue`                   | Imperatively set value in the editor                                                                                                                    |
| `submitEditor`                     | Submit value of a editor                                                                                                                                |
| `updateSelectionStartEndReference` | Internal function to update selection references                                                                                                        |
| `tokenizer`                        | Tokenizer formulas to identify selections and structured references                                                                                     |
| `flash`                            | Flash a range of cells with a specified color and duration                                                                                              |
| `showCellPopover`                  | Show a popover at a specific cell location with custom content                                                                                          |
| `dispatchEvent`                    | Dispatch events to the spreadsheet grid                                                                                                                 |
| `redrawGrid`                       | Manually trigger a redraw of the grid                                                                                                                   |

## Examples

### Flash cells

Flash a range of cells to draw user attention:

```tsx
const { flash } = useSpreadsheet();

// Flash a range with yellow color for 1.5 seconds
flash?.(
  {
    startRowIndex: 2,
    endRowIndex: 3,
    startColumnIndex: 2,
    endColumnIndex: 3,
    sheetId: activeSheetId,
  },
  "#ffcc00",
  1500
);
```

### Show cell popover

Display custom content in a popover at a specific cell:

```tsx
const { showCellPopover } = useSpreadsheet();

showCellPopover?.(
  {
    rowIndex: 2,
    columnIndex: 3,
    sheetId: 1,
  },
  () => <div>Custom popover content</div>
);
```

### Redraw grid

Manually trigger a grid redraw (useful after loading custom fonts):

```tsx
const { redrawGrid } = useSpreadsheet();

loadWebFont(["Lobster"]).then(() => {
  redrawGrid?.();
});
```

# Hooks

Utility hooks for advanced spreadsheet functionality

The spreadsheet provides several utility hooks for common operations beyond the main `useSpreadsheetState` hook.

## useNavigateToSheetRange

Navigate to a specific cell or range in a sheet, optionally with a visual flash effect.

### Basic Usage

```tsx
import { useNavigateToSheetRange } from "@rowsncolumns/spreadsheet";
import { useSpreadsheetState } from "@rowsncolumns/spreadsheet-state";

function MySpreadsheet() {
  const navigateToSheetRange = useNavigateToSheetRange();

const handleGoToRange = () => {
    navigateToSheetRange?.({
      sheetId: 2,
      startRowIndex: 10,
      endRowIndex: 15,
      startColumnIndex: 5,
      endColumnIndex: 8,
    });
  };

return (
    <button onClick={handleGoToRange}>
      Go to Sheet 2, Range F11:I16
    </button>
  );
}
```

### Parameters

```typescript
navigateToSheetRange(
  sheetRange: SheetRange,     // The range to navigate to
  {
    enableFlash?: boolean,       // Show flash effect (default: true)
    flashColor?: Color,          // Flash color (default: "#ffcc00")
    flashDuration?: number       // Flash duration in ms (default: 1500)
  }
)
```

### Features

* **Sheet switching**: Automatically switches to the target sheet
* **Cell positioning**: Sets active cell to the top-left of the range
* **Scrolling**: Scrolls the range into view
* **Visual feedback**: Optional flash effect to highlight the range

### Example with Custom Flash

```tsx
const navigateToSheetRange = useNavigateToSheetRange();

// Navigate with red flash for 2 seconds
navigateToSheetRange?.(
  {
    sheetId: 1,
    startRowIndex: 5,
    endRowIndex: 10,
    startColumnIndex: 3,
    endColumnIndex: 6,
  },
  {
    enableFlash: true,      // Enable flash
    flashColor: "#ff0000", // Red color
    flashDuration: 2000       // 2 seconds
  }  
);
```

### Use Cases

* **Jump to errors**: Navigate to cells with validation errors
* **Go to formulas**: Jump to cells referenced in formulas
* **Search results**: Navigate to search result cells
* **Links**: Implement cell links to other sheet locations
* **Named ranges**: Jump to named range locations

## useLoadingIndicator

Display a loading indicator during async operations.

### Basic Usage

```tsx
import { useLoadingIndicator, LoadingIndicator } from "@rowsncolumns/spreadsheet";

function MySpreadsheet() {
  const [showLoader, hideLoader] = useLoadingIndicator();

const handleAsyncOperation = async () => {
    showLoader();
    try {
      await someAsyncOperation();
    } finally {
      hideLoader();
    }
  };

return (
    <>
      <button onClick={handleAsyncOperation}>
        Load Data
      </button>
      <CanvasGrid />
      <LoadingIndicator />
    </>
  );
}
```

### API

The hook returns a tuple:

```typescript
const [showLoader, hideLoader] = useLoadingIndicator();
```

* `showLoader()`: Shows the loading indicator
* `hideLoader()`: Hides the loading indicator

### Example with Multiple Operations

```tsx
function SpreadsheetWithAsyncOps() {
  const [showLoader, hideLoader] = useLoadingIndicator();

const saveData = async () => {
    showLoader();
    try {
      await saveSpreadsheetData(sheetData);
    } finally {
      hideLoader();
    }
  };

return (
    <>
      <button onClick={loadData}>Load</button>
      <button onClick={saveData}>Save</button>
      <CanvasGrid />
      <LoadingIndicator />
    </>
  );
}
```

### Component

The `LoadingIndicator` component must be rendered in your app (typically at the root level):

```tsx
<SpreadsheetProvider>
  <Toolbar />
  <CanvasGrid />
  <LoadingIndicator />  {/* Required for the hook to work */}
</SpreadsheetProvider>
```

### Use Cases

* **Data loading**: Show loader while fetching data from server
* **File import**: Display during Excel/CSV import operations
* **Calculations**: Show during long-running calculations
* **Export operations**: Display while generating exports

## useSpreadsheetApi

Access the imperative API for programmatic control of the spreadsheet.

### Basic Usage

```tsx
import { useSpreadsheetApi } from "@rowsncolumns/spreadsheet";

function MyComponent() {
  const api = useSpreadsheetApi();

const updateCell = () => {
    api?.getActiveSheet()
      ?.getRange({ rowIndex: 1, columnIndex: 1 })
      .setValue("Hello World")
      .setFormat("backgroundColor", "#ffcc00");
  };

return <button onClick={updateCell}>Update A1</button>;
}
```

See [Imperative Spreadsheet API](/getting-started/imperative-spreadsheet-api) for complete documentation.

## Complete Example

```tsx
import React, { useState } from "react";
import {
  SpreadsheetProvider,
  CanvasGrid,
  LoadingIndicator,
  useLoadingIndicator,
  useNavigateToSheetRange,
  useSpreadsheetApi,
} from "@rowsncolumns/spreadsheet";
import {
  useSpreadsheetState,
  type SheetData,
} from "@rowsncolumns/spreadsheet-state";

function SpreadsheetWithHooks() {
  const [sheets, setSheets] = useState([
    { sheetId: 1, rowCount: 100, columnCount: 26, title: "Sheet 1" },
    { sheetId: 2, rowCount: 100, columnCount: 26, title: "Sheet 2" },
  ]);
  const [sheetData, setSheetData] = useState<SheetData>({});

return (
    <SpreadsheetProvider>
      <SpreadsheetControls
        sheets={sheets}
        sheetData={sheetData}
        onChangeSheets={setSheets}
        onChangeSheetData={setSheetData}
      />
    </SpreadsheetProvider>
  );
}

function SpreadsheetControls({ sheets, sheetData, onChangeSheets, onChangeSheetData }) {
  const [showLoader, hideLoader] = useLoadingIndicator();
  const navigateToSheetRange = useNavigateToSheetRange();
  const api = useSpreadsheetApi();

const updateCellProgrammatically = () => {
    api?.getActiveSheet()
      ?.getRange({ rowIndex: 1, columnIndex: 1 })
      .setValue("Updated via API");
  };

return (
    <>
      <div className="toolbar">
        <button onClick={findAndNavigate}>
          Find and Navigate
        </button>
        <button onClick={updateCellProgrammatically}>
          Update A1
        </button>
      </div>

<LoadingIndicator />
    </>
  );
}

export default SpreadsheetWithHooks;
```

## Hook Dependencies

### useNavigateToSheetRange

Requires `SpreadsheetProvider` context:

```tsx
<SpreadsheetProvider>
  {/* Component using useNavigateToSheetRange */}
</SpreadsheetProvider>
```

### useLoadingIndicator

Requires `LoadingIndicator` component to be rendered:

```tsx
<SpreadsheetProvider>
  <YourComponents />
  <LoadingIndicator />  {/* Required */}
</SpreadsheetProvider>
```

### useSpreadsheetApi

Requires `SpreadsheetProvider` and active spreadsheet state:

```tsx
<SpreadsheetProvider>
  {/* Component using useSpreadsheetApi */}
</SpreadsheetProvider>
```

## Best Practices

### useNavigateToSheetRange

1. **User feedback**: Always provide visual feedback when navigating (use flash effect)
2. **Bounds checking**: Ensure the range exists before navigating
3. **Sheet existence**: Verify the target sheet exists

### useLoadingIndicator

1. **Always hide**: Use try-finally to ensure hideLoader is called
2. **Error handling**: Show errors to users if operations fail
3. **Timeout**: Consider adding timeouts for long operations
4. **Multiple operations**: Use separate show/hide pairs for different operations

### useSpreadsheetApi

1. **Null checking**: Always use optional chaining (`api?.`)
2. **State management**: Prefer declarative state over imperative API when possible
3. **Batch operations**: Use batch methods for multiple changes

## TypeScript Support

All hooks are fully typed:

```typescript
import type { SheetRange, Color } from "@rowsncolumns/spreadsheet";

const navigateToSheetRange = useNavigateToSheetRange();
// Type: (range: SheetRange, flash?: boolean, color?: Color, duration?: number) => void

const [showLoader, hideLoader] = useLoadingIndicator();
// Type: [() => void, () => void]

const api = useSpreadsheetApi();
// Type: SpreadsheetAPI | null
```

## Troubleshooting

### useNavigateToSheetRange not working

Ensure you're inside `SpreadsheetProvider`:

```tsx
<SpreadsheetProvider>
  <YourComponent />  {/* Hook works here */}
</SpreadsheetProvider>
```

### LoadingIndicator not showing

Verify the component is rendered:

```tsx
<LoadingIndicator />  {/* Must be present */}
```

### useSpreadsheetApi returns null

The API is only available after the spreadsheet is mounted:

```tsx
useEffect(() => {
  if (api) {
    // API is ready
  }
}, [api]);
```

# Modules

Spreadsheet 2 comes with various modules to help you compose the spreadsheet that you like.

## Calculator

Calculator contains tools to parse formula strings and evaluate them. We use a custom version of [fast-formula-parser](https://github.com/LesterLyu/fast-formula-parser).

```
yarn add @rowsncolumns/calculator
```

## Calculator Web worker

You can also run calculations in a web worker. Only the evaluation is done in a worker thread, while the dependency graph and dependency parser remains in the main UI thread

```
yarn add @rowsncolumns/calculator-webworker
```

## DAG - Directed acyclic graph

The dag package is used to store cell dependencies. You can use it to get dependents and precedents of a cell

```
yarn add @rowsncolumns/dag
```

## Functions

The functions package contains built-in functions supported by Spreadsheet. It also contains function descriptions, parameters etc.

```
yarn add @rowsncolumns/functions
```

## Grid

This is the main canvas grid that powers the spreadsheet

```
yarn add @rowsncolumns/grid
```

## Icons

Contains all icons used by Spreadsheet

```
yarn add @rowsncolumns/icons
```

## Toolkit

All export/import functions are available in the toolkit

```
yarn add @rowsncolumns/toolkit
```

## Spreadsheet State

Exposes hooks to manage spreadsheet state. Only required if you are not using a custom state management solution

```
yarn add @rowsncolumns/spreadsheet-state
```

## UI Components

The UI package contains all shared components used by Spreadsheet. CSS is powered by [Stitches](https://stitches.dev/). We do have plans to migrate to tailwind

```
yarn add @rowsncolumns/ui
```

## Utilities

Shared sheet utility functions

```
yarn add @rowsncolumns/utils
```

## Y Spreadsheet

```json
yarn add @rowsncolumns/y-spreadsheet
```

## Pivot

The pivot package provides advanced pivot table functionality powered by DuckDB for row/column grouping and aggregations.

```
yarn add @rowsncolumns/pivot
```

# SheetCell

Sheet Cell is a primitive to generate CellData object

### How to use SheetCell

{% code overflow="wrap" %}

```tsx
import { SheetCell } from "@rowsncolumns/spreadsheet-state"

const sheetCell = new SheetCell()

// Extend if necessary from existing cellData
const existingCellData = {}
sheetCell.assign(sheetId, { rowIndex, columnIndex }, existingCellData)

// Set user entered value
sheetCell.setUserEnteredValue("$20")

// Get cell data
const cellData = sheetCell.getCellData()
```

{% endcode %}

CellData is the cell representation used in Spreadsheet 2. Short-form keys (`ue` / `ev` / `uf` / `fv`) are preferred for new writes — see [Cell Data](/configuration/api/cell-data) for the full type. The same short-form convention applies inside `ExtendedValue`: `nv` (number), `sv` (string), `bv` (bool), `fv` (formula), `ev` (error).

```json
{
    "ue": {
        "sv": "20"
    },
    "ev": {
        "nv": 20
    },
    "fv": "$20",
    "uf": {
        "numberFormat": {
            "type": "CURRENCY",
            "pattern": "\"$\"#,##0"
        }
    }
}
```

{% hint style="info" %}
`effectiveFormat` / `ef` are no longer written on `CellData`. The renderer derives the effective format on the fly from `uf`, the cell value, and (for formula cells) precedent formats. Older saved data with `effectiveFormat` still loads.
{% endhint %}

# Using Spreadsheet with NextJS

SSR is supported, but Server components, not yet

Add `use client` at the top of your file, so this component will be part of client bundle

More info here - <https://beta.nextjs.org/docs/rendering/server-and-client-components#convention>

```tsx
"use client";
import "@rowsncolumns/spreadsheet/dist/spreadsheet.min.css";
import { SpreadsheetProvider, CanvasGrid } from "@rowsncolumns/spreadsheet";

export const Sheet = () => {
  return (
    <SpreadsheetProvider>
      <CanvasGrid />
    </SpreadsheetProvider>
  );
};
```

## Loading Canvas in Node

NextJS throws error while compiling canvas during SSR. If you see these errors,

```
Error: Module not found: Can't resolve 'canvas'
Did you mean './canvas'?
```

```
ModuleParseError: Module parse failed: Unexpected character '�' (1:0)
You may need an appropriate loader to handle this file type, currently no loaders are configured to process this file. See https://webpack.js.org/concepts#loaders
(Source code omitted for this binary file)
```

the solution would be to install `canvas` and add it as an external module in nextJS

```
yarn add canvas --dev
```

```typescript
/** @type {import('next').NextConfig} */
const nextConfig = {
  webpack (config) {
    config.externals.push('canvas')
    return config
  }
}

module.exports = nextConfig
```

### CSS Specificity when importing stylesheet

NextJS does not respect the order of CSS imports. So there could be style conflicts if you are using tailwindcss in a nextJS project.

The proposed solution is in tailwindcss v3 is

1. Install `postcss-import` and add it to your `postcss.config.js`

```javascript
module.exports = {
  plugins: {
    "postcss-import": {},
    tailwindcss: {},
    autoprefixer: {},
  },
};
```

2. Import spreadsheet style using the import statement

```
@import "tailwindcss/base";
@import "@rowsncolumns/spreadsheet/dist/spreadsheet.min.css";

@tailwind components;
@tailwind utilities;
```

Credit to <https://github.com/radix-ui/themes/issues/109#issuecomment-1747345743> for the fix

In tailwindcss v4

```
@import "tailwindcss";
@import "@rowsncolumns/spreadsheet/dist/spreadsheet.min.css" layer(components);;
```

### (Optional) Using tailwindcss preset to configure spreadsheet styles

If you are still having problems with conflicting css in nextjs, this is another way to solve it.

Install the rowsncolumns tailwind preset

```sh
yarn add @rowsncolumns/tailwindcss-preset --dev

// or 
npm install @rowsncolumns/tailwindcss-preset
```

Update tailwindcss content and add the preset

```javascript
// tailwind.config.js
content: [
   ...// your files
   "./node_modules/@rowsncolumns/*/dist/**/*.js"
],
presets: [
  require('@rowsncolumns/tailwindcss-preset')
]
```

Import spreadsheet css variables

Add a css file `spreadsheet.css` and add contents from <https://github.com/rowsncolumns/spreadsheet/blob/main/apps/spreadsheet/spreadsheet.css>

Import this css file in global.css

```
// global.css
@tailwind base;
@tailwind components;
@tailwind utilities;

@import "./spreadsheet.css"
```

# Keyboard shortcuts

Use keyboard shortcuts to navigate, format and use formulas.

### Common actions

| Description         | Mac shortcut                      | Windows shortcut                        |
| ------------------- | --------------------------------- | --------------------------------------- |
| Select column       | Ctrl + Space                      | Ctrl + Space                            |
| Select row          | Shift + Space                     | Shift + Space                           |
| Select all          | <p>⌘ + A<br>⌘ + Shift + Space</p> | <p>Ctrl + A<br>Ctrl + Shift + Space</p> |
| Undo                | ⌘ + Z                             | Ctrl + Z                                |
| Redo                | <p>⌘ + Y<br>⌘ + Shift + Z</p>     | <p>Ctrl + Y<br>Ctrl + Shift + Z</p>     |
| Find                | ⌘ + F                             | Ctrl + F                                |
| Fill range          | ⌘ + Enter                         | Ctrl + Enter                            |
| Fill down           | ⌘ + D                             | Ctrl + D                                |
| Fill right          | ⌘ + R                             | Ctrl + R                                |
| Print               | ⌘ + P                             | Ctrl + P                                |
| Copy                | ⌘ + C                             | Ctrl + C                                |
| Cut                 | ⌘ + X                             | Ctrl + X                                |
| Paste               | ⌘ + V                             | Ctrl + V                                |
| Paste values only   | ⌘ + Shift + V                     | Ctrl + Shift + V                        |
| Insert new sheet    | Shift + F11                       | Shift + F11                             |
| Clear selected cell | Backspace or Delete               | Backspace or Delete                     |

### Format Cells

| Description              | Mac shortcut           | Windows shortcut       |
| ------------------------ | ---------------------- | ---------------------- |
| Bold                     | ⌘ + b                  | Cltr + B               |
| Underline                | ⌘ + U                  | Cltr + U               |
| Italic                   | ⌘ + I                  | Cltr + I               |
| Strikethrough            | ⌘ + Shift + X          | Cltr + Shift + X       |
| Centre align             | ⌘ + Shift + E          | Ctrl + Shift + E       |
| Left align               | ⌘ + Shift + L          | Ctrl + Shift + L       |
| Right align              | ⌘ + Shift + R          | Ctrl + Shift + R       |
| Apply top border         | Alt + Shift + 1        | Option + Shift + 1     |
| Apply right border       | Alt + Shift + 2        | Option + Shift + 2     |
| Apply bottom border      | Alt + Shift + 3        | Option + Shift + 3     |
| Apply left border        | Alt + Shift + 4        | Option + Shift + 4     |
| Remove borders           | Alt + Shift + 6        | Option + Shift + 6     |
| Apply outer border       | Alt + Shift + 7        | Option + Shift + 7     |
| Insert time              | ⌘ + Shift + ;          | Ctrl + Shift + ;       |
| Insert date              | ⌘ + ;                  | Ctrl + ;               |
| Insert date and time     | ⌘ + Option + Shift + ; | Ctrl + Alt + Shift + ; |
| Format as decimal        | Ctrl + Shift + 1       | Ctrl + Shift + 1       |
| Format as time           | Ctrl + Shift + 2       | Ctrl + Shift + 2       |
| Format as date           | Ctrl + Shift + 3       | Ctrl + Shift + 3       |
| Format as currency       | Ctrl + Shift + 4       | Ctrl + Shift + 4       |
| Format as percentage     | Ctrl + Shift + 5       | Ctrl + Shift + 5       |
| Format as exponent (TBD) | Ctrl + Shift + 6       | Ctrl + Shift + 6       |
| Clear formatting         | ⌘ + \\                 | Ctrl + \\              |
| Show format dialog       | ⌘ + Option + 1         | Ctrl + Alt + 1\|       |

### Navigate spreadsheet

| Description                | Mac shortcut                                | Windows shortcut                            |
| -------------------------- | ------------------------------------------- | ------------------------------------------- |
| Move to beginning of row   | Fn + Left arrow                             | Home                                        |
| Move to beginning of sheet | ⌘ + Fn + Left arrow                         | Ctrl + Home                                 |
| Move to end of row         | Fn + Right arrow                            | End                                         |
| Move to end of sheet       | ⌘ + Fn + Right arrow                        | Ctrl + End                                  |
| Scroll to active cell      | ⌘ + Backspace                               | Ctrl + Backspace                            |
| Move to next sheet         | <p>Option + Down arrow<br>⌘ + Page Down</p> | <p>Alt + Down arrow<br>Ctrl + Page Down</p> |
| Move to previous sheet     | <p>Option + Up arrow<br>⌘ + Page Up</p>     | <p>Alt + Up arrow<br>Ctrl + Page Up</p>     |

### Edit notes

| Description      | Mac shortcut | Windows shortcut |
| ---------------- | ------------ | ---------------- |
| Insert/edit note | Shift + F2   | Shift + F2       |

### Open menu

| Description  | Mac shortcut | Windows shortcut |
| ------------ | ------------ | ---------------- |
| Context menu | Shift + F10  | Shift + F10      |

### Add or change rows and columns

| Description                 | Mac shortcut   | Windows shortcut |
| --------------------------- | -------------- | ---------------- |
| Insert rows above           |                |                  |
| Insert rows below           |                |                  |
| Insert columns to the left  |                |                  |
| Insert columns to the right |                |                  |
| Delete rows                 |                |                  |
| Delete columns              |                |                  |
| Hide row                    | ⌘ + Option + 9 | Ctrl + Alt + 9   |
| Hide column                 | ⌘ + Option + 0 | Ctrl + Alt + 0   |

### Use formulas

| Description       | Mac shortcut | Windows shortcut |
| ----------------- | ------------ | ---------------- |
| Show all formulae | Ctrl + \~    | Ctrl + \~        |

# Server-side Spreadsheet

Update spreadsheet state and run formula evaluation on the backend

Use `Spreadsheet` from `libs/spreadsheet-state/interface/spreadsheet-interface.ts` when you want to apply spreadsheet operations on the server (API routes, workers, job processors), then evaluate formulas before persisting or broadcasting changes.

## Import

Use the server entrypoint:

```ts
import { Spreadsheet } from "@rowsncolumns/spreadsheet-state/server";
```

## 1) Initialize state

```ts
import type { CellData, Sheet, TableView } from "@rowsncolumns/spreadsheet";
import type { SheetData } from "@rowsncolumns/spreadsheet-state";
import { Spreadsheet } from "@rowsncolumns/spreadsheet-state/server";

const spreadsheet = new Spreadsheet();

const sheets: Sheet[] = [
  { sheetId: 1, rowCount: 200, columnCount: 26, title: "Sheet1" },
];
const sheetData: SheetData<CellData> = { 1: [] };
const tables: TableView[] = [];

spreadsheet.sheets = sheets;
spreadsheet.sheetData = sheetData;
spreadsheet.tables = tables;
```

## 2) Apply updates

Use `changeBatch` for cell values/formulas (single or multi-range):

```ts
spreadsheet.changeBatch(
  1,
  {
    startRowIndex: 1,
    endRowIndex: 1,
    startColumnIndex: 1,
    endColumnIndex: 1,
  },
  [[10]],
);

spreadsheet.changeBatch(
  1,
  {
    startRowIndex: 1,
    endRowIndex: 1,
    startColumnIndex: 2,
    endColumnIndex: 2,
  },
  [["=A1*2"]],
);
```

You can also use structural APIs like `insertRow`, `insertColumn`, `deleteRow`, `deleteColumn`, `changeFormatting`, `updateTable`, etc. on the same `Spreadsheet` instance.

## 3) Run evaluation

After backend edits, explicitly flush calculations:

```ts
const results = await spreadsheet.calculatePending();
```

Useful variants:

* `await spreadsheet.calculatePending()`: Runs only queued operations and returns calculated result entries.
* `await spreadsheet.flushCalculations()`: Runs queued operations but does not return result entries.
* `await spreadsheet.calculateAll()`: Scans current `sheetData` formulas and evaluates them.

If you replace `sheetData` directly (outside `changeBatch`), call `calculateAll()` for a full formula pass, or call `rebuildGraph()` and enqueue explicit operations before `calculatePending()`.

## 4) Read updated values

`calculatePending`/`flushCalculations`/`calculateAll` apply results back into `spreadsheet.sheetData` via the internal calculation pipeline.

```ts
const cellB1 = spreadsheet.sheetData[1]?.[1]?.values?.[2];
```

## 5) Persist or broadcast patches

Every mutation pushes history patches that you can forward to persistence/collab layers.

```ts
const patchTuples = spreadsheet.getPatchTuples(); // for undo/redo style patch consumers
const fullStatePatches = await spreadsheet.generateStatePatches(); // full-state patch export
spreadsheet.clearPatches(); // optional reset after persisting/broadcasting
```

## Worker configuration (recommended)

For backend runtimes, provide a calculation worker explicitly:

```ts
import { Worker } from "node:worker_threads";
import { Spreadsheet } from "@rowsncolumns/spreadsheet-state/server";

const spreadsheet = new Spreadsheet({
  createCalculationWorker: () =>
    new Worker(require.resolve("@rowsncolumns/calculation-worker/worker")),
});
```

# Real time collaboration

Built for real-time editing and viewing of Spreadsheets

With a supported real-time back-end, you can have a full collaborative and real-time Spreadsheet. The UI is data agnostic, so both OT and CRDT data structures are supported.

SheetGrid exposes the following prop to highlight users in the canvas grid.

```tsx
const App = () => {
  const currentUserId = 1
  <SheetGrid
    users={
      [
        {
          userId: 1,
          title: 'Foo bar',
          // Active cell that will be highlighted
          activeCell: { rowIndex: 2, columnIndex: 3},
          // Which sheetID is currently in focus
          sheetId: 1
        },
        {
          userId: 2,
          title: 'Foo bar',
          activeCell: { rowIndex: 2, columnIndex: 3},
          sheetId: 1
        }
      ]
    }
    userId={currentUserId}
  />
}
```

## Immer and useSpreadsheetState

If you are using `useSpreadsheetState` hook to manage the state of Spreadsheet, Immer is the state library that is used to modify state.

Immer has really good API for JSON patches that is sent over the wire for real-time collaboration. JSON patches also helps in building a robust undo/redo functionality.

`onChangeHistory` callback is fired when user modifies state.

```tsx
import { SpreadsheetProvider, CanvasGrid } from "@rowsncolumns/spreadsheet";
import { tokenize as tokenizer } from "@rowsncolumns/calculator";
import { useSpreadsheetState } from "@rowsncolumns/spreadsheet-state";

const App = () => (
  <SpreadsheetProvider>
    <MySpreadsheet />
  </SpreadsheetProvider>
);
```

# Yjs (CRDT) Collaboration

Add real-time collaboration to Spreadsheet 2 using Yjs

There are two ways we can use yjs collaboration

1. Sending patches to yjs document and synchorizing these patches between users
2. Saving the entire data, like sheetData, sheets in yjs document. More performance and easy to restore an entire document

You can install Yjs hook as a separate module

{% tabs %}
{% tab title="yarn" %}

```sh
yarn add "@rowsncolumns/y-spreadsheet"
```

{% endtab %}

{% tab title="npm" %}

```sh
npm install "@rowsncolumns/y-spreadsheet"
```

{% endtab %}
{% endtabs %}

## Initializing Yjs

This hook uses `WebSocketProvider` from Yjs to initialize a connection to one of the demo servers `wss://demos.yjs.dev`

{% hint style="info" %}
The default provider can be easily switched to WebRTCProvider, but as of right now, WebRTC does not support `synced` events.
{% endhint %}

### Running yjs locally

```
HOST=localhost PORT=1234 npx y-websocket
```

```tsx
import {
  SheetData,
  useSpreadsheetState,
} from "@rowsncolumns/spreadsheet-state";

// Option 1
import { useYSpreadsheet } from "@rowsncolumns/yjs-spreadsheet"

// Option 2, Same API
import { useYSpreadsheetV2 } from "@rowsncolumns/yjs-spreadsheet"

import { SpreadsheetProvider, CanvasGrid } from '@rowsncolumns/spreadsheet'

const version = "v1"
const yDoc = new Y.Doc({ gc: true });
const yWebsocketProvider = new WebsocketProvider(
  "ws://localhost:1234",
  `y-spreadsheet-${version}`,
  yDoc,
  {
    connect: true,
  }
);

// User info
    userId,
    title: name,
  });

return (
    <CanvasGrid
      {...}
      users={users}
      userId={userId}
    >
  )

}

const App = () => (
  <SpreadsheetProvider>
    <MySpreadsheet />
  </SpreadsheetProvider>
)
```

## Import excel file and applying updates to yjs

# ShareDB (OT) Collaboration

Real-time collaboration using ShareDB

ShareDB is an OT-based real-time database that enables collaborative editing with automatic conflict resolution. The `@rowsncolumns/sharedb` package provides a React hook for integrating ShareDB with your spreadsheet.

## Installation

{% tabs %}
{% tab title="yarn" %}

```sh
yarn add "@rowsncolumns/sharedb sharedb reconnecting-websocket"
```

{% endtab %}

{% tab title="npm" %}

```sh
npm install "@rowsncolumns/sharedb sharedb reconnecting-websocket"
```

{% endtab %}
{% endtabs %}

## Quick Start

```tsx
import { useShareDBSpreadsheet } from "@rowsncolumns/sharedb";
import ShareDBClient from "sharedb/lib/client";
import ReconnectingWebSocket from "reconnecting-websocket";

// Create ShareDB connection
const socket = new ReconnectingWebSocket("ws://localhost:8080");
const connection = new ShareDBClient.Connection(socket);

function SpreadsheetEditor() {
  const [sheetData, setSheetData] = useState({});
  const [sheets, setSheets] = useState([]);
  const [tables, setTables] = useState([]);
  const [sheetId, setSheetId] = useState(1);
  const [activeCell, setActiveCell] = useState({ rowIndex: 1, columnIndex: 1 });

const { onBroadcastPatch, users, synced, isLeader } = useShareDBSpreadsheet({
    connection,
    collection: "spreadsheets",
    documentId: "my-spreadsheet",
    userId: "user-123",
    title: "John Doe",
    sheetId,
    activeCell,
    initialSheets: [],
    onChangeSheetData: setSheetData,
    onChangeSheets: setSheets,
    onChangeTables: setTables,
    onChangeActiveSheet: setSheetId,
    calculateNow,
    enqueueGraphOperation: (op) => {
      // Handle dependency graph updates for formula recalculation
    },
  });

// Pass onBroadcastPatch to useSpreadsheetState
  return <Spreadsheet sheetData={sheetData} sheets={sheets} users={users} />;
}
```

## Integration with useSpreadsheetState

Connect the ShareDB adapter to your spreadsheet state:

```tsx
import { useSpreadsheetState } from "@rowsncolumns/spreadsheet-state";
import { useShareDBSpreadsheet } from "@rowsncolumns/sharedb";

function CollaborativeSpreadsheet() {
  const {
    sheetData,
    sheets,
    tables,
    charts,
    embeds,
    namedRanges,
    protectedRanges,
    conditionalFormats,
    dataValidations,
    pivotTables,
    cellXfs,
    sharedStrings,
    setSheetData,
    setSheets,
    setTables,
    setCharts,
    setEmbeds,
    setNamedRanges,
    setProtectedRanges,
    setConditionalFormats,
    setDataValidations,
    setPivotTables,
    setCellXfs,
    setSharedStrings,
    enqueueGraphOperation,
    sheetId,
    activeCell,
    calculateNow,
  } = useSpreadsheetState({
    // Your spreadsheet state config
  });

const { onBroadcastPatch, users, synced } = useShareDBSpreadsheet({
    connection,
    collection: "spreadsheets",
    documentId: "doc-id",
    userId: currentUser.id,
    title: currentUser.name,
    sheetId,
    activeCell,
    initialSheets: [],
    calculateNow,
    onChangeSheetData: setSheetData,
    onChangeSheets: setSheets,
    onChangeTables: setTables,
    onChangeCharts: setCharts,
    onChangeEmbeds: setEmbeds,
    onChangeNamedRanges: setNamedRanges,
    onChangeProtectedRanges: setProtectedRanges,
    onChangeConditionalFormats: setConditionalFormats,
    onChangeDataValidations: setDataValidations,
    onChangePivotTables: setPivotTables,
    onChangeCellXfs: setCellXfs,
    onChangeSharedStrings: setSharedStrings,
    enqueueGraphOperation,
  });

// Pass onBroadcastPatch to your spreadsheet
  // ...
}
```

## Setting Up a ShareDB Server

### Basic Server

Create a file `server.js`:

```javascript
const http = require("http");
const express = require("express");
const ShareDB = require("sharedb");
const WebSocket = require("ws");
const WebSocketJSONStream = require("@teamwork/websocket-json-stream");

// Initialize ShareDB
const backend = new ShareDB();

// Create Express app and HTTP server
const app = express();
const server = http.createServer(app);

// Create WebSocket server
const wss = new WebSocket.Server({ server });

// Handle WebSocket connections
wss.on("connection", (ws) => {
  const stream = new WebSocketJSONStream(ws);
  backend.listen(stream);
});

// Start server
const PORT = process.env.PORT || 8080;
server.listen(PORT, () => {
  console.log(`ShareDB server listening on port ${PORT}`);
});
```

Install dependencies:

```bash
npm install express sharedb ws @teamwork/websocket-json-stream
```

Run the server:

```bash
node server.js
```

### Server with MongoDB Persistence

For production environments, persist data to MongoDB:

```bash
npm install sharedb-mongo mongodb
```

```javascript
const ShareDBMongo = require("sharedb-mongo");

// Connect to MongoDB
const db = new ShareDBMongo("mongodb://localhost:27017/spreadsheets");

// Initialize ShareDB with MongoDB
const backend = new ShareDB({ db });
```

### Server with PostgreSQL Persistence

```bash
npm install sharedb-postgres pg
```

```javascript
const ShareDBPostgres = require("sharedb-postgres");

const db = new ShareDBPostgres({
  connectionString: "postgresql://user:password@localhost:5432/spreadsheets",
});

const backend = new ShareDB({ db });
```

## Document Structure

The ShareDB document stores all spreadsheet data:

```typescript
type ShareDBSpreadsheetDoc = {
  // Cell data: flat map with keys like "1!A1" -> { value, sId, r, c }
  sheetData: Record<string, CellDataV3>;

// Sheet definitions
  sheets: Sheet[];

// Tables, charts, embeds
  tables: TableView[];
  charts: EmbeddedChart[];
  embeds: EmbeddedObject[];

// Named ranges, protected ranges
  namedRanges: NamedRange[];
  protectedRanges: ProtectedRange[];

// Conditional formats, data validations
  conditionalFormats: ConditionalFormatRule[];
  dataValidations: DataValidationRuleRecord[];

// Pivot tables
  pivotTables: PivotTable[];

// Cell formats and shared strings
  cellXfs: Record<string, CellFormat>;
  sharedStrings: Record<string, string>;
};
```

### Cell Key Format

Cell keys follow the pattern `${sheetId}!${A1Address}`:

| Key         | Description           |
| ----------- | --------------------- |
| `"1!A1"`    | Cell A1 on sheet 1    |
| `"2!B5"`    | Cell B5 on sheet 2    |
| `"1!AA100"` | Cell AA100 on sheet 1 |

### CellDataV3 Structure

Each cell value is stored with its position metadata:

```typescript
type CellDataV3<T> = {
  value: T; // The cell data (text, formula, number, etc.)
  sId: number; // Sheet ID
  r: number; // Row index (0-based)
  c: number; // Column index (0-based)
};
```

## Presence Awareness

The hook automatically manages presence, allowing you to display other users' cursor positions:

```tsx
const { users } = useShareDBSpreadsheet({ ... });

// Render collaborators in your grid
<CanvasGrid
  users={users}
  userId={currentUserId}
/>
```

Each user in the `users` array includes:

```typescript
type Collaborator = {
  userId: string;
  title: string;
  sheetId: number;
  activeCell: { rowIndex: number; columnIndex: number };
};
```

## Leader Election

The adapter automatically elects a leader among connected clients. The leader is responsible for coordinating recalculation operations.

```tsx
const { isLeader } = useShareDBSpreadsheet({ ... });

// Leader-specific logic
if (isLeader) {
  // This client is responsible for coordinating recalcs
}
```

## Error Handling

Handle connection errors with the `onError` callback:

```tsx
useShareDBSpreadsheet({
  // ...
  onError: (err) => {
    console.error("ShareDB error:", err);
    toast.error("Connection lost. Reconnecting...");
  },
});
```

## Why ShareDB for Spreadsheets?

ShareDB's [Operational Transformation (OT)](https://en.wikipedia.org/wiki/Operational_transformation) approach is particularly well-suited for spreadsheet collaboration compared to CRDT-based solutions like Yjs.

### Comparison with Y.js

| Aspect              | ShareDB (OT)                            | Yjs (CRDT)                                   |
| ------------------- | --------------------------------------- | -------------------------------------------- |
| Conflict Resolution | OT - Server determines canonical order  | CRDT - Automatic merge, eventual consistency |
| Server Required     | Yes                                     | Optional (P2P possible)                      |
| Recalculation       | Leader election makes coordination easy | Requires additional coordination layer       |
| Undo/Redo           | Manual (via Immer patches)              | Built-in                                     |
| Offline Support     | Requires server connection              | Full offline-first support                   |
| Audit Trails        | Sequential operation log                | Distributed history                          |
| Data Persistence    | MongoDB, PostgreSQL, etc.               | LevelDB, IndexedDB, etc.                     |

### Why OT Works Well for Spreadsheets

1. **Cell-level granularity** - The V3 flat map structure (`"sheetId!A1"` keys) maps perfectly to ShareDB's json0 OT type. Each cell is an independent key-value pair, so conflicts are rare.
2. **Server-centric calculation** - Spreadsheets typically need a server anyway for formula calculation, persistence, and permissions. OT's server authority aligns naturally with this architecture.
3. **Simpler undo/redo** - OT's sequential operation log makes history management straightforward. The server maintains a clear order of operations.
4. **Predictable conflict resolution** - When two users edit the same cell simultaneously (rare in practice), the server determines the winner. No surprising merged states.
5. **Batched operations** - Large operations (paste 1000 cells, delete rows) can be batched into a single atomic `submitOp` call, maintaining consistency.

### When to Choose ShareDB

* Need a traditional client-server architecture
* Want to leverage existing MongoDB/PostgreSQL infrastructure
* Prefer predictable OT semantics for conflict resolution
* Server-side formula calculation is required
* Need clean audit trails and operation history

### When to Choose Y.js

* Need offline-first capabilities
* Want peer-to-peer collaboration without a server
* Need built-in undo/redo support
* Decentralized architecture is preferred

For most spreadsheet use cases with a server backend, ShareDB provides a cleaner, more predictable collaboration model.

---

[Next Page](/llms-full.txt/1)

Additional Information

Project Description

Related Charts

Add Notes