@particle-academy/holy-sheet 2.7.0 → 2.9.0

package/dist/index.d.cts

@@ -63,6 +63,8 @@ interface SheetSchema {
     print?: {
         orientation?: "portrait" | "landscape";
         fitToWidth?: boolean;
+        /** One page wide AND tall: a one-page summary with a chart prints whole. */
+        fitToPage?: boolean;
         /** `{page}` / `{pages}` print the page number and count. */
         footer?: {
             left?: string;
@@ -70,6 +72,33 @@ interface SheetSchema {
             right?: string;
         };
     };
+    /** Native charts drawn over cell ranges; they stay live when the cells change. */
+    charts?: ChartSchema[];
+}
+interface ChartSchema {
+    type: "column" | "bar" | "line" | "pie";
+    title?: string;
+    /** Axis labels, e.g. "A5:A7" or "'Other sheet'!A5:A7". */
+    categories?: string;
+    /** points colours single points (0-based within values) to make the finding stand out. */
+    series: {
+        name?: string;
+        values: string;
+        color?: string;
+        points?: {
+            index: number;
+            color: string;
+        }[];
+    }[];
+    /** Top-left and bottom-right cells; defaults to beside the data. */
+    position?: {
+        from: string;
+        to: string;
+    };
+    dataLabels?: boolean;
+    legend?: boolean;
+    /** Excel number format for the axis and labels, e.g. "$#,##0". */
+    format?: string;
 }
 interface HolySheetSchema {
     sheets: SheetSchema[];
@@ -235,7 +264,7 @@ interface SetMetaOp {
 }
 
 /** This package's own version, pinned to package.json by `version.test.ts`. */
-declare const VERSION = "2.7.0";
+declare const VERSION = "2.9.0";
 type Any$6 = any;
 /**
  * Agent — the structured-tool surface for Holy Sheet. Mirrors PHP `Agent`.
@@ -307,7 +336,7 @@ type Any$5 = any;
  * over `Agent`. Provided for parity / DI ergonomics; most callers use `Agent`.
  */
 declare class HolySheet {
-    static readonly VERSION = "2.7.0";
+    static readonly VERSION = "2.9.0";
     validate(schema: Any$5): ValidationError[];
     toBytes(schema: Any$5): Uint8Array;
     write(schema: Any$5, path: string): Promise<WriteResult>;
@@ -440,16 +469,66 @@ declare class MergedRegion {
     ref(): string;
 }
 
+/**
+ * A cell range a chart reads from. Mirrors PHP `Workbook\ChartRange`:
+ * "B5:B7", "B5", "'Q3 Revenue'!B5:B7" or "Data!B5:B7", resolved against the
+ * chart's own sheet when no sheet is named.
+ */
+declare class ChartRange {
+    readonly sheet: string;
+    /** 0-based first column. */
+    readonly c1: number;
+    /** 1-based first row. */
+    readonly r1: number;
+    readonly c2: number;
+    readonly r2: number;
+    constructor(sheet: string, 
+    /** 0-based first column. */
+    c1: number, 
+    /** 1-based first row. */
+    r1: number, c2: number, r2: number);
+    static parse(ref: unknown, defaultSheet: string): ChartRange | null;
+    /** 'Q3 Revenue'!$B$5:$B$7 */
+    formula(): string;
+    /** "B5:B7" on its own sheet, "'Data'!B5:B7" on another. */
+    toSchema(ownSheet: string): string;
+    /** A1 addresses, row by row. */
+    addresses(): string[];
+}
+
 /** How a sheet prints. Mirrors the PHP `Sheet::$print` array. */
 interface PrintSetup {
     orientation: "portrait" | "landscape" | null;
     fitToWidth: boolean;
+    /** One page wide AND tall. */
+    fitToPage: boolean;
     footer: {
         left: string;
         center: string;
         right: string;
     } | null;
 }
+/** A native chart, normalised. Mirrors the PHP `Sheet::$charts` entries. */
+interface NormalizedChart {
+    type: "column" | "bar" | "line" | "pie";
+    title: string | null;
+    categories: ChartRange | null;
+    series: {
+        name: string | null;
+        values: ChartRange;
+        color: string | null;
+        points: {
+            index: number;
+            color: string;
+        }[];
+    }[];
+    /** [col, row], both 0-based. */
+    from: [number, number];
+    to: [number, number];
+    legend: boolean | null;
+    dataLabels: boolean;
+    format: string | null;
+}
 /** A worksheet. Mirrors PHP `Workbook\Sheet`. Cells are an A1-keyed map. */
 declare class Sheet {
     readonly name: string;
@@ -461,9 +540,11 @@ declare class Sheet {
     /** 1-based row number → pixels. */
     readonly rowHeights: Map<number, number>;
     readonly print: PrintSetup | null;
+    readonly charts: NormalizedChart[];
     constructor(name: string, cells?: Map<string, Cell>, mergedRegions?: MergedRegion[], columnWidths?: Map<number, number>, frozenRows?: number, frozenCols?: number, 
     /** 1-based row number → pixels. */
-    rowHeights?: Map<number, number>, print?: PrintSetup | null);
+    rowHeights?: Map<number, number>, print?: PrintSetup | null, charts?: NormalizedChart[]);
+    withCharts(charts: NormalizedChart[]): Sheet;
     /** rowNumber → (colLetter → Cell), sorted by ascending row number. */
     rows(): Map<number, Map<string, Cell>>;
     hasComments(): boolean;
@@ -580,6 +661,7 @@ declare class XlsxWriter {
     private rootRelsXml;
     private workbookXml;
     private workbookRelsXml;
+    /** Comments keep rId1 (vml) and rId2 (comments); the chart drawing takes the next id. */
     private sheetRelsXml;
     private sheetXml;
     private cellXml;
@@ -823,4 +905,4 @@ declare function zipSync(files: ZipFile[]): Uint8Array;
 
 declare function unzipSync(data: Uint8Array): Record<string, Uint8Array>;
 
-export { type AddSheetOp, Agent, type AggOp, ArrayBuilder, type BuilderOptions, CellAddress, type CellData, type CellFormatInput, type CellPrimitive, type ClearCellOp, type ColumnSchema, type ColumnType, type CommentInput, CsvBuilder, type DeleteColumnsOp, type DeleteRowsOp, type DisplayFormat, FormatSniffer, FormulaLinter, type FormulaProblem, HolySheet, type HolySheetSchema, Inference, type InsertColumnsOp, type InsertRowsOp, type MoveSheetOp, Normalizer, OdsReader, type RemoveSheetOp, type RenameSheetOp, type RepairResult, Repairer, type ReplaceSheetOp, type RowCell, SchemaException, type SetCellOp, type SetColumnWidthsOp, type SetFrozenOp, type SetMergedRegionsOp, type SetMetaOp, type SetRangeOp, type SetWorkbookOp, SheetDiff, type SheetOp, SheetOpSchema, type SheetOpType, SheetReducer, type SheetSchema, type SpreadsheetFormat, Theme, type ThemeKey, UnsupportedFormatException, VERSION, type ValidationError, Validator, type WriteResult, XlsxReader, XlsxWriter, type ZipFile, unzipSync, zipSync };
+export { type AddSheetOp, Agent, type AggOp, ArrayBuilder, type BuilderOptions, CellAddress, type CellData, type CellFormatInput, type CellPrimitive, type ChartSchema, type ClearCellOp, type ColumnSchema, type ColumnType, type CommentInput, CsvBuilder, type DeleteColumnsOp, type DeleteRowsOp, type DisplayFormat, FormatSniffer, FormulaLinter, type FormulaProblem, HolySheet, type HolySheetSchema, Inference, type InsertColumnsOp, type InsertRowsOp, type MoveSheetOp, Normalizer, OdsReader, type RemoveSheetOp, type RenameSheetOp, type RepairResult, Repairer, type ReplaceSheetOp, type RowCell, SchemaException, type SetCellOp, type SetColumnWidthsOp, type SetFrozenOp, type SetMergedRegionsOp, type SetMetaOp, type SetRangeOp, type SetWorkbookOp, SheetDiff, type SheetOp, SheetOpSchema, type SheetOpType, SheetReducer, type SheetSchema, type SpreadsheetFormat, Theme, type ThemeKey, UnsupportedFormatException, VERSION, type ValidationError, Validator, type WriteResult, XlsxReader, XlsxWriter, type ZipFile, unzipSync, zipSync };

package/dist/index.d.ts

@@ -63,6 +63,8 @@ interface SheetSchema {
     print?: {
         orientation?: "portrait" | "landscape";
         fitToWidth?: boolean;
+        /** One page wide AND tall: a one-page summary with a chart prints whole. */
+        fitToPage?: boolean;
         /** `{page}` / `{pages}` print the page number and count. */
         footer?: {
             left?: string;
@@ -70,6 +72,33 @@ interface SheetSchema {
             right?: string;
         };
     };
+    /** Native charts drawn over cell ranges; they stay live when the cells change. */
+    charts?: ChartSchema[];
+}
+interface ChartSchema {
+    type: "column" | "bar" | "line" | "pie";
+    title?: string;
+    /** Axis labels, e.g. "A5:A7" or "'Other sheet'!A5:A7". */
+    categories?: string;
+    /** points colours single points (0-based within values) to make the finding stand out. */
+    series: {
+        name?: string;
+        values: string;
+        color?: string;
+        points?: {
+            index: number;
+            color: string;
+        }[];
+    }[];
+    /** Top-left and bottom-right cells; defaults to beside the data. */
+    position?: {
+        from: string;
+        to: string;
+    };
+    dataLabels?: boolean;
+    legend?: boolean;
+    /** Excel number format for the axis and labels, e.g. "$#,##0". */
+    format?: string;
 }
 interface HolySheetSchema {
     sheets: SheetSchema[];
@@ -235,7 +264,7 @@ interface SetMetaOp {
 }
 
 /** This package's own version, pinned to package.json by `version.test.ts`. */
-declare const VERSION = "2.7.0";
+declare const VERSION = "2.9.0";
 type Any$6 = any;
 /**
  * Agent — the structured-tool surface for Holy Sheet. Mirrors PHP `Agent`.
@@ -307,7 +336,7 @@ type Any$5 = any;
  * over `Agent`. Provided for parity / DI ergonomics; most callers use `Agent`.
  */
 declare class HolySheet {
-    static readonly VERSION = "2.7.0";
+    static readonly VERSION = "2.9.0";
     validate(schema: Any$5): ValidationError[];
     toBytes(schema: Any$5): Uint8Array;
     write(schema: Any$5, path: string): Promise<WriteResult>;
@@ -440,16 +469,66 @@ declare class MergedRegion {
     ref(): string;
 }
 
+/**
+ * A cell range a chart reads from. Mirrors PHP `Workbook\ChartRange`:
+ * "B5:B7", "B5", "'Q3 Revenue'!B5:B7" or "Data!B5:B7", resolved against the
+ * chart's own sheet when no sheet is named.
+ */
+declare class ChartRange {
+    readonly sheet: string;
+    /** 0-based first column. */
+    readonly c1: number;
+    /** 1-based first row. */
+    readonly r1: number;
+    readonly c2: number;
+    readonly r2: number;
+    constructor(sheet: string, 
+    /** 0-based first column. */
+    c1: number, 
+    /** 1-based first row. */
+    r1: number, c2: number, r2: number);
+    static parse(ref: unknown, defaultSheet: string): ChartRange | null;
+    /** 'Q3 Revenue'!$B$5:$B$7 */
+    formula(): string;
+    /** "B5:B7" on its own sheet, "'Data'!B5:B7" on another. */
+    toSchema(ownSheet: string): string;
+    /** A1 addresses, row by row. */
+    addresses(): string[];
+}
+
 /** How a sheet prints. Mirrors the PHP `Sheet::$print` array. */
 interface PrintSetup {
     orientation: "portrait" | "landscape" | null;
     fitToWidth: boolean;
+    /** One page wide AND tall. */
+    fitToPage: boolean;
     footer: {
         left: string;
         center: string;
         right: string;
     } | null;
 }
+/** A native chart, normalised. Mirrors the PHP `Sheet::$charts` entries. */
+interface NormalizedChart {
+    type: "column" | "bar" | "line" | "pie";
+    title: string | null;
+    categories: ChartRange | null;
+    series: {
+        name: string | null;
+        values: ChartRange;
+        color: string | null;
+        points: {
+            index: number;
+            color: string;
+        }[];
+    }[];
+    /** [col, row], both 0-based. */
+    from: [number, number];
+    to: [number, number];
+    legend: boolean | null;
+    dataLabels: boolean;
+    format: string | null;
+}
 /** A worksheet. Mirrors PHP `Workbook\Sheet`. Cells are an A1-keyed map. */
 declare class Sheet {
     readonly name: string;
@@ -461,9 +540,11 @@ declare class Sheet {
     /** 1-based row number → pixels. */
     readonly rowHeights: Map<number, number>;
     readonly print: PrintSetup | null;
+    readonly charts: NormalizedChart[];
     constructor(name: string, cells?: Map<string, Cell>, mergedRegions?: MergedRegion[], columnWidths?: Map<number, number>, frozenRows?: number, frozenCols?: number, 
     /** 1-based row number → pixels. */
-    rowHeights?: Map<number, number>, print?: PrintSetup | null);
+    rowHeights?: Map<number, number>, print?: PrintSetup | null, charts?: NormalizedChart[]);
+    withCharts(charts: NormalizedChart[]): Sheet;
     /** rowNumber → (colLetter → Cell), sorted by ascending row number. */
     rows(): Map<number, Map<string, Cell>>;
     hasComments(): boolean;
@@ -580,6 +661,7 @@ declare class XlsxWriter {
     private rootRelsXml;
     private workbookXml;
     private workbookRelsXml;
+    /** Comments keep rId1 (vml) and rId2 (comments); the chart drawing takes the next id. */
     private sheetRelsXml;
     private sheetXml;
     private cellXml;
@@ -823,4 +905,4 @@ declare function zipSync(files: ZipFile[]): Uint8Array;
 
 declare function unzipSync(data: Uint8Array): Record<string, Uint8Array>;
 
-export { type AddSheetOp, Agent, type AggOp, ArrayBuilder, type BuilderOptions, CellAddress, type CellData, type CellFormatInput, type CellPrimitive, type ClearCellOp, type ColumnSchema, type ColumnType, type CommentInput, CsvBuilder, type DeleteColumnsOp, type DeleteRowsOp, type DisplayFormat, FormatSniffer, FormulaLinter, type FormulaProblem, HolySheet, type HolySheetSchema, Inference, type InsertColumnsOp, type InsertRowsOp, type MoveSheetOp, Normalizer, OdsReader, type RemoveSheetOp, type RenameSheetOp, type RepairResult, Repairer, type ReplaceSheetOp, type RowCell, SchemaException, type SetCellOp, type SetColumnWidthsOp, type SetFrozenOp, type SetMergedRegionsOp, type SetMetaOp, type SetRangeOp, type SetWorkbookOp, SheetDiff, type SheetOp, SheetOpSchema, type SheetOpType, SheetReducer, type SheetSchema, type SpreadsheetFormat, Theme, type ThemeKey, UnsupportedFormatException, VERSION, type ValidationError, Validator, type WriteResult, XlsxReader, XlsxWriter, type ZipFile, unzipSync, zipSync };
+export { type AddSheetOp, Agent, type AggOp, ArrayBuilder, type BuilderOptions, CellAddress, type CellData, type CellFormatInput, type CellPrimitive, type ChartSchema, type ClearCellOp, type ColumnSchema, type ColumnType, type CommentInput, CsvBuilder, type DeleteColumnsOp, type DeleteRowsOp, type DisplayFormat, FormatSniffer, FormulaLinter, type FormulaProblem, HolySheet, type HolySheetSchema, Inference, type InsertColumnsOp, type InsertRowsOp, type MoveSheetOp, Normalizer, OdsReader, type RemoveSheetOp, type RenameSheetOp, type RepairResult, Repairer, type ReplaceSheetOp, type RowCell, SchemaException, type SetCellOp, type SetColumnWidthsOp, type SetFrozenOp, type SetMergedRegionsOp, type SetMetaOp, type SetRangeOp, type SetWorkbookOp, SheetDiff, type SheetOp, SheetOpSchema, type SheetOpType, SheetReducer, type SheetSchema, type SpreadsheetFormat, Theme, type ThemeKey, UnsupportedFormatException, VERSION, type ValidationError, Validator, type WriteResult, XlsxReader, XlsxWriter, type ZipFile, unzipSync, zipSync };