ooxml-core 1.12.2 → 1.14.0

package/dist/automation/node.cjs

@@ -8,14 +8,32 @@ var crypto = require('crypto');
 function createFileOperations(rootDir = process.cwd()) {
   const pending = /* @__PURE__ */ new Map();
   const maxBytes = 64 * 1024 * 1024;
+  async function rel(target) {
+    const root = await promises.realpath(path.resolve(rootDir));
+    return path.relative(root, target).split(path.sep).join("/") || ".";
+  }
+  async function scrub(action) {
+    try {
+      return await action();
+    } catch (error) {
+      if (!(error instanceof Error)) throw error;
+      const hosts = [path.resolve(rootDir), await promises.realpath(path.resolve(rootDir)).catch(() => "")];
+      let message = error.message;
+      for (const host of hosts.filter(Boolean).sort((a, b) => b.length - a.length))
+        message = message.split(host + path.sep).join("").split(host).join("<root>");
+      const safe = new Error(message, { cause: void 0 });
+      safe.code = error.code;
+      throw safe;
+    }
+  }
   async function pathFor(file, extensions) {
     const root = await promises.realpath(path.resolve(rootDir));
     const path$1 = path.resolve(root, file);
     const parent = await promises.realpath(path.dirname(path$1));
     let actual = path.resolve(parent, path.basename(path$1));
     const inside = (target) => {
-      const rel = path.relative(root, target);
-      if (rel === ".." || rel.startsWith("../") || rel.startsWith("..\\") || path.isAbsolute(rel))
+      const rel2 = path.relative(root, target);
+      if (rel2 === ".." || rel2.startsWith("../") || rel2.startsWith("..\\") || path.isAbsolute(rel2))
         throw new Error("Path is outside the configured root");
     };
     inside(actual);
@@ -74,7 +92,29 @@ function createFileOperations(rootDir = process.cwd()) {
       if (pending.get(path) === current) pending.delete(path);
     }
   }
-  return {
+  async function directoryFor(dir) {
+    const root = await promises.realpath(path.resolve(rootDir));
+    let probe = path.resolve(root, dir);
+    const rest = [];
+    for (; ; ) {
+      try {
+        probe = await promises.realpath(probe);
+        break;
+      } catch (error) {
+        if (error.code !== "ENOENT") throw error;
+        const parent = path.dirname(probe);
+        if (parent === probe) throw error;
+        rest.unshift(path.basename(probe));
+        probe = parent;
+      }
+    }
+    const actual = path.resolve(probe, ...rest);
+    const r = path.relative(root, actual);
+    if (r === ".." || r.startsWith("../") || r.startsWith("..\\") || path.isAbsolute(r))
+      throw new Error("Path is outside the configured root");
+    return r.split(path.sep).join("/") || ".";
+  }
+  const api = {
     async inspect(file, extensions, inspect) {
       const path = await pathFor(file, extensions);
       return serial(path, async () => inspect(await read(path)));
@@ -83,7 +123,7 @@ function createFileOperations(rootDir = process.cwd()) {
       const path = await pathFor(file, extensions);
       return serial(path, async () => {
         await write(path, await create(), false);
-        return { filePath: path, saved: true };
+        return { filePath: await rel(path), saved: true };
       });
     },
     async edit(file, extensions, edit, outputPath) {
@@ -94,10 +134,30 @@ function createFileOperations(rootDir = process.cwd()) {
       return serial(path$1, async () => {
         const { bytes, ...result } = await edit(await read(path$1));
         await write(output, bytes, output === path$1);
-        return { ...result, filePath: output, saved: true };
+        return { ...result, filePath: await rel(output), saved: true };
       });
-    }
+    },
+    /** Read a confined file (no serialisation; use inside {@link exclusive}). */
+    async readFile(file, extensions) {
+      return read(await pathFor(file, extensions));
+    },
+    /** Atomically replace a confined file (no serialisation; use inside {@link exclusive}). */
+    async writeFile(file, extensions, bytes) {
+      await write(await pathFor(file, extensions), bytes, true);
+    },
+    /** Run `action` holding the per-path lock of a confined file. */
+    async exclusive(file, extensions, action) {
+      return serial(await pathFor(file, extensions), action);
+    },
+    /** Confine a directory under the root and return its root-relative path. */
+    directory: directoryFor,
+    /** Root-relative description of a root-confined file path. */
+    relativePath: async (file, extensions) => rel(await pathFor(file, extensions))
   };
+  const wrapped = {};
+  for (const [name, fn] of Object.entries(api))
+    wrapped[name] = (...args) => scrub(() => fn(...args));
+  return wrapped;
 }
 
 exports.createFileOperations = createFileOperations;

package/dist/automation/node.d.ts

@@ -12,5 +12,15 @@ export declare function createFileOperations(rootDir?: string): {
         filePath: string;
         saved: boolean;
     }>;
+    /** Read a confined file (no serialisation; use inside {@link exclusive}). */
+    readFile(file: string, extensions: readonly string[]): Promise<Uint8Array<ArrayBuffer>>;
+    /** Atomically replace a confined file (no serialisation; use inside {@link exclusive}). */
+    writeFile(file: string, extensions: readonly string[], bytes: Uint8Array): Promise<void>;
+    /** Run `action` holding the per-path lock of a confined file. */
+    exclusive<T>(file: string, extensions: readonly string[], action: () => Promise<T>): Promise<T>;
+    /** Confine a directory under the root and return its root-relative path. */
+    directory: (dir: string) => Promise<string>;
+    /** Root-relative description of a root-confined file path. */
+    relativePath: (file: string, extensions: readonly string[]) => Promise<string>;
 };
 //# sourceMappingURL=node.d.ts.map

package/dist/automation/node.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"node.d.ts","sourceRoot":"","sources":["../../automation/node.ts"],"names":[],"mappings":"AAIA,MAAM,WAAW,cAAc;IAC9B,KAAK,EAAE,UAAU,CAAC;CAClB;AAED,2EAA2E;AAC3E,wBAAgB,oBAAoB,CAAC,OAAO,SAAgB;IAmEpD,OAAO,CAAC,CAAC,QACR,MAAM,cACA,SAAS,MAAM,EAAE,WACpB,CAAC,KAAK,EAAE,UAAU,KAAK,OAAO,CAAC,CAAC,CAAC;IAKrC,MAAM,OAAO,MAAM,cAAc,SAAS,MAAM,EAAE,UAAU,MAAM,OAAO,CAAC,UAAU,CAAC;;;;IAOrF,IAAI,CAAC,CAAC,SAAS,cAAc,QAC5B,MAAM,cACA,SAAS,MAAM,EAAE,QACvB,CAAC,KAAK,EAAE,UAAU,KAAK,OAAO,CAAC,CAAC,CAAC,eAC1B,MAAM;;;;EAarB"}
+{"version":3,"file":"node.d.ts","sourceRoot":"","sources":["../../automation/node.ts"],"names":[],"mappings":"AAIA,MAAM,WAAW,cAAc;IAC9B,KAAK,EAAE,UAAU,CAAC;CAClB;AAED,2EAA2E;AAC3E,wBAAgB,oBAAoB,CAAC,OAAO,SAAgB;YAkH5C,CAAC,QACR,MAAM,cACA,SAAS,MAAM,EAAE,WACpB,CAAC,KAAK,EAAE,UAAU,KAAK,OAAO,CAAC,CAAC,CAAC;iBAKxB,MAAM,cAAc,SAAS,MAAM,EAAE,UAAU,MAAM,OAAO,CAAC,UAAU,CAAC;;;;SAOhF,CAAC,SAAS,cAAc,QAC5B,MAAM,cACA,SAAS,MAAM,EAAE,QACvB,CAAC,KAAK,EAAE,UAAU,KAAK,OAAO,CAAC,CAAC,CAAC,eAC1B,MAAM;;;;IAYpB,6EAA6E;mBACxD,MAAM,cAAc,SAAS,MAAM,EAAE;IAG1D,2FAA2F;oBACrE,MAAM,cAAc,SAAS,MAAM,EAAE,SAAS,UAAU;IAG9E,iEAAiE;cACjD,CAAC,QAAQ,MAAM,cAAc,SAAS,MAAM,EAAE,UAAU,MAAM,OAAO,CAAC,CAAC,CAAC;IAGxF,4EAA4E;qBAlE5C,MAAM;IAoEtC,8DAA8D;yBACnC,MAAM,cAAc,SAAS,MAAM,EAAE;EASjE"}

