rowpine 0.0.0-stage → 1.0.0

package/dist/pdf/doc.d.ts

@@ -0,0 +1,357 @@
+/**
+ * PDF document builder on pdfmake: page size / orientation / margins, a
+ * repeated header row on every page, "Page X of Y" + date footer, per-column
+ * alignment and widths, group and subtotal rows, an optional title /
+ * subtitle / logo, and header and zebra colors.
+ *
+ * `buildPdfDocDefinition` is a pure function (no pdfmake, no DOM) returning
+ * the docDefinition object; `exportPdf` (./index) feeds it to pdfmake.
+ */
+export type PdfPageSize = 'A4' | 'A3' | 'A5' | 'LETTER' | 'LEGAL';
+/** The font files pdfmake reads, by name, as base64. */
+export type PdfVirtualFileSystem = Record<string, string>;
+/**
+ * The font map inside whatever `import('pdfmake/build/vfs_fonts')` returned.
+ *
+ * The file has changed shape across pdfmake releases and bundlers wrap it
+ * once more: `{ pdfMake: { vfs } }` (0.1.x), `{ vfs }`, either of those under
+ * `default`, and since 0.2.8 the module IS the map (`module.exports = vfs`,
+ * so an ESM interop hands it over as `default` with the `.ttf` names as
+ * keys). Only the last shape ships today, and it is the one the old lookup
+ * did not recognise, which left registration to a side effect of import
+ * order (see {@link registerPdfFonts}). Returns `null` when nothing in the
+ * module looks like a font map.
+ */
+export declare function resolvePdfVfs(mod: unknown): PdfVirtualFileSystem | null;
+/** The parts of pdfmake's browser API that font registration touches. */
+export type PdfMakeLike = {
+    vfs?: PdfVirtualFileSystem;
+    addVirtualFileSystem?: (vfs: PdfVirtualFileSystem) => void;
+};
+/**
+ * Hand the fonts to the pdfmake instance that will create the document,
+ * explicitly. `vfs_fonts` registers itself only as a side effect: at import
+ * time it looks for a global `pdfMake` with `addVirtualFileSystem` and calls
+ * it. Under a bundler that global is whichever instance happened to load
+ * first, and when a dev server re-optimises its dependencies mid-session
+ * that is a stale one, so the instance doing the export has no fonts and
+ * `createPdf` fails with "File 'Roboto-Medium.ttf' not found in virtual
+ * file system". Registering here, on the instance in hand, removes the
+ * dependence on import order: `addVirtualFileSystem` where the version has
+ * it (0.2.x, where `createPdf` reads that before the `vfs` property) and the
+ * `vfs` property as well, which older versions read. Returns whether a map
+ * was found to register.
+ */
+/**
+ * The PDF as a Blob from either pdfmake line. 0.2 hands it to a callback; 0.3
+ * made `getBlob` async and never calls one, so waiting on the callback alone
+ * hung every export once pnpm or yarn installed 0.3 for `pnpm add pdfmake`.
+ */
+export declare function pdfBlob(doc: {
+    getBlob(cb?: (b: Blob) => void): unknown;
+}): Promise<Blob>;
+export declare function registerPdfFonts(pdfMake: PdfMakeLike, vfsModule: unknown): boolean;
+export type PdfExportOptions = {
+    pageSize?: PdfPageSize;
+    pageOrientation?: 'portrait' | 'landscape';
+    /** [left, top, right, bottom] in pt. Default [28, 34, 28, 34]. */
+    margins?: [number, number, number, number];
+    /** Document title rendered above the table. */
+    title?: string;
+    /** Smaller line under the title. */
+    subtitle?: string;
+    /** Logo as a data URL, rendered top-left above the title. */
+    logo?: string;
+    /** Logo width in pt (height auto). Default 90. */
+    logoWidth?: number;
+    /** Base font size in pt. Default 8. */
+    fontSize?: number;
+    /** Header row fill color. Default '#334155'. */
+    headerColor?: string;
+    /** Header row text color. Default '#ffffff'. */
+    headerTextColor?: string;
+    /** Zebra-stripe alternate rows. Default true. */
+    zebra?: boolean;
+    /** Zebra fill color. Default '#f1f5f9'. */
+    zebraColor?: string;
+    /** Repeat the header row on every page. Default true. */
+    repeatHeader?: boolean;
+    /** Show the "Page X of Y" + date footer. Default true. */
+    showPageNumbers?: boolean;
+    /**
+     * Column widths: '*' (fill, default), 'auto', or an explicit array of
+     * pt numbers / 'auto' / '*' per column.
+     */
+    columnWidths?: '*' | 'auto' | Array<number | 'auto' | '*'>;
+    /** Switch to landscape automatically when column count exceeds this (and no
+     *  explicit orientation was set). Default 8. */
+    autoLandscapeThreshold?: number;
+    /** Group header row fill color. Default '#e2e8f0'. */
+    groupColor?: string;
+    /** Group header row text color. Default '#0f172a'. */
+    groupTextColor?: string;
+    /** Subtotal row fill color. Default '#f8fafc'. */
+    subtotalColor?: string;
+    /**
+     * Charts to print with the table, as image data URLs, each with an
+     * optional title and caption. Printed at the content width unless `width`
+     * (pt) says otherwise.
+     */
+    charts?: ReadonlyArray<PdfChartImage>;
+    /** Where the charts go: above the table (default) or below it. */
+    chartsPosition?: 'above' | 'below';
+    /**
+     * A strip of headline numbers above the table: a label, the value, and an
+     * optional delta line in its own colour ("+4.2%" in green).
+     */
+    kpis?: ReadonlyArray<PdfKpi>;
+    /** KPI box fill. Default '#f8fafc'. */
+    kpiColor?: string;
+    /** Body text colour. Default black. */
+    textColor?: string;
+    /** Table line colour. Default '#e2e8f0'. */
+    borderColor?: string;
+    /**
+     * What to do when the columns do not fit across the page.
+     * - `'auto'` (default): shrink the table text, down to three quarters of
+     *   `fontSize`; past that, split the columns over several pages.
+     * - `'shrink'`: only shrink, down to 4 pt.
+     * - `'split'`: only split.
+     * - `'none'`: leave it to pdfmake, which lets a wide table run off the page.
+     */
+    fit?: 'auto' | 'shrink' | 'split' | 'none';
+    /** When the columns are split over pages, how many leading columns repeat on every page. Default 1. */
+    repeatColumns?: number;
+    /** A grouped export ends with a total row over every row. Default true. */
+    grandTotal?: boolean;
+    /**
+     * The words the PDF prints itself, for another language or house style:
+     * the page footer, the footer date, a group's subtotal label, and the total
+     * row's label.
+     */
+    labels?: {
+        page?: (page: number, pages: number) => string;
+        date?: (now: Date) => string;
+        subtotal?: (group: string) => string;
+        total?: string;
+    };
+    /** Text printed large and faint across every page: "DRAFT", "CONFIDENTIAL". */
+    watermark?: string | {
+        text: string;
+        color?: string;
+        opacity?: number;
+    };
+    /** Author recorded in the PDF's document properties. */
+    author?: string;
+    /**
+     * A font to print with instead of Roboto, which has no Chinese, Japanese,
+     * Korean, Arabic, Hebrew, Thai or Indic characters (they print as empty
+     * boxes). Each file is the font's base64 data or a URL pdfmake can fetch.
+     * It must cover Latin too: the whole document uses it.
+     */
+    font?: PdfFont;
+};
+/** A TrueType / OpenType font for the PDF. Missing styles fall back to `normal`. */
+export type PdfFont = {
+    name: string;
+    normal: string;
+    bold?: string;
+    italics?: string;
+    bolditalics?: string;
+};
+/**
+ * Register `font` with pdfmake next to Roboto. Base64 files go into the
+ * virtual file system, merged with what is there (`addVirtualFileSystem`
+ * replaces the map rather than adding to it); URLs are passed through for
+ * pdfmake to fetch.
+ */
+export declare function registerPdfFont(pdfMake: PdfMakeLike & {
+    fonts?: Record<string, unknown>;
+    addFonts?: (fonts: Record<string, unknown>) => void;
+}, font: PdfFont): void;
+/**
+ * Text Roboto has no glyphs for: CJK, Hangul, Arabic, Hebrew, Thai, the Indic
+ * scripts, dingbats (check marks, stars) and emoji. Exported so an export can
+ * warn that it needs `pdf.font`.
+ */
+export declare const PDF_ROBOTO_MISSING: RegExp;
+/** One cell's look, the same keys `ExportCellStyle` has. */
+export type PdfCellStyle = {
+    color?: string;
+    backgroundColor?: string;
+    fontWeight?: 'normal' | 'bold' | number;
+    fontStyle?: 'normal' | 'italic';
+    fontSize?: number | string;
+    textAlign?: 'left' | 'right' | 'center';
+};
+/** Blanket styles for the PDF table: what `ExportOptions.styles` carries. */
+export type PdfStyles = {
+    headerRow?: PdfCellStyle;
+    rows?: PdfCellStyle;
+    rowAlternate?: PdfCellStyle;
+    /** Per-cell overrides by Excel-style reference: `A1` is the first header cell, `A2` the first data cell. */
+    cells?: Record<string, PdfCellStyle>;
+};
+/** A line above or below the table: what `ExportOptions.header` / `footer` carry. */
+export type PdfPageLine = {
+    text: string;
+    style?: PdfCellStyle;
+} | {
+    image: string;
+    width?: number;
+    height?: number;
+} | {
+    left?: string;
+    center?: string;
+    right?: string;
+};
+/** A merged block of data cells, zero-based within the data rows. */
+export type PdfMerge = {
+    row: number;
+    col: number;
+    rowSpan?: number;
+    colSpan?: number;
+};
+/** A color theme for the PDF table; explicit options and `styles` win over it. */
+export type PdfTheme = Partial<Pick<PdfExportOptions, 'headerColor' | 'headerTextColor' | 'textColor' | 'zebraColor' | 'borderColor' | 'groupColor' | 'groupTextColor' | 'subtotalColor'>>;
+/** `rgb(...)` / `rgba(...)` / `#hex` -> `#rrggbb`, or null for transparent and anything else. */
+export declare function cssColorToHex(value: string | null | undefined): string | null;
+/** Relative luminance of a `#rrggbb`, 0 (black) to 1 (white). */
+export declare function hexLuminance(hex: string): number;
+/** One box of the KPI strip. */
+export type PdfKpi = {
+    label: string;
+    value: string;
+    /** A second line under the value: a change, a target, a period. */
+    delta?: string;
+    /** Colour of the delta line. Default '#64748b'. */
+    color?: string;
+};
+/** A chart whose image is ready: what `buildPdfDocDefinition` consumes. */
+export type PdfChartImage = {
+    image: string;
+    title?: string;
+    caption?: string;
+    width?: number;
+};
+/**
+ * A body row for the PDF table. `data` is a normal row; `group` is a bold,
+ * full-width group header (from grid grouping); `subtotal` is a per-group
+ * summary row (bold, aligned like the data).
+ */
+export type PdfBodyRow = {
+    kind: 'data';
+    cells: ReadonlyArray<string>; /** The row's index in the exported rows. */
+    source?: number;
+} | {
+    kind: 'group';
+    label: string;
+    level?: number;
+} | {
+    kind: 'subtotal';
+    cells: ReadonlyArray<string>;
+};
+/** A table's look, as data; {@link hydratePdfDoc} turns it into pdfmake's layout callbacks. */
+export type PdfLayoutSpec = {
+    kind: 'table';
+    stripes: number[];
+    zebraColor: string;
+    lineColor: string;
+} | {
+    kind: 'kpi';
+};
+/** The document as plain data, safe to post to a worker. */
+export type PdfDocData = {
+    pageSize: PdfPageSize;
+    pageOrientation: 'portrait' | 'landscape';
+    pageMargins: [number, number, number, number];
+    defaultStyle: {
+        fontSize: number;
+        font?: string;
+    };
+    content: unknown[];
+    watermark?: {
+        text: string;
+        color: string;
+        opacity: number;
+        bold: boolean;
+    };
+    /** The PDF's document properties, which a viewer shows in place of the file name. */
+    info?: {
+        title?: string;
+        author?: string;
+        subject?: string;
+        creator: string;
+        creationDate: Date;
+    };
+    /** The footer, as data: margins, the date text, and a page template with `{page}` / `{pages}`. */
+    rpFooter?: {
+        margin: number[];
+        date: string;
+        page: string;
+    };
+};
+/** The document pdfmake renders: the data with its layouts and footer as functions. */
+export type PdfDocDefinition = PdfDocData & {
+    footer?: (currentPage: number, pageCount: number) => unknown;
+};
+/** What the PDF table is built from. `now` is injected for a deterministic footer date in tests. */
+export type PdfDocParams = {
+    columns: ReadonlyArray<{
+        header: string;
+        align?: 'left' | 'center' | 'right';
+    }>;
+    /** Data rows as pre-formatted strings, in column order (no header row).
+     *  Convenience for the flat (ungrouped) case. */
+    rows?: ReadonlyArray<ReadonlyArray<string>>;
+    /** Structured body with group headers + subtotals. Takes precedence over
+     *  `rows` when provided (used for grouped exports). */
+    body?: ReadonlyArray<PdfBodyRow>;
+    /** Per-data-cell visual override (conditional formatting). `dataRowIdx` is
+     *  the 0-based index among data rows. */
+    dataCellStyle?: (dataRowIdx: number, colIdx: number) => {
+        fill?: string;
+        color?: string;
+        bold?: boolean;
+        icon?: string;
+        iconOnly?: boolean;
+    } | undefined;
+    /** Per-data-cell hyperlink URL. */
+    dataCellLink?: (dataRowIdx: number, colIdx: number) => string | undefined;
+    opts?: PdfExportOptions;
+    /** Chart images; take precedence over `opts.charts`. */
+    charts?: ReadonlyArray<PdfChartImage>;
+    /** Blanket header / row / zebra / per-cell styles. */
+    styles?: PdfStyles;
+    /** A color theme; `opts` and `styles` win over it. */
+    theme?: PdfTheme;
+    /** Lines printed above the table (`ExportOptions.header`). */
+    headerLines?: ReadonlyArray<PdfPageLine>;
+    /** Lines printed below the table (`ExportOptions.footer`). */
+    footerLines?: ReadonlyArray<PdfPageLine>;
+    /** Merged data cells; ignored with a structured `body`, whose rows own the layout. */
+    merges?: ReadonlyArray<PdfMerge>;
+    now?: Date;
+};
+/**
+ * Build the pdfmake document from resolved columns + formatted string rows,
+ * as plain data: no functions, so it can be posted to a worker. Hand it to
+ * {@link hydratePdfDoc} before pdfmake sees it, or use
+ * {@link buildPdfDocDefinition}, which does both.
+ */
+export declare function buildPdfDocData(params: PdfDocParams): PdfDocData;
+/**
+ * Build the pdfmake document for a table and hand it over ready to render.
+ * Same as {@link buildPdfDocData}, with its layouts and footer turned into
+ * the functions pdfmake calls.
+ */
+export declare function buildPdfDocDefinition(params: PdfDocParams): PdfDocDefinition;
+/**
+ * Give a document from {@link buildPdfDocData} the functions pdfmake calls:
+ * each table's fill and line callbacks and the page footer. Runs where the
+ * PDF is rendered, which may be a worker the functions could not be sent to.
+ * `page` overrides the footer's page template with the caller's own function.
+ */
+export declare function hydratePdfDoc(doc: PdfDocData, opts?: {
+    page?: (page: number, pages: number) => string;
+}): PdfDocDefinition;

