@reductoai-collab/components

A collection of React components for document visualization and processing. Designed for use with Reducto AI extraction results.

Components

| Component | Description | |-----------|-------------| | SpreadsheetViewer | Excel viewer with bounding box overlays |

Installation

This package is distributed via GitHub Packages. You need to configure npm to use GitHub Packages for the @reductoai-collab scope.

1. Create a GitHub Personal Access Token

1. Go to GitHub Settings > Developer settings > Personal access tokens
2. Generate a new token (classic) with read:packages scope
3. Copy the token

2. Configure npm

Create or update ~/.npmrc (global) or .npmrc in your project root:

@reductoai-collab:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=YOUR_GITHUB_TOKEN

Or use the npm login command:

npm login --scope=@reductoai-collab --registry=https://npm.pkg.github.com
# Username: your-github-username
# Password: your-github-token
# Email: your-email

3. Install the package

npm install @reductoai-collab/components
# or
pnpm add @reductoai-collab/components
# or
yarn add @reductoai-collab/components

SpreadsheetViewer

A React component for viewing Excel spreadsheets with bounding box overlay support.

Features

• View Excel files (.xlsx, .xls) in the browser
• Overlay bounding boxes on specific cells (Reducto format)
• Multi-sheet support with tab navigation
• Fully customizable styling via CSS variables
• No Tailwind dependency - works with any CSS framework
• TypeScript support with full type definitions

Quick Start

// Import from main package
import { SpreadsheetViewer } from '@reductoai-collab/components';
import '@reductoai-collab/components/styles/spreadsheet-viewer.css';

// Or import directly from submodule
import { SpreadsheetViewer } from '@reductoai-collab/components/spreadsheet-viewer';
import '@reductoai-collab/components/styles/spreadsheet-viewer.css';

function App() {
  return (
    <SpreadsheetViewer
      url="https://example.com/spreadsheet.xlsx"
      bboxes={[
        {
          id: '1',
          page: 1,      // Sheet number (1-indexed)
          top: 2,       // Row (1-indexed)
          left: 1,      // Column (1-indexed)
          width: 3,     // Cells wide
          height: 2,    // Cells tall
          color: 'blue',
          label: 'Header',
        }
      ]}
      onBboxClick={(bbox) => console.log('Clicked:', bbox)}
    />
  );
}

Props

| Prop | Type | Required | Description | |------|------|----------|-------------| | url | string | Yes | URL to the Excel file | | bboxes | BoundingBox[] | No | Bounding boxes to overlay | | onBboxClick | (bbox: BoundingBox) => void | No | Called when a bbox is clicked | | onSheetChange | (index: number, name: string) => void | No | Called when user changes sheet | | onLoad | (metadata: WorkbookMetadata) => void | No | Called when workbook loads | | onError | (error: SpreadsheetError) => void | No | Called on error | | activeSheetIndex | number | No | Controlled sheet index (0-indexed) | | className | string | No | Additional CSS classes | | style | CSSProperties | No | Inline styles | | maxCells | number | No | Max cells before truncation (default: 100000) |

BoundingBox Type

interface BoundingBox {
  id: string;           // Unique identifier
  page: number;         // Sheet number (1-indexed)
  top: number;          // Row (1-indexed)
  left: number;         // Column (1-indexed)
  width: number;        // Cell span width
  height: number;       // Cell span height
  color?: BoundingBoxColor;  // 'blue' | 'green' | 'red' | 'yellow' | etc.
  label?: string;       // Hover text
  invisible?: boolean;  // Hide this bbox
  zIndex?: number;      // Stacking order
  metadata?: Record<string, unknown>;  // Custom data for click handler
}

Customization

CSS Variables

Override these CSS variables to customize the appearance:

:root {
  /* Base colors */
  --sv-background: #ffffff;
  --sv-foreground: #1f2937;
  --sv-border-color: #e5e7eb;

  /* Tab styling */
  --sv-tab-background-active: #ffffff;
  --sv-tab-foreground-active: #1f2937;

  /* Table styling */
  --sv-table-border-color: #d1d5db;
  --sv-table-header-background: #f9fafb;

  /* Bbox colors (example for blue) */
  --sv-bbox-blue-background: rgba(59, 130, 246, 0.2);
  --sv-bbox-blue-border: #3b82f6;
  --sv-bbox-blue-label: #3b82f6;
}

Available Color Variables

Each bbox color has these variables:

• --sv-bbox-{color}-background
• --sv-bbox-{color}-hover-background
• --sv-bbox-{color}-border
• --sv-bbox-{color}-label

Colors: blue, green, red, yellow, purple, orange, cyan, pink, gray

Advanced Usage

With Reducto Extraction Results

import { SpreadsheetViewer } from '@reductoai-collab/components';
import '@reductoai-collab/components/styles/spreadsheet-viewer.css';

function DocumentViewer({ documentUrl, extractionResult }) {
  // Convert Reducto blocks to bboxes
  const bboxes = extractionResult.blocks.map(block => ({
    id: block.id,
    page: block.bbox.page,
    top: block.bbox.top,
    left: block.bbox.left,
    width: block.bbox.width,
    height: block.bbox.height,
    color: block.type === 'table' ? 'blue' : 'green',
    label: block.type,
    metadata: { blockId: block.id, content: block.content },
  }));

  return (
    <SpreadsheetViewer
      url={documentUrl}
      bboxes={bboxes}
      onBboxClick={(bbox) => {
        console.log('Block ID:', bbox.metadata?.blockId);
      }}
    />
  );
}

Using Individual Hooks

import { useSpreadsheet } from '@reductoai-collab/components';

function CustomViewer({ url }) {
  const { sheets, workbook, loading, error } = useSpreadsheet({
    url,
    maxCells: 50000,
    onLoad: (meta) => console.log('Loaded:', meta),
  });

  // Build your own UI with the parsed data
  return (
    <div>
      {sheets.map((sheet, i) => (
        <div key={i}>{sheet.name}</div>
      ))}
    </div>
  );
}

TypeScript

Full TypeScript support is included. Import types as needed:

import type {
  BoundingBox,
  BoundingBoxColor,
  WorkbookMetadata,
  SpreadsheetError,
  SpreadsheetViewerProps,
} from '@reductoai-collab/components';

Browser Support

• Chrome/Edge 88+
• Firefox 78+
• Safari 14+

License

This is proprietary software. Access requires a valid license from Reducto AI.

Contact: [email protected]