package/dist/automation/node.mjs

@@ -1,19 +1,37 @@
 import { realpath, open, unlink, rename, link } from 'fs/promises';
-import { extname, resolve, dirname, basename, relative, isAbsolute } from 'path';
+import { resolve, sep, dirname, basename, relative, isAbsolute, extname } from 'path';
 import { randomUUID } from 'crypto';
 
 // automation/node.ts
 function createFileOperations(rootDir = process.cwd()) {
   const pending = /* @__PURE__ */ new Map();
   const maxBytes = 64 * 1024 * 1024;
+  async function rel(target) {
+    const root = await realpath(resolve(rootDir));
+    return relative(root, target).split(sep).join("/") || ".";
+  }
+  async function scrub(action) {
+    try {
+      return await action();
+    } catch (error) {
+      if (!(error instanceof Error)) throw error;
+      const hosts = [resolve(rootDir), await realpath(resolve(rootDir)).catch(() => "")];
+      let message = error.message;
+      for (const host of hosts.filter(Boolean).sort((a, b) => b.length - a.length))
+        message = message.split(host + sep).join("").split(host).join("<root>");
+      const safe = new Error(message, { cause: void 0 });
+      safe.code = error.code;
+      throw safe;
+    }
+  }
   async function pathFor(file, extensions) {
     const root = await realpath(resolve(rootDir));
     const path = resolve(root, file);
     const parent = await realpath(dirname(path));
     let actual = resolve(parent, basename(path));
     const inside = (target) => {
-      const rel = relative(root, target);
-      if (rel === ".." || rel.startsWith("../") || rel.startsWith("..\\") || isAbsolute(rel))
+      const rel2 = relative(root, target);
+      if (rel2 === ".." || rel2.startsWith("../") || rel2.startsWith("..\\") || isAbsolute(rel2))
         throw new Error("Path is outside the configured root");
     };
     inside(actual);
@@ -72,7 +90,29 @@ function createFileOperations(rootDir = process.cwd()) {
       if (pending.get(path) === current) pending.delete(path);
     }
   }
-  return {
+  async function directoryFor(dir) {
+    const root = await realpath(resolve(rootDir));
+    let probe = resolve(root, dir);
+    const rest = [];
+    for (; ; ) {
+      try {
+        probe = await realpath(probe);
+        break;
+      } catch (error) {
+        if (error.code !== "ENOENT") throw error;
+        const parent = dirname(probe);
+        if (parent === probe) throw error;
+        rest.unshift(basename(probe));
+        probe = parent;
+      }
+    }
+    const actual = resolve(probe, ...rest);
+    const r = relative(root, actual);
+    if (r === ".." || r.startsWith("../") || r.startsWith("..\\") || isAbsolute(r))
+      throw new Error("Path is outside the configured root");
+    return r.split(sep).join("/") || ".";
+  }
+  const api = {
     async inspect(file, extensions, inspect) {
       const path = await pathFor(file, extensions);
       return serial(path, async () => inspect(await read(path)));
@@ -81,7 +121,7 @@ function createFileOperations(rootDir = process.cwd()) {
       const path = await pathFor(file, extensions);
       return serial(path, async () => {
         await write(path, await create(), false);
-        return { filePath: path, saved: true };
+        return { filePath: await rel(path), saved: true };
       });
     },
     async edit(file, extensions, edit, outputPath) {
@@ -92,10 +132,30 @@ function createFileOperations(rootDir = process.cwd()) {
       return serial(path, async () => {
         const { bytes, ...result } = await edit(await read(path));
         await write(output, bytes, output === path);
-        return { ...result, filePath: output, saved: true };
+        return { ...result, filePath: await rel(output), saved: true };
       });
-    }
+    },
+    /** Read a confined file (no serialisation; use inside {@link exclusive}). */
+    async readFile(file, extensions) {
+      return read(await pathFor(file, extensions));
+    },
+    /** Atomically replace a confined file (no serialisation; use inside {@link exclusive}). */
+    async writeFile(file, extensions, bytes) {
+      await write(await pathFor(file, extensions), bytes, true);
+    },
+    /** Run `action` holding the per-path lock of a confined file. */
+    async exclusive(file, extensions, action) {
+      return serial(await pathFor(file, extensions), action);
+    },
+    /** Confine a directory under the root and return its root-relative path. */
+    directory: directoryFor,
+    /** Root-relative description of a root-confined file path. */
+    relativePath: async (file, extensions) => rel(await pathFor(file, extensions))
   };
+  const wrapped = {};
+  for (const [name, fn] of Object.entries(api))
+    wrapped[name] = (...args) => scrub(() => fn(...args));
+  return wrapped;
 }
 
 export { createFileOperations };

package/dist/automation/outline.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Structured content a host (an assistant, a template, an import) turns into a new file. The
+ * shapes are deliberately small: they name what Word and Excel already have a built-in style or
+ * cell for, so the result is an ordinary document the editors open and change like any other.
+ */
+export type DocxOutlineBlock = {
+    type: 'title';
+    text: string;
+} | {
+    type: 'heading';
+    text: string;
+    level?: 1 | 2 | 3;
+} | {
+    type: 'paragraph';
+    text: string;
+} | {
+    type: 'bullets' | 'numbered';
+    items: readonly string[];
+};
+export interface XlsxOutlineSheet {
+    name: string;
+    /** Row-major cell inputs; a string starting with `=` is a formula, as typed into a cell. */
+    rows: readonly (readonly (string | number | boolean | null)[])[];
+}
+/** A new Word document from headings, paragraphs and lists, using the built-in styles. */
+export declare function createDocxFromOutline(outline: readonly DocxOutlineBlock[]): Promise<Uint8Array>;
+/** A new workbook with one sheet per entry, each filled from its rows starting at A1. */
+export declare function createXlsxFromSheets(sheets: readonly XlsxOutlineSheet[]): Promise<Uint8Array>;
+//# sourceMappingURL=outline.d.ts.map

package/dist/automation/outline.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"outline.d.ts","sourceRoot":"","sources":["../../automation/outline.ts"],"names":[],"mappings":"AAQA;;;;GAIG;AACH,MAAM,MAAM,gBAAgB,GACzB;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAC/B;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;CAAE,GACpD;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GACnC;IAAE,IAAI,EAAE,SAAS,GAAG,UAAU,CAAC;IAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE,CAAC;AAE9D,MAAM,WAAW,gBAAgB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,4FAA4F;IAC5F,IAAI,EAAE,SAAS,CAAC,SAAS,CAAC,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,CAAC,EAAE,CAAC,EAAE,CAAC;CACjE;AAWD,0FAA0F;AAC1F,wBAAsB,qBAAqB,CAC1C,OAAO,EAAE,SAAS,gBAAgB,EAAE,GAClC,OAAO,CAAC,UAAU,CAAC,CAuCrB;AAED,yFAAyF;AACzF,wBAAsB,oBAAoB,CACzC,MAAM,EAAE,SAAS,gBAAgB,EAAE,GACjC,OAAO,CAAC,UAAU,CAAC,CAiCrB"}

package/dist/automation/xlsx.d.ts

@@ -22,4 +22,25 @@ export declare function setXlsxCells(bytes: Uint8Array, sheetIndex: number, cell
     bytes: Uint8Array<ArrayBufferLike>;
     warnings: string[];
 }>;
+/**
+ * Every filled cell of every sheet, in row-major order, up to `maxCells` in all. Unlike a fixed
+ * range it misses nothing inside the cap, and it says how much was left out when the cap is hit.
+ */
+export declare function readXlsxFilledCells(bytes: Uint8Array, { maxCells }?: {
+    maxCells?: number | undefined;
+}): Promise<{
+    sheets: {
+        index: number;
+        name: string;
+        cells: {
+            address: string;
+            value: unknown;
+            formula?: string;
+        }[];
+        total: number;
+        omitted: number;
+    }[];
+    truncated: boolean;
+    warnings: string[];
+}>;
 //# sourceMappingURL=xlsx.d.ts.map

package/dist/automation/xlsx.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"xlsx.d.ts","sourceRoot":"","sources":["../../automation/xlsx.ts"],"names":[],"mappings":"AAOA,wBAAsB,WAAW,CAAC,KAAK,EAAE,UAAU;;;;;;;GAOlD;AAED,wBAAsB,UAAU,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAAC,UAAU,CAAC,CAW9E;AAED,wBAAsB,aAAa,CAAC,KAAK,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM;;;;;;;GAoB3F;AAED,wBAAsB,YAAY,CACjC,KAAK,EAAE,UAAU,EACjB,UAAU,EAAE,MAAM,EAClB,KAAK,EAAE,SAAS;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,EAAE;;;GAgBpD"}
+{"version":3,"file":"xlsx.d.ts","sourceRoot":"","sources":["../../automation/xlsx.ts"],"names":[],"mappings":"AAOA,wBAAsB,WAAW,CAAC,KAAK,EAAE,UAAU;;;;;;;GAOlD;AAED,wBAAsB,UAAU,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAAC,UAAU,CAAC,CAW9E;AAED,wBAAsB,aAAa,CAAC,KAAK,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM;;;;;;;GAoB3F;AAED,wBAAsB,YAAY,CACjC,KAAK,EAAE,UAAU,EACjB,UAAU,EAAE,MAAM,EAClB,KAAK,EAAE,SAAS;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,EAAE;;;GAgBpD;AAED;;;GAGG;AACH,wBAAsB,mBAAmB,CAAC,KAAK,EAAE,UAAU,EAAE,EAAE,QAAe,EAAE;;CAAK;;;;;qBAI3D,MAAM;mBAAS,OAAO;sBAAY,MAAM;;;;;;;GAoBjE"}

