Advanced Grid Features

AI-powered autofill and advanced grid navigation features

This document covers advanced features available in the CanvasGrid component that enhance user interaction and productivity.

Magic Fill

Magic Fill is an AI-powered autofill feature that intelligently predicts and fills data based on patterns. When enabled, it enhances the standard autofill functionality with smart pattern recognition.

Enabling Magic Fill

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

function MySpreadsheet() {
  const {
    activeCell,
    activeSheetId,
    selections,
    // ... other hook values
  } = useSpreadsheetState({
    sheets,
    sheetData,
    onChangeSheets,
    onChangeSheetData,
  });

  return (
    <SpreadsheetProvider>
      <CanvasGrid
        sheetId={activeSheetId}
        activeCell={activeCell}
        selections={selections}
        enableMagicFill={true}  // Enable magic fill
        // ... other props
      />
    </SpreadsheetProvider>
  );
}

How It Works

Magic Fill analyzes the selected data and intelligently fills the remaining cells:

1. User selects a range of cells with data

2. User drags the fill handle or uses autofill

3. Magic Fill analyzes the pattern and fills intelligently

4. Can handle complex patterns, dates, text series, and more

Use Cases

• Smart series completion: Fills dates, numbers, or text patterns

• Data transformation: Applies consistent transformations across cells

• Pattern recognition: Detects and continues complex patterns

Data Boundary Navigation

Data Boundary Navigation allows users to quickly jump to the edges of data ranges using keyboard shortcuts (typically Ctrl+Arrow keys).

Enabling Data Boundary Navigation

<CanvasGrid
  enableDataBoundaryNavigation={true}
  // ... other props
/>

How It Works

When enabled, users can:

• Ctrl+Arrow Up: Jump to the first non-empty cell or edge of data above

• Ctrl+Arrow Down: Jump to the last non-empty cell or edge of data below

• Ctrl+Arrow Left: Jump to the first non-empty cell or edge of data to the left

• Ctrl+Arrow Right: Jump to the last non-empty cell or edge of data to the right

This feature mimics Excel's behavior and is essential for navigating large datasets efficiently.

Example

import React, { useState } from "react";
import {
  SpreadsheetProvider,
  CanvasGrid,
} from "@rowsncolumns/spreadsheet";
import { useSpreadsheetState } from "@rowsncolumns/spreadsheet-state";

function SpreadsheetWithNavigation() {
  const [sheets, setSheets] = useState([
    { sheetId: 1, rowCount: 1000, columnCount: 26, title: "Data" }
  ]);
  const [sheetData, setSheetData] = useState({});

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

  return (
    <SpreadsheetProvider>
      <CanvasGrid
        sheetId={activeSheetId}
        activeCell={activeCell}
        selections={selections}
        getCellData={getCellData}
        onChangeActiveCell={onChangeActiveCell}
        onChangeSelections={onChangeSelections}
        enableDataBoundaryNavigation={true}
        // ... other props
      />
    </SpreadsheetProvider>
  );
}

Selection Resize Handles

Selection resize handles provide visual indicators and interaction points for resizing selections, similar to Excel's selection handles.

Enabling Resize Handles

<CanvasGrid
  showSelectionResizeHandles={true}
  // ... other props
/>

Features

• Visual handles: Small squares at the corners and edges of selections

• Click and drag: Resize selections by dragging handles

• Fill handle: Special handle at the bottom-right for autofill operations

• Multi-selection support: Works with multiple selections

Usage Example

<CanvasGrid
  sheetId={activeSheetId}
  activeCell={activeCell}
  selections={selections}
  showSelectionResizeHandles={true}  // Show resize handles
  onFill={onFill}  // Required for fill handle functionality
  onChangeSelections={onChangeSelections}  // Required for resizing
  // ... other props
/>

Readonly Mode

Readonly mode disables all editing functionality while still allowing viewing and navigation.

Enabling Readonly Mode

<CanvasGrid
  readonly={true}
  // ... other props
/>

Features When Readonly

• No editing: Users cannot modify cell values

• Navigation enabled: Arrow keys and scrolling still work

• Selection allowed: Users can select cells and ranges

• Copy enabled: Users can copy data