package/dist/pdf/index.d.ts

@@ -0,0 +1,11 @@
+import { type ReadOptions, type Sheet, type TableLike } from '../table-source';
+import { type PdfDocParams, type PdfExportOptions } from './doc';
+export type PdfTableExportOptions = ReadOptions & PdfExportOptions & {
+    fileName?: string;
+    /** Save the file in the browser. Default true. */
+    download?: boolean;
+};
+/** The pdfmake document parameters for a sheet. Pure. */
+export declare function sheetToPdfParams(sheet: Sheet, opts?: PdfTableExportOptions, notes?: string[], now?: Date): PdfDocParams;
+/** Export the table to a PDF file. Returns the file as a Blob. */
+export declare function exportPdf(table: TableLike, opts?: PdfTableExportOptions): Promise<Blob>;

package/dist/pivot/designer.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Pivot designer state: the four wells (rows, columns, values, filters), the
+ * rules for moving fields between them, filters, totals switches and presets.
+ *
+ * Every operation is a pure function from one layout to the next, so any UI
+ * (the shadcn `PivotDesigner`, a custom one, a saved-view store) can drive it
+ * and persist the layout as plain JSON.
+ */
+import { type PivotTable, type ToColumnsOptions } from './tanstack';
+import type { PivotAggregatorId, PivotConfig } from './pivot';
+/** One field the designer offers. Dimensions land in Rows by default; measures in Values. */
+export type PivotField<T = Record<string, unknown>> = {
+    field: keyof T & string;
+    /** Name shown in the field list and on chips. */
+    label: string;
+    kind: 'dimension' | 'measure';
+    /** Optional group heading in the field list, e.g. 'Customer'. */
+    group?: string;
+    /** Display text for this field's values when it is a measure. */
+    format?: (value: unknown) => string;
+    /** Aggregation used when the field is added to Values. Default 'sum' for measures. */
+    defaultAgg?: PivotAggregatorId;
+};
+/** A chip in the Values well. */
+export type PivotValueChip = {
+    field: string;
+    agg: PivotAggregatorId;
+    label?: string;
+};
+/** A chip in the Filters well. `allowed: null` lets every value through. */
+export type PivotFilterChip = {
+    field: string;
+    allowed: string[] | null;
+};
+/** The whole designer state, as plain JSON. */
+export type PivotLayout = {
+    rows: string[];
+    cols: string[];
+    values: PivotValueChip[];
+    filters: PivotFilterChip[];
+    /** Hide subtotal rows between groups. */
+    hideSubtotals?: boolean;
+    /** Hide the grand-total row and column. */
+    hideGrandTotals?: boolean;
+};
+/** A saved layout offered in the designer's Presets menu. */
+export type PivotPreset = {
+    name: string;
+    layout: PivotLayout;
+};
+export type Well = 'rows' | 'cols' | 'values' | 'filters';
+export declare const WELL_LABEL: Record<Well, string>;
+/** Which wells each kind of field may go to. */
+export declare const KIND_WELLS: Record<PivotField['kind'], Well[]>;
+export declare const ALL_AGGREGATORS: PivotAggregatorId[];
+export declare const AGG_LABEL: Record<PivotAggregatorId, string>;
+export declare const EMPTY_LAYOUT: PivotLayout;
+/** First dimension in Rows, first measure in Values. */
+export declare function defaultLayoutFor<T>(fields: ReadonlyArray<PivotField<T>>): PivotLayout;
+/** The well a field goes to when added without one. */
+export declare function defaultWellFor(field: Pick<PivotField, 'kind'>): Well;
+export declare function isFieldInLayout(layout: PivotLayout, field: string): boolean;
+/**
+ * Add a field to a well at `index` (default: the end). In Rows, Columns and
+ * Filters a field appears at most once, so adding it moves it. In Values the
+ * same field may appear with different aggregations (sum and average of one
+ * amount), but not twice with the same one. `sourceIndex` is the chip's
+ * position in Values when it is being moved out of that well.
+ */
+export declare function addToWell<T>(layout: PivotLayout, fields: ReadonlyArray<PivotField<T>>, field: string, well: Well, index?: number, sourceIndex?: number): PivotLayout;
+/** Remove a field from a well. In Values, `valueIndex` picks the one chip. */
+export declare function removeFromWell(layout: PivotLayout, field: string, well: Well, valueIndex?: number): PivotLayout;
+/** Field-list checkbox: take the field out of every well, or add it to its default well. */
+export declare function toggleField<T>(layout: PivotLayout, fields: ReadonlyArray<PivotField<T>>, field: string): PivotLayout;
+/** Change a value chip's aggregation. A change that would duplicate another chip removes this one. */
+export declare function setAggregatorAt<T>(layout: PivotLayout, fields: ReadonlyArray<PivotField<T>>, index: number, agg: PivotAggregatorId): PivotLayout;
+/** Set which values of a filter field pass. `null` lets everything through. */
+export declare function setFilterAllowed(layout: PivotLayout, field: string, allowed: string[] | null): PivotLayout;
+export declare function clearWell(layout: PivotLayout, well: Well): PivotLayout;
+/** Every distinct value of a field in the full data, as text, sorted. */
+export declare function distinctValues<T>(data: ReadonlyArray<T>, field: string): string[];
+/** The rows that pass the layout's filters. */
+export declare function applyLayoutFilters<T>(data: ReadonlyArray<T>, layout: PivotLayout): T[];
+/** The engine config for a layout. */
+export declare function layoutToConfig<T>(layout: PivotLayout, fields: ReadonlyArray<PivotField<T>>): PivotConfig<T>;
+/**
+ * Filter, pivot and label in one step. Returns null when the layout has no
+ * values yet, which a UI shows as an empty state.
+ */
+export declare function pivotFromLayout<T>(data: ReadonlyArray<T>, layout: PivotLayout, fields: ReadonlyArray<PivotField<T>>, opts?: ToColumnsOptions): PivotTable | null;