package/dist/chart/auto-title.d.ts

@@ -0,0 +1,31 @@
+/**
+ * The text a chart's title shows, including Office's AUTO title (COM-verified in PowerPoint).
+ *
+ * A `c:title` with no `c:tx` is not an empty title: Office shows the only series' name for a
+ * single-series chart (a pie titled "Sales") and the literal "Chart Title" otherwise. The
+ * Office 2016+ extended (`cx:`) chart types have no "lone series name" convention: an empty
+ * `cx:title` always renders "Chart Title", even for a single-series waterfall or funnel.
+ */
+/** Office's placeholder for an auto title on a multi-series chart. */
+export declare const CHART_AUTO_TITLE = "Chart Title";
+/** Whether `chartType` is one of the `cx:` (chartex) families. */
+export declare function isChartexOnlyType(chartType: string): boolean;
+export interface AutoTitleInput {
+    chartType: string;
+    /** Series names, in order (an empty string for an unnamed series). */
+    seriesNames: readonly string[];
+    /** The explicit title, when the chart authors one. */
+    title?: string | undefined;
+    /** `style.hasTitle` as authored; `undefined` when the chart does not say. */
+    hasTitle?: boolean | undefined;
+    /** `c:autoTitleDeleted`. */
+    autoTitleDeleted?: boolean | undefined;
+}
+/**
+ * Whether a classic chart with NO `c:title` element still gets an auto title: exactly one named
+ * series, no authored toggle, `c:autoTitleDeleted` unset and not a chartex family.
+ */
+export declare function impliesAutoTitle(input: AutoTitleInput): boolean;
+/** The title text to draw, or `undefined` when the chart shows no title. */
+export declare function resolveAutoTitleText(input: AutoTitleInput): string | undefined;
+//# sourceMappingURL=auto-title.d.ts.map

