rowpine 0.0.0-stage → 1.0.0

package/dist/table-source.d.ts

@@ -0,0 +1,147 @@
+/**
+ * Reads a TanStack Table instance into a plain sheet: the visible columns in
+ * screen order, and the rows the user is looking at (filtered and sorted,
+ * groups and tree rows in place). Every exporter works from this.
+ *
+ * The table is typed structurally (`TableLike`) so this file is the only
+ * place that knows TanStack's API. Both a v8 `Table<TData>` and a v9
+ * `Table<TFeatures, TData>` fit it: v9 only has the methods of the features
+ * you register, so everything past the core is optional here, and v9's
+ * start/end pinning and `table.store` state are read alongside v8's
+ * left/right pinning and `getState()`.
+ */
+/** Per-column export settings, read from `columnDef.meta.rowpine`. */
+export type RowpineColumnMeta<TData = any> = {
+    /** Header text in the file. Default: the column's string header, else its id. */
+    header?: string;
+    /** Excel number format, e.g. `'"$"#,##0.00'` or `'yyyy-mm-dd'`. */
+    numFmt?: string;
+    /** Display text for CSV and PDF. Default: numbers and dates in the browser locale. */
+    format?: (value: unknown, row: TData) => string;
+    /** Column width in px. Default: the column's TanStack size. */
+    width?: number;
+    /** Horizontal alignment. Default: right for numbers, left otherwise. */
+    align?: 'left' | 'center' | 'right';
+    /** Cell colors, e.g. for conditional formatting. */
+    cellStyle?: (value: unknown, row: TData) => CellStyle | undefined;
+    /** Leave this column out of every export. */
+    exclude?: boolean;
+};
+export type CellStyle = {
+    fill?: string;
+    color?: string;
+    bold?: boolean;
+};
+/** The parts of a TanStack column the exporters read. */
+export interface ColumnLike {
+    id: string;
+    columnDef: {
+        header?: unknown;
+        meta?: unknown;
+        aggregationFn?: unknown;
+    };
+    parent?: ColumnLike;
+    getSize?(): number;
+}
+/** The parts of a TanStack row the exporters read. */
+export interface RowLike {
+    id: string;
+    depth: number;
+    original: unknown;
+    subRows: RowLike[];
+    groupingColumnId?: string;
+    groupingValue?: unknown;
+    getValue(columnId: string): unknown;
+    getIsGrouped?(): boolean;
+}
+type RowModelLike = {
+    rows: RowLike[];
+};
+/** The parts of a TanStack table the exporters read. */
+export interface TableLike {
+    getAllLeafColumns(): ColumnLike[];
+    getVisibleLeafColumns?(): ColumnLike[];
+    getLeftVisibleLeafColumns?(): ColumnLike[];
+    getRightVisibleLeafColumns?(): ColumnLike[];
+    getStartVisibleLeafColumns?(): ColumnLike[];
+    getEndVisibleLeafColumns?(): ColumnLike[];
+    getCenterVisibleLeafColumns?(): ColumnLike[];
+    getCoreRowModel(): RowModelLike;
+    getFilteredRowModel?(): RowModelLike;
+    getGroupedRowModel?(): RowModelLike;
+    getSortedRowModel?(): RowModelLike;
+    getRowModel(): RowModelLike;
+    getSelectedRowModel?(): RowModelLike;
+    /** v8 state. */
+    getState?(): {
+        grouping?: string[];
+    };
+    /** v9 state. */
+    store?: {
+        readonly state: {
+            grouping?: string[];
+        };
+    };
+    /** v9 React: the selected state. */
+    state?: {
+        grouping?: string[];
+    };
+}
+/** Which rows to export. */
+export type RowScope = 
+/** Every row that passes the filter, on every page, in the current sort (default). */
+'all'
+/** Only the rows on the current page. */
+ | 'page'
+/** Only the selected rows. */
+ | 'selected';
+export type ReadOptions = {
+    rows?: RowScope;
+    /** Style a whole row (e.g. bold totals). Called with the row's original data. */
+    rowStyle?: (original: unknown) => CellStyle | undefined;
+};
+/** Aggregations that have an Excel SUBTOTAL equivalent. */
+export type SubtotalAgg = 'sum' | 'mean' | 'min' | 'max';
+export type SheetColumn = {
+    id: string;
+    header: string;
+    width: number;
+    align: 'left' | 'center' | 'right' | undefined;
+    numFmt?: string;
+    format?: (value: unknown, row: unknown) => string;
+    cellStyle?: (value: unknown, row: unknown) => CellStyle | undefined;
+    /** The column's aggregation when it maps to SUBTOTAL; `auto` resolves per value. */
+    subtotal?: SubtotalAgg | 'auto';
+};
+export type SheetRow = {
+    /** `group` is a TanStack grouped row; `data` is anything else. */
+    kind: 'group' | 'data';
+    /** Nesting depth: 0 for top-level rows. */
+    depth: number;
+    /** Raw values, aligned with the columns. Group rows hold aggregates. */
+    values: unknown[];
+    /** Which values to leave blank on screen-shaped output (grouped-by cells of leaf rows). */
+    blank: boolean[];
+    /** Index of the column showing a group row's label, and the label. */
+    labelAt?: number;
+    label?: string;
+    /** How many sheet rows directly follow this one as its descendants. */
+    descendants: number;
+    /** True when the row has child rows (a group, or a parent in tree data). */
+    hasChildren: boolean;
+    original: unknown;
+    style?: CellStyle;
+};
+export type Sheet = {
+    columns: SheetColumn[];
+    rows: SheetRow[];
+    /** Leading columns pinned left on screen. */
+    freezeColumns: number;
+};
+/** Read a TanStack table into a sheet. */
+export declare function readTable(table: TableLike, opts?: ReadOptions): Sheet;
+/** Text for one value, for CSV-free outputs (PDF). */
+export declare function displayText(column: SheetColumn, value: unknown, original: unknown): string;
+/** Alignment for a column: its own, else right when its values are numbers. */
+export declare function alignOf(column: SheetColumn, sheet: Sheet, index: number): 'left' | 'center' | 'right';
+export {};

