@office-kit/pptx-editor 0.1.1 → 0.2.0

package/README.md

@@ -194,7 +194,8 @@ tool with the next release.
 
 - **Names** are the export names (`setShapeFill`, `addSlideShape`, …), sorted.
   Four tools are the editor's own, for finding what the others take:
-  `listSlides`, `listShapes` (refs, kind, bounds and text of each shape),
+  `listSlides`, `listShapes` (refs, kind, bounds and text of each shape, and a
+  chart's kind, title, categories and series values),
   `listLayouts` and `listComments`.
 - **Descriptions** are the exports' TSDoc. **Input schemas** are JSON Schema
   (draft 2020-12) generated from the functions' TypeScript signatures, one
@@ -326,6 +327,38 @@ The merge itself is `mergeDecks(base, ours, theirs)` from
 `@office-kit/pptx-editor/merge`. It has no DOM dependency, for hosts that merge
 on a server, and returns `{ ok: true, bytes }` or `{ ok: false, conflicts }`.
 
+### Small edits without the editor
+
+`@office-kit/pptx-editor/headless` gives an agent that has no editor (on a
+server, say) nine edits for small revisions, as one tool: `setShapeText`,
+`setTableCellText`, `setChartData`, `setShapeTextFormat` (size, bold, italic,
+color of a shape's whole text), `setShapeFill`, `setShapeBounds`,
+`removeShape`, `moveSlide` and `removeSlide`, in one compact schema. Text edits always keep the formatting of the text they do not change.
+It has no DOM dependency and runs in Node.
+
+```ts
+import { loadPresentation, savePresentation } from '@office-kit/pptx';
+import {
+  agentEditSchema,
+  applyAgentEdits,
+  decodeAgentEdits,
+  readForAgent,
+} from '@office-kit/pptx-editor/headless';
+
+const deck = await loadPresentation(bytes);
+const context = readForAgent(deck, null); // slides, notes, shapes, chart values
+// Give the model `agentEditSchema` as one tool's input schema; it answers `{ edits }`.
+const { edits, touchedSlides } = decodeAgentEdits(input.edits);
+await applyAgentEdits(deck, edits);
+const revised = await savePresentation(deck);
+```
+
+`decodeAgentEdits` checks the whole batch without a presentation and throws an
+`AgentEditError` (`index: null`) naming every problem by its JSON Pointer.
+`applyAgentEdits` applies the edits in order; when one fails it rejects with
+that edit's `index`, and the edits before it have been applied, so discard
+the presentation.
+
 ## Behaviour on your page
 
 - **Styles are isolated.** The editor renders inside a shadow root on an

package/dist/{agent-tools-CEZAOXNe.js → agent-tools-EU7Eb-FV.js}

@@ -1,5 +1,17 @@
-import { r as shapeRef } from "./src-BrBOgen_.js";
+import { i as shapeRef } from "./shape-ref-B5iNfYWh.js";
 import * as pptx from "@office-kit/pptx";
+//#region \0rolldown/runtime.js
+var __defProp = Object.defineProperty;
+var __exportAll = (all, no_symbols) => {
+	let target = {};
+	for (var name in all) __defProp(target, name, {
+		get: all[name],
+		enumerable: true
+	});
+	if (!no_symbols) __defProp(target, Symbol.toStringTag, { value: "Module" });
+	return target;
+};
+//#endregion
 //#region src/manifest/tools.generated.ts
 const generatedTools = {
 	notTools: {
@@ -1995,10 +2007,6 @@ const generatedTools = {
 						type: "string",
 						enum: ["in", "out"]
 					},
-					AnimationInOutOrString: { anyOf: [{ $ref: "#/$defs/AnimationInOut" }, {
-						type: "string",
-						enum: ["none", "cross"]
-					}] },
 					Bar3DShape: {
 						type: "string",
 						enum: [
@@ -2074,7 +2082,7 @@ const generatedTools = {
 							type: "string",
 							enum: ["none", "cross"]
 						}],
-						description: "Major-tick mark mode on the category axis (`<c:catAx><c:majorTickMark>`)."
+						description: "Major-tick mark mode on the category axis (`<c:catAx><c:majorTickMark>`).\nDefault: `'none'` on bar / column charts, `'out'` otherwise."
 					},
 					CategoryAxisMinorGridlineColor: {
 						type: "string",
@@ -2093,7 +2101,7 @@ const generatedTools = {
 							type: "string",
 							enum: ["none", "cross"]
 						}],
-						description: "Minor-tick mark mode on the category axis (`<c:catAx><c:minorTickMark>`)."
+						description: "Minor-tick mark mode on the category axis (`<c:catAx><c:minorTickMark>`); default `'none'`."
 					},
 					CategoryAxisNoMultiLevelLabel: {
 						type: "boolean",
@@ -2429,8 +2437,20 @@ const generatedTools = {
 								type: "number",
 								description: "Axis line width in EMU, the mirror of `ChartSpec.valueAxisLineWidthEmu`."
 							},
-							majorTickMark: { $ref: "#/$defs/AnimationInOutOrString" },
-							minorTickMark: { $ref: "#/$defs/AnimationInOutOrString" },
+							majorTickMark: {
+								anyOf: [{ $ref: "#/$defs/AnimationInOut" }, {
+									type: "string",
+									enum: ["none", "cross"]
+								}],
+								description: "Major tick marks; default `'out'`."
+							},
+							minorTickMark: {
+								anyOf: [{ $ref: "#/$defs/AnimationInOut" }, {
+									type: "string",
+									enum: ["none", "cross"]
+								}],
+								description: "Minor tick marks; default `'none'`."
+							},
 							tickLabelPos: {
 								type: "string",
 								enum: [
@@ -2865,7 +2885,7 @@ const generatedTools = {
 					PointDataLabels: {
 						type: "array",
 						items: { anyOf: [{ type: "null" }, { $ref: "#/$defs/ChartDataLabels" }] },
-						description: "Optional per-data-point data-label overrides\n(`<c:dLbls><c:dLbl><c:idx val=\"N\"/>…`). Sparse — `null` slots fall back\nto the series-level `dataLabels`. The reference desktop app draws the per-point element\nover the series defaults, which is how pie / doughnut exporters give each\nslice its own label content and font."
+						description: "Optional per-data-point data-label overrides\n(`<c:dLbls><c:dLbl><c:idx val=\"N\"/>…`). Sparse — `null` slots fall back\nto the series-level `dataLabels`, else the chart-level `dataLabels`, else\nno label. That fallback is written as the series' own `<c:dLbls>`, so\nreading the chart back reports it as the series' `dataLabels`. The\nreference desktop app draws the per-point element\nover the series defaults, which is how pie / doughnut exporters give each\nslice its own label content and font."
 					},
 					PointExplosions: {
 						type: "array",
@@ -3064,7 +3084,7 @@ const generatedTools = {
 							type: "string",
 							enum: ["none", "cross"]
 						}],
-						description: "Minor-tick mark mode on the value axis (`<c:valAx><c:minorTickMark>`)."
+						description: "Minor-tick mark mode on the value axis (`<c:valAx><c:minorTickMark>`); default `'none'`."
 					},
 					ValueAxisOrientation: {
 						type: "string",
@@ -4560,7 +4580,7 @@ const generatedTools = {
 		},
 		{
 			name: "compactPackage",
-			description: "Removes media parts that no rels graph references. Returns the\nlist of removed part names. Useful after a sequence of slide\nremovals leaves orphan images behind.\n\nOnly `/ppt/media/...` parts are considered. The check walks every\n`.rels` part in the package and resolves each internal rel target\nagainst its source part name to build the live media set.",
+			description: "Removes every part that cannot be reached from the package root\n(`/_rels/.rels`) through internal relationships, together with its\n`.rels` part and its `[Content_Types].xml` override. Returns the\nremoved part names.\n\n`removeSlide` removes only the slide and its `.rels`, so the slide's\ncharts, embedded workbooks, notes slide, tags and media stay in the\npackage until this runs. Parts still in use — including layouts no\nslide uses, which their master references — are kept. Any other part\nnothing points at, such as custom data added without a relationship, is\nremoved too. When `/_rels/.rels` does not reach `/ppt/presentation.xml`,\nnothing is removed.",
 			args: [null],
 			input_schema: {
 				type: "object",
@@ -5072,7 +5092,7 @@ const generatedTools = {
 		},
 		{
 			name: "removeSlide",
-			description: "Removes the given slide from the deck. Removes the `<p:sldId>`, the\n`presentation.xml.rels` entry, and the slide part + its `.rels` part.\nLinks to this slide from other slides are cleared to prevent accidental\nretargeting when a slide part name is reused.\n\nMedia parts are intentionally NOT cleaned up — they may be shared\nwith other slides. The freed `sldId` is NOT reused on subsequent\n`addSlide` calls (the reference desktop app's quirk, see plan §Risks).",
+			description: "Removes the given slide from the deck. Removes the `<p:sldId>`, the\n`presentation.xml.rels` entry, and the slide part + its `.rels` part.\nLinks to this slide from other slides are cleared to prevent accidental\nretargeting when a slide part name is reused.\n\nParts the slide referenced (media, charts and their workbooks, the notes\nslide, tags) are left in place because other slides may share them; call\n`compactPackage` afterwards to drop the ones nothing references any more.\nThe freed `sldId` is NOT reused on subsequent `addSlide` calls (the\nreference desktop app's quirk, see plan §Risks).",
 			args: [null, "slide"],
 			input_schema: {
 				type: "object",
@@ -5685,6 +5705,87 @@ const generatedTools = {
 			},
 			output: { type: "null" }
 		},
+		{
+			name: "setChartData",
+			description: "Replaces the data of a bar, column, line, area, pie or doughnut chart.\n\nWhen `kind` is the chart's own and `series` names the same series (in any\norder), only the values change: everything else in the chart, its\nformatting included, is kept. Changing `kind`, or adding, removing or\nrenaming a series, builds the chart again from its title, axis titles,\nlegend, series names and colors, and the rest of its formatting returns\nto the defaults; to keep it, copy the series names exactly as they are\nread. Each series needs one value per category: when changing\n`categories`, pass every series with values of the same length. A pie or\ndoughnut chart takes exactly one series. On a date axis the categories\nare read as date serial numbers (days since 1899-12-30, e.g. `\"45292\"`\nfor 2024-01-01) and must be passed the same way. The embedded workbook\nis rewritten with the new data.\n\nThrows when the chart is of another kind (scatter, bubble, stock,\nsurface, radar, or one this library cannot read), when `categories` or\n`series` is empty, when a series has more or fewer values than there are\ncategories, when a date-axis category is not a number, and when\ncategories change on a chart whose categories have several levels.",
+			args: ["chart", "data"],
+			input_schema: {
+				type: "object",
+				properties: {
+					chart: { $ref: "#/$defs/ChartRef" },
+					data: {
+						type: "object",
+						properties: {
+							kind: {
+								type: "string",
+								enum: [
+									"bar",
+									"column",
+									"line",
+									"pie",
+									"doughnut",
+									"area"
+								]
+							},
+							categories: {
+								type: "array",
+								items: { type: "string" }
+							},
+							series: {
+								type: "array",
+								items: {
+									type: "object",
+									properties: {
+										name: { type: "string" },
+										values: {
+											type: "array",
+											items: { type: ["null", "number"] },
+											description: "One value per category; `null` leaves the point empty."
+										}
+									},
+									required: ["name", "values"],
+									additionalProperties: false
+								},
+								description: "Every series of the chart, in order."
+							}
+						},
+						additionalProperties: false
+					}
+				},
+				required: ["chart", "data"],
+				additionalProperties: false,
+				$defs: {
+					ChartRef: {
+						$ref: "#/$defs/ShapeRef",
+						description: "A chart, by the ShapeRef of the graphic frame that holds it."
+					},
+					ShapeRef: {
+						type: "object",
+						description: "A shape, by its slide and id, as `listShapes` or the user's selection reports it. `slideIndex` and `name` are informational.",
+						properties: {
+							slide: { $ref: "#/$defs/SlideRef" },
+							shapeId: {
+								type: "integer",
+								minimum: 0
+							},
+							slideIndex: {
+								type: "integer",
+								minimum: 0
+							},
+							name: { type: "string" }
+						},
+						required: ["slide", "shapeId"],
+						additionalProperties: false
+					},
+					SlideRef: {
+						type: "string",
+						pattern: "^/ppt/slides/[^/]+\\.xml$",
+						description: "A slide, by its part name as `listSlides` reports it, e.g. \"/ppt/slides/slide1.xml\"."
+					}
+				}
+			},
+			output: { type: "null" }
+		},
 		{
 			name: "setChartSpec",
 			description: "Replaces the chart definition on an existing graphic-frame chart\nshape. Updates the inline `<c:strCache>` / `<c:numCache>` blocks so\nthe reference desktop app renders the new data without opening the embedded\nworkbook. The shape's geometry (position / size / rotation) is\npreserved verbatim.\n\nThe embedded xlsx is re-written too — it's what the \"Edit data\"\naffordance opens. The previous workbook is replaced wholesale (no\nattempt to preserve styles a user added in a spreadsheet app).\n\nPass any `ChartSpec`, including a different `kind` from the\noriginal; this acts as \"change my column chart to a line chart with\nfresh data.\"",
@@ -7416,10 +7517,6 @@ const generatedTools = {
 						type: "string",
 						enum: ["in", "out"]
 					},
-					AnimationInOutOrString: { anyOf: [{ $ref: "#/$defs/AnimationInOut" }, {
-						type: "string",
-						enum: ["none", "cross"]
-					}] },
 					Bar3DShape: {
 						type: "string",
 						enum: [
@@ -7495,7 +7592,7 @@ const generatedTools = {
 							type: "string",
 							enum: ["none", "cross"]
 						}],
-						description: "Major-tick mark mode on the category axis (`<c:catAx><c:majorTickMark>`)."
+						description: "Major-tick mark mode on the category axis (`<c:catAx><c:majorTickMark>`).\nDefault: `'none'` on bar / column charts, `'out'` otherwise."
 					},
 					CategoryAxisMinorGridlineColor: {
 						type: "string",
@@ -7514,7 +7611,7 @@ const generatedTools = {
 							type: "string",
 							enum: ["none", "cross"]
 						}],
-						description: "Minor-tick mark mode on the category axis (`<c:catAx><c:minorTickMark>`)."
+						description: "Minor-tick mark mode on the category axis (`<c:catAx><c:minorTickMark>`); default `'none'`."
 					},
 					CategoryAxisNoMultiLevelLabel: {
 						type: "boolean",
@@ -7854,8 +7951,20 @@ const generatedTools = {
 								type: "number",
 								description: "Axis line width in EMU, the mirror of `ChartSpec.valueAxisLineWidthEmu`."
 							},
-							majorTickMark: { $ref: "#/$defs/AnimationInOutOrString" },
-							minorTickMark: { $ref: "#/$defs/AnimationInOutOrString" },
+							majorTickMark: {
+								anyOf: [{ $ref: "#/$defs/AnimationInOut" }, {
+									type: "string",
+									enum: ["none", "cross"]
+								}],
+								description: "Major tick marks; default `'out'`."
+							},
+							minorTickMark: {
+								anyOf: [{ $ref: "#/$defs/AnimationInOut" }, {
+									type: "string",
+									enum: ["none", "cross"]
+								}],
+								description: "Minor tick marks; default `'none'`."
+							},
 							tickLabelPos: {
 								type: "string",
 								enum: [
@@ -8286,7 +8395,7 @@ const generatedTools = {
 					PointDataLabels: {
 						type: "array",
 						items: { anyOf: [{ type: "null" }, { $ref: "#/$defs/ChartDataLabels" }] },
-						description: "Optional per-data-point data-label overrides\n(`<c:dLbls><c:dLbl><c:idx val=\"N\"/>…`). Sparse — `null` slots fall back\nto the series-level `dataLabels`. The reference desktop app draws the per-point element\nover the series defaults, which is how pie / doughnut exporters give each\nslice its own label content and font."
+						description: "Optional per-data-point data-label overrides\n(`<c:dLbls><c:dLbl><c:idx val=\"N\"/>…`). Sparse — `null` slots fall back\nto the series-level `dataLabels`, else the chart-level `dataLabels`, else\nno label. That fallback is written as the series' own `<c:dLbls>`, so\nreading the chart back reports it as the series' `dataLabels`. The\nreference desktop app draws the per-point element\nover the series defaults, which is how pie / doughnut exporters give each\nslice its own label content and font."
 					},
 					PointExplosions: {
 						type: "array",
@@ -8503,7 +8612,7 @@ const generatedTools = {
 							type: "string",
 							enum: ["none", "cross"]
 						}],
-						description: "Minor-tick mark mode on the value axis (`<c:valAx><c:minorTickMark>`)."
+						description: "Minor-tick mark mode on the value axis (`<c:valAx><c:minorTickMark>`); default `'none'`."
 					},
 					ValueAxisOrientation: {
 						type: "string",
@@ -22957,6 +23066,12 @@ const generatedTools = {
 };
 //#endregion
 //#region src/core/agent-tools.ts
+var agent_tools_exports = /* @__PURE__ */ __exportAll({
+	editorTools: () => editorTools,
+	runTool: () => runTool,
+	schemaErrors: () => schemaErrors,
+	shapeSummary: () => shapeSummary
+});
 const library = pptx;
 const DEFS = "#/$defs/";
 function slideByPartName(presentation, partName) {
@@ -23206,6 +23321,7 @@ const NO_INPUT = {
 	properties: {},
 	additionalProperties: false
 };
+/** A shape as `listShapes` reports it. */
 function shapeSummary(presentation, shape) {
 	const bounds = pptx.getShapeBoundsResolved(presentation, shape);
 	const summary = {
@@ -23222,6 +23338,17 @@ function shapeSummary(presentation, shape) {
 	if (pptx.isTableShape(shape)) {
 		const { rows, cols } = pptx.getTableDimensions(shape);
 		summary.cells = Array.from({ length: rows }, (_, row) => Array.from({ length: cols }, (_, col) => pptx.getTableCellText(pptx.getTableCell(shape, row, col))));
+	} else if (pptx.isChartShape(shape)) {
+		const spec = pptx.getShapeChartSpec(shape);
+		summary.chart = spec && {
+			kind: spec.kind,
+			title: spec.title ?? null,
+			categories: spec.categories,
+			series: spec.series.map(({ name, values }) => ({
+				name,
+				values
+			}))
+		};
 	} else if (pptx.hasShapeText(shape)) summary.text = pptx.getShapeText(shape);
 	return summary;
 }
@@ -23243,7 +23370,7 @@ const readTools = [
 	},
 	{
 		name: "listShapes",
-		description: `Lists the shapes on a slide, back to front: each shape's ref (which other tools take as "shape", or with "row" and "col" added as a table "cell"), its kind, placeholder type, bounds and text (for a table, the text of every cell). Bounds are in EMU: 914400 per inch, 360000 per cm, 12700 per point.`,
+		description: `Lists the shapes on a slide, back to front: each shape's ref (which other tools take as "shape", or with "row" and "col" added as a table "cell"), its kind, placeholder type, bounds and text (for a table, the text of every cell; for a chart, its kind, title, categories and series values, or null when its kind cannot be read; date-axis categories are date serial numbers). Bounds are in EMU: 914400 per inch, 360000 per cm, 12700 per point.`,
 		input_schema: SLIDE_INPUT,
 		read: (presentation, input) => pptx.getSlideShapes(input.slide).map((shape) => shapeSummary(presentation, shape))
 	},
@@ -23284,6 +23411,18 @@ function defsOf(schema) {
 	return schema.$defs ?? {};
 }
 /**
+* The problems with `value` against `schema`, a root schema with its own
+* `$defs`, each named by its JSON Pointer; empty when it matches.
+*/
+function schemaErrors(schema, value) {
+	const checking = {
+		defs: defsOf(schema),
+		errors: []
+	};
+	decode(schema, value, "", checking);
+	return checking.errors;
+}
+/**
 * Runs tool `name` with the model's `input`. Rejects, editing nothing, when
 * there is no such tool or the input does not match its schema; the message
 * lists each problem by its JSON Pointer, for the model to correct.
@@ -23292,12 +23431,8 @@ async function runTool(host, name, input) {
 	const tool = byName.get(name);
 	if (!tool) throw new Error(`There is no tool ${JSON.stringify(name)}. Call one of the tools listed.`);
 	const defs = defsOf(tool.input_schema);
-	const checking = {
-		defs,
-		errors: []
-	};
-	decode(tool.input_schema, input, "", checking);
-	if (checking.errors.length > 0) throw new Error(`Invalid input for ${name}:\n${checking.errors.map((error) => `- ${error}`).join("\n")}`);
+	const errors = schemaErrors(tool.input_schema, input);
+	if (errors.length > 0) throw new Error(`Invalid input for ${name}:\n${errors.map((error) => `- ${error}`).join("\n")}`);
 	const resolve = (presentation) => decode(tool.input_schema, input, "", {
 		defs,
 		errors: [],
@@ -23318,6 +23453,6 @@ async function runTool(host, name, input) {
 	return result;
 }
 //#endregion
-export { editorTools, runTool };
+export { generatedTools as a, shapeSummary as i, runTool as n, schemaErrors as r, agent_tools_exports as t };
 
-//# sourceMappingURL=agent-tools-CEZAOXNe.js.map
+//# sourceMappingURL=agent-tools-EU7Eb-FV.js.map