npm package: @nuptechs/nup-xlsx-core
Description: Lightweight, Edge-compatible Excel parser with full style resolution
Latest version: 0.1.1

# @aspect/nup-xlsx-core

Lightweight, Edge-compatible Excel (.xlsx) and CSV parser with full style resolution including theme colors.

## Features

- **Edge-Compatible**: Zero Node.js dependencies, works in Cloudflare Workers, Vercel Edge, and browsers
- **Small Bundle**: ~6KB gzipped (uses only fflate for ZIP handling)
- **Full Style Resolution**: Theme colors, indexed colors, and tint calculations
- **TypeScript**: 100% TypeScript with full type definitions
- **Tree-shakeable**: Named exports with no side effects

## Installation

```bash
npm install @aspect/nup-xlsx-core
```

## Usage

### Parse XLSX

```typescript
import { parseXlsx } from '@aspect/nup-xlsx-core';

const response = await fetch('spreadsheet.xlsx');
const buffer = await response.arrayBuffer();
const workbook = await parseXlsx(buffer);

for (const sheet of workbook.sheets) {
  console.log(`Sheet: ${sheet.name}`);
  for (const row of sheet.cells) {
    for (const cell of row) {
      console.log(cell.value, cell.style);
    }
  }
}
```

### Parse CSV

```typescript
import { parseCsv } from '@aspect/nup-xlsx-core';

const csvText = 'Name,Age\nAlice,30\nBob,25';
const sheet = parseCsv(csvText);

console.log(sheet.cells[0][0].value); // "Name"
console.log(sheet.cells[1][1].value); // 30
```

### Color Resolution

```typescript
import { resolveColor, getDefaultTheme } from '@aspect/nup-xlsx-core';

const theme = getDefaultTheme();

// Resolve theme color
const color = resolveColor({ theme: 4, tint: 0.5 }, theme);
console.log(color); // "#A7BFDD" (lightened accent1)
```

### Cell Reference Utilities

```typescript
import { cellRefToCoords, coordsToCellRef } from '@aspect/nup-xlsx-core';

cellRefToCoords('B4'); // { row: 3, col: 1 }
coordsToCellRef({ row: 3, col: 1 }); // "B4"
```

## API

### Main Functions

- `parseXlsx(data: ArrayBuffer | Uint8Array): Promise<NupWorkbook>` - Parse XLSX file
- `parseCsv(text: string, options?: CsvOptions): NupWorksheet` - Parse CSV text

### Color Functions

- `resolveColor(color: ColorSpec, theme: NupTheme): string` - Resolve any color to #RRGGBB
- `getDefaultTheme(): NupTheme` - Get default Office theme
- `applyTint(hexColor: string, tint: number): string` - Apply tint to a color
- `getIndexedColor(index: number): string` - Get indexed palette color

### Utility Functions

- `cellRefToCoords(ref: string): CellRef` - Convert "B4" to {row: 3, col: 1}
- `coordsToCellRef(coords: CellRef): string` - Convert {row: 3, col: 1} to "B4"

## Types

```typescript
interface NupWorkbook {
  name: string;
  sheets: NupWorksheet[];
  theme: NupTheme;
  metadata?: { creator?: string; created?: Date; modified?: Date };
}

interface NupWorksheet {
  name: string;
  cells: NupCell[][];
  columns: ColumnInfo[];
  rows: RowInfo[];
  merges: MergeRange[];
  frozen?: FreezePane;
}

interface NupCell {
  value: string | number | boolean | Date | null;
  formula?: string;
  style: NupCellStyle;
  type: 'string' | 'number' | 'boolean' | 'date' | 'formula' | 'empty';
}

interface NupCellStyle {
  font?: FontStyle;
  fill?: FillStyle;
  border?: BorderStyle;
  alignment?: AlignmentStyle;
  numberFormat?: string;
}
```

## License

MIT