package/dist/xlsx/index.d.ts

@@ -0,0 +1,17 @@
+import { type ReadOptions, type Sheet, type TableLike } from '../table-source';
+import { type XlsxModel } from './ooxml';
+export type XlsxExportOptions = ReadOptions & {
+    fileName?: string;
+    /** Worksheet name. Default 'Sheet1'. */
+    sheetName?: string;
+    /** Fill color of group rows. Default '#eef2f0'. */
+    groupFill?: string;
+    /** Save the file in the browser. Default true. */
+    download?: boolean;
+};
+/** The workbook model for a sheet. Pure: no zip, no license check. */
+export declare function sheetToXlsxModel(sheet: Sheet, opts?: XlsxExportOptions, notes?: string[]): XlsxModel;
+/** The workbook model for a table. Pure apart from reading the table. */
+export declare function tableToXlsxModel(table: TableLike, opts?: XlsxExportOptions, notes?: string[]): XlsxModel;
+/** Export the table to an .xlsx file. Returns the file as a Blob. */
+export declare function exportXlsx(table: TableLike, opts?: XlsxExportOptions): Promise<Blob>;

package/dist/xlsx/ooxml.d.ts

@@ -0,0 +1,115 @@
+/**
+ * Native OOXML (.xlsx) writer. Builds a real workbook from scratch
+ * (styles.xml + sheet.xml, zipped with jszip) with, in one file:
+ *   - typed number / date cells with a number format (Excel sums + sorts them),
+ *   - per-cell fills / font color / bold (conditional formatting),
+ *   - a frozen header (and optional frozen columns),
+ *   - explicit column widths,
+ *   - outline rows (row groups Excel can collapse) and formula cells,
+ *   - real cell hyperlinks.
+ *
+ * It's split into a pure `buildXlsxParts` (returns the XML parts - fully unit
+ * testable) and `packageXlsx` (zips them into a Blob via a provided JSZip).
+ */
+/** One worksheet cell, already resolved by the caller. */
+export type XlsxCell = {
+    /** 'n' number, 'd' date, 's' string, 'b' boolean. */
+    t: 'n' | 'd' | 's' | 'b';
+    value: number | string | boolean | Date | null | undefined;
+    /**
+     * A formula without the leading '=', e.g. `SUBTOTAL(9,C3:C9)`. `value` is
+     * written as its cached result, so viewers that do not recalculate still
+     * show the number.
+     */
+    formula?: string;
+    /** Excel number-format code (for 'n' / 'd'). */
+    numFmt?: string;
+    align?: 'left' | 'center' | 'right';
+    /** Background fill hex (e.g. '#fee2e2'). */
+    fill?: string;
+    /** Font color hex. */
+    color?: string;
+    bold?: boolean;
+    /** Hyperlink URL. */
+    link?: string;
+};
+/**
+ * A native Excel Table (ListObject) over the data: filter dropdowns, banded
+ * rows, structured references, and (optionally) a totals row with SUBTOTAL
+ * formulas per numeric column.
+ */
+export type XlsxTableSpec = {
+    /** Table name (no spaces; must start with a letter). E.g. 'Table1'. */
+    name: string;
+    /** Add a totals row. */
+    totalsRow: boolean;
+    /** Table style id (default 'TableStyleMedium2'). */
+    style?: string;
+    /** Per-column totals function, aligned with `header`. */
+    totalsFns: ReadonlyArray<'sum' | 'average' | 'count' | undefined>;
+};
+/**
+ * Native Excel conditional formatting over a whole column's data range - a
+ * data bar or a 2/3-stop color scale. Unlike per-cell fills, Excel computes
+ * these itself (and recomputes when the user edits), so they're interactive
+ * and higher fidelity.
+ */
+export type XlsxCondFormat = {
+    kind: 'dataBar';
+    colIdx: number;
+    color: string;
+} | {
+    kind: 'colorScale';
+    colIdx: number;
+    colors: ReadonlyArray<string>;
+};
+export type XlsxModel = {
+    sheetName: string;
+    /** Header labels (row 1). */
+    header: ReadonlyArray<string>;
+    /** Data rows (each an array of cells, column-aligned with `header`). */
+    rows: ReadonlyArray<ReadonlyArray<XlsxCell>>;
+    /** Per-column widths in pixels (optional). */
+    widths?: ReadonlyArray<number>;
+    /** Freeze the header row. */
+    freezeHeader?: boolean;
+    /** Freeze this many leading columns. */
+    freezeColumns?: number;
+    /** Native column conditional formatting (data bars / color scales). */
+    condFormats?: ReadonlyArray<XlsxCondFormat>;
+    /** Wrap the data in a native Excel Table. */
+    table?: XlsxTableSpec;
+    /**
+     * Outline level per data row (0 = top level), aligned with `rows`. Rows
+     * with a level above 0 form groups Excel can collapse; the summary row sits
+     * above its detail rows, as on screen.
+     */
+    outline?: ReadonlyArray<number>;
+    /** Plain text lines written below the data, after one empty row. */
+    notes?: ReadonlyArray<string>;
+};
+/** 0-based column index -> Excel letter (0 -> A, 26 -> AA). */
+export declare function colName(index: number): string;
+/**
+ * Excel serial date: days since 1899-12-30 on the LOCAL wall clock.
+ *
+ * An Excel serial has no timezone; it is the date and time a person reads. So
+ * it has to be built from the local parts the grid displays. Subtracting a UTC
+ * epoch from `getTime()` wrote local midnight on the 15th as 45305.9167 in
+ * UTC+2, which Excel shows as the 14th, and west of UTC added a spurious time
+ * to every pure date (#103).
+ */
+export declare function toSerialDate(d: Date): number;
+/**
+ * Build the OOXML package parts for a single-sheet workbook. Returns a map of
+ * `path -> xml string` ready to be zipped by {@link packageXlsx}.
+ */
+export declare function buildXlsxParts(model: XlsxModel): Record<string, string>;
+/** Zip the parts into an xlsx Blob using a provided JSZip constructor. */
+export declare function packageXlsx(parts: Record<string, string>, JSZip: new () => {
+    file(path: string, data: string): void;
+    generateAsync(opts: {
+        type: 'blob';
+        mimeType?: string;
+    }): Promise<Blob>;
+}): Promise<Blob>;