package/dist/chart/auto-title.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auto-title.d.ts","sourceRoot":"","sources":["../../chart/auto-title.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,sEAAsE;AACtE,eAAO,MAAM,gBAAgB,gBAAgB,CAAC;AAY9C,kEAAkE;AAClE,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAE5D;AAED,MAAM,WAAW,cAAc;IAC9B,SAAS,EAAE,MAAM,CAAC;IAClB,sEAAsE;IACtE,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;IAC/B,sDAAsD;IACtD,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC3B,6EAA6E;IAC7E,QAAQ,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IAC/B,4BAA4B;IAC5B,gBAAgB,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;CACvC;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,cAAc,GAAG,OAAO,CAQ/D;AAED,4EAA4E;AAC5E,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,cAAc,GAAG,MAAM,GAAG,SAAS,CAM9E"}

package/dist/chart/axis-format.d.ts

@@ -0,0 +1,13 @@
+/**
+ * PowerPoint's compact axis-value formatting (1.2K / 3.4M / integer / one-decimal).
+ *
+ * `formatCode` is the chart's own `c:numFmt/@formatCode`. When the source declares one
+ * (`0%`, `#,##0`, `$#,##0.00`) it wins: the cached values behind a percentage chart are
+ * fractions, and the compact fallback renders them as `0.5` where Office shows `50%`. Codes
+ * outside the supported subset fall through to the compact form.
+ *
+ * Distinct from the Excel painter's `formatAxisValue` (`chart/render/chart-scale.ts`), which
+ * groups thousands instead of abbreviating them.
+ */
+export declare function formatCompactAxisValue(value: number, formatCode?: string): string;
+//# sourceMappingURL=axis-format.d.ts.map

