@office-kit/pptx 0.16.0 → 0.17.0

package/CHANGELOG.md

@@ -1,4 +1,53 @@
-# pptx-kit
+# @office-kit/pptx
+
+## 0.17.0
+
+### Minor Changes
+
+- 71deec5: feat: author every chart type — scatter, bubble, radar, stock, surface, the 3-D variants and pie-of-pie
+
+  `addSlideChart` / `setChartSpec` now write all sixteen plot types of ECMA-376, and `getShapeChartSpec` reads every one of them back.
+
+  - `kind: 'scatter' | 'bubble' | 'radar'` are authorable (they used to throw "read-only"). Scatter and bubble series carry their own `xValues` (and `bubbleSizes`); the embedded workbook lays them out per series so "Edit data" opens onto the right cells.
+  - New kinds `'stock'` (3 series: high, low, close; or 4 with open first, drawn as candlesticks) and `'surface'` (`surfaceContour` for the top-down contour plot, `surfaceWireframe` for the mesh).
+  - 3-D is a modifier: `view3D: { rotX, rotY, rightAngleAxes, perspective, depthPercent, heightPercent }` on `bar` / `column` / `line` / `area` / `pie` selects the 3-D element, with `bar3DShape` (cylinder, cone, pyramid, …), `gapDepthPct` and `seriesAxis`. `bubble3D` shades bubbles as spheres.
+  - `ofPie` turns a pie into a pie-of-pie / bar-of-pie chart.
+  - Per series: `errorBars` / `xErrorBars` (fixed, percentage, standard deviation, standard error, custom), `fillOpacity`.
+  - Per chart: `dataTable`, `upDownBars`, `categoryAxisDate` (date axis with time units), `categoryGroupLevels` (multi-level category labels), `categoryAxisScaling` (the x axis of scatter / bubble charts, or a date axis' range), `plotAreaLayout` / `titleLayout` / `legend.layout` (manual placement), `valueAxisLineHidden` / `categoryAxisLineHidden`, `valueAxis.displayUnitsLabel`.
+  - Data labels gain `showBubbleSize`, `showLegendKey`, `fillColor`, and per-point `text` (a literal label, e.g. naming one scatter point).
+  - A spec whose fields contradict each other (`view3D` on a scatter chart, error bars on a pie, a date axis with non-numeric categories, …) throws with a message naming the field, instead of writing a chart PowerPoint would repair.
+
+  Behavior changes when reading existing decks:
+
+  - A stock chart now reads as `kind: 'stock'` (was `'line'`) and a surface chart as `kind: 'surface'` (was `'column'`). `getPresentationChartKindCounts` has the two new keys.
+  - 3-D charts still read as their flat kind, now with `view3D` set, so `setChartSpec(chart, getShapeChartSpec(shape))` no longer flattens a 3-D chart.
+  - fix: for scatter / bubble charts `valueAxis` (and the other `valueAxis*` fields) described the **x** axis. They now describe the y axis; the x axis reads into `categoryAxis*` and `categoryAxisScaling`.
+  - fix: charts with more than 25 series wrote workbook references past column `Z` as invalid cell addresses.
+
+  `@office-kit/pptx-preview` draws stock charts as lines and surface charts as columns (as before), and honors `categoryAxisScaling` on scatter / bubble charts.
+
+- 71deec5: feat: embed video, audio and online video with `addSlideMedia`, and read them back with `getShapeMedia`
+
+  - `addSlideMedia(slide, { kind: 'video' | 'audio', data, ... })` embeds a clip from bytes; `{ kind: 'online', url }` links an online video. YouTube watch / `youtu.be` / shorts URLs are rewritten to the embed URL; any other `http(s)` URL is stored as given, and anything else throws.
+  - The container is detected from the bytes (mp4, m4v, mov, webm, avi, wmv, mp3, wav, m4a, ogg, wma); pass `format` to override. An undetectable clip, an unreadable `poster`, or a bad URL throws before anything is added to the package.
+  - The new shape is a picture showing the poster frame: `setShapeImage` / `getShapeImageBytes` replace and read it. Without `poster`, a small built-in play-button image is used.
+  - The slide gets the `<p:video>` / `<p:audio>` time node PowerPoint writes itself, which is what makes the play controls appear in the slide show. Identical clip bytes are stored once per deck.
+  - `getShapeMedia(shape)` returns `{ kind: 'video' | 'audio', partName, contentType, bytes }` or `{ kind: 'online', url }`, also for media authored by PowerPoint, PptxGenJS or python-pptx. `findShapesWithMedia(slide)` lists a slide's clips.
+  - `@office-kit/pptx-dsl` gains a `Media` element with the same `kind` / `data` / `url` / `poster` props. It now requires `@office-kit/pptx` >= 0.17.0.
+  - `copyShape` gives the copied clip its own time node, `removeShape` / `clearSlideShapes` remove it, and `importSlide` now carries video / audio parts (copied once per clip) and online-video links across decks — previously an imported slide with media was left with dangling relationships.
+  - `setShapeAnimation` now works on a slide that holds a clip but no animation yet (it used to throw), and `clearSlideAnimations` keeps clips' time nodes instead of removing their play controls.
+  - fix: `duplicateSlide` copied a slide's video / audio bytes for every duplicate, because the library's video / audio / media relationship-type constants did not match the URIs PowerPoint writes. Clips are now shared between the original and the duplicate, as documented.
+  - `validatePresentation` reports a video / audio relationship whose part is missing, and a media time node whose shape is no longer on the slide.
+
+## 0.16.1
+
+### Patch Changes
+
+- b8adc13: Duplicated slides now have independent charts, embedded workbooks and notes.
+  Editing a duplicate no longer changes the original's chart or notes. Unknown
+  owned dependency parts are copied too, including cyclic relationships. Layouts,
+  masters, themes and media remain shared. Invalid missing dependencies fail before
+  parts are added.
 
 ## 0.16.0
 

package/README.md

@@ -28,6 +28,16 @@ const out: Uint8Array = await savePresentation(pres);
 
 ## Why this library
 
+For declarative TSX authoring, use the companion
+[`@office-kit/pptx-dsl`](packages/dsl) and
+[`@office-kit/pptx-dev`](packages/dev) packages. They provide typed elements,
+template editing, a local watch preview and PPTX export, with no React or Vue
+runtime. The dev package initializes a project with VSCode tasks and a
+`CLAUDE.md` authoring guide. Start with the
+[authoring guide](https://office-kit.github.io/pptx/docs/authoring): install the
+Claude Code skill and describe your presentation. The agent handles project
+setup, preview and export using the published npm packages.
+
 - **It reads as well as it writes.** Open a deck made in PowerPoint, Keynote,
   or Google Slides, change it, and save it. Every setter has a getter, and
   there are deck-wide queries (find every hyperlink, every comment by an
@@ -40,9 +50,8 @@ const out: Uint8Array = await savePresentation(pres);
   breaks Keynote is treated as a bug.
 - **One ESM bundle for Node and the browser.** No `fs`, `Buffer`, or `zlib` on
   the hot path, and one runtime dependency ([fflate](https://github.com/101arrowz/fflate), for ZIP).
-- **You ship only what you import.** The API is 451 side-effect-free functions.
-  A `load → save` bundle is about 56 KB unminified; the entire API is about
-  142 KB. CI fails if either grows past its cap (`test/tree-shake.test.ts`).
+- **You ship only what you import.** The API uses side-effect-free functions.
+  CI checks tree-shaking and bundle-size limits (`test/tree-shake.test.ts`).
 - **Types follow the spec.** The model mirrors ECMA-376 Part 1 §19
   (PresentationML). Positions are branded `Emu` numbers, so inches and points
   cannot be mixed up by accident.
@@ -57,26 +66,25 @@ PptxGenJS cannot open it.
 
 Compared against PptxGenJS 4.0.1:
 
-|                                   | `@office-kit/pptx`                                                                           | PptxGenJS                                                 |
-| --------------------------------- | -------------------------------------------------------------------------------------------- | --------------------------------------------------------- |
-| Open and edit an existing `.pptx` | ✅ Load, change, save; unknown parts are preserved                                           | ❌ Creates new files only                                 |
-| Templates                         | Any `.pptx` a designer made in PowerPoint                                                    | Slide masters defined in code (`defineSlideMaster`)       |
-| Read back what is in a deck       | ✅ Every setter has a getter, plus deck-wide queries                                         | ❌ The API is write-only                                  |
-| API shape                         | Tree-shakeable functions (`addSlideChart(slide, …)`)                                         | One class with methods (`slide.addChart(…)`)              |
-| Module formats                    | ESM only                                                                                     | ESM, CommonJS, and a script-tag bundle                    |
-| Runtime dependencies              | 1 (`fflate`)                                                                                 | 4 (`jszip`, `image-size`, `https`, `@types/node`)         |
-| Slide transitions                 | ✅                                                                                           | ❌                                                        |
-| Animations                        | ✅ Four entrance / exit presets                                                              | ❌                                                        |
-| Comments                          | ✅                                                                                           | ❌ (speaker notes only)                                   |
-| Chart types you can author        | Bar, column, line, pie, doughnut, area; combos, secondary axis, trendlines, per-point labels | Those, plus scatter, bubble, radar, and 3D bar            |
-| Audio, video, YouTube embeds      | ❌ Not yet (media already in a deck is preserved)                                            | ✅                                                        |
-| HTML `<table>` to slides          | ❌                                                                                           | ✅ With automatic paging                                  |
-| Render a slide to an image        | ✅ SVG and PNG, via [`@office-kit/pptx-preview`](packages/preview)                           | ❌                                                        |
-| How output is checked             | Open XML SDK validator and ECMA-376 XSDs, in CI                                              | Manual runs in PowerPoint and other apps before a release |
-
-**Pick PptxGenJS** if you only ever generate new decks and need video,
-scatter / bubble / radar charts, HTML-table import, CommonJS, or a
-`<script>`-tag build.
+|                                   | `@office-kit/pptx`                                                                                              | PptxGenJS                                                                        |
+| --------------------------------- | --------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
+| Open and edit an existing `.pptx` | ✅ Load, change, save; unknown parts are preserved                                                              | ❌ Creates new files only                                                        |
+| Templates                         | Any `.pptx` a designer made in PowerPoint                                                                       | Slide masters defined in code (`defineSlideMaster`)                              |
+| Read back what is in a deck       | ✅ Every setter has a getter, plus deck-wide queries                                                            | ❌ The API is write-only                                                         |
+| API shape                         | Tree-shakeable functions (`addSlideChart(slide, …)`)                                                            | One class with methods (`slide.addChart(…)`)                                     |
+| Module formats                    | ESM only                                                                                                        | ESM, CommonJS, and a script-tag bundle                                           |
+| Runtime dependencies              | 1 (`fflate`)                                                                                                    | 4 (`jszip`, `image-size`, `https`, `@types/node`)                                |
+| Slide transitions                 | ✅                                                                                                              | ❌                                                                               |
+| Animations                        | ✅ Four entrance / exit presets                                                                                 | ❌                                                                               |
+| Comments                          | ✅                                                                                                              | ❌ (speaker notes only)                                                          |
+| Chart types you can author        | ✅ All 16 ECMA-376 plot types, incl. 3-D, stock, surface, pie-of-pie; combos, error bars, data table, date axis | Bar, line, area, pie, doughnut, scatter, bubble, radar, 3-D bar / bubble; combos |
+| Audio, video, YouTube embeds      | ✅ Embedded from bytes (Node and browser), with read-back (`getShapeMedia`); clips de-duplicated per deck       | ✅ From a path or base64; write-only                                             |
+| HTML `<table>` to slides          | ❌                                                                                                              | ✅ With automatic paging                                                         |
+| Render a slide to an image        | ✅ SVG and PNG, via [`@office-kit/pptx-preview`](packages/preview)                                              | ❌                                                                               |
+| How output is checked             | Open XML SDK validator and ECMA-376 XSDs, in CI                                                                 | Manual runs in PowerPoint and other apps before a release                        |
+
+**Pick PptxGenJS** if you only ever generate new decks and need HTML-table
+import, CommonJS, or a `<script>`-tag build.
 
 **Pick `@office-kit/pptx`** if a template, an existing deck, or a validation
 requirement is involved, or if you need to read a deck as well as write one.
@@ -85,13 +93,14 @@ The two also work together. Decks written by PptxGenJS are part of this
 library's test fixtures (`test/pptxgenjs-compat.test.ts`), so you can generate
 with PptxGenJS and post-process the result here.
 
-### The same slide in both
+### The same slide with PptxGenJS, the core API, and TSX
 
 ```ts
 // PptxGenJS
 import pptxgen from 'pptxgenjs';
 
 const pptx = new pptxgen();
+pptx.layout = 'LAYOUT_WIDE';
 const slide = pptx.addSlide();
 slide.addText('Q3 Review', { x: 1, y: 0.5, w: 8, h: 1, fontSize: 28, bold: true });
 slide.addChart(
@@ -109,28 +118,21 @@ await pptx.writeFile({ fileName: 'out.pptx' });
 ```
 
 ```ts
-// @office-kit/pptx
-import {
-  addBlankSlide,
-  addSlideChart,
-  addSlideTextBox,
-  createPresentation,
-  inches,
-  setShapeTextFormat,
-} from '@office-kit/pptx';
-import { savePresentationToFile } from '@office-kit/pptx/node';
+// @office-kit/pptx: the Node barrel includes the core API and file helpers.
+import * as pptx from '@office-kit/pptx/node';
 
-const pres = createPresentation();
-const slide = addBlankSlide(pres);
-const title = addSlideTextBox(slide, {
+const { inches } = pptx;
+const pres = pptx.createPresentation();
+const slide = pptx.addBlankSlide(pres);
+const title = pptx.addSlideTextBox(slide, {
   x: inches(1),
   y: inches(0.5),
   w: inches(8),
   h: inches(1),
   text: 'Q3 Review',
 });
-setShapeTextFormat(title, { size: 28, bold: true });
-addSlideChart(slide, {
+pptx.setShapeTextFormat(title, { size: 28, bold: true });
+pptx.addSlideChart(slide, {
   x: inches(1),
   y: inches(1.5),
   w: inches(8),
@@ -141,13 +143,42 @@ addSlideChart(slide, {
     series: [{ name: 'Revenue', values: [120, 180] }],
   },
 });
-await savePresentationToFile(pres, 'out.pptx');
+await pptx.savePresentationToFile(pres, 'out.pptx');
 ```
 
-Two differences show up straight away. Positions are explicit units
-(`inches(1)`, `cm(2.5)`, `pt(12)`) rather than bare numbers, and everything is
-a function that takes the thing it changes, which is what lets a bundler drop
-the ones you do not call.
+```tsx
+// @office-kit/pptx-dsl — deck.tsx
+import { Presentation, Slide, Text, Chart } from '@office-kit/pptx-dsl';
+
+export default (
+  <Presentation>
+    <Slide>
+      <Text x={1} y={0.5} width={8} height={1} size={28} bold>
+        Q3 Review
+      </Text>
+      <Chart
+        x={1}
+        y={1.5}
+        width={8}
+        height={4}
+        spec={{
+          kind: 'column',
+          categories: ['Q1', 'Q2'],
+          series: [{ name: 'Revenue', values: [120, 180] }],
+        }}
+      />
+    </Slide>
+  </Presentation>
+);
+```
+
+Save the TSX example as `deck.tsx` in an
+[initialized authoring project](https://office-kit.github.io/pptx/docs/tsx), then
+run `npx --no-install office-pptx build deck.tsx --out out.pptx`.
+
+The core API uses explicit units (`inches(1)`, `cm(2.5)`, `pt(12)`). The DSL uses
+inches for numeric geometry and points for font sizes, and compiles to the same
+core model. Both produce editable PowerPoint text and charts.
 
 ## How output is checked
 
@@ -178,11 +209,10 @@ of level 4. Items marked "post-1.0" are not implemented yet:
 | L3    | Authoring on top of existing themes / masters / layouts             | ✅                              |
 | L3    | Rebranding a deck: theme colors and theme fonts                     | ✅                              |
 | L3    | Constructing new themes / masters / layouts from scratch            | ❌ post-1.0                     |
-| L3    | Charts: bar, column, line, pie, doughnut, area, and combos          | ✅                              |
-| L3    | Charts: scatter, radar, bubble                                      | Read + preview only             |
+| L3    | Charts: all 16 plot types (incl. 3-D, stock, surface), and combos   | ✅                              |
 | L4    | Notes, comments, transitions                                        | ✅                              |
 | L4    | Simple animations (entrance / exit presets)                         | ✅                              |
-| L4    | Audio / video authoring                                             | ❌ post-1.0 (read pass-through) |
+| L4    | Audio / video / online video: embed, link and read back             | ✅                              |
 | L4    | SmartArt authoring                                                  | ❌ post-1.0 (read pass-through) |
 | L4    | Complex animation timing trees                                      | ❌ post-1.0                     |
 | L4    | OLE / ActiveX authoring                                             | ❌ post-1.0 (read pass-through) |
@@ -239,13 +269,31 @@ const out = await savePresentation(pres);
 
 ## Driving @office-kit/pptx from an AI agent
 
-[`skill/SKILL.md`](skill/SKILL.md) is a self-contained guide for an LLM agent
-authoring presentations with this library: the canonical call for each
-capability, the design rules that keep output from looking template-generated,
-the handful of API footguns worth memorizing, and a QA loop to run before
-declaring a deck done. Its [worked example](skill/examples/business-deck.md) is
-exercised by the test suite, so the code there is known to produce a
-schema-valid deck.
+Install the Claude Code plugin once from the shared [Office Kit marketplace](https://github.com/office-kit/skills):
+
+```sh
+claude plugin marketplace add office-kit/skills
+claude plugin install pptx@office-kit
+```
+
+In Claude Code, open `/plugin` → **Marketplaces** → **office-kit** and enable
+**auto-update** once. Third-party marketplaces do not enable it by default.
+Updates load after `/reload-plugins` or a new session.
+
+Then ask Claude Code:
+
+```text
+/pptx:office-kit-pptx Create a quarterly business review with a revenue chart
+and a next-actions table. Use labelled sample data where needed.
+```
+
+The [skill](skill/SKILL.md) creates a TSX project, starts the view-only preview,
+checks the source and exports an editable PPTX. Ask for changes in the same
+conversation; the preview updates as the agent edits TSX. You need Node.js 22.18+
+and Git alongside Claude Code. See the
+[authoring guide](https://office-kit.github.io/pptx/docs/authoring) for template
+editing and manual setup. The bundled [core reference](skill/references/core-api.md)
+and [tested example](skill/examples/business-deck.md) cover direct API use.
 
 ## Usage
 
@@ -319,7 +367,7 @@ setShapeText(findSlidePlaceholder(slide, 'ctrTitle')!, 'Authored with @office-ki
 const out: Uint8Array = await savePresentation(pres);
 ```
 
-### Build a deck from a blank template
+### Add slides to your own template
 
 ```ts
 import {
@@ -336,7 +384,8 @@ import {
   setShapeText,
 } from '@office-kit/pptx';
 
-const pres = await loadPresentation(await fetch('/blank.pptx').then((r) => r.arrayBuffer()));
+// Layout names come from the template; list them with getSlideLayouts(pres).
+const pres = await loadPresentation(await fetch('/template.pptx').then((r) => r.arrayBuffer()));
 
 const titleLayout = findSlideLayout(pres, 'Title Slide')!;
 const slide1 = addSlide(pres, { layout: titleLayout });
@@ -360,6 +409,49 @@ moveSlide(pres, dup, 0);
 const out: Uint8Array = await savePresentation(pres);
 ```
 
+### Add video, audio or an online video
+
+```ts
+import { addSlideMedia, getShapeMedia, inches } from '@office-kit/pptx';
+
+const box = { x: inches(1), y: inches(1.5), w: inches(8), h: inches(4.5) };
+
+// Embedded video / audio, from bytes. The container is detected from the bytes.
+const clip = addSlideMedia(slide, {
+  kind: 'video',
+  data: mp4Bytes,
+  poster: posterPngBytes,
+  ...box,
+});
+addSlideMedia(slide, {
+  kind: 'audio',
+  data: mp3Bytes,
+  x: inches(0.5),
+  y: inches(6.5),
+  w: inches(0.6),
+  h: inches(0.6),
+});
+
+// Online video. YouTube watch / youtu.be / shorts URLs become the embed URL.
+addSlideMedia(slide2, {
+  kind: 'online',
+  url: 'https://www.youtube.com/watch?v=dQw4w9WgXcQ',
+  ...box,
+});
+
+const media = getShapeMedia(clip);
+// { kind: 'video', partName: '/ppt/media/media1.mp4', contentType: 'video/mp4', bytes }
+// an online video reads back as { kind: 'online', url }
+```
+
+The shape is an ordinary picture showing the poster frame, so `setShapeImage`
+replaces the poster and `getShapeImageBytes` reads it. Without `poster` a neutral
+play-button image is used. Containers detected from the bytes: mp4, m4v, mov,
+webm, avi, wmv, mp3, wav, m4a, ogg, wma — pass `format` when the signature
+check cannot tell which of those a file is. Identical clip bytes are stored once
+per deck, and the clip survives `copyShape`, `duplicateSlide` and `importSlide`.
+Whether a clip plays depends on the codecs of the application showing the deck.
+
 ### Replace an image in place
 
 ```ts
@@ -497,7 +589,7 @@ shown together.
 | Transitions          | `getSlideTransition` / `setSlideTransition` / `clearSlideTransition`                                                                                                                                                                                                                                                                                                                                                                                      |
 | Animations           | `getShapeAnimation` / `setShapeAnimation` (`fadeIn` / `fadeOut` / `appear` / `disappear`), `clearSlideAnimations`                                                                                                                                                                                                                                                                                                                                         |
 | Comments             | `addSlideComment`, `getSlideComments`, `removeSlideComment`, `getCommentAuthors`, `getCommentText` / `getCommentAuthor` / `getCommentPosition`                                                                                                                                                                                                                                                                                                            |
-| Shape authoring      | `addSlideTextBox`, `addSlideShape`, `addSlideLine`, `addSlideTable`, `addSlideImage`, `addSlideChart`                                                                                                                                                                                                                                                                                                                                                     |
+| Shape authoring      | `addSlideTextBox`, `addSlideShape`, `addSlideLine`, `addSlideTable`, `addSlideImage`, `addSlideMedia`, `addSlideChart`                                                                                                                                                                                                                                                                                                                                    |
 | Shape lookup         | `findShapeByName`, `findShapesByName`, `findShapesByKind`, `findShapeInPresentation`, `getAllShapes`, `getSlideShapes`                                                                                                                                                                                                                                                                                                                                    |
 | Shape text           | `setShapeText`, `setShapeParagraphs`, `setShapeBullets`, `setShapeAlignment`, `setShapeTextFormat`, `setShapeHyperlink` / `getShapeHyperlink`                                                                                                                                                                                                                                                                                                             |
 | Per-paragraph        | `setParagraphAlignment` / `getParagraphAlignment`, `setParagraphLevel` / `getParagraphLevel`, `setParagraphBullet` / `getParagraphBullet`, `setParagraphSpacing` / `getParagraphSpacing`, `setParagraphLineSpacing` / `getParagraphLineSpacing`, `getParagraphEndFormat`                                                                                                                                                                                  |