package/package.json

@@ -1,6 +1,65 @@
 {
   "name": "rowpine",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "description": "Pivot tables and Excel and PDF export for TanStack Table and shadcn/ui data tables.",
+  "keywords": [
+    "tanstack",
+    "tanstack-table",
+    "react-table",
+    "shadcn",
+    "pivot",
+    "pivot-table",
+    "excel",
+    "xlsx",
+    "pdf",
+    "export",
+    "data-table"
+  ],
+  "homepage": "https://rowpine.com/",
+  "bugs": {
+    "url": "https://github.com/rowpine/rowpine/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rowpine/rowpine.git"
+  },
+  "license": "SEE LICENSE IN LICENSE.md",
+  "author": "Rowpine",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "LICENSE.md",
+    "README.md"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsup && tsc -p tsconfig.build.json",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@noble/ed25519": "^3.2.0",
+    "jszip": "^3.10.2",
+    "pdfmake": "^0.3.14"
+  },
+  "devDependencies": {
+    "@tanstack/table-core": "^9.3.1",
+    "@types/node": "^26.6.6",
+    "table-core-v8": "npm:@tanstack/table-core@^8.21.3",
+    "tsup": "^9.0.0",
+    "typescript": "^7.0.2",
+    "vitest": "^5.1.0"
+  }
+}