@hirokisakabe/pom 0.1.12 → 0.2.0

package/README.md

@@ -9,19 +9,6 @@
 > [!NOTE]
 > The PPTX generation feature (`buildPptx`) only works in Node.js environments. However, if you only need the input schema, you can import it from `@hirokisakabe/pom/schema` for use in browser environments.
 
-## Table of Contents
-
-- [Requirements](#requirements)
-- [Installation](#installation)
-- [Quick Start](#quick-start)
-- [Features](#features)
-- [Nodes](#nodes)
-- [Master Slide](#master-slide)
-- [Serverless Environments](#serverless-environments)
-- [LLM Integration](#llm-integration)
-  - [Input Validation in Browser Environments](#input-validation-in-browser-environments)
-- [License](#license)
-
 ## Installation
 
 ```bash
@@ -70,575 +57,34 @@ await pptx.writeFile({ fileName: "presentation.pptx" });
 - **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
 
-## Nodes
-
-### Common Properties
-
-Layout attributes that all nodes can have.
-
-```typescript
-{
-  w?: number | "max" | `${number}%`;
-  h?: number | "max" | `${number}%`;
-  minW?: number;
-  maxW?: number;
-  minH?: number;
-  maxH?: number;
-  padding?: number;
-  backgroundColor?: string;
-  border?: {
-    color?: string;
-    width?: number;
-    dashType?: "solid" | "dash" | "dashDot" | "lgDash" | "lgDashDot" | "lgDashDotDot" | "sysDash" | "sysDot";
-  };
-  borderRadius?: number;
-}
-```
-
-- `backgroundColor` applies a fill to the entire node (e.g., `"F8F9FA"`).
-- `border.width` is specified in px and can be combined with color and `dashType` to control the border.
-- `borderRadius` specifies the corner radius in px. When specified, the background/border shape becomes a rounded rectangle.
-
-### Node List
-
-#### 1. Text
-
-A node for displaying text.
-
-```typescript
-{
-  type: "text";
-  text: string;
-  fontPx?: number;
-  color?: string;
-  alignText?: "left" | "center" | "right";
-  bold?: boolean;
-  fontFamily?: string;
-  lineSpacingMultiple?: number;
-  bullet?: boolean | BulletOptions;
-
-  // Common properties
-  w?: number | "max" | `${number}%`;
-  h?: number | "max" | `${number}%`;
-  ...
-}
-```
-
-- `color` specifies the text color as a hex color code (e.g., `"FF0000"`).
-- `bold` enables bold text.
-- `fontFamily` specifies the font family (default: `"Noto Sans JP"`).
-- `lineSpacingMultiple` specifies the line spacing multiplier (default: `1.3`).
-- `bullet` enables bullet points. Use `true` for default bullets, or an object for detailed settings.
-
-**BulletOptions:**
-
-```typescript
-{
-  type?: "bullet" | "number";  // "bullet": symbol, "number": numbered
-  indent?: number;             // Indent level
-  numberType?: "alphaLcParenBoth" | "alphaLcParenR" | "alphaLcPeriod" |
-               "alphaUcParenBoth" | "alphaUcParenR" | "alphaUcPeriod" |
-               "arabicParenBoth" | "arabicParenR" | "arabicPeriod" | "arabicPlain" |
-               "romanLcParenBoth" | "romanLcParenR" | "romanLcPeriod" |
-               "romanUcParenBoth" | "romanUcParenR" | "romanUcPeriod";
-  numberStartAt?: number;      // Starting number
-}
-```
-
-**Usage Examples:**
-
-```typescript
-// Simple bullet list
-{
-  type: "text",
-  text: "Item 1\nItem 2\nItem 3",
-  bullet: true,
-}
-
-// Numbered list
-{
-  type: "text",
-  text: "Step 1\nStep 2\nStep 3",
-  bullet: { type: "number" },
-}
-
-// Lowercase alphabet (a. b. c.)
-{
-  type: "text",
-  text: "Item A\nItem B\nItem C",
-  bullet: { type: "number", numberType: "alphaLcPeriod" },
-}
-
-// Numbered list starting from 5
-{
-  type: "text",
-  text: "Fifth\nSixth\nSeventh",
-  bullet: { type: "number", numberStartAt: 5 },
-}
-```
-
-#### 2. Image
-
-A node for displaying images.
-
-- If `w` and `h` are not specified, the actual image size is automatically used
-- If size is specified, the image is displayed at that size (aspect ratio is not preserved)
-
-```typescript
-{
-  type: "image";
-  src: string;  // Image path (local path, URL, or base64 data)
-
-  // Common properties
-  w?: number | "max" | `${number}%`;
-  h?: number | "max" | `${number}%`;
-  ...
-}
-```
-
-#### 3. Table
-
-A node for drawing tables. Column widths and row heights are declared in px, with fine-grained control over cell decoration.
-
-```typescript
-{
-  type: "table";
-  columns: { width?: number }[];
-  rows: {
-    height?: number;
-    cells: {
-      text: string;
-      fontPx?: number;
-      color?: string;
-      bold?: boolean;
-      alignText?: "left" | "center" | "right";
-      backgroundColor?: string;
-    }[];
-  }[];
-  defaultRowHeight?: number;
-
-  // Common properties
-  w?: number | "max" | `${number}%`;
-  h?: number | "max" | `${number}%`;
-  ...
-}
-```
-
-- If `columns[].width` is omitted, columns are evenly distributed across the table width.
-- The sum of `columns` becomes the natural width of the table (can be overridden with `w` if needed).
-- If `rows` `height` is omitted, `defaultRowHeight` is applied (32px if unspecified).
-- Cell background and font decoration can be specified individually for each element in `cells`.
-
-#### 4. Shape
-
-A node for drawing shapes. Different representations are possible with or without text, supporting complex visual effects.
-
-```typescript
-{
-  type: "shape";
-  shapeType: PptxGenJS.SHAPE_NAME;  // e.g., "roundRect", "ellipse", "cloud", "star5"
-  text?: string;                     // Text to display inside the shape (optional)
-  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;
-  color?: string;
-  alignText?: "left" | "center" | "right";
-
-  // Common properties
-  w?: number | "max" | `${number}%`;
-  h?: number | "max" | `${number}%`;
-  ...
-}
-```
-
-**Common Shape Types:**
-
-- `roundRect`: Rounded rectangle (title boxes, category displays)
-- `ellipse`: Ellipse/circle (step numbers, badges)
-- `cloud`: Cloud shape (comments, key points)
-- `wedgeRectCallout`: Callout with arrow (annotations)
-- `cloudCallout`: Cloud callout (comments)
-- `star5`: 5-pointed star (emphasis, decoration)
-- `downArrow`: Down arrow (flow diagrams)
-
-#### 5. Box
-
-A generic container that wraps a single child element.
-
-- Only **one** child element
-- Used for grouping with padding or fixed size
-
-```typescript
-{
-  type: "box";
-  children: POMNode;
-
-  // Common properties
-  w?: number | "max" | `${number}%`;
-  h?: number | "max" | `${number}%`;
-  ...
-}
-```
-
-#### 6. VStack
-
-Arranges child elements **vertically**.
-
-```typescript
-{
-  type: "vstack";
-  children: POMNode[];
-  alignItems: "start" | "center" | "end" | "stretch";
-  justifyContent: "start" | "center" | "end" | "spaceBetween";
-  gap?: number;
-
-  // Common properties
-  w?: number | "max" | `${number}%`;
-  h?: number | "max" | `${number}%`;
-  ...
-}
-```
-
-#### 7. HStack
-
-Arranges child elements **horizontally**.
-
-```typescript
-{
-  type: "hstack";
-  children: POMNode[];
-  alignItems: "start" | "center" | "end" | "stretch";
-  justifyContent: "start" | "center" | "end" | "spaceBetween";
-  gap?: number;
-
-  // Common properties
-  w?: number | "max" | `${number}%`;
-  h?: number | "max" | `${number}%`;
-  ...
-}
-```
-
-#### 8. Chart
-
-A node for drawing charts. Supports bar charts, line charts, pie charts, area charts, doughnut charts, and radar charts.
-
-```typescript
-{
-  type: "chart";
-  chartType: "bar" | "line" | "pie" | "area" | "doughnut" | "radar";
-  data: {
-    name?: string;           // Series name
-    labels: string[];        // Category labels
-    values: number[];        // Values
-  }[];
-  showLegend?: boolean;      // Show legend (default: false)
-  showTitle?: boolean;       // Show title (default: false)
-  title?: string;            // Title string
-  chartColors?: string[];    // Data color array (hex color codes)
-  radarStyle?: "standard" | "marker" | "filled";  // Radar-only: chart style
-
-  // Common properties
-  w?: number | "max" | `${number}%`;
-  h?: number | "max" | `${number}%`;
-  ...
-}
-```
-
-**Usage Examples:**
-
-```typescript
-// Bar chart
-{
-  type: "chart",
-  chartType: "bar",
-  w: 600,
-  h: 400,
-  data: [
-    {
-      name: "Sales",
-      labels: ["Jan", "Feb", "Mar", "Apr"],
-      values: [100, 200, 150, 300],
-    },
-    {
-      name: "Profit",
-      labels: ["Jan", "Feb", "Mar", "Apr"],
-      values: [30, 60, 45, 90],
-    },
-  ],
-  showLegend: true,
-  showTitle: true,
-  title: "Monthly Sales & Profit",
-  chartColors: ["0088CC", "00AA00"],
-}
-
-// Pie chart
-{
-  type: "chart",
-  chartType: "pie",
-  w: 400,
-  h: 300,
-  data: [
-    {
-      name: "Market Share",
-      labels: ["Product A", "Product B", "Product C", "Others"],
-      values: [40, 30, 20, 10],
-    },
-  ],
-  showLegend: true,
-  chartColors: ["0088CC", "00AA00", "FF6600", "888888"],
-}
-
-// Radar chart
-{
-  type: "chart",
-  chartType: "radar",
-  w: 400,
-  h: 300,
-  data: [
-    {
-      name: "Skill Assessment",
-      labels: ["Technical", "Design", "PM", "Sales", "Support"],
-      values: [80, 60, 70, 50, 90],
-    },
-  ],
-  showLegend: true,
-  radarStyle: "filled",
-  chartColors: ["0088CC"],
-}
-```
-
-## Master Slide
-
-You can automatically insert common headers, footers, and page numbers across all pages.
-
-### Basic Usage
-
-```typescript
-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: "Company Name",
-            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", // or "locale"
-      },
-    },
-  },
-);
-```
-
-### Master Slide Options
-
-```typescript
-type MasterSlideOptions = {
-  header?: POMNode; // Header (any POMNode can be specified)
-  footer?: POMNode; // Footer (any POMNode can be specified)
-  pageNumber?: {
-    position: "left" | "center" | "right"; // Page number position
-  };
-  date?: {
-    format: "YYYY/MM/DD" | "locale"; // Date format
-  };
-};
-```
-
-### Placeholders
-
-The following placeholders can be used in text within headers and footers:
-
-- `{{page}}`: Current page number
-- `{{totalPages}}`: Total number of pages
-- `{{date}}`: Date (in the format specified by `date.format`)
-
-### Features
-
-- **Flexibility**: Headers and footers can use any POMNode (VStack, HStack, Box, etc.)
-- **Automatic Composition**: Headers and footers are automatically added to each page's content
-- **Dynamic Replacement**: Placeholders are automatically replaced per page
-- **Backward Compatibility**: The master option is optional and has no impact on existing code
-
-## Serverless Environments
-
-pom uses the `canvas` package by default to measure text width and determine line break positions. However, in serverless environments like Vercel or AWS Lambda, Japanese fonts (such as Noto Sans JP) are not installed, which may cause text line breaks to be misaligned.
-
-To address this issue, you can specify the text measurement method using the `textMeasurement` option.
-
-### textMeasurement Option
-
-```typescript
-const pptx = await buildPptx(
-  [slide],
-  { w: 1280, h: 720 },
-  {
-    textMeasurement: "auto", // "canvas" | "fallback" | "auto"
-  },
-);
-```
-
-| Value        | Description                                                                            |
-| ------------ | -------------------------------------------------------------------------------------- |
-| `"canvas"`   | Always use canvas for text width measurement (for environments with fonts installed)   |
-| `"fallback"` | Always use fallback calculation (CJK characters = 1em, alphanumeric = 0.5em estimated) |
-| `"auto"`     | Auto-detect font availability and fall back if unavailable (default)                   |
-
-### Recommended Settings
-
-- **Local development / Docker**: Default (`"auto"`) works fine
-- **Serverless environments**: Default `"auto"` will automatically fall back
-- **Environments with fonts installed**: Explicitly specifying `"canvas"` enables more accurate measurement
-
-## LLM Integration
-
-pom supports use cases where slides are created from JSON generated by LLMs (GPT-4o, Claude, etc.).
-
-### LLM Specification Guide
-
-[`llm-guide.md`](./llm-guide.md) is a compact specification document for having LLMs generate JSON in pom format. Include it in your system prompt.
-
-**Contents:**
-
-- Node list and main properties
-- Standard settings (slide size, padding, gap, font size guidelines)
-- Pattern examples (basic structure, 2-column, table, shapes, charts, etc.)
-- Common mistakes and correct usage
-
-### Input Schema
-
-Use `inputPomNodeSchema` to validate JSON generated by LLMs.
-
-```typescript
-import { inputPomNodeSchema, buildPptx, InputPOMNode } from "@hirokisakabe/pom";
-
-// Validate JSON output from LLM
-const jsonFromLLM = `{
-  "type": "vstack",
-  "padding": 48,
-  "gap": 24,
-  "children": [
-    { "type": "text", "text": "Title", "fontPx": 32, "bold": true },
-    { "type": "text", "text": "Body text", "fontPx": 16 }
-  ]
-}`;
-
-const parsed = JSON.parse(jsonFromLLM);
-const result = inputPomNodeSchema.safeParse(parsed);
-
-if (result.success) {
-  // Validation successful - generate PPTX
-  const pptx = await buildPptx([result.data], { w: 1280, h: 720 });
-  await pptx.writeFile({ fileName: "output.pptx" });
-} else {
-  // Validation failed - check error details
-  console.error("Validation failed:", result.error.format());
-}
-```
-
-### Available Input Schemas
-
-| Schema                          | Description                                |
-| ------------------------------- | ------------------------------------------ |
-| `inputPomNodeSchema`            | Main node schema (includes all node types) |
-| `inputTextNodeSchema`           | For text nodes                             |
-| `inputImageNodeSchema`          | For image nodes                            |
-| `inputTableNodeSchema`          | For table nodes                            |
-| `inputShapeNodeSchema`          | For shape nodes                            |
-| `inputChartNodeSchema`          | For chart nodes                            |
-| `inputBoxNodeSchema`            | For Box nodes                              |
-| `inputVStackNodeSchema`         | For VStack nodes                           |
-| `inputHStackNodeSchema`         | For HStack nodes                           |
-| `inputMasterSlideOptionsSchema` | For master slide settings                  |
-
-### Input Validation in Browser Environments
-
-If you want to validate LLM output in browser environments (SPAs like React, Vue, Svelte), you can import schemas from `@hirokisakabe/pom/schema`. This subpath exports only schemas without Node.js dependencies, so it works in browsers.
-
-```typescript
-// Available in browser environments
-import { inputPomNodeSchema } from "@hirokisakabe/pom/schema";
-
-// Validate response from LLM
-const result = inputPomNodeSchema.safeParse(llmResponse);
-
-if (result.success) {
-  // Validation successful - send to server for PPTX generation
-  await fetch("/api/generate-pptx", {
-    method: "POST",
-    headers: { "Content-Type": "application/json" },
-    body: JSON.stringify(result.data),
-  });
-} else {
-  // Validation failed - show error to user
-  console.error("Validation failed:", result.error.format());
-}
-```
-
-**Difference between `@hirokisakabe/pom` and `@hirokisakabe/pom/schema`:**
-
-| Import Path                | Environment     | Included Features                            |
-| -------------------------- | --------------- | -------------------------------------------- |
-| `@hirokisakabe/pom`        | Node.js         | Everything (PPTX generation, schemas, types) |
-| `@hirokisakabe/pom/schema` | Browser-capable | Schemas and types only (no PPTX generation)  |
+## Available Nodes
+
+| Node         | Description                                    |
+| ------------ | ---------------------------------------------- |
+| text         | Text with font styling 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                        |
+
+For detailed node documentation, see [Nodes Reference](./docs/nodes.md).
+
+## Documentation
+
+| Document                                        | Description                             |
+| ----------------------------------------------- | --------------------------------------- |
+| [Nodes Reference](./docs/nodes.md)              | Complete reference for all node types   |
+| [Master Slide](./docs/master-slide.md)          | Headers, footers, and page numbers      |
+| [Serverless Environments](./docs/serverless.md) | Text measurement options for serverless |
+| [LLM Integration](./docs/llm-integration.md)    | Guide for generating slides with AI/LLM |
 
 ## License
 

package/dist/calcYogaLayout/calcYogaLayout.js

@@ -88,6 +88,11 @@ async function buildPomWithYogaTree(node, parentYoga, parentNode) {
         case "image":
         case "table":
         case "shape":
+        case "timeline":
+        case "matrix":
+        case "tree":
+        case "flow":
+        case "processArrow":
             // 子要素なし
             break;
     }
@@ -345,5 +350,12 @@ async function applyStyleToYogaNode(node, yn) {
                 // テキストがない場合は、明示的にサイズが指定されていることを期待
             }
             break;
+        case "timeline":
+        case "matrix":
+        case "tree":
+        case "flow":
+        case "processArrow":
+            // 明示的にサイズが指定されていることを期待
+            break;
     }
 }