package/dist/chart/axis-format.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"axis-format.d.ts","sourceRoot":"","sources":["../../chart/axis-format.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;GAUG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,MAAM,CAOjF"}

package/dist/chart/bubble-radius.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Bubble sizing shared by every format: how a `c:bubbleSize` value becomes a radius, given the
+ * chart's `c:bubbleScale`, `c:sizeRepresents` and `c:showNegBubbles`. Moved from the PowerPoint
+ * renderer (`chart-view-model-points.ts`) so the shared SVG painter sizes bubbles identically.
+ */
+/** `c:bubbleScale` / `c:sizeRepresents` inputs to {@link computeBubbleRadius}. */
+export interface BubbleRadiusOptions {
+    /** `c:bubbleScale` (0-300%). Office's own default, 100, leaves the envelope unscaled. */
+    bubbleScale?: number | undefined;
+    /**
+     * `c:sizeRepresents`. `'area'` (ECMA-376's own default) sizes bubbles so the rendered AREA is
+     * proportional to the value (radius scales with the square root of it); `'w'` sizes so the
+     * DIAMETER is proportional (radius scales linearly). Defaults to `'w'` here so the raw
+     * helper's three-argument callers stay unchanged; a chart-wide painter resolves the `'area'`
+     * default itself before calling in.
+     */
+    sizeRepresents?: 'area' | 'w' | undefined;
+}
+/**
+ * Radius of a bubble given its size value, the max size in the chart, and a median radius derived
+ * from the plot area. With no size value the bubble uses the median radius (scaled by
+ * `bubbleScale`); otherwise it scales from 0.5x to 2x the median, linearly (`'w'`) or by square
+ * root (`'area'`, so the bubble's rendered AREA, not its diameter, tracks the value).
+ */
+export declare function computeBubbleRadius(sizeVal: number | undefined, maxBubble: number, medianRadius: number, options?: BubbleRadiusOptions): number;
+/** The size every bubble of the chart is measured against: the largest magnitude, at least 1. */
+export declare function maxBubbleSize(sizes: readonly number[]): number;
+/** The median bubble radius for a plot area (4% of its shorter side). */
+export declare function medianBubbleRadius(plotWidth: number, plotHeight: number): number;
+//# sourceMappingURL=bubble-radius.d.ts.map