• Formulas visible: Formula bar shows cell formulas (read-only)

Use Cases

• Viewing reports: Display data without modification risk

• Approval workflows: Show data for review before editing

• Public dashboards: Share spreadsheets in view-only mode

• Template preview: Show template structure before using

Example

import { useState } from "react";
import { CanvasGrid, SpreadsheetProvider } from "@rowsncolumns/spreadsheet";

function ReadonlySpreadsheet({ data, allowEditing = false }) {
  return (
    <SpreadsheetProvider>
      <div>
        <p>{allowEditing ? "Edit Mode" : "View Only"}</p>
        <CanvasGrid
          readonly={!allowEditing}
          // ... other props
        />
      </div>
    </SpreadsheetProvider>
  );
}

Complete Example with All Features

import React, { useState } from "react";
import {
  SpreadsheetProvider,
  CanvasGrid,
  Toolbar,
  BottomBar,
  SheetTabs,
} from "@rowsncolumns/spreadsheet";
import {
  useSpreadsheetState,
  type SheetData,
} from "@rowsncolumns/spreadsheet-state";

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

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

  return (
    <SpreadsheetProvider>
      <Toolbar>
        <button onClick={() => setReadonly(!readonly)}>
          {readonly ? "Enable Editing" : "Make Readonly"}
        </button>
      </Toolbar>

      <CanvasGrid
        sheetId={activeSheetId}
        activeCell={activeCell}
        selections={selections}
        getCellData={getCellData}
        onChangeActiveCell={onChangeActiveCell}
        onChangeSelections={onChangeSelections}
        onFill={onFill}
        
        // Advanced features
        enableMagicFill={true}
        enableDataBoundaryNavigation={true}
        showSelectionResizeHandles={true}
        readonly={readonly}
      />

      <BottomBar>
        <SheetTabs
          sheets={sheets}
          activeSheetId={activeSheetId}
          onChangeActiveSheet={onChangeActiveSheet}
          readonly={readonly}
        />
      </BottomBar>
    </SpreadsheetProvider>
  );
}

CanvasGrid Props Reference

Prop	Type	Default	Description
enableMagicFill	boolean	false	Enable AI-powered intelligent autofill
enableDataBoundaryNavigation	boolean	false	Enable Ctrl+Arrow navigation to data boundaries
showSelectionResizeHandles	boolean	false	Show visual handles for resizing selections
readonly	boolean	false	Disable all editing functionality

Best Practices

Magic Fill

1. Test with your data: Magic fill works best with consistent patterns

2. Provide examples: Give at least 2-3 examples for best results

3. Review results: Always review magic-filled data for accuracy

Data Boundary Navigation

1. Large datasets: Essential for spreadsheets with thousands of rows

2. Keyboard-first users: Great for power users who prefer keyboard navigation

3. Combine with other shortcuts: Works well with Shift+Ctrl+Arrow for selecting ranges

Selection Resize Handles

1. Visual clarity: Makes it clear what is selected

2. Touch interfaces: Especially useful on touch devices

3. Performance: May impact performance with very large selections

Readonly Mode

1. Clear indication: Show visual feedback that sheet is readonly

2. Toggle capability: Provide a way to switch between readonly and edit modes

3. Permissions: Use with authentication/authorization systems

Performance Considerations

• Magic Fill: May have slight delay for complex pattern detection

• Large selections: Resize handles on very large selections (1000+ cells) may impact performance

• Data boundary navigation: Optimized for large datasets

Browser Compatibility

All features work in modern browsers:

• Chrome/Edge 90+

• Firefox 88+

• Safari 14+

Troubleshooting

Magic Fill Not Working

Ensure you have autofill callback implemented:

const { onFill } = useSpreadsheetState({
  // configuration
});

<CanvasGrid
  enableMagicFill={true}
  onFill={onFill}  // Required
/>

Data Boundary Navigation Not Responding

Check that the feature is enabled and you have cell data:

<CanvasGrid
  enableDataBoundaryNavigation={true}
  getCellData={getCellData}  // Required to detect boundaries
/>

Selection Handles Not Visible

Verify the prop is set and selections exist:

<CanvasGrid
  showSelectionResizeHandles={true}
  selections={selections}  // Must have active selections
/>