@hirokisakabe/pom 0.1.4 → 0.1.6

package/README.md

@@ -1,13 +1,63 @@
 # pom
 
-**pom (PowerPoint Object Model)** は、PowerPoint プレゼンテーション（pptx）を TypeScript で宣言的に記述するためのライブラリです。
+**pom (PowerPoint Object Model)** は、PowerPoint プレゼンテーション（pptx）を TypeScript で宣言的に記述するためのライブラリです。生成 AI に出力させた POM 形式の JSON を、PowerPoint ファイルに変換するユースケースを想定しています。
+
+## 目次
+
+- [インストール](#インストール)
+- [クイックスタート](#クイックスタート)
+- [特徴](#特徴)
+- [ノード](#ノード)
+- [マスタースライド](#マスタースライド)
+- [LLM 連携](#llm-連携)
+- [ライセンス](#ライセンス)
+
+## インストール
+
+```bash
+npm install @hirokisakabe/pom
+```
+
+## クイックスタート
+
+```typescript
+import { buildPptx, POMNode } from "@hirokisakabe/pom";
+
+const slide: POMNode = {
+  type: "vstack",
+  w: "100%",
+  h: "max",
+  padding: 48,
+  gap: 24,
+  alignItems: "start",
+  children: [
+    {
+      type: "text",
+      text: "プレゼンテーションタイトル",
+      fontPx: 48,
+      bold: true,
+    },
+    {
+      type: "text",
+      text: "サブタイトル",
+      fontPx: 24,
+      color: "666666",
+    },
+  ],
+};
+
+const pptx = await buildPptx([slide], { w: 1280, h: 720 });
+await pptx.writeFile({ fileName: "presentation.pptx" });
+```
 
 ## 特徴
 
 - **型安全**: TypeScript による厳密な型定義
 - **宣言的**: JSON ライクなオブジェクトでスライドを記述
+- **PowerPoint ファースト**: Shape 機能をネイティブサポート
 - **柔軟なレイアウト**: VStack/HStack/Box による自動レイアウト
 - **ピクセル単位**: 直感的なピクセル単位での指定（内部でインチに変換）
+- **マスタースライド**: 全ページ共通のヘッダー・フッター・ページ番号を自動挿入
 - **AI フレンドリー**: LLM がコード生成しやすいシンプルな構造
 
 ## ノード
@@ -48,7 +98,11 @@
   type: "text";
   text: string;
   fontPx?: number;
+  color?: string;
   alignText?: "left" | "center" | "right";
+  bold?: boolean;
+  fontFamily?: string;
+  lineSpacingMultiple?: number;
 
   // 共通プロパティ
   w?: number | "max" | `${number}%`;
@@ -57,6 +111,11 @@
 }
 ```
 
+- `color` で文字色を 16 進カラーコード（例: `"FF0000"`）として指定できます。
+- `bold` で太字を指定できます。
+- `fontFamily` でフォントファミリーを指定できます（デフォルト: `"Noto Sans JP"`）。
+- `lineSpacingMultiple` で行間倍率を指定できます（デフォルト: `1.3`）。
+
 #### 2. Image
 
 画像を表示するノード。
@@ -108,7 +167,54 @@
 - `rows` の `height` を省略すると `defaultRowHeight`（未指定なら32px）が適用されます。
 - セル背景やフォント装飾を `cells` の各要素で個別に指定できます。
 
-#### 4. Box
+#### 4. Shape
+
+図形を描画するノード。テキスト付き/なしで異なる表現が可能で、複雑なビジュアル効果をサポートしています。
+
+```typescript
+{
+  type: "shape";
+  shapeType: PptxGenJS.SHAPE_NAME;  // 例: "roundRect", "ellipse", "cloud", "star5" など
+  text?: string;                     // 図形内に表示するテキスト（オプション）
+  fill?: {
+    color?: string;
+    transparency?: number;
+  };
+  line?: {
+    color?: string;
+    width?: number;
+    dashType?: "solid" | "dash" | "dashDot" | "lgDash" | "lgDashDot" | "lgDashDotDot" | "sysDash" | "sysDot";
+  };
+  shadow?: {
+    type: "outer" | "inner";
+    opacity?: number;
+    blur?: number;
+    angle?: number;
+    offset?: number;
+    color?: string;
+  };
+  fontPx?: number;
+  fontColor?: string;
+  alignText?: "left" | "center" | "right";
+
+  // 共通プロパティ
+  w?: number | "max" | `${number}%`;
+  h?: number | "max" | `${number}%`;
+  ...
+}
+```
+
+**主な図形タイプの例:**
+
+- `roundRect`: 角丸長方形（タイトルボックス、カテゴリ表示）
+- `ellipse`: 楕円/円（ステップ番号、バッジ）
+- `cloud`: 雲型（コメント、重要ポイント）
+- `wedgeRectCallout`: 矢印付き吹き出し（注記）
+- `cloudCallout`: 雲吹き出し（コメント）
+- `star5`: 5つ星（強調、デコレーション）
+- `downArrow`: 下矢印（フロー図）
+
+#### 5. Box
 
 単一の子要素をラップする汎用コンテナ。
 
@@ -127,7 +233,7 @@
 }
 ```
 
-#### 5. VStack
+#### 6. VStack
 
 子要素を **縦方向** に並べる。
 
@@ -146,7 +252,7 @@
 }
 ```
 
-#### 6. HStack
+#### 7. HStack
 
 子要素を **横方向** に並べる。
 
@@ -165,49 +271,184 @@
 }
 ```
 
-#### 7. Shape
+## マスタースライド
 
-図形を描画するノード。テキスト付き/なしで異なる表現が可能で、複雑なビジュアル効果をサポートしています。
+全ページに共通のヘッダー・フッター・ページ番号を自動挿入できます。
+
+### 基本的な使い方
 
 ```typescript
-{
-  type: "shape";
-  shapeType: PptxGenJS.SHAPE_NAME;  // 例: "roundRect", "ellipse", "cloud", "star5" など
-  text?: string;                     // 図形内に表示するテキスト（オプション）
-  fill?: {
-    color?: string;
-    transparency?: number;
-  };
-  line?: {
-    color?: string;
-    width?: number;
-    dashType?: "solid" | "dash" | "dashDot" | "lgDash" | "lgDashDot" | "lgDashDotDot" | "sysDash" | "sysDot";
+import { buildPptx } from "@hirokisakabe/pom";
+
+const pptx = await buildPptx(
+  [page1, page2, page3],
+  { w: 1280, h: 720 },
+  {
+    master: {
+      header: {
+        type: "hstack",
+        h: 40,
+        padding: { left: 48, right: 48, top: 12, bottom: 0 },
+        justifyContent: "spaceBetween",
+        alignItems: "center",
+        backgroundColor: "0F172A",
+        children: [
+          {
+            type: "text",
+            text: "会社名",
+            fontPx: 14,
+            color: "FFFFFF",
+          },
+          {
+            type: "text",
+            text: "{{date}}",
+            fontPx: 12,
+            color: "E2E8F0",
+          },
+        ],
+      },
+      footer: {
+        type: "hstack",
+        h: 30,
+        padding: { left: 48, right: 48, top: 0, bottom: 8 },
+        justifyContent: "spaceBetween",
+        alignItems: "center",
+        children: [
+          {
+            type: "text",
+            text: "Confidential",
+            fontPx: 10,
+            color: "1E293B",
+          },
+          {
+            type: "text",
+            text: "Page {{page}} / {{totalPages}}",
+            fontPx: 10,
+            color: "1E293B",
+            alignText: "right",
+          },
+        ],
+      },
+      date: {
+        format: "YYYY/MM/DD", // または "locale"
+      },
+    },
+  },
+);
+```
+
+### マスタースライドのオプション
+
+```typescript
+type MasterSlideOptions = {
+  header?: POMNode; // ヘッダー（任意の POMNode を指定可能）
+  footer?: POMNode; // フッター（任意の POMNode を指定可能）
+  pageNumber?: {
+    position: "left" | "center" | "right"; // ページ番号の位置
   };
-  shadow?: {
-    type: "outer" | "inner";
-    opacity?: number;
-    blur?: number;
-    angle?: number;
-    offset?: number;
-    color?: string;
+  date?: {
+    format: "YYYY/MM/DD" | "locale"; // 日付のフォーマット
   };
-  fontPx?: number;
-  fontColor?: string;
-  alignText?: "left" | "center" | "right";
+};
+```
 
-  // 共通プロパティ
-  w?: number | "max" | `${number}%`;
-  h?: number | "max" | `${number}%`;
-  ...
+### プレースホルダー
+
+ヘッダー・フッター内のテキストで以下のプレースホルダーが使用できます：
+
+- `{{page}}`: 現在のページ番号
+- `{{totalPages}}`: 総ページ数
+- `{{date}}`: 日付（`date.format` で指定した形式）
+
+### 特徴
+
+- **柔軟性**: ヘッダー・フッターには任意の POMNode（VStack、HStack、Box など）を使用可能
+- **自動合成**: 各ページのコンテンツに自動的にヘッダー・フッターが追加されます
+- **動的置換**: プレースホルダーはページごとに自動的に置換されます
+- **後方互換性**: master オプションは省略可能で、既存コードへの影響はありません
+
+## LLM 連携
+
+pom は LLM（GPT-4o、Claude など）で生成した JSON からスライドを作成するユースケースに対応しています。
+
+### 入力用スキーマ
+
+`inputPomNodeSchema` を使って、LLM が生成した JSON を検証できます。
+
+```typescript
+import { inputPomNodeSchema, buildPptx, InputPOMNode } from "@hirokisakabe/pom";
+
+// LLMからのJSON出力を検証
+const jsonFromLLM = `{
+  "type": "vstack",
+  "padding": 48,
+  "gap": 24,
+  "children": [
+    { "type": "text", "text": "タイトル", "fontPx": 32, "bold": true },
+    { "type": "text", "text": "本文テキスト", "fontPx": 16 }
+  ]
+}`;
+
+const parsed = JSON.parse(jsonFromLLM);
+const result = inputPomNodeSchema.safeParse(parsed);
+
+if (result.success) {
+  // 検証成功 - PPTXを生成
+  const pptx = await buildPptx([result.data], { w: 1280, h: 720 });
+  await pptx.writeFile({ fileName: "output.pptx" });
+} else {
+  // 検証失敗 - エラー内容を確認
+  console.error("Validation failed:", result.error.format());
 }
 ```
 
-**主な図形タイプの例:**
+### OpenAI Structured Outputs との連携
 
-- `roundRect`: 角丸長方形（タイトルボックス、カテゴリ表示）
-- `ellipse`: 楕円/円（ステップ番号、バッジ）
-- `cloud`: 雲型（コメント、重要ポイント）
-- `wedgeRectCallout`: 矢印付き吹き出し（注記）
-- `cloudCallout`: 雲吹き出し（コメント）
-- `star5`: 5つ星（強調、デコレーション）
-- `downArrow`: 下矢印（フロー図）
+OpenAI SDK の `zodResponseFormat` を使用して、LLM に直接スキーマ準拠の JSON を生成させることができます。
+
+```typescript
+import { inputPomNodeSchema, buildPptx } from "@hirokisakabe/pom";
+import OpenAI from "openai";
+import { zodResponseFormat } from "openai/helpers/zod";
+
+const openai = new OpenAI();
+
+const response = await openai.chat.completions.create({
+  model: "gpt-4o",
+  messages: [
+    {
+      role: "system",
+      content:
+        "あなたはプレゼンテーション作成アシスタントです。指定されたスキーマに従ってスライドのJSONを生成してください。",
+    },
+    {
+      role: "user",
+      content:
+        "売上報告のスライドを作成して。タイトルと3つの箇条書きを含めて。",
+    },
+  ],
+  response_format: zodResponseFormat(inputPomNodeSchema, "slide"),
+});
+
+const slideData = JSON.parse(response.choices[0].message.content!);
+const pptx = await buildPptx([slideData], { w: 1280, h: 720 });
+await pptx.writeFile({ fileName: "sales-report.pptx" });
+```
+
+### 利用可能な入力用スキーマ
+
+| スキーマ                        | 説明                                           |
+| ------------------------------- | ---------------------------------------------- |
+| `inputPomNodeSchema`            | メインのノードスキーマ（全ノードタイプを含む） |
+| `inputTextNodeSchema`           | テキストノード用                               |
+| `inputImageNodeSchema`          | 画像ノード用                                   |
+| `inputTableNodeSchema`          | テーブルノード用                               |
+| `inputShapeNodeSchema`          | 図形ノード用                                   |
+| `inputBoxNodeSchema`            | Boxノード用                                    |
+| `inputVStackNodeSchema`         | VStackノード用                                 |
+| `inputHStackNodeSchema`         | HStackノード用                                 |
+| `inputMasterSlideOptionsSchema` | マスタースライド設定用                         |
+
+## ライセンス
+
+MIT

package/dist/buildPptx.d.ts

@@ -1,6 +1,8 @@
-import { POMNode } from "./types";
+import { POMNode, MasterSlideOptions } from "./types";
 export declare function buildPptx(nodes: POMNode[], slideSize: {
     w: number;
     h: number;
+}, options?: {
+    master?: MasterSlideOptions;
 }): Promise<import("pptxgenjs").default>;
 //# sourceMappingURL=buildPptx.d.ts.map

package/dist/buildPptx.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"buildPptx.d.ts","sourceRoot":"","sources":["../src/buildPptx.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,OAAO,EAAkB,MAAM,SAAS,CAAC;AAElD,wBAAsB,SAAS,CAC7B,KAAK,EAAE,OAAO,EAAE,EAChB,SAAS,EAAE;IAAE,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAA;CAAE,wCAapC"}
+{"version":3,"file":"buildPptx.d.ts","sourceRoot":"","sources":["../src/buildPptx.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,OAAO,EAAkB,kBAAkB,EAAE,MAAM,SAAS,CAAC;AAiGtE,wBAAsB,SAAS,CAC7B,KAAK,EAAE,OAAO,EAAE,EAChB,SAAS,EAAE;IAAE,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAA;CAAE,EACnC,OAAO,CAAC,EAAE;IAAE,MAAM,CAAC,EAAE,kBAAkB,CAAA;CAAE,wCAgB1C"}

package/dist/buildPptx.js

@@ -1,11 +1,75 @@
 import { calcYogaLayout } from "./calcYogaLayout/calcYogaLayout";
 import { renderPptx } from "./renderPptx/renderPptx";
 import { toPositioned } from "./toPositioned/toPositioned";
-export async function buildPptx(nodes, slideSize) {
+function replacePlaceholders(node, pageNumber, totalPages, date) {
+    if (node.type === "text") {
+        return {
+            ...node,
+            text: node.text
+                .replace(/\{\{page\}\}/g, String(pageNumber))
+                .replace(/\{\{totalPages\}\}/g, String(totalPages))
+                .replace(/\{\{date\}\}/g, date),
+        };
+    }
+    if (node.type === "box") {
+        return {
+            ...node,
+            children: replacePlaceholders(node.children, pageNumber, totalPages, date),
+        };
+    }
+    if (node.type === "vstack" || node.type === "hstack") {
+        return {
+            ...node,
+            children: node.children.map((child) => replacePlaceholders(child, pageNumber, totalPages, date)),
+        };
+    }
+    return node;
+}
+function composePage(content, master, pageNumber, totalPages) {
+    if (!master) {
+        return content;
+    }
+    const date = master.date?.format === "locale"
+        ? new Date().toLocaleDateString()
+        : new Date().toISOString().split("T")[0].replace(/-/g, "/");
+    const children = [];
+    // ヘッダーを追加
+    if (master.header) {
+        children.push(replacePlaceholders(master.header, pageNumber, totalPages, date));
+    }
+    // コンテンツを追加
+    children.push(content);
+    // フッターを追加
+    if (master.footer) {
+        children.push(replacePlaceholders(master.footer, pageNumber, totalPages, date));
+    }
+    // ページ番号を追加
+    if (master.pageNumber) {
+        const pageNumberNode = {
+            type: "text",
+            text: String(pageNumber),
+            fontPx: 12,
+            alignText: master.pageNumber.position,
+        };
+        children.push(pageNumberNode);
+    }
+    return {
+        type: "vstack",
+        w: "100%",
+        h: "100%",
+        alignItems: "stretch",
+        justifyContent: "start",
+        children,
+    };
+}
+export async function buildPptx(nodes, slideSize, options) {
     const positionedPages = [];
-    for (const node of nodes) {
-        await calcYogaLayout(node, slideSize);
-        const positioned = toPositioned(node);
+    const totalPages = nodes.length;
+    for (let i = 0; i < nodes.length; i++) {
+        const node = nodes[i];
+        const composedNode = composePage(node, options?.master, i + 1, totalPages);
+        await calcYogaLayout(composedNode, slideSize);
+        const positioned = toPositioned(composedNode);
         positionedPages.push(positioned);
     }
     const pptx = renderPptx(positionedPages, slideSize);

package/dist/index.d.ts

@@ -1,3 +1,4 @@
 export * from "./types";
+export * from "./inputSchema";
 export { buildPptx } from "./buildPptx";
 //# 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,cAAc,SAAS,CAAC;AACxB,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,SAAS,CAAC;AACxB,cAAc,eAAe,CAAC;AAC9B,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC"}

package/dist/index.js

@@ -1,2 +1,3 @@
 export * from "./types";
+export * from "./inputSchema";
 export { buildPptx } from "./buildPptx";