package/dist/chart/bubble-radius.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bubble-radius.d.ts","sourceRoot":"","sources":["../../chart/bubble-radius.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,kFAAkF;AAClF,MAAM,WAAW,mBAAmB;IACnC,yFAAyF;IACzF,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACjC;;;;;;OAMG;IACH,cAAc,CAAC,EAAE,MAAM,GAAG,GAAG,GAAG,SAAS,CAAC;CAC1C;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAClC,OAAO,EAAE,MAAM,GAAG,SAAS,EAC3B,SAAS,EAAE,MAAM,EACjB,YAAY,EAAE,MAAM,EACpB,OAAO,CAAC,EAAE,mBAAmB,GAC3B,MAAM,CAUR;AAED,iGAAiG;AACjG,wBAAgB,aAAa,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,CAE9D;AAED,yEAAyE;AACzE,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,CAEhF"}

package/dist/chart/error-bar-amount.d.ts

@@ -0,0 +1,22 @@
+import type { ChartErrorValueType } from './model-analysis.js';
+/** What the amount of an error bar depends on (`ChartErrorBars`, resolved). */
+export interface ChartErrorAmountOptions {
+    valueType: ChartErrorValueType;
+    /** `c:val`: the fixed value, the percentage or the standard-deviation multiple. */
+    value?: number | undefined;
+    /** Custom amounts by source point index. */
+    customPlus?: readonly number[] | undefined;
+    customMinus?: readonly number[] | undefined;
+}
+/**
+ * The sample variance of `values` (`n - 1` denominator). A single value has none: the denominator
+ * is clamped to 1 so the result is 0, not a division by zero.
+ */
+export declare function chartSampleVariance(values: readonly number[]): number;
+/**
+ * The error amount of one point. `values` are the series' values along the bar's direction, in
+ * display order; `displayIndex` is the point's place among them and `sourceIndex` its index in the
+ * series (custom amounts are indexed by it); `side` is the half of the bar being drawn.
+ */
+export declare function chartErrorBarAmount(options: ChartErrorAmountOptions, values: readonly number[], displayIndex: number, sourceIndex: number, side: 'plus' | 'minus'): number;
+//# sourceMappingURL=error-bar-amount.d.ts.map