package/dist/pivot/extent.d.ts

@@ -0,0 +1,7 @@
+/**
+ * The smallest and largest of a list of any length. `Math.max(...values)` passes
+ * each value as an argument and throws a RangeError past about 120,000 of them.
+ * Like `Math.max`: an empty list gives the start value, and a NaN gives NaN.
+ */
+export declare function maxOf(values: Iterable<number>, start?: number): number;
+export declare function minOf(values: Iterable<number>, start?: number): number;

package/dist/pivot/pivot.d.ts

@@ -0,0 +1,106 @@
+/** Built-in pivot measures, named in {@link PivotValueConfig}. */
+export type PivotAggregatorId = 'sum' | 'avg' | 'min' | 'max' | 'count' | 'countDistinct' | 'first' | 'last';
+/** A custom measure: reduce the values under one cell to the number to display. */
+export type PivotAggregator = (values: ReadonlyArray<unknown>) => unknown;
+/** One measure: the field to aggregate and how to aggregate it. */
+export type PivotValueConfig<TData> = {
+    /** Row field whose values get aggregated. */
+    field: keyof TData & string;
+    /** Built-in aggregator id, or a custom reducer. */
+    agg: PivotAggregatorId | PivotAggregator;
+    /** Display name in the column header. Defaults to `${field} (${agg})`. */
+    label?: string;
+    /** Turns a value cell into display text. Default: numbers with grouping separators. */
+    format?: (value: unknown) => string;
+};
+/** A pivot definition: the row axis, the column axis, and the measures at their intersections. */
+export type PivotConfig<TData> = {
+    /** Outer-most first. Each entry becomes one level of row grouping. */
+    rows: ReadonlyArray<keyof TData & string>;
+    /** Outer-most first. Each entry becomes one level of column grouping. */
+    cols: ReadonlyArray<keyof TData & string>;
+    /** One or more measures aggregated under each column-axis leaf. */
+    values: ReadonlyArray<PivotValueConfig<TData>>;
+    /** Grand-total row at the bottom. Default `true`. */
+    grandTotalRow?: boolean;
+    /** Grand-total column on the right. Default `true`. */
+    grandTotalCol?: boolean;
+    /** Subtotal rows between row groups. Default `true`. */
+    rowSubtotals?: boolean;
+    /** Optional sort for column-axis values per dim level (defaults to alpha). */
+    colSort?: (a: unknown, b: unknown, level: number) => number;
+    /** Optional sort for row-axis values per dim level (defaults to alpha). */
+    rowSort?: (a: unknown, b: unknown, level: number) => number;
+};
+/** What a pivot row represents - a group header, a subtotal, a leaf, or the grand total. */
+export type PivotRowKind = 'group' | 'subtotal' | 'leaf' | 'grandTotal';
+/**
+ * Shape of one entry in `result.rows`. The first-column label lives at
+ * `__pivotLabel`; every value cell lives at the column id matching the
+ * leaf column generated for its (col-path × measure).
+ *
+ * `__pivotParentId` is the `__pivotId` of the row's row-axis parent
+ * (or `null` for top-level groups, the grand-total row, and the one
+ * synthetic "All" row when no row dims are configured). Use it with
+ * `filterCollapsedPivotRows` to hide leaves whose ancestor is
+ * collapsed - that's how expandable pivots are built on top of the
+ * model.
+ *
+ * `__pivotExpandable` is `true` for `group` rows that have at least
+ * one descendant. A renderer uses this to decide whether to show a
+ * chevron next to the label.
+ */
+export type PivotRow = {
+    __pivotId: string;
+    __pivotKind: PivotRowKind;
+    __pivotDepth: number;
+    __pivotLabel: string;
+    __pivotParentId: string | null;
+    __pivotExpandable: boolean;
+    /** Aggregated value cells - keyed by leaf column id. */
+    [columnId: string]: unknown;
+};
+/** One generated column. A leaf has a `measure`; a header group has `columns`. */
+export type PivotColumn = {
+    id: string;
+    header: string;
+    /** Child columns, for a column-axis header group. */
+    columns?: PivotColumn[];
+    /** Index into `config.values`, for a value leaf. */
+    measure?: number;
+    /** The measure's formatter, for a value leaf. */
+    format?: (value: unknown) => string;
+    /** Suggested width in px. */
+    width?: number;
+    /** True for the first column, which holds each row's label. */
+    isRowHeader?: boolean;
+    /** True for the grand-total column group and its leaves. */
+    isTotal?: boolean;
+};
+/** A built pivot: the rows to display, and the generated columns for its column axis. */
+export type PivotResult = {
+    rows: PivotRow[];
+    columns: PivotColumn[];
+};
+/**
+ * Build a pivot table from flat rows: cross the row axis with the column axis,
+ * aggregate each intersection, and return rows plus the generated column tree.
+ */
+export declare function createPivotModel<TData>(data: ReadonlyArray<TData>, config: PivotConfig<TData>): PivotResult;
+/**
+ * Public registry of built-in aggregators. Useful for surfacing the
+ * available options in a pivot designer UI.
+ */
+export declare const pivotAggregators: Record<PivotAggregatorId, PivotAggregator>;
+/**
+ * Filter a `result.rows` array down to only the rows the user should
+ * see given the current expansion state. A row stays in the output if
+ * its entire ancestor chain (via `__pivotParentId`) is in `expandedIds`.
+ *
+ * Pass `true` to bypass filtering (everything visible - the default
+ * shape `createPivotModel` already returns). Pass an empty array /
+ * empty Set to collapse every group to its subtotal row.
+ *
+ * The result is a new array; the input is not mutated.
+ */
+export declare function filterCollapsedPivotRows(rows: ReadonlyArray<PivotRow>, expandedIds: ReadonlyArray<string> | Set<string> | true): PivotRow[];

