reamkit 1.15.0 → 1.15.2

package/dist/esm/core/drawingml/chart-geometry.d.ts

@@ -1,4 +1,8 @@
 import { Chart, ChartSeries } from '../document-model/index.js';
+/**
+ * An axis-aligned rectangle in the scene's local y-up frame: bars, scatter
+ * point markers, legend swatches. Position is the bottom-left corner.
+ */
 export interface ChartRect {
     readonly x: number;
     readonly y: number;
@@ -8,17 +12,24 @@ export interface ChartRect {
     readonly strokeHex?: string;
     readonly strokeWidthPt?: number;
 }
+/** An open stroked polyline: line-chart series, gridlines and axis lines. */
 export interface ChartPolyline {
     readonly points: ReadonlyArray<readonly [number, number]>;
     readonly strokeHex: string;
     readonly widthPt: number;
 }
+/** A closed, filled polygon (area-chart bands). Drawn before strokes/labels. */
 export interface ChartPolygon {
     readonly points: ReadonlyArray<readonly [number, number]>;
     readonly fillHex: string;
     readonly strokeHex?: string;
     readonly widthPt?: number;
 }
+/**
+ * A circular sector (pie/doughnut slice), centred at `(cx, cy)` with radius `r`.
+ * `startRad`/`sweepRad` are radians in the y-up frame; sweeps are negative for
+ * Excel's clockwise winding. The doughnut hole is a white wedge drawn last.
+ */
 export interface ChartWedge {
     readonly cx: number;
     readonly cy: number;
@@ -28,15 +39,25 @@ export interface ChartWedge {
     readonly fillHex: string;
     readonly strokeHex?: string;
 }
+/** How a {@link ChartLabel} sits horizontally relative to its anchor point. */
 export type LabelAlign = 'left' | 'center' | 'right';
+/** A text label (title, axis tick, category, data value, legend entry). */
 export interface ChartLabel {
     readonly text: string;
+    /** Anchor point; `align` says how text sits relative to it. */
     readonly x: number;
+    /** Text baseline. */
     readonly y: number;
     readonly sizePt: number;
     readonly colorHex: string;
     readonly align: LabelAlign;
 }
+/**
+ * The fully laid-out chart: rectangles, polylines, wedges and labels (plus
+ * optional filled polygons) in a local y-up frame, origin bottom-left. The
+ * renderer maps these to draw commands — rects/polylines/wedges/polygons via the
+ * vector layer, labels via the text pass.
+ */
 export interface ChartScene {
     readonly rects: ReadonlyArray<ChartRect>;
     readonly polylines: ReadonlyArray<ChartPolyline>;
@@ -44,21 +65,125 @@ export interface ChartScene {
     readonly labels: ReadonlyArray<ChartLabel>;
     readonly polygons?: ReadonlyArray<ChartPolygon>;
 }
+/**
+ * Injected text-width measurer: the rendered advance width (points) of `text` at
+ * `sizePt`. Keeps this module free of any font/PDF dependency, so it is
+ * unit-testable in isolation.
+ */
 export type MeasureText = (text: string, sizePt: number) => number;
+/** Font size (points) for axis ticks, category/data labels and legend text. */
 export declare const CHART_LABEL_PT = 9;
+/** Font size (points) for the chart title. */
 export declare const CHART_TITLE_PT = 13;
+/** The Office accent cycle (RRGGBB) for series without an explicit colour. */
 export declare const SERIES_COLORS: string[];
+/**
+ * Resolve a series colour: the series' own `colorHex` if set, else cycling
+ * through `cycle` (the chart's theme accent cycle) or, failing that,
+ * {@link SERIES_COLORS} by index.
+ *
+ * @param s     The series.
+ * @param i     The series index, used to pick from the cycle.
+ * @param cycle Optional per-chart colour cycle; falls back to {@link SERIES_COLORS}.
+ * @returns An RRGGBB hex string.
+ */
 export declare const seriesColor: (s: ChartSeries, i: number, cycle?: ReadonlyArray<string>) => string;
+/** A value-axis scale: the rounded `min`/`max` extent and the tick `step`. */
 export interface Scale {
     readonly min: number;
     readonly max: number;
     readonly step: number;
 }
+/**
+ * Compute a human-friendly axis {@link Scale} for the data range using
+ * Heckbert's "nice numbers" algorithm: rounded endpoints and a 1/2/5·10ⁿ step
+ * that yields about `maxTicks` ticks. A degenerate range (`dataMin === dataMax`)
+ * is widened by 1 so the axis is non-empty.
+ *
+ * @param dataMin  The smallest data value to cover.
+ * @param dataMax  The largest data value to cover.
+ * @param maxTicks Target upper bound on tick count (default 6).
+ * @returns The rounded min/max and tick step.
+ */
 export declare function niceScale(dataMin: number, dataMax: number, maxTicks?: number): Scale;
+/**
+ * Format an axis tick value, choosing decimal places from the tick `step` so
+ * `0.25`-spaced ticks read `0.25` while integer steps drop the fraction.
+ *
+ * @param v    The tick value.
+ * @param step The tick spacing (from {@link niceScale}).
+ * @returns The label text.
+ */
 export declare function formatTick(v: number, step: number): string;
+/**
+ * Lay out a bar/column {@link Chart} into a {@link ChartScene}. Honours
+ * `chart.grouping` (clustered / stacked / percentStacked) and `chart.barDir`
+ * (column vs horizontal bar), over the shared cartesian frame.
+ *
+ * @param chart   The bar/column chart.
+ * @param wPt     Frame width in points.
+ * @param hPt     Frame height in points.
+ * @param measure Text measurer used to size labels and reserve axis gutters.
+ * @returns The positioned scene primitives.
+ */
 export declare function buildBarScene(chart: Chart, wPt: number, hPt: number, measure: MeasureText): ChartScene;
+/**
+ * Lay out an area {@link Chart} into a {@link ChartScene}: each series becomes a
+ * filled polygon down to the value baseline (stacked when `chart.grouping` is
+ * stacked / percentStacked), over the shared cartesian frame.
+ *
+ * @param chart   The area chart.
+ * @param wPt     Frame width in points.
+ * @param hPt     Frame height in points.
+ * @param measure Text measurer used to size labels and reserve axis gutters.
+ * @returns The positioned scene primitives.
+ */
 export declare function buildAreaScene(chart: Chart, wPt: number, hPt: number, measure: MeasureText): ChartScene;
+/**
+ * Lay out a scatter {@link Chart} into a {@link ChartScene}: numeric X/Y series
+ * plotted as marker points over a frame with two value axes (X from each
+ * series' `xValues`, Y from its `values`).
+ *
+ * @param chart   The scatter chart.
+ * @param wPt     Frame width in points.
+ * @param hPt     Frame height in points.
+ * @param measure Text measurer used to size labels and reserve axis gutters.
+ * @returns The positioned scene primitives.
+ */
 export declare function buildScatterScene(chart: Chart, wPt: number, hPt: number, measure: MeasureText): ChartScene;
+/**
+ * Lay out a line {@link Chart} into a {@link ChartScene}: each series becomes a
+ * stroked polyline across the category slots, over the shared cartesian frame.
+ * Unlike bars/areas the value axis auto-mins (it need not include 0).
+ *
+ * @param chart   The line chart.
+ * @param wPt     Frame width in points.
+ * @param hPt     Frame height in points.
+ * @param measure Text measurer used to size labels and reserve axis gutters.
+ * @returns The positioned scene primitives.
+ */
 export declare function buildLineScene(chart: Chart, wPt: number, hPt: number, measure: MeasureText): ChartScene;
+/**
+ * Lay out a pie/doughnut {@link Chart} into a {@link ChartScene}: the first
+ * series' values become proportional wedges (a centre hole for doughnut),
+ * with a legend instead of axes.
+ *
+ * @param chart   The pie/doughnut chart.
+ * @param wPt     Frame width in points.
+ * @param hPt     Frame height in points.
+ * @param measure Text measurer used to size labels and the legend.
+ * @returns The positioned scene primitives.
+ */
 export declare function buildPieScene(chart: Chart, wPt: number, hPt: number, measure: MeasureText): ChartScene;
+/**
+ * Lay out any supported {@link Chart} into a {@link ChartScene}, dispatching by
+ * `chart.type` to the per-type builders.
+ *
+ * @param chart   The chart to lay out.
+ * @param wPt     Frame width in points.
+ * @param hPt     Frame height in points.
+ * @param measure Text measurer used to size labels and reserve gutters.
+ * @returns The positioned scene, or `null` for an unrenderable type (the
+ *          renderer then reserves the box with a light border).
+ */
 export declare function buildChartScene(chart: Chart, wPt: number, hPt: number, measure: MeasureText): ChartScene | null;

package/dist/esm/core/drawingml/chart-geometry.js

@@ -2,6 +2,7 @@ var AXIS_COLOR = "595959";
 var GRID_COLOR = "D9D9D9";
 var LABEL_COLOR = "595959";
 var TITLE_COLOR = "404040";
+/** The Office accent cycle (RRGGBB) for series without an explicit colour. */
 var SERIES_COLORS = [
 	"4472C4",
 	"ED7D31",
@@ -10,6 +11,16 @@ var SERIES_COLORS = [
 	"5B9BD5",
 	"70AD47"
 ];
+/**
+* Resolve a series colour: the series' own `colorHex` if set, else cycling
+* through `cycle` (the chart's theme accent cycle) or, failing that,
+* {@link SERIES_COLORS} by index.
+*
+* @param s     The series.
+* @param i     The series index, used to pick from the cycle.
+* @param cycle Optional per-chart colour cycle; falls back to {@link SERIES_COLORS}.
+* @returns An RRGGBB hex string.
+*/
 var seriesColor = (s, i, cycle) => s.colorHex ?? (cycle && cycle.length > 0 ? cycle[i % cycle.length] : SERIES_COLORS[i % SERIES_COLORS.length]);
 function niceNum(range, round) {
 	const exp = Math.floor(Math.log10(range));
@@ -19,6 +30,17 @@ function niceNum(range, round) {
 	else nf = f <= 1 ? 1 : f <= 2 ? 2 : f <= 5 ? 5 : 10;
 	return nf * 10 ** exp;
 }
+/**
+* Compute a human-friendly axis {@link Scale} for the data range using
+* Heckbert's "nice numbers" algorithm: rounded endpoints and a 1/2/5·10ⁿ step
+* that yields about `maxTicks` ticks. A degenerate range (`dataMin === dataMax`)
+* is widened by 1 so the axis is non-empty.
+*
+* @param dataMin  The smallest data value to cover.
+* @param dataMax  The largest data value to cover.
+* @param maxTicks Target upper bound on tick count (default 6).
+* @returns The rounded min/max and tick step.
+*/
 function niceScale(dataMin, dataMax, maxTicks = 6) {
 	const lo = Math.min(dataMin, dataMax);
 	let hi = Math.max(dataMin, dataMax);
@@ -30,6 +52,14 @@ function niceScale(dataMin, dataMax, maxTicks = 6) {
 		step
 	};
 }
+/**
+* Format an axis tick value, choosing decimal places from the tick `step` so
+* `0.25`-spaced ticks read `0.25` while integer steps drop the fraction.
+*
+* @param v    The tick value.
+* @param step The tick spacing (from {@link niceScale}).
+* @returns The label text.
+*/
 function formatTick(v, step) {
 	if (Number.isInteger(step) && Number.isInteger(v)) return String(v);
 	const decimals = Math.max(0, -Math.floor(Math.log10(step)));
@@ -220,6 +250,17 @@ function groupingFrameOpts(chart, nCats) {
 	}
 	return {};
 }
+/**
+* Lay out a bar/column {@link Chart} into a {@link ChartScene}. Honours
+* `chart.grouping` (clustered / stacked / percentStacked) and `chart.barDir`
+* (column vs horizontal bar), over the shared cartesian frame.
+*
+* @param chart   The bar/column chart.
+* @param wPt     Frame width in points.
+* @param hPt     Frame height in points.
+* @param measure Text measurer used to size labels and reserve axis gutters.
+* @returns The positioned scene primitives.
+*/
 function buildBarScene(chart, wPt, hPt, measure) {
 	const g = chart.grouping ?? "clustered";
 	const stacked = g === "stacked" || g === "percentStacked";
@@ -350,6 +391,17 @@ function areaBand(top, base, f, xAt, fillHex) {
 		widthPt: 1
 	};
 }
+/**
+* Lay out an area {@link Chart} into a {@link ChartScene}: each series becomes a
+* filled polygon down to the value baseline (stacked when `chart.grouping` is
+* stacked / percentStacked), over the shared cartesian frame.
+*
+* @param chart   The area chart.
+* @param wPt     Frame width in points.
+* @param hPt     Frame height in points.
+* @param measure Text measurer used to size labels and reserve axis gutters.
+* @returns The positioned scene primitives.
+*/
 function buildAreaScene(chart, wPt, hPt, measure) {
 	const g = chart.grouping ?? "standard";
 	const stacked = g === "stacked" || g === "percentStacked";
@@ -386,6 +438,17 @@ function buildAreaScene(chart, wPt, hPt, measure) {
 		polygons
 	};
 }
+/**
+* Lay out a scatter {@link Chart} into a {@link ChartScene}: numeric X/Y series
+* plotted as marker points over a frame with two value axes (X from each
+* series' `xValues`, Y from its `values`).
+*
+* @param chart   The scatter chart.
+* @param wPt     Frame width in points.
+* @param hPt     Frame height in points.
+* @param measure Text measurer used to size labels and reserve axis gutters.
+* @returns The positioned scene primitives.
+*/
 function buildScatterScene(chart, wPt, hPt, measure) {
 	const rects = [];
 	const polylines = [];
@@ -442,6 +505,17 @@ function buildScatterScene(chart, wPt, hPt, measure) {
 		labels
 	};
 }
+/**
+* Lay out a line {@link Chart} into a {@link ChartScene}: each series becomes a
+* stroked polyline across the category slots, over the shared cartesian frame.
+* Unlike bars/areas the value axis auto-mins (it need not include 0).
+*
+* @param chart   The line chart.
+* @param wPt     Frame width in points.
+* @param hPt     Frame height in points.
+* @param measure Text measurer used to size labels and reserve axis gutters.
+* @returns The positioned scene primitives.
+*/
 function buildLineScene(chart, wPt, hPt, measure) {
 	const allVals = chart.series.flatMap((s) => s.values);
 	const f = buildFrame(chart, wPt, hPt, measure, false, { dataRange: allVals.length > 0 ? [Math.min(...allVals), Math.max(...allVals)] : [0, 1] });
@@ -479,6 +553,17 @@ function buildLineScene(chart, wPt, hPt, measure) {
 	};
 }
 var sliceColor = (series, i) => pointColor(series, i) ?? SERIES_COLORS[i % SERIES_COLORS.length];
+/**
+* Lay out a pie/doughnut {@link Chart} into a {@link ChartScene}: the first
+* series' values become proportional wedges (a centre hole for doughnut),
+* with a legend instead of axes.
+*
+* @param chart   The pie/doughnut chart.
+* @param wPt     Frame width in points.
+* @param hPt     Frame height in points.
+* @param measure Text measurer used to size labels and the legend.
+* @returns The positioned scene primitives.
+*/
 function buildPieScene(chart, wPt, hPt, measure) {
 	const rects = [];
 	const wedges = [];
@@ -624,6 +709,17 @@ function layoutLegend(entries, hasLegend, pos, wPt, hPt, measure) {
 		}
 	};
 }
+/**
+* Lay out any supported {@link Chart} into a {@link ChartScene}, dispatching by
+* `chart.type` to the per-type builders.
+*
+* @param chart   The chart to lay out.
+* @param wPt     Frame width in points.
+* @param hPt     Frame height in points.
+* @param measure Text measurer used to size labels and reserve gutters.
+* @returns The positioned scene, or `null` for an unrenderable type (the
+*          renderer then reserves the box with a light border).
+*/
 function buildChartScene(chart, wPt, hPt, measure) {
 	if (chart.type === "bar") return buildBarScene(chart, wPt, hPt, measure);
 	if (chart.type === "line") return buildLineScene(chart, wPt, hPt, measure);

package/dist/esm/core/drawingml/chart-parser.d.ts

@@ -1,6 +1,40 @@
 import { Chart } from '../document-model/index.js';
 import { OpcPackage } from '../opc/index.js';
 import { ColorResolver } from './colors.js';
+/**
+ * Parse a DrawingML chart part (chart1.xml) into a {@link Chart}, reading the
+ * CACHED data (`c:numCache` / `c:strCache`) rather than the embedded spreadsheet
+ * — the cache holds the last-computed categories and values, exactly what Word
+ * renders. Supports bar/column, line, pie/doughnut, area and scatter; other
+ * chart types parse with `type: 'unknown'` (the renderer reserves the box but
+ * draws nothing). Categories are shared and taken from the first series carrying
+ * them.
+ *
+ * @param chartXml     The raw chart1.xml part bytes.
+ * @param resolveColor Maps a DrawingML colour reference to a 6-hex string.
+ * @returns The parsed chart, or `null` when there is no `c:chart` / `c:plotArea`.
+ */
 export declare function parseChart(chartXml: Uint8Array, resolveColor: ColorResolver): Chart | null;
+/**
+ * MS-ODRAWXML chartColorStyle (charts/colorsN.xml): the top-level colour list is
+ * the series cycle (`meth="cycle"` — the common case; variations are luminance
+ * tweaks for `>N` series and are ignored in v1).
+ *
+ * @param colorsXml    The raw colorsN.xml part bytes.
+ * @param resolveColor Maps a DrawingML colour reference to a 6-hex string.
+ * @returns The resolved series-colour cycle, in order (empty if none resolve).
+ */
 export declare function parseChartColorStyle(colorsXml: Uint8Array, resolveColor: ColorResolver): Array<string>;
+/**
+ * Augment a parsed {@link Chart} with its custom series-colour cycle when the
+ * chart part's own relationships carry a chartColorStyle (colorsN.xml). Returns
+ * the chart unchanged when no such relationship resolves to a non-empty cycle.
+ * Shared by the docx and xlsx readers.
+ *
+ * @param chart         The parsed chart to augment.
+ * @param pkg           The OPC package, for relationship lookup.
+ * @param chartPartPath The chart part path, used as the relationship source.
+ * @param resolveColor  Maps a DrawingML colour reference to a 6-hex string.
+ * @returns The chart, with `seriesColorCycle` set when a cycle is found.
+ */
 export declare function withChartColorStyle(chart: Chart, pkg: OpcPackage, chartPartPath: string, resolveColor: ColorResolver): Chart;

package/dist/esm/core/drawingml/chart-parser.js

@@ -23,6 +23,19 @@ var TYPE_OF_TAG = {
 	"c:area3DChart": "area",
 	"c:scatterChart": "scatter"
 };
+/**
+* Parse a DrawingML chart part (chart1.xml) into a {@link Chart}, reading the
+* CACHED data (`c:numCache` / `c:strCache`) rather than the embedded spreadsheet
+* — the cache holds the last-computed categories and values, exactly what Word
+* renders. Supports bar/column, line, pie/doughnut, area and scatter; other
+* chart types parse with `type: 'unknown'` (the renderer reserves the box but
+* draws nothing). Categories are shared and taken from the first series carrying
+* them.
+*
+* @param chartXml     The raw chart1.xml part bytes.
+* @param resolveColor Maps a DrawingML colour reference to a 6-hex string.
+* @returns The parsed chart, or `null` when there is no `c:chart` / `c:plotArea`.
+*/
 function parseChart(chartXml, resolveColor) {
 	const chart = poFindByPath(parser.parse(decoder.decode(chartXml)), ["c:chartSpace", "c:chart"]);
 	if (!chart) return null;
@@ -191,6 +204,15 @@ function isLegendPos(v) {
 function isGrouping(v) {
 	return v === "clustered" || v === "stacked" || v === "percentStacked" || v === "standard";
 }
+/**
+* MS-ODRAWXML chartColorStyle (charts/colorsN.xml): the top-level colour list is
+* the series cycle (`meth="cycle"` — the common case; variations are luminance
+* tweaks for `>N` series and are ignored in v1).
+*
+* @param colorsXml    The raw colorsN.xml part bytes.
+* @param resolveColor Maps a DrawingML colour reference to a 6-hex string.
+* @returns The resolved series-colour cycle, in order (empty if none resolve).
+*/
 function parseChartColorStyle(colorsXml, resolveColor) {
 	const root = parser.parse(new TextDecoder().decode(colorsXml)).find((n) => {
 		const tag = Object.keys(n).find((k) => k !== ":@" && k !== "#text");
@@ -204,6 +226,18 @@ function parseChartColorStyle(colorsXml, resolveColor) {
 	}
 	return out;
 }
+/**
+* Augment a parsed {@link Chart} with its custom series-colour cycle when the
+* chart part's own relationships carry a chartColorStyle (colorsN.xml). Returns
+* the chart unchanged when no such relationship resolves to a non-empty cycle.
+* Shared by the docx and xlsx readers.
+*
+* @param chart         The parsed chart to augment.
+* @param pkg           The OPC package, for relationship lookup.
+* @param chartPartPath The chart part path, used as the relationship source.
+* @param resolveColor  Maps a DrawingML colour reference to a 6-hex string.
+* @returns The chart, with `seriesColorCycle` set when a cycle is found.
+*/
 function withChartColorStyle(chart, pkg, chartPartPath, resolveColor) {
 	for (const rel of pkg.getPartRelationships(chartPartPath)) {
 		if (rel.type !== REL_CHART_COLOR_STYLE) continue;

package/dist/esm/core/drawingml/chart-serializer.d.ts

@@ -1,2 +1,14 @@
 import { Chart } from '../document-model/index.js';
+/**
+ * Serialize a {@link Chart} to a DrawingML chart part (chart1.xml) — the inverse
+ * of `parseChart`. Emits exactly the cached data the parser reads
+ * (`c:numCache` / `c:strCache`), so a parse → serialize → parse round-trip
+ * preserves type, series, categories, colours, title, legend and axis titles.
+ * Pie/doughnut charts omit axes; scatter emits two value axes (`c:valAx`);
+ * everything else gets a category + value axis pair. Shared by the xlsx writer
+ * (embedded charts, WT1) and the docx writer (drawing charts, WT3).
+ *
+ * @param chart The chart to serialize.
+ * @returns The chart1.xml document as a string (with the XML declaration).
+ */
 export declare function chartSpaceXml(chart: Chart): string;

package/dist/esm/core/drawingml/chart-serializer.js

@@ -12,6 +12,18 @@ var GROUP_TAG = {
 };
 var CAT_AX_ID = 111111111;
 var VAL_AX_ID = 222222222;
+/**
+* Serialize a {@link Chart} to a DrawingML chart part (chart1.xml) — the inverse
+* of `parseChart`. Emits exactly the cached data the parser reads
+* (`c:numCache` / `c:strCache`), so a parse → serialize → parse round-trip
+* preserves type, series, categories, colours, title, legend and axis titles.
+* Pie/doughnut charts omit axes; scatter emits two value axes (`c:valAx`);
+* everything else gets a category + value axis pair. Shared by the xlsx writer
+* (embedded charts, WT1) and the docx writer (drawing charts, WT3).
+*
+* @param chart The chart to serialize.
+* @returns The chart1.xml document as a string (with the XML declaration).
+*/
 function chartSpaceXml(chart) {
 	const isScatter = chart.type === "scatter";
 	const isPie = chart.type === "pie" || chart.doughnut === true;

package/dist/esm/core/drawingml/colors.d.ts

@@ -1,8 +1,19 @@
 import { PoNode } from '../po-helpers.js';
+/**
+ * A colour transform child (§20.1.2.3): `lumMod`/`lumOff` modulate luminance,
+ * `shade` darkens toward black, `tint` lightens toward white. `val` is normalised
+ * to 0..1 (the XML stores thousandths of a percent). `alpha` is parsed but ignored
+ * (solid fills emit no transparency).
+ */
 export interface ColorMod {
     readonly kind: 'lumMod' | 'lumOff' | 'shade' | 'tint' | 'alpha';
     readonly val: number;
 }
+/**
+ * A theme-agnostic colour reference emitted by the shape parser: either a direct
+ * sRGB value or a theme scheme-name reference, each with optional colour
+ * transforms. A {@link ColorResolver} maps it to a concrete 6-hex string.
+ */
 export type RawColor = {
     readonly srgb: string;
     readonly mods?: ReadonlyArray<ColorMod>;
@@ -10,11 +21,53 @@ export type RawColor = {
     readonly scheme: string;
     readonly mods?: ReadonlyArray<ColorMod>;
 };
+/** Maps a {@link RawColor} to a 6-hex string, or `undefined` when unresolvable. */
 export type ColorResolver = (raw: RawColor) => string | undefined;
+/**
+ * Apply DrawingML colour transforms ({@link ColorMod}s) to a 6-hex value,
+ * returning a 6-hex value. `shade`/`tint` scale in RGB; `lumMod`/`lumOff` adjust
+ * luminance in HSL. An empty `mods` returns `hex` unchanged.
+ *
+ * @param hex  The base colour, RRGGBB.
+ * @param mods The transforms to apply, in order.
+ * @returns The transformed colour, uppercase RRGGBB.
+ */
 export declare function applyColorMods(hex: string, mods: ReadonlyArray<ColorMod>): string;
+/**
+ * Office 2013 default theme palette — the colours Word assigns to the standard
+ * scheme slots when a document carries no custom theme part.
+ */
 export declare const DEFAULT_THEME_PALETTE: ReadonlyMap<string, string>;
+/**
+ * Resolve a `schemeClr` text/background alias (`tx1`/`bg1`/`tx2`/`bg2`,
+ * §20.1.2.3.29) to its underlying `dk`/`lt` slot name; other names pass through.
+ */
 export declare function resolveSchemeName(name: string): string;
+/**
+ * Build a {@link ColorResolver} over a scheme-name → hex `palette`. sRGB
+ * references pass through verbatim (upper-cased); scheme references are aliased
+ * (via {@link resolveSchemeName}) then looked up; colour transforms are applied.
+ *
+ * @param palette The scheme-name → RRGGBB map (e.g. {@link DEFAULT_THEME_PALETTE}).
+ * @returns A resolver that maps a {@link RawColor} to a hex string or `undefined`.
+ */
 export declare function makeColorResolver(palette: ReadonlyMap<string, string>): ColorResolver;
+/** A {@link ColorResolver} backed by the {@link DEFAULT_THEME_PALETTE}. */
 export declare const defaultColorResolver: ColorResolver;
+/**
+ * Read the colour transform children ({@link ColorMod}s) under an `a:srgbClr` /
+ * `a:schemeClr` node, normalising each `val` from thousandths-of-a-percent to 0..1.
+ */
 export declare function readColorMods(colorNode: PoNode): Array<ColorMod>;
+/**
+ * Resolve an `a:srgbClr` / `a:schemeClr` node to a hex string (with colour
+ * transforms applied). Returns `undefined` when the node is some other element,
+ * valueless, or the resolver does not know the colour. Container traversal policy
+ * (stop at the first colour node vs continue past unresolved ones) stays with the
+ * callers.
+ *
+ * @param c            The candidate colour node.
+ * @param resolveColor The resolver mapping a {@link RawColor} to hex.
+ * @returns The resolved RRGGBB, or `undefined`.
+ */
 export declare function resolveColorNode(c: PoNode, resolveColor: ColorResolver): string | undefined;

package/dist/esm/core/drawingml/colors.js

@@ -69,6 +69,15 @@ function hslToRgb(h, s, l) {
 		b + m
 	];
 }
+/**
+* Apply DrawingML colour transforms ({@link ColorMod}s) to a 6-hex value,
+* returning a 6-hex value. `shade`/`tint` scale in RGB; `lumMod`/`lumOff` adjust
+* luminance in HSL. An empty `mods` returns `hex` unchanged.
+*
+* @param hex  The base colour, RRGGBB.
+* @param mods The transforms to apply, in order.
+* @returns The transformed colour, uppercase RRGGBB.
+*/
 function applyColorMods(hex, mods) {
 	if (mods.length === 0) return hex;
 	const n = parseInt(hex, 16);
@@ -91,6 +100,10 @@ function applyColorMods(hex, mods) {
 	const toHex = (x) => Math.round(clamp01(x) * 255).toString(16).padStart(2, "0");
 	return (toHex(r) + toHex(g) + toHex(b)).toUpperCase();
 }
+/**
+* Office 2013 default theme palette — the colours Word assigns to the standard
+* scheme slots when a document carries no custom theme part.
+*/
 var DEFAULT_THEME_PALETTE = new Map([
 	["dk1", "000000"],
 	["lt1", "FFFFFF"],
@@ -111,9 +124,21 @@ var SCHEME_ALIAS = {
 	tx2: "dk2",
 	bg2: "lt2"
 };
+/**
+* Resolve a `schemeClr` text/background alias (`tx1`/`bg1`/`tx2`/`bg2`,
+* §20.1.2.3.29) to its underlying `dk`/`lt` slot name; other names pass through.
+*/
 function resolveSchemeName(name) {
 	return SCHEME_ALIAS[name] ?? name;
 }
+/**
+* Build a {@link ColorResolver} over a scheme-name → hex `palette`. sRGB
+* references pass through verbatim (upper-cased); scheme references are aliased
+* (via {@link resolveSchemeName}) then looked up; colour transforms are applied.
+*
+* @param palette The scheme-name → RRGGBB map (e.g. {@link DEFAULT_THEME_PALETTE}).
+* @returns A resolver that maps a {@link RawColor} to a hex string or `undefined`.
+*/
 function makeColorResolver(palette) {
 	return (raw) => {
 		const base = "srgb" in raw ? raw.srgb.toUpperCase() : palette.get(resolveSchemeName(raw.scheme));
@@ -121,7 +146,12 @@ function makeColorResolver(palette) {
 		return raw.mods && raw.mods.length > 0 ? applyColorMods(base, raw.mods) : base;
 	};
 }
+/** A {@link ColorResolver} backed by the {@link DEFAULT_THEME_PALETTE}. */
 var defaultColorResolver = makeColorResolver(DEFAULT_THEME_PALETTE);
+/**
+* Read the colour transform children ({@link ColorMod}s) under an `a:srgbClr` /
+* `a:schemeClr` node, normalising each `val` from thousandths-of-a-percent to 0..1.
+*/
 function readColorMods(colorNode) {
 	const mods = [];
 	for (const c of poChildren(colorNode)) for (const kind of [
@@ -139,6 +169,17 @@ function readColorMods(colorNode) {
 	}
 	return mods;
 }
+/**
+* Resolve an `a:srgbClr` / `a:schemeClr` node to a hex string (with colour
+* transforms applied). Returns `undefined` when the node is some other element,
+* valueless, or the resolver does not know the colour. Container traversal policy
+* (stop at the first colour node vs continue past unresolved ones) stays with the
+* callers.
+*
+* @param c            The candidate colour node.
+* @param resolveColor The resolver mapping a {@link RawColor} to hex.
+* @returns The resolved RRGGBB, or `undefined`.
+*/
 function resolveColorNode(c, resolveColor) {
 	const isSrgb = poIs(c, "a:srgbClr");
 	if (!isSrgb && !poIs(c, "a:schemeClr")) return void 0;

package/dist/esm/core/drawingml/preset-geometry.d.ts

@@ -1,6 +1,36 @@
 import { CustomGeometry } from '../document-model/index.js';
 import { PathSegment, VectorPath } from '../vector.js';
+/**
+ * The four closed segments of the `w`×`h` bounding rectangle, in the local y-up
+ * frame (origin bottom-left). The fallback geometry for unknown presets.
+ */
 export declare function rectSegments(w: number, h: number): ReadonlyArray<PathSegment>;
+/** The `w`×`h` bounding rectangle as a {@link VectorPath}. */
 export declare function rectPath(w: number, h: number): VectorPath;
+/**
+ * Map a preset shape name (§20.1.10.55) to its vector path(s) in the local y-up
+ * frame, sized `w`×`h` points and shaped by the `adjust` guides. Returns `null`
+ * for an unknown preset so the caller falls back to the bounding rectangle —
+ * graceful degradation that keeps even unimplemented presets visible (with the
+ * right fill/line) and never throws.
+ *
+ * @param preset The preset geometry name (e.g. `'roundRect'`, `'rightArrow'`).
+ * @param w      Box width in points.
+ * @param h      Box height in points.
+ * @param adjust Raw `a:gd` adjust guides by name (thousandths of a percent).
+ * @returns The path(s), or `null` for an unrecognised preset.
+ */
 export declare function presetPaths(preset: string, w: number, h: number, adjust: ReadonlyMap<string, number>): Array<VectorPath> | null;
+/**
+ * Convert a custom geometry (§20.1.9) to a vector path. Path-space coordinates
+ * (y-down, origin top-left) are scaled to the shape box and flipped to the local
+ * y-up frame; quadratics are elevated to cubics; `arcTo` is decomposed via the
+ * shared arc helper. Angles are 1/60000° clockwise in y-down, which becomes
+ * negative (CCW) once y is flipped.
+ *
+ * @param geom The parsed custom geometry (path size + draw commands).
+ * @param wPt  Box width in points.
+ * @param hPt  Box height in points.
+ * @returns A single-element array holding the built path.
+ */
 export declare function customPaths(geom: CustomGeometry, wPt: number, hPt: number): Array<VectorPath>;