package/dist/chart/error-bar-amount.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-bar-amount.d.ts","sourceRoot":"","sources":["../../chart/error-bar-amount.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AAE5D,+EAA+E;AAC/E,MAAM,WAAW,uBAAuB;IACvC,SAAS,EAAE,mBAAmB,CAAC;IAC/B,mFAAmF;IACnF,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC3B,4CAA4C;IAC5C,UAAU,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,CAAC;IAC3C,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,CAAC;CAC5C;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,CAKrE;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAClC,OAAO,EAAE,uBAAuB,EAChC,MAAM,EAAE,SAAS,MAAM,EAAE,EACzB,YAAY,EAAE,MAAM,EACpB,WAAW,EAAE,MAAM,EACnB,IAAI,EAAE,MAAM,GAAG,OAAO,GACpB,MAAM,CAeR"}

package/dist/chart/hierarchy.d.ts

@@ -0,0 +1,69 @@
+/**
+ * The category hierarchy behind the treemap and sunburst families, shared by every format.
+ * Moved from the PowerPoint renderer (`chart-treemap-hierarchy.ts`).
+ *
+ * An Office 2016+ chart (`cx:`) stores its categories leaf first: `cx:strDim type="cat"` holds
+ * one `cx:lvl` per level, the first being the leaf labels and the last the outermost parents, each
+ * parent label written only on the first row it covers. {@link normalizeLevels} fills those gaps
+ * and the builders turn the levels plus the leaf values into a weighted tree.
+ */
+import { type TreemapBox } from './treemap-squarify.js';
+export type ParentLabelLayout = 'none' | 'banner' | 'overlapping';
+export interface HierarchyNode {
+    label: string;
+    /** A leaf's absolute value; a parent's is the sum of its children (see {@link aggregate}). */
+    weight: number;
+    children?: HierarchyNode[];
+    seriesIndex?: number;
+    pointIndex?: number;
+    colorIndex: number;
+    parentLabelLayout: ParentLabelLayout;
+}
+/** One series of a hierarchy: its leaf values and the layout of its parent labels. */
+export interface HierarchySeries {
+    name: string;
+    values: readonly number[];
+    parentLabelLayout?: ParentLabelLayout | undefined;
+}
+/** Fills the blanks of each level with the label above them (parents are written once). */
+export declare function normalizeLevels(levels: ReadonlyArray<ReadonlyArray<string>>, pointCount: number): string[][];
+/** Sets every parent's weight to the sum of its descendants'. */
+export declare function aggregate(node: HierarchyNode): number;
+/**
+ * The weighted tree of a chart: one root per top-level branch (one per series when there are
+ * several), weights aggregated, and one colour index per top-level branch painted on every leaf
+ * below it (COM-verified in PowerPoint: every leaf under "Branch 1" takes its legend swatch).
+ */
+export declare function buildHierarchyRoots(series: readonly HierarchySeries[], categoryLabels: ReadonlyArray<string>, categoryLevels: ReadonlyArray<ReadonlyArray<string>> | undefined): HierarchyNode[];
+/**
+ * The top-level branch labels a legend should show, in the order colours are assigned to roots:
+ * one per series when there are several, else one per unique outermost category level, else (a
+ * flat treemap) one per leaf category.
+ */
+export declare function hierarchyBranchLabels(series: readonly {
+    name: string;
+    values: readonly number[];
+}[], categoryLabels: ReadonlyArray<string>, categoryLevels: ReadonlyArray<ReadonlyArray<string>> | undefined): string[];
+/** A rectangle of the treemap layout, in the order it is painted. */
+export type TreemapCell = {
+    kind: 'parent';
+    label: string;
+    x: number;
+    y: number;
+} | {
+    kind: 'leaf';
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+    label: string;
+    colorIndex: number;
+    seriesIndex: number;
+    pointIndex: number;
+    /** Whether the cell is big enough to carry its label, and the label's font size. */
+    labelFits: boolean;
+    labelSize: number;
+};
+/** Squarified layout of the roots into `box`: parent labels and leaf cells, depth first. */
+export declare function layoutTreemap(nodes: HierarchyNode[], box: TreemapBox): TreemapCell[];
+//# sourceMappingURL=hierarchy.d.ts.map