package/dist/pivot/tanstack.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Pivot results in TanStack Table's shape: rows nested through `subRows`
+ * (so `getSubRows` and the expanded model collapse groups), and column
+ * definitions with plain accessor functions.
+ */
+import type { RowpineColumnMeta, TableLike } from '../table-source';
+import { type PivotColumn, type PivotConfig, type PivotRow } from './pivot';
+/** A pivot row with its children attached. */
+export type PivotTreeRow = PivotRow & {
+    subRows?: PivotTreeRow[];
+};
+/** Metadata on every generated column. */
+export type PivotColumnMeta = {
+    rowpine: RowpineColumnMeta<PivotTreeRow>;
+    pivot: {
+        isRowHeader: boolean;
+        isTotal: boolean;
+        measure?: number;
+    };
+};
+/** A generated column: an accessor leaf or a header group. Fits TanStack's `ColumnDef<PivotTreeRow>`. */
+export type PivotColumnDef = {
+    id: string;
+    header: string;
+    accessorFn: (row: PivotTreeRow) => unknown;
+    size?: number;
+    meta: PivotColumnMeta;
+} | {
+    id: string;
+    header: string;
+    columns: PivotColumnDef[];
+    meta: PivotColumnMeta;
+};
+/** Nest flat pivot rows under their parents. The grand-total row stays last. */
+export declare function pivotToTree(rows: ReadonlyArray<PivotRow>): PivotTreeRow[];
+export type ToColumnsOptions = {
+    /** Excel number format for every value column, e.g. `'#,##0.00'`. */
+    numFmt?: string;
+};
+/** Turn a pivot's column tree into TanStack column definitions. */
+export declare function toTanStackColumns(columns: ReadonlyArray<PivotColumn>, opts?: ToColumnsOptions): PivotColumnDef[];
+/** Bold group, subtotal and grand-total rows in exports. Pass as `rowStyle`. */
+export declare function pivotRowStyle(original: unknown): {
+    bold?: boolean;
+} | undefined;
+export type PivotTable = {
+    /** Rows for `useReactTable({ data })`, with `getSubRows: (r) => r.subRows`. */
+    data: PivotTreeRow[];
+    /** Columns for `useReactTable({ columns })`. */
+    columns: PivotColumnDef[];
+    /** The flat rows, as the engine produced them. */
+    rows: PivotRow[];
+    /** The pivot as a table the exporters read: `exportXlsx(pivot.table)`. */
+    table: TableLike;
+};
+/**
+ * A pivot as a read-only table for the exporters, with no TanStack instance
+ * behind it, so exporting a pivot works the same under any TanStack version.
+ */
+export declare function pivotAsTable(data: PivotTreeRow[], columns: PivotColumnDef[]): TableLike;
+/**
+ * Pivot `data` and return rows and columns ready for TanStack Table.
+ * Without a license key it still runs and logs a notice once.
+ */
+export declare function createPivot<TData>(data: ReadonlyArray<TData>, config: PivotConfig<TData>, opts?: ToColumnsOptions): PivotTable;