@openpresentation/opf-pptx 0.11.9 → 0.12.1

package/dist/chart-options.js

@@ -0,0 +1,276 @@
+// RR-35: chart options (axis titles, legend position, data labels) in the PPTX export and import.
+//
+// Core owns the normalisation and the per-type support table (`resolveChartOptions`, `chartOptionSupport`); the preview
+// (opf-render) reads the same resolved options. This module writes them natively and reads them back:
+//
+//   classic charts   c:catAx/c:title and c:valAx/c:title (through PptxGenJS options), c:legend/c:legendPos (through PptxGenJS
+//                    options), and a c:dLbls block per series and per chart group (post-processed XML, see `applyDataLabels`);
+//   chartex charts   cx:axis/cx:title, cx:legend pos and cx:dataLabels pos (see chartex.js, which calls the helpers here).
+//
+// A chart that carries none of the three fields resolves to `active: false`; nothing below runs and its parts are unchanged.
+import * as opfCore from '@openpresentation/opf';
+
+const INACTIVE = Object.freeze({active: false, axisTitles: {}, diagnostics: []});
+
+/** True when the installed core knows the chart option fields (older cores ignore them on export and import). */
+export const coreKnowsChartOptions = () => typeof opfCore.resolveChartOptions === 'function' && typeof opfCore.chartOptionSupport === 'function';
+
+/** The resolved options of a chart (an older core without `resolveChartOptions` ignores the fields). */
+export function resolveChartOptionsFor(chart) {
+  if (typeof opfCore.resolveChartOptions !== 'function' || !chart || typeof chart !== 'object') return INACTIVE;
+  return opfCore.resolveChartOptions(chart, opfCore.chartOptionTarget(chart.type));
+}
+
+export function reportChartOptionDiagnostics(resolved, path, onDiagnostic) {
+  for (const diagnostic of resolved.diagnostics) onDiagnostic?.({...diagnostic, path: `${path}.${diagnostic.option}`});
+}
+
+const LEGEND_POS = Object.freeze({top: 't', bottom: 'b', left: 'l', right: 'r'});
+const LEGEND_POS_BACK = Object.freeze({t: 'top', b: 'bottom', l: 'left', r: 'right'});
+
+/** PptxGenJS addChart options for the legend and the axis titles; `{}` for a chart that uses neither. */
+export function classicChartOptions(resolved, {labelColor, font, textSize}) {
+  const out = {};
+  if (resolved.legend === 'none') out.showLegend = false;
+  else if (resolved.legend) Object.assign(out, {showLegend: true, legendPos: LEGEND_POS[resolved.legend]});
+  const title = (axis, text) => ({
+    [`show${axis}AxisTitle`]: true, [`${axis.toLowerCase()}AxisTitle`]: text,
+    [`${axis.toLowerCase()}AxisTitleColor`]: labelColor, [`${axis.toLowerCase()}AxisTitleFontFace`]: font, [`${axis.toLowerCase()}AxisTitleFontSize`]: textSize / 100,
+  });
+  if (resolved.axisTitles.category) Object.assign(out, title('Cat', resolved.axisTitles.category));
+  if (resolved.axisTitles.value) Object.assign(out, title('Val', resolved.axisTitles.value));
+  return out;
+}
+
+// ---------------------------------------------------------------------------
+// Classic data labels
+
+const DLBL_POS = Object.freeze({center: 'ctr', 'inside-end': 'inEnd', 'inside-base': 'inBase', 'outside-end': 'outEnd', above: 't', below: 'b', left: 'l', right: 'r'});
+const DLBL_POS_BACK = Object.freeze(Object.fromEntries(Object.entries(DLBL_POS).map(([key, value]) => [value, key])));
+const INSIDE = new Set(['center', 'inside-end', 'inside-base']);
+const escapeXml = value => String(value).replace(/[&<>"']/g, char => ({'&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&apos;'}[char]));
+
+function labelText(color, size, font) {
+  const face = escapeXml(font);
+  return `<c:txPr><a:bodyPr/><a:lstStyle/><a:p><a:pPr><a:defRPr sz="${size}" b="0" i="0" u="none" strike="noStrike"><a:solidFill><a:srgbClr val="${color}"/></a:solidFill>` +
+    `<a:latin typeface="${face}"/><a:ea typeface="${face}"/><a:cs typeface="${face}"/></a:defRPr></a:pPr><a:endParaRPr lang="en-US"/></a:p></c:txPr>`;
+}
+
+// The flags and position of a label set, in CT_DLbls order after the text properties.
+function labelFlags(labels, {leaderLines}) {
+  const has = part => labels.content.includes(part) ? 1 : 0;
+  return (labels.position === null ? '' : `<c:dLblPos val="${DLBL_POS[labels.position]}"/>`) +
+    '<c:showLegendKey val="0"/>' +
+    `<c:showVal val="${has('value')}"/><c:showCatName val="${has('category')}"/><c:showSerName val="0"/><c:showPercent val="${has('percent')}"/><c:showBubbleSize val="0"/>` +
+    `<c:separator>${escapeXml(labels.separator)}</c:separator>` +
+    (leaderLines ? '<c:showLeaderLines val="0"/>' : '');
+}
+
+const dLbl = (index, color, labels, {size, font}) =>
+  `<c:dLbl><c:idx val="${index}"/><c:numFmt formatCode="General" sourceLinked="0"/><c:spPr><a:noFill/><a:ln><a:noFill/></a:ln></c:spPr>${labelText(color, size, font)}${labelFlags(labels, {leaderLines: false})}</c:dLbl>`;
+
+/**
+ * Rewrite the c:dLbls of a generated classic chart for the resolved data labels. PptxGenJS writes labels per series and per
+ * chart group, with a "General" or "#,##0" number format that differs by type and, on pie and doughnut charts, per point
+ * overrides that hide every label; this writes one consistent block everywhere:
+ *
+ *   - the General number format (the preview prints values the same way) and an explicit separator;
+ *   - c:dLblPos only where the chart type has a position choice (core's support table; area, doughnut and radar have none);
+ *   - the label text colour: the chart text colour outside a mark, the contrasting colour (core's `textColorForFill`, as the
+ *     preview) inside one, per series, and per point on pie and doughnut charts.
+ *
+ * `info`: {resolved, kind, palette (series colours, hex without #), labelColor, font, textSize, pointCount}.
+ */
+export function applyDataLabels(xml, info) {
+  const {resolved, kind, palette, labelColor, font, textSize, pointCount} = info;
+  const labels = resolved.dataLabels;
+  // Where the label sits on its mark: a bar or pie label placed inside the mark, and the labels of an area or a doughnut ring,
+  // take the colour that contrasts with the mark; every other label keeps the chart text colour (as the preview does).
+  const inside = kind === 'area' || kind === 'doughnut' || (['bar', 'pie', 'histogram', 'pareto', 'waterfall'].includes(kind) && INSIDE.has(labels.position));
+  const contrast = fill => typeof opfCore.textColorForFill === 'function' ? String(opfCore.textColorForFill(`#${fill}`, `#${labelColor}`)).replace(/^#/, '').toUpperCase() : labelColor;
+  const block = (color, {points = 0, leaderLines = false} = {}) =>
+    `<c:dLbls>${Array.from({length: points}, (_, index) => dLbl(index, inside ? contrast(palette[index % palette.length]) : labelColor, labels, {size: textSize, font})).join('')}` +
+    `<c:numFmt formatCode="General" sourceLinked="0"/><c:spPr><a:noFill/><a:ln><a:noFill/></a:ln></c:spPr>${labelText(color, textSize, font)}${labelFlags(labels, {leaderLines})}</c:dLbls>`;
+  const circular = kind === 'pie' || kind === 'doughnut';
+  const replaceBlocks = (text, make) => text.replace(/<c:dLbls>[\s\S]*?<\/c:dLbls>/g, existing => make(existing));
+  // Series-level blocks first (the colour follows the series), then the group-level block each chart group carries.
+  let seriesIndex = 0;
+  const withSeries = xml.replace(/<c:ser>[\s\S]*?<\/c:ser>/g, ser => {
+    const index = seriesIndex++;
+    const color = inside && !circular ? contrast(palette[index % palette.length]) : labelColor;
+    return replaceBlocks(ser, existing => block(color, {points: circular ? pointCount : 0, leaderLines: /<c:showLeaderLines\b/.test(existing)}));
+  });
+  const outside = withSeries.split(/(<c:ser>[\s\S]*?<\/c:ser>)/);
+  const groupLevel = outside.map((part, index) => index % 2 ? part : replaceBlocks(part, existing => block(labelColor, {leaderLines: /<c:showLeaderLines\b/.test(existing)}))).join('');
+  // A chart type without a series- or group-level c:dLbls (scatter and radar carry only the group one) is covered above; one with
+  // neither is left as written (every generated type has at least one).
+  return groupLevel;
+}
+
+// ---------------------------------------------------------------------------
+// Import (classic)
+
+const asArray = value => value === undefined ? [] : Array.isArray(value) ? value : [value];
+const text = node => {
+  if (node === undefined || node === null) return '';
+  if (typeof node === 'string') return node;
+  if (typeof node === 'number') return String(node);
+  if (Array.isArray(node)) return node.map(text).join('');
+  return node['#text'] !== undefined ? String(node['#text']) : '';
+};
+const flag = node => node !== undefined && node?.val !== '0' && node?.val !== 'false' && node?.val !== 0;
+
+// The rich-text paragraphs of a c:title (or cx:txData), joined into one plain string; undefined when the title carries no text.
+function titleString(title) {
+  const rich = title?.['c:tx']?.['c:rich'];
+  if (!rich) return undefined;
+  const value = asArray(rich['a:p']).map(paragraph => asArray(paragraph['a:r']).map(run => text(run['a:t'])).join('')).join(' ').trim();
+  return value || undefined;
+}
+
+/**
+ * The options of a parsed classic chart (fast-xml-parser, prefixes kept, attributes plain): `{axisTitles?, legend?, dataLabels?}`
+ * plus `notes` naming what the three fields cannot express. `defaults` is what an export writes without the field:
+ * `{legend: 'right' | undefined}` (a legend at the right of multi-series, pie and doughnut charts) and the chart kind.
+ */
+export function chartOptionsFromClassic(chartSpace, {chartNode, target, seriesCount, circular, scatter}) {
+  // An older core's schema has no such fields (additionalProperties is false), so nothing is added to the imported chart.
+  if (!coreKnowsChartOptions()) return {options: {}, notes: []};
+  const chart = chartSpace?.['c:chart'];
+  const plotArea = chart?.['c:plotArea'];
+  const out = {};
+  const notes = [];
+
+  const axisTitles = {};
+  if (scatter) {
+    const [x, y] = asArray(plotArea?.['c:valAx']);
+    const xTitle = titleString(x?.['c:title']), yTitle = titleString(y?.['c:title']);
+    if (xTitle) axisTitles.category = xTitle;
+    if (yTitle) axisTitles.value = yTitle;
+  } else if (!circular) {
+    const category = titleString(asArray(plotArea?.['c:catAx'])[0]?.['c:title']), value = titleString(asArray(plotArea?.['c:valAx'])[0]?.['c:title']);
+    if (category) axisTitles.category = category;
+    if (value) axisTitles.value = value;
+  }
+  if (Object.keys(axisTitles).length) out.axisTitles = axisTitles;
+
+  const defaultLegend = circular || seriesCount > 1;
+  const legend = chart?.['c:legend'];
+  if (legend) {
+    const pos = legend['c:legendPos']?.val ?? 'r';
+    const mapped = LEGEND_POS_BACK[pos];
+    if (!mapped) notes.push({option: 'legend', message: `The legend position '${pos}' (top right) has no OPF equivalent; it imports as 'right'.`});
+    const position = mapped ?? 'right';
+    if (!(defaultLegend && position === 'right')) out.legend = position;
+  } else if (defaultLegend) out.legend = 'none';
+
+  const dataLabels = classicDataLabels(chartNode, target, notes);
+  if (dataLabels !== undefined) out.dataLabels = dataLabels;
+  return {options: out, notes};
+}
+
+function classicDataLabels(chartNode, target, notes) {
+  const series = asArray(chartNode?.['c:ser']);
+  // The labels the chart shows: the first series' block when it has one (PptxGenJS writes pie and doughnut visibility as per
+  // point overrides), else the chart group's block.
+  const serLabels = series.map(entry => entry?.['c:dLbls']).find(block => block !== undefined);
+  const block = serLabels ?? chartNode?.['c:dLbls'];
+  if (!block) return undefined;
+  const points = asArray(block['c:dLbl']);
+  const source = points.length ? points.find(point => String(point?.['c:idx']?.val) === '0') ?? points[0] : block;
+  const content = [];
+  if (flag(source['c:showCatName'])) content.push('category');
+  if (flag(source['c:showVal'])) content.push('value');
+  if (flag(source['c:showPercent'])) content.push('percent');
+  if (!content.length) return undefined;
+  for (const hidden of ['c:showSerName', 'c:showLegendKey', 'c:showBubbleSize']) {
+    if (flag(source[hidden])) notes.push({option: 'dataLabels', message: `Data labels that show ${hidden.slice(6)} cannot be expressed; only category, value and percent import.`});
+  }
+  const support = target && typeof opfCore.chartOptionSupport === 'function' ? opfCore.chartOptionSupport(target) : undefined;
+  const numberFormat = source['c:numFmt']?.formatCode ?? block['c:numFmt']?.formatCode;
+  if (numberFormat && numberFormat !== 'General' && numberFormat !== '#,##0' && numberFormat !== '0%') notes.push({option: 'dataLabels', message: `The label number format '${numberFormat}' cannot be expressed; labels import in the General format.`});
+  const out = {};
+  const position = DLBL_POS_BACK[source['c:dLblPos']?.val ?? block['c:dLblPos']?.val];
+  const supported = support?.dataLabels.positions ?? [];
+  if (position && position !== support?.dataLabels.defaultPosition) {
+    if (!support || supported.includes(position)) out.position = position;
+    else notes.push({option: 'dataLabels.position', message: `The label position '${position}' is not available on this chart type; it imports as the default.`});
+  }
+  const separator = text(source['c:separator'] ?? block['c:separator']);
+  if (content.length > 1 && separator && separator !== ', ') out.separator = separator;
+  const nonDefaultContent = !(content.length === 1 && content[0] === 'value');
+  if (nonDefaultContent) out.content = content;
+  return Object.keys(out).length ? out : true;
+}
+
+/** The core option target of a chart type id (undefined for an id outside the catalog or an older core). */
+export function chartTargetFor(typeId) {
+  return typeof opfCore.chartOptionTarget === 'function' ? opfCore.chartOptionTarget(typeId) : undefined;
+}
+
+// ---------------------------------------------------------------------------
+// Import (chartex)
+
+const CX_POSITION_BACK = Object.freeze({ctr: 'center', inEnd: 'inside-end', inBase: 'inside-base', outEnd: 'outside-end'});
+const cxFlag = value => value === '1' || value === 'true' || value === true || value === 1;
+
+function axisTitleText(axis) {
+  const value = axis?.['cx:title'];
+  // Rich text (what PowerPoint writes for a typed title, and what this exporter writes) or cached formula text (cx:txData/cx:v).
+  const rich = value?.['cx:tx']?.['cx:rich'];
+  if (rich) {
+    const typed = asArray(rich['a:p']).map(paragraph => asArray(paragraph['a:r']).map(run => text(run['a:t'])).join('')).join(' ').trim();
+    if (typed) return typed;
+  }
+  const v = value?.['cx:tx']?.['cx:txData']?.['cx:v'];
+  return v === undefined ? undefined : (text(v).trim() || undefined);
+}
+
+/**
+ * The options of a parsed cx:chartSpace: `{axisTitles?, legend?, dataLabels?}` plus `notes`. A chartex export without the option
+ * writes the construct's defaults (a right legend on a multi-series box-and-whisker chart; category names on a treemap, values
+ * on a funnel), so only what differs from them is returned.
+ */
+export function chartOptionsFromChartex(space, {type, seriesCount}) {
+  if (!coreKnowsChartOptions()) return {options: {}, notes: []};
+  const chart = space?.['cx:chart'];
+  const out = {};
+  const notes = [];
+  const axes = asArray(chart?.['cx:plotArea']?.['cx:axis']);
+  const axisTitles = {};
+  const category = axisTitleText(axes.find(axis => String(axis?.id) === '0')), value = axisTitleText(axes.find(axis => String(axis?.id) === '1'));
+  if (category) axisTitles.category = category;
+  if (value) axisTitles.value = value;
+  if (Object.keys(axisTitles).length) out.axisTitles = axisTitles;
+
+  const boxWhisker = type === 'box-and-whisker';
+  const legend = chart?.['cx:legend'];
+  if (legend) {
+    const mapped = LEGEND_POS_BACK[legend.pos ?? 'r'] ?? 'right';
+    if (boxWhisker && !(seriesCount > 1 && mapped === 'right')) out.legend = mapped;
+    else if (!boxWhisker) notes.push({option: 'legend', message: `The '${type}' chart's legend has no OPF option; it is not imported.`});
+  } else if (boxWhisker && seriesCount > 1) out.legend = 'none';
+
+  const series = asArray(chart?.['cx:plotArea']?.['cx:plotAreaRegion']?.['cx:series']).find(entry => entry?.ownerIdx === undefined);
+  const labels = series?.['cx:dataLabels'];
+  const defaultContent = type === 'treemap' ? ['category'] : type === 'funnel' ? ['value'] : undefined;
+  if (labels) {
+    const visibility = labels['cx:visibility'] ?? {};
+    const content = [];
+    if (cxFlag(visibility.categoryName)) content.push('category');
+    if (cxFlag(visibility.value)) content.push('value');
+    if (cxFlag(visibility.seriesName)) notes.push({option: 'dataLabels', message: 'Chartex data labels that show the series name cannot be expressed; only category and value import.'});
+    const position = CX_POSITION_BACK[labels.pos];
+    const support = typeof opfCore.chartOptionSupport === 'function' && typeof opfCore.chartOptionTarget === 'function' ? opfCore.chartOptionSupport(opfCore.chartOptionTarget(type) ?? {kind: type}) : undefined;
+    const isDefault = defaultContent && content.length === defaultContent.length && content.every((part, index) => part === defaultContent[index]) && (!position || position === 'center');
+    const separator = text(labels['cx:separator']);
+    const result = {};
+    if (!(content.length === 1 && content[0] === 'value')) result.content = content.length ? content : undefined;
+    if (position && position !== support?.dataLabels.defaultPosition && (support?.dataLabels.positions ?? [position]).includes(position)) result.position = position;
+    if (content.length > 1 && separator && separator !== ', ') result.separator = separator;
+    for (const key of Object.keys(result)) if (result[key] === undefined) delete result[key];
+    if (content.length && !(isDefault && !result.separator)) out.dataLabels = Object.keys(result).length ? result : true;
+    else if (!content.length && defaultContent) out.dataLabels = false;
+  } else if (defaultContent) out.dataLabels = false;
+  return {options: out, notes};
+}

package/dist/chartex.js

@@ -16,6 +16,7 @@
 // chart type (an owned `paretoLine` marks the Office Pareto chart), and the
 // cached dimensions restore the category-major data.
 import {CHARTEX_NAMESPACES, chartTypeFromChartex} from './chart-types.js';
+import {chartOptionsFromChartex} from './chart-options.js';
 
 const NS = Object.freeze({
   a: 'http://schemas.openxmlformats.org/drawingml/2006/main',
@@ -126,7 +127,18 @@ function textProperties(labelColor, font, size) {
   return `<cx:txPr><a:bodyPr/><a:lstStyle/><a:p><a:pPr><a:defRPr sz="${size}">${solidFill(labelColor)}<a:latin typeface="${face}"/><a:ea typeface="${face}"/><a:cs typeface="${face}"/></a:defRPr></a:pPr><a:endParaRPr lang="en-US"/></a:p></cx:txPr>`;
 }
 
-function dataLabels(spec, text) {
+const CX_POSITION = Object.freeze({center: 'ctr', 'inside-end': 'inEnd', 'inside-base': 'inBase', 'outside-end': 'outEnd'});
+
+// RR-35: an explicit dataLabels option writes the selected content, position and separator for every construct that takes it;
+// `dataLabels: false` removes the labels a treemap or funnel carries by default. Without the option the defaults are unchanged.
+function dataLabels(spec, text, options) {
+  if (options?.dataLabelsOff) return '';
+  const labels = options?.dataLabels;
+  if (labels) {
+    const has = part => labels.content.includes(part) ? 1 : 0;
+    const position = labels.position === null ? (spec.layoutId === 'treemap' || spec.layoutId === 'funnel' ? 'ctr' : undefined) : CX_POSITION[labels.position];
+    return `<cx:dataLabels${position ? ` pos="${position}"` : ''}>${text}<cx:visibility seriesName="0" categoryName="${has('category')}" value="${has('value')}"/><cx:separator>${escapeXml(labels.separator)}</cx:separator></cx:dataLabels>`;
+  }
   if (spec.layoutId === 'treemap') return `<cx:dataLabels pos="ctr">${text}<cx:visibility seriesName="0" categoryName="1" value="0"/></cx:dataLabels>`;
   if (spec.layoutId === 'funnel') return `<cx:dataLabels pos="ctr">${text}<cx:visibility seriesName="0" categoryName="0" value="1"/></cx:dataLabels>`;
   return '';
@@ -140,14 +152,26 @@ export function chartexPointColors(layoutId, values, palette) {
   return values.map(() => null);
 }
 
-function axes(spec, gridColor, text) {
+// RR-35: an axis title is the plain text of the axis (CT_AxisTitle: tx, spPr, txPr), after the axis scaling.
+// Native check 2026-10-01: PowerPoint empties a title written as cx:txData/cx:v (that form holds a cell formula's cached text, and no
+// cx:f is written), so the title is rich text, the way PowerPoint writes a typed chartex title; the importer reads both forms.
+const axisTitle = (value, text, run) => {
+  if (!value) return '';
+  const face = escapeXml(run.font), size = run.textSize;
+  const props = `sz="${size}" b="0"`;
+  const fill = `<a:solidFill><a:srgbClr val="${run.labelColor}"/></a:solidFill><a:latin typeface="${face}"/><a:ea typeface="${face}"/><a:cs typeface="${face}"/>`;
+  return `<cx:title><cx:tx><cx:rich><a:bodyPr spcFirstLastPara="1" vertOverflow="ellipsis" horzOverflow="overflow" wrap="square" lIns="0" tIns="0" rIns="0" bIns="0" anchor="ctr" anchorCtr="1"/><a:lstStyle/>` +
+    `<a:p><a:pPr algn="ctr"><a:defRPr ${props}>${fill}</a:defRPr></a:pPr><a:r><a:rPr lang="en-US" ${props}>${fill}</a:rPr><a:t>${escapeXml(value)}</a:t></a:r></a:p></cx:rich></cx:tx></cx:title>`;
+};
+
+function axes(spec, gridColor, text, titles = {}, run = {}) {
   if (!spec.axes) return '';
   const gridlines = `<cx:majorGridlines><cx:spPr><a:ln w="9525"><a:solidFill><a:srgbClr val="${gridColor}"><a:alpha val="70000"/></a:srgbClr></a:solidFill></a:ln></cx:spPr></cx:majorGridlines>`;
   const gapWidth = {clusteredColumn: '0.06', paretoLine: '0.06', boxWhisker: '1', waterfall: '0.5', funnel: '0.06'}[spec.layoutId] ?? '1';
   // CT_Axis order: scaling, units, majorGridlines, tickLabels, spPr, txPr.
-  const category = `<cx:axis id="0"><cx:catScaling gapWidth="${gapWidth}"/><cx:tickLabels/>${text}</cx:axis>`;
+  const category = `<cx:axis id="0"><cx:catScaling gapWidth="${gapWidth}"/>${axisTitle(titles.category, text, run)}<cx:tickLabels/>${text}</cx:axis>`;
   if (spec.layoutId === 'funnel') return `${category}<cx:axis id="1" hidden="1"><cx:valScaling/><cx:tickLabels/>${text}</cx:axis>`;
-  const value = `<cx:axis id="1"><cx:valScaling/>${gridlines}<cx:tickLabels/>${text}</cx:axis>`;
+  const value = `<cx:axis id="1"><cx:valScaling/>${axisTitle(titles.value, text, run)}${gridlines}<cx:tickLabels/>${text}</cx:axis>`;
   const percentage = spec.layoutId === 'paretoLine' ? `<cx:axis id="2"><cx:valScaling max="1" min="0"/><cx:units unit="percentage"/><cx:tickLabels/>${text}</cx:axis>` : '';
   return `${category}${value}${percentage}`;
 }
@@ -159,7 +183,7 @@ function axes(spec, gridColor, text) {
  * layout is PptxGenJS's: Sheet1, headings in row 1, categories in column A and
  * one series per following column.
  */
-export function chartexPartXml({spec, series, hasCategories, number, workbookRelId, fill, labelColor, gridColor, font, palette, textSize}) {
+export function chartexPartXml({spec, series, hasCategories, number, workbookRelId, fill, labelColor, gridColor, font, palette, textSize, options}) {
   const rows = series[0].labels.length;
   const range = (letter) => `Sheet1!$${letter}$2:$${letter}$${rows + 1}`;
   const categories = hasCategories
@@ -179,19 +203,23 @@ export function chartexPartXml({spec, series, hasCategories, number, workbookRel
     const line = spec.layoutId === 'boxWhisker' ? `<a:ln w="9525">${solidFill(labelColor)}</a:ln>` : '';
     return `<cx:series layoutId="${spec.owner ?? spec.layoutId}" uniqueId="${seriesUniqueId(number, index)}">` +
       `<cx:tx><cx:txData><cx:f>Sheet1!$${letter}$1</cx:f><cx:v>${escapeXml(entry.name)}</cx:v></cx:txData></cx:tx>` +
-      `<cx:spPr>${solidFill(color)}${line}</cx:spPr>${pointFills}${dataLabels(spec, text)}<cx:dataId val="${index}"/>${layoutProperties(spec, entry, hasCategories)}` +
+      `<cx:spPr>${solidFill(color)}${line}</cx:spPr>${pointFills}${dataLabels(spec, text, options)}<cx:dataId val="${index}"/>${layoutProperties(spec, entry, hasCategories)}` +
       (spec.axes ? '<cx:axisId val="0"/><cx:axisId val="1"/>' : '') + '</cx:series>';
   });
   if (spec.owner) {
     // The Office Pareto chart: the cumulative-percentage line owned by the binned columns, on the percentage axis.
     plotted.push(`<cx:series layoutId="${spec.layoutId}" ownerIdx="0" uniqueId="${seriesUniqueId(number, series.length)}"><cx:spPr><a:ln w="19050"><a:solidFill><a:srgbClr val="${palette[1 % palette.length]}"/></a:solidFill></a:ln></cx:spPr><cx:axisId val="0"/><cx:axisId val="2"/></cx:series>`);
   }
-  const legend = spec.layoutId === 'boxWhisker' && series.length > 1 ? `<cx:legend pos="r" align="ctr" overlay="0">${text}</cx:legend>` : '';
+  // RR-35: a box-and-whisker legend follows the option (`none` removes it, a position moves it); the other constructs take none.
+  const legendPosition = {top: 't', bottom: 'b', left: 'l', right: 'r'}[options?.legend];
+  const legend = spec.layoutId === 'boxWhisker' && options?.legend !== undefined
+    ? (legendPosition ? `<cx:legend pos="${legendPosition}" align="ctr" overlay="0">${text}</cx:legend>` : '')
+    : spec.layoutId === 'boxWhisker' && series.length > 1 ? `<cx:legend pos="r" align="ctr" overlay="0">${text}</cx:legend>` : '';
   const alpha = fill.transparency > 0 ? Math.round((100 - fill.transparency) * 1000) : undefined;
   return '<?xml version="1.0" encoding="UTF-8" standalone="yes"?>' +
     `<cx:chartSpace xmlns:a="${NS.a}" xmlns:r="${NS.r}" xmlns:cx="${NS.cx}">` +
     `<cx:chartData><cx:externalData r:id="${workbookRelId}" cx:autoUpdate="0"/>${data}</cx:chartData>` +
-    `<cx:chart><cx:plotArea><cx:plotAreaRegion>${plotted.join('')}</cx:plotAreaRegion>${axes(spec, gridColor, text)}</cx:plotArea>${legend}</cx:chart>` +
+    `<cx:chart><cx:plotArea><cx:plotAreaRegion>${plotted.join('')}</cx:plotAreaRegion>${axes(spec, gridColor, text, options?.axisTitles, {labelColor, font, textSize})}</cx:plotArea>${legend}</cx:chart>` +
     `<cx:spPr>${solidFill(fill.color, alpha)}<a:ln><a:noFill/></a:ln></cx:spPr>${text}` +
     '</cx:chartSpace>';
 }
@@ -324,7 +352,7 @@ const scalar = value => typeof value === 'string' ? value : value && typeof valu
  * heading recovered from the workbook, `limits` the cache bounds
  * ({points, cells}) and `invalid(message, path)` throws the import error.
  */
-export function chartFromChartex(doc, {heading, limits, invalid, path}) {
+export function chartFromChartex(doc, {heading, limits, invalid, path, report}) {
   const space = doc?.['cx:chartSpace'];
   const region = space?.['cx:chart']?.['cx:plotArea']?.['cx:plotAreaRegion'];
   const allSeries = asArray(region?.['cx:series']);
@@ -384,8 +412,11 @@ export function chartFromChartex(doc, {heading, limits, invalid, path}) {
   if (rowCount === 0) return null;
   if (rowCount * (values.length + (labels ? 1 : 0)) > limits.cells) invalid('chart cache exceeds the 1,000,000-cell import limit', path);
   // A histogram or Pareto chart binned from one value column has no category dimension: the column comes back as authored.
-  if (!labels) return {type, data: {columns: [names[0]], rows: values[0].slice(0, rowCount).map((value, index) => [values[0][index] ?? null])}};
+  // RR-35: axis titles, legend position and data labels read back into the chart's option fields.
+  const {options, notes} = chartOptionsFromChartex(space, {type, seriesCount: plotted.length});
+  for (const note of notes) report?.(note);
+  if (!labels) return {type, data: {columns: [names[0]], rows: values[0].slice(0, rowCount).map((value, index) => [values[0][index] ?? null])}, ...options};
   const rows = [];
   for (let index = 0; index < rowCount; index += 1) rows.push([labels[index] ?? null, ...values.map(row => row[index] ?? null)]);
-  return {type, data: {columns: [heading ?? 'Category', ...names], rows}};
+  return {type, data: {columns: [heading ?? 'Category', ...names], rows}, ...options};
 }

package/dist/code-provenance.js

@@ -1,4 +1,5 @@
 import { XMLParser } from 'fast-xml-parser';
+import { withDisplayedNumbers } from './numbered-list.js';
 
 // Native shape tags are standard PresentationML customer data. Uppercase hex
 // protects case-sensitive source from PowerPoint's case-insensitive Tags API.
@@ -29,7 +30,7 @@ export function attachCodeTags(entries, records) {
 
 export {unhex as decodeTextTag, hex as encodeTextTag};
 
-export function attachTextTags(entries, records, tagName, prefix, kind, {pictures = false} = {}) {
+export function attachTextTags(entries, records, tagName, prefix, kind, {pictures = false, descriptions} = {}) {
   if (!records.size) return;
   let count = 0;
   const seen = new Set(), types = [];
@@ -50,6 +51,9 @@ export function attachTextTags(entries, records, tagName, prefix, kind, {picture
       entries[part] = enc.encode(`<?xml version="1.0" encoding="UTF-8" standalone="yes"?><p:tagLst xmlns:p="${NS}"><p:tag name="${tagName}" val="${hex(records.get(name))}"/></p:tagLst>`);
       types.push(`<Override PartName="/${part}" ContentType="application/vnd.openxmlformats-officedocument.presentationml.tags+xml"/>`);
       rels = rels.replace('</Relationships>',`<Relationship Id="${id}" Type="${REL}" Target="../tags/${prefix}${count}.xml"/></Relationships>`);
+      // Optional alternative text (a:cNvPr descr) for generated decoration such as the metric trend arrow.
+      const descr = descriptions?.get(name);
+      if (descr !== undefined) shape = shape.replace(/<p:cNvPr\b([^>]*?)>/, (_match, attributes) => `<p:cNvPr${attributes} descr="${descr.replace(/&/g,'&amp;').replace(/</g,'&lt;').replace(/"/g,'&quot;')}">`);
       shape = shape.replace(/<p:nvPr\s*\/>/,'<p:nvPr></p:nvPr>');
       if (!shape.includes('</p:nvPr>')) throw new Error(`Generated ${kind} shape has no native application properties.`);
       return shape.replace('</p:nvPr>',`<p:custDataLst><p:tags r:id="${id}"/></p:custDataLst></p:nvPr>`);
@@ -72,26 +76,46 @@ export function nativeShapeParagraphs(xml, rootElement = 'p:sld') {
   const root = children(reader.parse(xml),rootElement)[0];
   const tree = children(children(root,'p:cSld')[0],'p:spTree')[0];
   return orderedShapes(tree).map(shape=>children(children(shape,'p:txBody')[0],'a:p').map(paragraph=>{
-    let text = '', maxFontSize = 0, bullet = false, level = 0;
+    let text = '', maxFontSize = 0, bullet = false, level = 0, math = null, autoNum;
     const fields = [];
-    for (const child of paragraph) {
-      if (child['a:br'] !== undefined) text += '\n';
-      if (child['a:fld'] !== undefined) fields.push({type: String(child[':@']?.type ?? ''), text: children(child['a:fld'],'a:t').map(plainText).join('')});
-      for (const key of ['a:r','a:fld']) if (child[key] !== undefined) {
-        text += children(child[key],'a:t').map(plainText).join('');
-        for (const run of child[key]) {
+    const readRuns = runs => {
+      let value = '';
+      for (const key of ['a:r','a:fld']) if (runs[key] !== undefined) {
+        value += children(runs[key],'a:t').map(plainText).join('');
+        for (const run of runs[key]) {
           const size = Number(run[':@']?.sz);
           if (run['a:rPr'] !== undefined && Number.isFinite(size)) maxFontSize = Math.max(maxFontSize,size/100);
         }
       }
+      return value;
+    };
+    for (const child of paragraph) {
+      if (child['a:br'] !== undefined) text += '\n';
+      if (child['a:fld'] !== undefined) fields.push({type: String(child[':@']?.type ?? ''), text: children(child['a:fld'],'a:t').map(plainText).join('')});
+      text += readRuns(child);
+      if (child['mc:AlternateContent'] !== undefined) {
+        // FF-45: an a14:m math zone (an OMML equation, m:oMathPara) has no OPF model. Its mc:Fallback runs (the text PowerPoint
+        // writes for older readers) are kept as plain text; without them the equation's m:t text is kept in order. The paragraph
+        // records the zones so the importer diagnoses the lost equation layout instead of dropping the paragraph silently.
+        const zones = children(child['mc:AlternateContent'],'mc:Choice').flatMap(choice=>children(choice,'a14:m'));
+        const fallback = children(child['mc:AlternateContent'],'mc:Fallback').flatMap(nodes=>nodes.map(readRuns)).join('');
+        const linear = zones.map(mathText).join('');
+        if (zones.length) math = {zones: (math?.zones ?? 0) + zones.length, text: (math?.text ?? '') + linear};
+        text += fallback || linear;
+      }
       if (child['a:pPr'] !== undefined) {
         level = Number(child[':@']?.lvl ?? 0);
         bullet = child['a:pPr'].some(node=>node['a:buChar'] !== undefined || node['a:buBlip'] !== undefined || node['a:buAutoNum'] !== undefined);
+        // RR-33: a native auto-number; the last bullet element of the paragraph properties wins.
+        const numbering = child['a:pPr'].findLast(node=>node['a:buAutoNum'] !== undefined || node['a:buNone'] !== undefined || node['a:buChar'] !== undefined || node['a:buBlip'] !== undefined);
+        autoNum = numbering?.['a:buAutoNum'] !== undefined ? {type: numbering[':@']?.type, startAt: numbering[':@']?.startAt} : undefined;
       }
     }
-    return {text,maxFontSize,bullet,level,fields};
-  }));
+    return {text,maxFontSize,bullet,level,fields,...(math ? {math} : {}),...(autoNum ? {autoNum} : {})};
+  })).map(withDisplayedNumbers);
 }
+/** The m:t text of an OMML tree in document order (its linear reading, without the equation's layout). */
+export const mathText = nodes => array(nodes).flatMap(node=>Object.entries(node).flatMap(([key,value])=>key === ':@' || key === '#text' ? [] : key === 'm:t' ? [plainText(value)] : mathText(value))).join('');
 
 function sourceFor(value, role, generated) {
   if (generated) return 'code';