@particle-academy/holy-sheet 2.8.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;
@@ -78,10 +80,15 @@ interface ChartSchema {
     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?: {
@@ -257,7 +264,7 @@ interface SetMetaOp {
 }
 
 /** This package's own version, pinned to package.json by `version.test.ts`. */
-declare const VERSION = "2.8.0";
+declare const VERSION = "2.9.0";
 type Any$6 = any;
 /**
  * Agent — the structured-tool surface for Holy Sheet. Mirrors PHP `Agent`.
@@ -329,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.8.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>;
@@ -493,6 +500,8 @@ declare class ChartRange {
 interface PrintSetup {
     orientation: "portrait" | "landscape" | null;
     fitToWidth: boolean;
+    /** One page wide AND tall. */
+    fitToPage: boolean;
     footer: {
         left: string;
         center: string;
@@ -508,6 +517,10 @@ interface NormalizedChart {
         name: string | null;
         values: ChartRange;
         color: string | null;
+        points: {
+            index: number;
+            color: string;
+        }[];
     }[];
     /** [col, row], both 0-based. */
     from: [number, number];

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;
@@ -78,10 +80,15 @@ interface ChartSchema {
     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?: {
@@ -257,7 +264,7 @@ interface SetMetaOp {
 }
 
 /** This package's own version, pinned to package.json by `version.test.ts`. */
-declare const VERSION = "2.8.0";
+declare const VERSION = "2.9.0";
 type Any$6 = any;
 /**
  * Agent — the structured-tool surface for Holy Sheet. Mirrors PHP `Agent`.
@@ -329,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.8.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>;
@@ -493,6 +500,8 @@ declare class ChartRange {
 interface PrintSetup {
     orientation: "portrait" | "landscape" | null;
     fitToWidth: boolean;
+    /** One page wide AND tall. */
+    fitToPage: boolean;
     footer: {
         left: string;
         center: string;
@@ -508,6 +517,10 @@ interface NormalizedChart {
         name: string | null;
         values: ChartRange;
         color: string | null;
+        points: {
+            index: number;
+            color: string;
+        }[];
     }[];
     /** [col, row], both 0-based. */
     from: [number, number];

package/dist/index.js

@@ -916,6 +916,20 @@ function toInt(v) {
   const n = Math.trunc(Number(v));
   return Number.isFinite(n) ? n : 0;
 }
+function normalizePoints(points2, count) {
+  if (!isPlainObject(points2) && !Array.isArray(points2)) return [];
+  const byIndex = /* @__PURE__ */ new Map();
+  for (const p of Object.values(points2)) {
+    const rec = isPlainObject(p) || Array.isArray(p) ? p : null;
+    const index = rec ? rec.index : void 0;
+    const color2 = rec ? rec.color : void 0;
+    const m = typeof color2 === "string" ? /^#([0-9A-Fa-f]{6})$/.exec(color2) : null;
+    if (typeof index === "number" && Number.isInteger(index) && index >= 0 && index < count && m) {
+      byIndex.set(index, m[1].toUpperCase());
+    }
+  }
+  return [...byIndex.entries()].sort((a, b) => a[0] - b[0]).map(([index, color2]) => ({ index, color: color2 }));
+}
 var CHART_TYPES = ["column", "bar", "line", "pie"];
 function normalizeCharts(charts, sheetName2, cells) {
   if (!isPlainObject(charts) && !Array.isArray(charts)) return [];
@@ -934,7 +948,12 @@ function normalizeCharts(charts, sheetName2, cells) {
       if (values2 === null) continue;
       const rec = s;
       const m = typeof rec.color === "string" ? /^#([0-9A-Fa-f]{6})$/.exec(rec.color) : null;
-      series.push({ name: typeof rec.name === "string" ? rec.name : null, values: values2, color: m ? m[1].toUpperCase() : null });
+      series.push({
+        name: typeof rec.name === "string" ? rec.name : null,
+        values: values2,
+        color: m ? m[1].toUpperCase() : null,
+        points: normalizePoints(rec.points, values2.addresses().length)
+      });
     }
     if (series.length === 0) continue;
     const stack = out.length;
@@ -981,6 +1000,7 @@ function normalizePrint(print) {
   const p = print;
   const orientation = p.orientation === "portrait" || p.orientation === "landscape" ? p.orientation : null;
   const fitToWidth = p.fitToWidth === true;
+  const fitToPage = p.fitToPage === true;
   let footer = null;
   if (isPlainObject(p.footer) || Array.isArray(p.footer)) {
     const f = p.footer;
@@ -988,8 +1008,8 @@ function normalizePrint(print) {
     footer = { left: slot("left"), center: slot("center"), right: slot("right") };
     if (footer.left === "" && footer.center === "" && footer.right === "") footer = null;
   }
-  if (orientation === null && !fitToWidth && footer === null) return null;
-  return { orientation, fitToWidth, footer };
+  if (orientation === null && !fitToWidth && !fitToPage && footer === null) return null;
+  return { orientation, fitToWidth, fitToPage, footer };
 }
 
 // src/schema/formula-linter.ts
@@ -1904,6 +1924,15 @@ var Validator = class {
             "true scales the sheet to one page wide when printed."
           ));
         }
+        if (print.fitToPage != null && typeof print.fitToPage !== "boolean") {
+          errors.push(error(
+            `${path}.print.fitToPage`,
+            "boolean",
+            typeOf(print.fitToPage),
+            print.fitToPage,
+            "true scales the sheet onto ONE page, wide and tall: a one-page summary with a chart prints whole."
+          ));
+        }
         if (print.footer != null) {
           if (!isPlainObject(print.footer) && !Array.isArray(print.footer)) {
             errors.push(error(
@@ -1975,6 +2004,39 @@ var Validator = class {
     return errors;
   }
 };
+function validatePoints(points2, at2, values2) {
+  if (!Array.isArray(points2)) {
+    return [
+      error(
+        at2,
+        "a list of points",
+        typeOf(points2),
+        points2,
+        'Colour single points: [{"index": 2, "color": "#C2410C"}], index 0-based within values.'
+      )
+    ];
+  }
+  const count = values2 === null ? 0 : values2.addresses().length;
+  const errors = [];
+  points2.forEach((p, k) => {
+    const rec = isPlainObject(p) || Array.isArray(p) ? p : null;
+    const index = rec ? rec.index ?? null : null;
+    const color2 = rec ? rec.color ?? null : null;
+    if (typeof index !== "number" || !Number.isInteger(index) || index < 0 || index >= count) {
+      errors.push(error(
+        `${at2}[${k}].index`,
+        "an index within values (0 to " + Math.max(0, count - 1) + ")",
+        typeOf(index),
+        index,
+        'The 0-based position of the point in its values range: "B5:B7" has points 0, 1 and 2.'
+      ));
+    }
+    if (typeof color2 !== "string" || !/^#[0-9A-Fa-f]{6}$/.test(color2)) {
+      errors.push(error(`${at2}[${k}].color`, "#RRGGBB", typeOf(color2), color2, 'A hex colour, like "#C2410C".'));
+    }
+  });
+  return errors;
+}
 function validateCharts(charts, path, sheetName2) {
   if (!Array.isArray(charts)) {
     return [
@@ -2031,6 +2093,9 @@ function validateCharts(charts, path, sheetName2) {
             errors.push(error(`${at2}.series[${j}].color`, "#RRGGBB", typeOf(color2), color2, 'A hex colour, like "#1F3A5F".'));
           }
         }
+        if (isObj && s.points != null) {
+          errors.push(...validatePoints(s.points, `${at2}.series[${j}].points`, ChartRange.parse(values2, sheetName2)));
+        }
       });
     }
     if (c.categories != null && ChartRange.parse(c.categories, sheetName2) === null) {
@@ -3135,6 +3200,7 @@ function sheetToSchema(sheet) {
     const print = {};
     if (sheet.print.orientation !== null) print["orientation"] = sheet.print.orientation;
     if (sheet.print.fitToWidth) print["fitToWidth"] = true;
+    if (sheet.print.fitToPage) print["fitToPage"] = true;
     if (sheet.print.footer !== null) {
       const footer = {};
       for (const k of ["left", "center", "right"]) if (sheet.print.footer[k] !== "") footer[k] = sheet.print.footer[k];
@@ -3156,6 +3222,7 @@ function chartToSchema(chart, sheetName2) {
     if (s.name !== null) series["name"] = s.name;
     series["values"] = s.values.toSchema(sheetName2);
     if (s.color !== null) series["color"] = "#" + s.color;
+    if (s.points.length > 0) series["points"] = s.points.map((p) => ({ index: p.index, color: "#" + p.color }));
     return series;
   });
   out["position"] = {
@@ -3680,7 +3747,7 @@ var ChartParser = {
         const catRef = formula(ser, "cat");
         categories = catRef !== null ? ChartRange.parse(catRef, sheetName2) : null;
       }
-      series.push({ name: seriesName(ser), values: values2, color: seriesColor(ser) });
+      series.push({ name: seriesName(ser), values: values2, color: seriesColor(ser), points: points(ser) });
     }
     if (series.length === 0) return null;
     const labels = el(plot, "dLbls");
@@ -3736,6 +3803,18 @@ function seriesName(ser) {
   const cached = descendants(tx, "v")[0];
   return cached ? cached.text : null;
 }
+function points(ser) {
+  const byIndex = /* @__PURE__ */ new Map();
+  for (const dPt of els(ser, "dPt")) {
+    const idx = at(el(dPt, "idx"), "val");
+    const clr = descendants(dPt, "srgbClr")[0];
+    const color2 = (clr ? at(clr, "val") ?? "" : "").toUpperCase();
+    if (idx !== void 0 && /^[0-9]+$/.test(idx) && /^[0-9A-F]{6}$/.test(color2)) {
+      byIndex.set(parseInt(idx, 10), color2);
+    }
+  }
+  return [...byIndex.entries()].sort((a, b) => a[0] - b[0]).map(([index, color2]) => ({ index, color: color2 }));
+}
 function seriesColor(ser) {
   const spPr = el(ser, "spPr");
   if (!spPr) return null;
@@ -3931,10 +4010,11 @@ function parsePrint(xml) {
   const o = at(setup, "orientation");
   const orientation = o === "portrait" || o === "landscape" ? o : null;
   const fitToWidth = fitToPage && setup !== void 0 && at(setup, "fitToWidth") === "1" && ["0", ""].includes(at(setup, "fitToHeight") ?? "");
+  const fitToPageOnly = fitToPage && setup !== void 0 && at(setup, "fitToWidth") === "1" && at(setup, "fitToHeight") === "1";
   const oddFooter = el(el(xml, "headerFooter"), "oddFooter");
   const footer = oddFooter !== void 0 ? parseFooterCodes(oddFooter.text) : null;
-  if (orientation === null && !fitToWidth && footer === null) return null;
-  return { orientation, fitToWidth, footer };
+  if (orientation === null && !fitToWidth && !fitToPageOnly && footer === null) return null;
+  return { orientation, fitToWidth, fitToPage: fitToPageOnly, footer };
 }
 function parseFooterCodes(codes) {
   const slots = { left: "", center: "", right: "" };
@@ -4412,7 +4492,12 @@ function seriesXml(i, s, chart, workbook) {
   const mark = type === "line" ? '<c:marker><c:symbol val="circle"/><c:size val="6"/></c:marker>' : "";
   const cat = chart.categories !== null ? "<c:cat>" + strRef(chart.categories, workbook) + "</c:cat>" : "";
   const smooth = type === "line" ? '<c:smooth val="0"/>' : "";
-  return `<c:ser><c:idx val="${i}"/><c:order val="${i}"/>` + name + fill + invert + mark + cat + "<c:val>" + numRef(s.values, workbook) + "</c:val>" + smooth + "</c:ser>";
+  let points2 = "";
+  for (const p of s.points) {
+    const solid = `<a:solidFill><a:srgbClr val="${p.color}"/></a:solidFill>`;
+    points2 += `<c:dPt><c:idx val="${p.index}"/>` + (type === "line" ? `<c:marker><c:symbol val="circle"/><c:size val="6"/><c:spPr>${solid}<a:ln>${solid}</a:ln></c:spPr></c:marker><c:bubble3D val="0"/>` : type === "pie" ? `<c:bubble3D val="0"/><c:spPr>${solid}</c:spPr>` : `<c:invertIfNegative val="0"/><c:bubble3D val="0"/><c:spPr>${solid}</c:spPr>`) + "</c:dPt>";
+  }
+  return `<c:ser><c:idx val="${i}"/><c:order val="${i}"/>` + name + fill + invert + mark + points2 + cat + "<c:val>" + numRef(s.values, workbook) + "</c:val>" + smooth + "</c:ser>";
 }
 function strRef(range, workbook) {
   let pts = "";
@@ -4626,10 +4711,12 @@ var XlsxWriter = class {
     }
     const legacyDrawing = sheet.hasComments() ? '<legacyDrawing r:id="rId1"/>' : "";
     const print = sheet.print;
-    const sheetPrXml = print?.fitToWidth ? '<sheetPr><pageSetUpPr fitToPage="1"/></sheetPr>' : "";
+    const fits = (print?.fitToWidth ?? false) || (print?.fitToPage ?? false);
+    const sheetPrXml = fits ? '<sheetPr><pageSetUpPr fitToPage="1"/></sheetPr>' : "";
     let pageSetupXml = "";
-    if (print !== null && (print.orientation !== null || print.fitToWidth)) {
-      pageSetupXml = "<pageSetup" + (print.orientation !== null ? ` orientation="${print.orientation}"` : "") + (print.fitToWidth ? ' fitToWidth="1" fitToHeight="0"' : "") + "/>";
+    if (print !== null && (print.orientation !== null || fits)) {
+      pageSetupXml = "<pageSetup" + (print.orientation !== null ? ` orientation="${print.orientation}"` : "") + // fitToPage: one page wide AND tall. fitToWidth: one wide, as tall as it needs.
+      (print.fitToPage ? ' fitToWidth="1" fitToHeight="1"' : print.fitToWidth ? ' fitToWidth="1" fitToHeight="0"' : "") + "/>";
     }
     const headerFooterXml = print?.footer ? `<headerFooter><oddFooter>${this.escape(footerCodes(print.footer))}</oddFooter></headerFooter>` : "";
     return '<?xml version="1.0" encoding="UTF-8" standalone="yes"?><worksheet xmlns="http://schemas.openxmlformats.org/spreadsheetml/2006/main" xmlns:r="http://schemas.openxmlformats.org/officeDocument/2006/relationships">' + sheetPrXml + sheetViewsXml + colsXml + `<sheetData>${rowsXml}</sheetData>` + mergesXml + pageSetupXml + headerFooterXml + (sheet.charts.length > 0 ? `<drawing r:id="${drawingRelId(sheet.hasComments())}"/>` : "") + legacyDrawing + "</worksheet>";
@@ -5777,7 +5864,20 @@ var holy_sheet_schema_default = {
                   properties: {
                     name: { type: "string", description: "Shown in the legend." },
                     values: { type: "string", description: 'The numbers, as a range the same length as categories: "B5:B7".' },
-                    color: { type: "string", description: "#RRGGBB. Ignored for a pie, whose slices take a palette." }
+                    color: { type: "string", description: "#RRGGBB. Ignored for a pie, whose slices take a palette." },
+                    points: {
+                      type: "array",
+                      description: 'Colour single points to make the finding stand out: the one bar or slice the title is about. index is 0-based within values: [{"index": 2, "color": "#C2410C"}].',
+                      items: {
+                        type: "object",
+                        additionalProperties: false,
+                        required: ["index", "color"],
+                        properties: {
+                          index: { type: "integer", minimum: 0 },
+                          color: { type: "string", description: "#RRGGBB" }
+                        }
+                      }
+                    }
                   }
                 }
               },
@@ -5800,6 +5900,7 @@ var holy_sheet_schema_default = {
           properties: {
             orientation: { type: "string", enum: ["portrait", "landscape"] },
             fitToWidth: { type: "boolean", description: "Scale the sheet to one page wide (as many pages tall as it needs)." },
+            fitToPage: { type: "boolean", description: "Scale the sheet onto ONE page, wide and tall. Use it for a one-page summary with a chart, so the page break never cuts the chart." },
             footer: {
               type: "object",
               additionalProperties: false,
@@ -6019,7 +6120,7 @@ var holy_sheet_schema_default = {
 };
 
 // src/agent.ts
-var VERSION = "2.8.0";
+var VERSION = "2.9.0";
 function toU8(input) {
   return input instanceof Uint8Array ? input : new Uint8Array(input);
 }