@hirokisakabe/pom 2.0.0 → 3.0.0

package/README.md

@@ -1,25 +1,60 @@
-# pom
+<h1 align="center">pom</h1>
+<p align="center">
+  Declarative PowerPoint generation from XML — built for AI
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@hirokisakabe/pom"><img src="https://img.shields.io/npm/v/@hirokisakabe/pom.svg" alt="npm version"></a>
+  <a href="https://github.com/hirokisakabe/pom/actions/workflows/ci.yml"><img src="https://github.com/hirokisakabe/pom/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+  <a href="https://github.com/hirokisakabe/pom/blob/main/LICENSE"><img src="https://img.shields.io/npm/l/@hirokisakabe/pom.svg" alt="License"></a>
+</p>
+
+<p align="center">
+  <b>pom (PowerPoint Object Model)</b> is a TypeScript library that converts XML into PowerPoint files (.pptx).<br>
+  Flexbox-style layout powered by <a href="https://www.yogalayout.dev/">yoga-layout</a>, rendered with <a href="https://github.com/nicktomlin/pptxgenjs">pptxgenjs</a>.
+</p>
+
+<p align="center">
+  <a href="https://pom-playground.vercel.app/"><b>Try it online — Playground</b></a>
+</p>
+
+<p align="center">
+  <a href="https://pom-playground.vercel.app/">
+    <img src="./docs/images/playground.png" alt="Playground" width="800">
+  </a>
+</p>
+
+---
+
+## Table of Contents
+
+- [Features](#features)
+- [Quick Start](#quick-start)
+- [Available Nodes](#available-nodes)
+- [Node Examples](#node-examples)
+- [Documentation](#documentation)
+- [License](#license)
 
-**pom (PowerPoint Object Model)** is a library for declaratively describing PowerPoint presentations (pptx) in TypeScript. It is designed for use cases where XML in POM format generated by AI is converted into PowerPoint files.
-
-> **[Try it online](https://pom-playground.vercel.app/)** — XML Playground
-
-## Requirements
+## Features
 
-- Node.js 18 or higher (for Node.js environments)
-- Modern browser with ES2020+ support (for browser environments)
+- **AI Friendly** — Simple XML structure designed for LLM code generation. Pair with [LLM Integration guide](./docs/llm-integration.md) for prompt-ready references.
+- **Declarative** — Describe slides as XML. No imperative API calls needed.
+- **Flexible Layout** — Flexbox-style layout with VStack / HStack / Box, powered by yoga-layout.
+- **Rich Nodes** — 15 built-in node types: charts, flowcharts, tables, timelines, org trees, and more.
+- **Schema-validated** — XML input is validated with Zod schemas at runtime with clear error messages.
+- **PowerPoint Native** — Full access to native PowerPoint shape features (roundRect, ellipse, arrows, etc.).
+- **Pixel Units** — Intuitive pixel-based sizing (internally converted to inches at 96 DPI).
+- **Master Slide** — Define headers, footers, and page numbers once — applied to all slides automatically.
+- **Accurate Text Measurement** — Text width measured with opentype.js and bundled Noto Sans JP fonts for consistent layout.
 
-> [!NOTE]
-> pom works in both Node.js and browser environments. Text measurement uses opentype.js with bundled Noto Sans JP fonts, ensuring consistent layout across all environments.
+## Quick Start
 
-## Installation
+> Requires Node.js 18+
 
 ```bash
 npm install @hirokisakabe/pom
 ```
 
-## Quick Start
-
 ```typescript
 import { buildPptx } from "@hirokisakabe/pom";
 
@@ -34,36 +69,121 @@ const pptx = await buildPptx(xml, { w: 1280, h: 720 });
 await pptx.writeFile({ fileName: "presentation.pptx" });
 ```
 
-## Features
-
-- **Schema-validated**: XML input validated with Zod schemas at runtime
-- **Declarative**: Describe slides with XML
-- **PowerPoint First**: Native support for Shape features
-- **Flexible Layout**: Automatic layout with VStack/HStack/Box
-- **Pixel Units**: Intuitive pixel-based sizing (internally converted to inches)
-- **Master Slide**: Automatically insert common headers, footers, and page numbers across all pages
-- **AI Friendly**: Simple structure that makes it easy for LLMs to generate code
-
 ## Available Nodes
 
-| Node         | Description                                           |
-| ------------ | ----------------------------------------------------- |
-| text         | Text with font styling, decoration, and bullet points |
-| image        | Images from file path, URL, or base64                 |
-| table        | Tables with customizable columns and rows             |
-| shape        | PowerPoint shapes (roundRect, ellipse, etc.)          |
-| chart        | Charts (bar, line, pie, area, doughnut, radar)        |
-| timeline     | Timeline/roadmap visualizations                       |
-| matrix       | 2x2 positioning maps                                  |
-| tree         | Organization charts and decision trees                |
-| flow         | Flowcharts with nodes and edges                       |
-| processArrow | Chevron-style process diagrams                        |
-| box          | Container for single child with padding               |
-| vstack       | Vertical stack layout                                 |
-| hstack       | Horizontal stack layout                               |
+| Node         | Description                                    |
+| ------------ | ---------------------------------------------- |
+| Text         | Text with font styling and decoration          |
+| Ul           | Unordered (bullet) list with Li items          |
+| Ol           | Ordered (numbered) list with Li items          |
+| Image        | Images from file path, URL, or base64          |
+| Table        | Tables with customizable columns and rows      |
+| Shape        | PowerPoint shapes (roundRect, ellipse, etc.)   |
+| Chart        | Charts (bar, line, pie, area, doughnut, radar) |
+| Timeline     | Timeline / roadmap visualizations              |
+| Matrix       | 2x2 positioning maps                           |
+| Tree         | Organization charts and decision trees         |
+| Flow         | Flowcharts with nodes and edges                |
+| ProcessArrow | Chevron-style process diagrams                 |
+| Line         | Horizontal / vertical lines                    |
+| Layer        | Absolute-positioned overlay container          |
+| Box          | Container for single child with padding        |
+| VStack       | Vertical stack layout                          |
+| HStack       | Horizontal stack layout                        |
 
 For detailed node documentation, see [Nodes Reference](./docs/nodes.md).
 
+## Node Examples
+
+### Chart
+
+```xml
+<Chart chartType="bar" w="350" h="250" showTitle="true" title="Bar Chart" showLegend="true">
+  <Series name="Q1">
+    <DataPoint label="Jan" value="30" />
+    <DataPoint label="Feb" value="45" />
+  </Series>
+</Chart>
+```
+
+<img src="./docs/images/chart.png" alt="Chart example" width="600">
+
+### Flow
+
+```xml
+<Flow direction="horizontal" w="100%" h="300">
+  <FlowNode id="start" shape="flowChartTerminator" text="Start" color="16A34A" />
+  <FlowNode id="process" shape="flowChartProcess" text="Process" color="1D4ED8" />
+  <FlowNode id="end" shape="flowChartTerminator" text="End" color="DC2626" />
+  <Connection from="start" to="process" />
+  <Connection from="process" to="end" />
+</Flow>
+```
+
+<img src="./docs/images/flow.png" alt="Flow example" width="600">
+
+### Tree
+
+```xml
+<Tree layout="vertical" nodeShape="roundRect" w="100%" h="400">
+  <TreeItem label="CEO" color="0F172A">
+    <TreeItem label="CTO" color="1D4ED8">
+      <TreeItem label="Dev Team" color="0EA5E9" />
+    </TreeItem>
+    <TreeItem label="CFO" color="16A34A">
+      <TreeItem label="Finance" color="0EA5E9" />
+    </TreeItem>
+  </TreeItem>
+</Tree>
+```
+
+<img src="./docs/images/tree.png" alt="Tree example" width="600">
+
+### Table
+
+```xml
+<Table defaultRowHeight="36">
+  <Column width="80" />
+  <Column width="200" />
+  <Row>
+    <Cell bold="true" backgroundColor="0F172A" color="FFFFFF">ID</Cell>
+    <Cell bold="true" backgroundColor="0F172A" color="FFFFFF">Name</Cell>
+  </Row>
+  <Row>
+    <Cell>001</Cell>
+    <Cell>Project Alpha</Cell>
+  </Row>
+</Table>
+```
+
+<img src="./docs/images/table.png" alt="Table example" width="600">
+
+### Timeline
+
+```xml
+<Timeline direction="horizontal" w="100%" h="200">
+  <TimelineItem date="2024 Q1" title="Phase 1" description="Planning" color="1D4ED8" />
+  <TimelineItem date="2024 Q2" title="Phase 2" description="Development" color="16A34A" />
+  <TimelineItem date="2024 Q3" title="Phase 3" description="Testing" color="0EA5E9" />
+</Timeline>
+```
+
+<img src="./docs/images/timeline.png" alt="Timeline example" width="600">
+
+### ProcessArrow
+
+```xml
+<ProcessArrow direction="horizontal" w="100%" h="100">
+  <Step label="Planning" color="4472C4" />
+  <Step label="Design" color="5B9BD5" />
+  <Step label="Development" color="70AD47" />
+  <Step label="Testing" color="FFC000" />
+  <Step label="Release" color="ED7D31" />
+</ProcessArrow>
+```
+
+<img src="./docs/images/processArrow.png" alt="ProcessArrow example" width="600">
+
 ## Documentation
 
 | Document                                         | Description                             |

package/dist/buildPptx.js

@@ -1,6 +1,6 @@
 import { calcYogaLayout } from "./calcYogaLayout/calcYogaLayout.js";
 import { setTextMeasurementMode, } from "./calcYogaLayout/measureText.js";
-import { parseXml } from "./parseXml.js";
+import { parseXml } from "./parseXml/parseXml.js";
 import { renderPptx } from "./renderPptx/renderPptx.js";
 import { toPositioned } from "./toPositioned/toPositioned.js";
 export async function buildPptx(xml, slideSize, options) {

package/dist/calcYogaLayout/calcYogaLayout.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"calcYogaLayout.d.ts","sourceRoot":"","sources":["../../src/calcYogaLayout/calcYogaLayout.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAA0B,MAAM,aAAa,CAAC;AAcnE;;;;;;GAMG;AACH,wBAAsB,cAAc,CAClC,IAAI,EAAE,OAAO,EACb,SAAS,EAAE;IAAE,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAA;CAAE,iBAiBpC"}
+{"version":3,"file":"calcYogaLayout.d.ts","sourceRoot":"","sources":["../../src/calcYogaLayout/calcYogaLayout.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAA0B,MAAM,aAAa,CAAC;AA6BnE;;;;;;GAMG;AACH,wBAAsB,cAAc,CAClC,IAAI,EAAE,OAAO,EACb,SAAS,EAAE;IAAE,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAA;CAAE,iBAiBpC"}

package/dist/calcYogaLayout/calcYogaLayout.js

@@ -1,8 +1,18 @@
 import { loadYoga } from "yoga-layout/load";
 import { measureText } from "./measureText.js";
-import { measureImage, prefetchImageSize } from "./measureImage.js";
-import { calcTableIntrinsicSize } from "../table/utils.js";
+import { measureImage, prefetchImageSize } from "../shared/measureImage.js";
+import { calcTableIntrinsicSize } from "../shared/tableUtils.js";
 import { measureProcessArrow, measureTimeline, measureMatrix, measureTree, measureFlow, } from "./measureCompositeNodes.js";
+/**
+ * コンポジットノードの最小スケール閾値。
+ * renderPptx/utils/scaleToFit.ts の MIN_SCALE_THRESHOLD と同じ値を維持すること。
+ */
+const MIN_SCALE_THRESHOLD = 0.5;
+/** 制約付きサイズを閾値でクランプする */
+function constrainWithMinScale(intrinsicSize, availableSize) {
+    const minSize = intrinsicSize * MIN_SCALE_THRESHOLD;
+    return Math.max(minSize, Math.min(intrinsicSize, availableSize));
+}
 /**
  * POMNode ツリーを Yoga でレイアウト計算する
  * POMNode ツリーの各ノードに yogaNode プロパティがセットされる
@@ -232,6 +242,37 @@ async function applyStyleToYogaNode(node, yn) {
                 });
             }
             break;
+        case "ul":
+        case "ol":
+            {
+                const combinedText = node.items.map((item) => item.text).join("\n");
+                const fontSizePx = node.fontPx ?? 24;
+                const fontFamily = "Noto Sans JP";
+                const fontWeight = node.bold ? "bold" : "normal";
+                const lineHeight = node.lineSpacingMultiple ?? 1.3;
+                yn.setMeasureFunc((width, widthMode) => {
+                    const maxWidthPx = (() => {
+                        switch (widthMode) {
+                            case yoga.MEASURE_MODE_UNDEFINED:
+                                return Number.POSITIVE_INFINITY;
+                            case yoga.MEASURE_MODE_EXACTLY:
+                            case yoga.MEASURE_MODE_AT_MOST:
+                                return width;
+                        }
+                    })();
+                    const { widthPx, heightPx } = measureText(combinedText, maxWidthPx, {
+                        fontFamily,
+                        fontSizePx,
+                        lineHeight,
+                        fontWeight,
+                    });
+                    return {
+                        width: widthPx,
+                        height: heightPx,
+                    };
+                });
+            }
+            break;
         case "image":
             {
                 const src = node.src;
@@ -262,9 +303,9 @@ async function applyStyleToYogaNode(node, yn) {
                     // テキストがある場合、テキストサイズを測定
                     const text = node.text;
                     const fontSizePx = node.fontPx ?? 24;
-                    const fontFamily = "Noto Sans JP";
+                    const fontFamily = node.fontFamily ?? "Noto Sans JP";
                     const fontWeight = node.bold ? "bold" : "normal";
-                    const lineHeight = 1.3;
+                    const lineHeight = node.lineSpacingMultiple ?? 1.3;
                     yn.setMeasureFunc((width, widthMode) => {
                         const maxWidthPx = (() => {
                             switch (widthMode) {
@@ -292,41 +333,76 @@ async function applyStyleToYogaNode(node, yn) {
             break;
         case "processArrow":
             {
-                yn.setMeasureFunc(() => {
-                    const { width, height } = measureProcessArrow(node);
-                    return { width, height };
+                yn.setMeasureFunc((width, widthMode, height, heightMode) => {
+                    const intrinsic = measureProcessArrow(node);
+                    return {
+                        width: widthMode !== yoga.MEASURE_MODE_UNDEFINED
+                            ? constrainWithMinScale(intrinsic.width, width)
+                            : intrinsic.width,
+                        height: heightMode !== yoga.MEASURE_MODE_UNDEFINED
+                            ? constrainWithMinScale(intrinsic.height, height)
+                            : intrinsic.height,
+                    };
                 });
             }
             break;
         case "timeline":
             {
-                yn.setMeasureFunc(() => {
-                    const { width, height } = measureTimeline(node);
-                    return { width, height };
+                yn.setMeasureFunc((width, widthMode, height, heightMode) => {
+                    const intrinsic = measureTimeline(node);
+                    return {
+                        width: widthMode !== yoga.MEASURE_MODE_UNDEFINED
+                            ? constrainWithMinScale(intrinsic.width, width)
+                            : intrinsic.width,
+                        height: heightMode !== yoga.MEASURE_MODE_UNDEFINED
+                            ? constrainWithMinScale(intrinsic.height, height)
+                            : intrinsic.height,
+                    };
                 });
             }
             break;
         case "matrix":
             {
-                yn.setMeasureFunc(() => {
-                    const { width, height } = measureMatrix(node);
-                    return { width, height };
+                yn.setMeasureFunc((width, widthMode, height, heightMode) => {
+                    const intrinsic = measureMatrix(node);
+                    return {
+                        width: widthMode !== yoga.MEASURE_MODE_UNDEFINED
+                            ? constrainWithMinScale(intrinsic.width, width)
+                            : intrinsic.width,
+                        height: heightMode !== yoga.MEASURE_MODE_UNDEFINED
+                            ? constrainWithMinScale(intrinsic.height, height)
+                            : intrinsic.height,
+                    };
                 });
             }
             break;
         case "tree":
             {
-                yn.setMeasureFunc(() => {
-                    const { width, height } = measureTree(node);
-                    return { width, height };
+                yn.setMeasureFunc((width, widthMode, height, heightMode) => {
+                    const intrinsic = measureTree(node);
+                    return {
+                        width: widthMode !== yoga.MEASURE_MODE_UNDEFINED
+                            ? constrainWithMinScale(intrinsic.width, width)
+                            : intrinsic.width,
+                        height: heightMode !== yoga.MEASURE_MODE_UNDEFINED
+                            ? constrainWithMinScale(intrinsic.height, height)
+                            : intrinsic.height,
+                    };
                 });
             }
             break;
         case "flow":
             {
-                yn.setMeasureFunc(() => {
-                    const { width, height } = measureFlow(node);
-                    return { width, height };
+                yn.setMeasureFunc((width, widthMode, height, heightMode) => {
+                    const intrinsic = measureFlow(node);
+                    return {
+                        width: widthMode !== yoga.MEASURE_MODE_UNDEFINED
+                            ? constrainWithMinScale(intrinsic.width, width)
+                            : intrinsic.width,
+                        height: heightMode !== yoga.MEASURE_MODE_UNDEFINED
+                            ? constrainWithMinScale(intrinsic.height, height)
+                            : intrinsic.height,
+                    };
                 });
             }
             break;

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 export { buildPptx } from "./buildPptx.ts";
 export type { TextMeasurementMode } from "./buildPptx.ts";
-export { ParseXmlError } from "./parseXml.ts";
+export { ParseXmlError } from "./parseXml/parseXml.ts";
 export type { SlideMasterOptions, SlideMasterBackground, SlideMasterMargin, MasterObject, MasterTextObject, MasterImageObject, MasterRectObject, MasterLineObject, SlideNumberOptions, } from "./types.ts";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAC3C,YAAY,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAC1D,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAC9C,YAAY,EACV,kBAAkB,EAClB,qBAAqB,EACrB,iBAAiB,EACjB,YAAY,EACZ,gBAAgB,EAChB,iBAAiB,EACjB,gBAAgB,EAChB,gBAAgB,EAChB,kBAAkB,GACnB,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAC3C,YAAY,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAC1D,OAAO,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AACvD,YAAY,EACV,kBAAkB,EAClB,qBAAqB,EACrB,iBAAiB,EACjB,YAAY,EACZ,gBAAgB,EAChB,iBAAiB,EACjB,gBAAgB,EAChB,gBAAgB,EAChB,kBAAkB,GACnB,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -1,2 +1,2 @@
 export { buildPptx } from "./buildPptx.js";
-export { ParseXmlError } from "./parseXml.js";
+export { ParseXmlError } from "./parseXml/parseXml.js";