package/dist/chart/hierarchy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hierarchy.d.ts","sourceRoot":"","sources":["../../chart/hierarchy.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,EAAY,KAAK,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAE/D,MAAM,MAAM,iBAAiB,GAAG,MAAM,GAAG,QAAQ,GAAG,aAAa,CAAC;AAElE,MAAM,WAAW,aAAa;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,8FAA8F;IAC9F,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,aAAa,EAAE,CAAC;IAC3B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,iBAAiB,EAAE,iBAAiB,CAAC;CACrC;AAED,sFAAsF;AACtF,MAAM,WAAW,eAAe;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1B,iBAAiB,CAAC,EAAE,iBAAiB,GAAG,SAAS,CAAC;CAClD;AAED,2FAA2F;AAC3F,wBAAgB,eAAe,CAC9B,MAAM,EAAE,aAAa,CAAC,aAAa,CAAC,MAAM,CAAC,CAAC,EAC5C,UAAU,EAAE,MAAM,GAChB,MAAM,EAAE,EAAE,CASZ;AA4CD,iEAAiE;AACjE,wBAAgB,SAAS,CAAC,IAAI,EAAE,aAAa,GAAG,MAAM,CAGrD;AAQD;;;;GAIG;AACH,wBAAgB,mBAAmB,CAClC,MAAM,EAAE,SAAS,eAAe,EAAE,EAClC,cAAc,EAAE,aAAa,CAAC,MAAM,CAAC,EACrC,cAAc,EAAE,aAAa,CAAC,aAAa,CAAC,MAAM,CAAC,CAAC,GAAG,SAAS,GAC9D,aAAa,EAAE,CAgBjB;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CACpC,MAAM,EAAE,SAAS;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE,EAAE,EAC9D,cAAc,EAAE,aAAa,CAAC,MAAM,CAAC,EACrC,cAAc,EAAE,aAAa,CAAC,aAAa,CAAC,MAAM,CAAC,CAAC,GAAG,SAAS,GAC9D,MAAM,EAAE,CAUV;AAED,qEAAqE;AACrE,MAAM,MAAM,WAAW,GACpB;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAA;CAAE,GACvD;IACA,IAAI,EAAE,MAAM,CAAC;IACb,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;IACV,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,oFAAoF;IACpF,SAAS,EAAE,OAAO,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;CACjB,CAAC;AAKL,4FAA4F;AAC5F,wBAAgB,aAAa,CAAC,KAAK,EAAE,aAAa,EAAE,EAAE,GAAG,EAAE,UAAU,GAAG,WAAW,EAAE,CAmCpF"}