pptx-custom 0.3.0 → 0.4.0

package/README.md

@@ -1,10 +1,11 @@
 # pptx-custom
 
-Utilities to customize PPTX JSON templates in two stages:
+[中文文档](./README.zh-CN.md)
 
-- `applyCustomContent`: replace default slide content from backend JSON text.
-- `applyCustomTheme`: apply user theme settings (palette/font/background).
-- `parseCustomContent`: parse custom content to slide data
+Utilities for customizing `json2pptx` JSON decks in two stages:
+
+- Content stage: map backend slide content into a template deck.
+- Theme stage: replace theme colors/font/background and apply scoped media.
 
 ## Install
 
@@ -12,31 +13,85 @@ Utilities to customize PPTX JSON templates in two stages:
 npm i pptx-custom
 ```
 
-## Usage
+## Exports
+
+- `applyCustomContent(template, input)`
+- `parseCustomContent(raw)`
+- `applyCustomContentToTemplate(template, slides)`
+- `applyCustomTheme(deck, themeInput)`
+
+Types are also exported, including:
+`CustomSlide`, `Deck`, `PptxCustomContentInput`, `PptxCustomThemeInput`,
+`PptxCustomOptions`, `TemplateJson`, `TemplateJsonSlide`, `TemplateJsonElement`,
+`TemplateJsonTheme`.
+
+## Quick Start
 
 ```ts
 import {
   applyCustomContent,
   applyCustomTheme,
   parseCustomContent,
+  applyCustomContentToTemplate
 } from 'pptx-custom'
 
-const deckWithContent = applyCustomContent(templateDeck, backendText)
+const withContent = applyCustomContent(templateDeck, backendText)
 
-const deckWithTheme = applyCustomTheme(deckWithContent, {
+const withTheme = applyCustomTheme(withContent, {
   themeColors: ['#111111', '#333333', '#555555', '#777777', '#999999', '#BBBBBB'],
   fontColor: '#222222',
-  backgroundColor: '#FFFFFF'
+  backgroundColor: '#FFFFFF',
+  backgroundImage: {
+    src: 'https://example.com/background.png',
+    scope: {
+      cover: false,
+      contents: true,
+      transition: true,
+      content: true,
+      end: false
+    }
+  },
+  logoImage: {
+    src: 'https://example.com/logo.png',
+    position: 'right',
+    scope: {
+      cover: true,
+      contents: true,
+      transition: true,
+      content: true,
+      end: true
+    }
+  }
 })
 
 const slides = parseCustomContent(backendText)
-const deckFromSlides = applyCustomContentToTemplate(templateDeck, slides)
-
+const withContentDirect = applyCustomContentToTemplate(templateDeck, slides)
 ```
 
-## Custom Content Format
+## Custom Content Input
+
+`parseCustomContent` and `applyCustomContent` support:
+
+1. NDJSON (one slide per line)
+2. JSON array of slides
+3. JSON object with a `slides` array
+4. JSON object containing a single slide (with `type`)
+
+Supported slide types:
 
-`applyCustomContent` and `parseCustomContent` accept NDJSON-style lines or JSON arrays/objects of slides:
+- `cover`
+- `contents`
+- `transition`
+- `content`
+- `end`
+
+Legacy aliases accepted in input:
+
+- `agenda` -> `contents`
+- `section` -> `transition`
+- `ending` -> `end`
+
+Example NDJSON:
 
 ```json
 {"type":"cover","data":{"title":"Title","text":"Subtitle"}}
@@ -46,8 +101,31 @@ const deckFromSlides = applyCustomContentToTemplate(templateDeck, slides)
 {"type":"end"}
 ```
 
-## Exported APIs
+## Theme Input
 
-- `applyCustomContent(template, input)`
-- `parseCustomContent(raw)`
-- `applyCustomTheme(deck, themeUpdate)`
+`applyCustomTheme` accepts `PptxCustomThemeInput`:
+
+- `themeColors: string[]` (uses first 6)
+- `fontColor: string`
+- `backgroundColor?: string`
+- `backgroundImage?: { src, scope, width?, height? }`
+- `logoImage?: { src, scope, position, width?, height? }`
+- `clearBackgroundImage?: boolean`
+- `clearLogoImage?: boolean`
+
+`scope` keys:
+`cover | contents | transition | content | end`
+
+## Behavior Notes
+
+- Both `applyCustomContent` and `applyCustomTheme` run through `json2pptx-schema`
+  parsing/normalization before returning.
+- `applyCustomContent` selects template slides by `type`, and for `contents/content`
+  prefers layouts with the closest capacity to the requested item count.
+- `applyCustomContent` normalizes logo elements (`imageType: "logo"`) to stay within
+  top margins and removes logo clipping.
+- `applyCustomTheme` inserts scoped background images as slide elements with
+  `imageType: "background"` and logo images with `imageType: "logo"`.
+- When both `backgroundImage` and `backgroundColor` are provided, background color is
+  applied as a 50% alpha overlay color on targeted slides.
+- `clearBackgroundImage` also clears logo images in current behavior.

package/README.zh-CN.md

@@ -0,0 +1,131 @@
+# pptx-custom
+
+[English](./README.md)
+
+用于对 `json2pptx` JSON deck 进行两阶段定制：
+
+- 内容阶段：将后端内容映射到模板 deck。
+- 主题阶段：替换主题色/字体/背景，并按范围应用媒体资源。
+
+## 安装
+
+```bash
+npm i pptx-custom
+```
+
+## 导出 API
+
+- `applyCustomContent(template, input)`
+- `parseCustomContent(raw)`
+- `applyCustomContentToTemplate(template, slides)`
+- `applyCustomTheme(deck, themeInput)`
+
+同时导出类型，包括：
+`CustomSlide`、`Deck`、`PptxCustomContentInput`、`PptxCustomThemeInput`、
+`PptxCustomOptions`、`TemplateJson`、`TemplateJsonSlide`、`TemplateJsonElement`、
+`TemplateJsonTheme`。
+
+## 快速开始
+
+```ts
+import {
+  applyCustomContent,
+  applyCustomTheme,
+  parseCustomContent,
+  applyCustomContentToTemplate
+} from 'pptx-custom'
+
+const withContent = applyCustomContent(templateDeck, backendText)
+
+const withTheme = applyCustomTheme(withContent, {
+  themeColors: ['#111111', '#333333', '#555555', '#777777', '#999999', '#BBBBBB'],
+  fontColor: '#222222',
+  backgroundColor: '#FFFFFF',
+  backgroundImage: {
+    src: 'https://example.com/background.png',
+    scope: {
+      cover: false,
+      contents: true,
+      transition: true,
+      content: true,
+      end: false
+    }
+  },
+  logoImage: {
+    src: 'https://example.com/logo.png',
+    position: 'right',
+    scope: {
+      cover: true,
+      contents: true,
+      transition: true,
+      content: true,
+      end: true
+    }
+  }
+})
+
+const slides = parseCustomContent(backendText)
+const withContentDirect = applyCustomContentToTemplate(templateDeck, slides)
+```
+
+## 自定义内容输入格式
+
+`parseCustomContent` 和 `applyCustomContent` 支持：
+
+1. NDJSON（每行一个 slide）
+2. JSON slide 数组
+3. 带 `slides` 字段的 JSON 对象
+4. 单个 slide JSON 对象（包含 `type`）
+
+支持的 slide 类型：
+
+- `cover`
+- `contents`
+- `transition`
+- `content`
+- `end`
+
+兼容的历史别名：
+
+- `agenda` -> `contents`
+- `section` -> `transition`
+- `ending` -> `end`
+
+NDJSON 示例：
+
+```json
+{"type":"cover","data":{"title":"Title","text":"Subtitle"}}
+{"type":"contents","data":{"items":["Part A","Part B"]}}
+{"type":"transition","data":{"title":"Part A","text":"Section intro"}}
+{"type":"content","data":{"title":"Topic","items":[{"title":"Point","text":"Detail"}]}}
+{"type":"end"}
+```
+
+## 主题输入
+
+`applyCustomTheme` 接收 `PptxCustomThemeInput`：
+
+- `themeColors: string[]`（最多使用前 6 个）
+- `fontColor: string`
+- `backgroundColor?: string`
+- `backgroundImage?: { src, scope, width?, height? }`
+- `logoImage?: { src, scope, position, width?, height? }`
+- `clearBackgroundImage?: boolean`
+- `clearLogoImage?: boolean`
+
+`scope` 可选键：
+`cover | contents | transition | content | end`
+
+## 行为说明
+
+- `applyCustomContent` 与 `applyCustomTheme` 都会在返回前经过
+  `json2pptx-schema` 的解析与规范化。
+- `applyCustomContent` 按 `type` 选模板页；对 `contents/content` 会优先选择
+  与输入条目数容量最接近的布局。
+- `applyCustomContent` 会规范化 logo 元素（`imageType: "logo"`）：
+  保持在顶部边距内，并移除 logo 裁剪配置。
+- `applyCustomTheme` 会将背景图以元素形式写入（`imageType: "background"`），
+  并将 logo 以 `imageType: "logo"` 写入。
+- 当同时提供 `backgroundImage` 与 `backgroundColor` 时，会在目标页应用
+  50% 透明度的背景色叠加效果。
+- 当前行为下，`clearBackgroundImage` 也会同时清除 logo 图片。

package/dist/index.js

@@ -453,6 +453,187 @@ function findMappingForColor(value, mappings) {
   );
 }
 
+// src/custom-theme/media.ts
+var FALLBACK_SLIDE_WIDTH2 = 1e3;
+var FALLBACK_SLIDE_HEIGHT2 = 562.5;
+var LOGO_MARGIN_X2 = 24;
+var LOGO_MARGIN_Y2 = 18;
+var LOGO_MAX_WIDTH_RATIO2 = 0.34;
+var LOGO_MAX_HEIGHT_RATIO2 = 0.16;
+var DEFAULT_LOGO_ASPECT_RATIO = 3.2;
+function mapSlideTypeToScopeKey(type) {
+  const normalized = type?.trim().toLowerCase();
+  if (!normalized) return null;
+  if (normalized === "cover") return "cover";
+  if (normalized === "contents" || normalized === "agenda") return "contents";
+  if (normalized === "transition" || normalized === "section") return "transition";
+  if (normalized === "content") return "content";
+  if (normalized === "end" || normalized === "ending") return "end";
+  return null;
+}
+function isSlideInScope(slide, scope) {
+  const key = mapSlideTypeToScopeKey(slide.type);
+  if (!key) return false;
+  return Boolean(scope[key]);
+}
+function createElementId(prefix, slideIndex) {
+  const random = Math.random().toString(36).slice(2, 10);
+  return `${prefix}-${slideIndex}-${random}`;
+}
+function toHalfOpacityColor(value) {
+  const rgb = parseColorToRgb(value);
+  if (!rgb) return value;
+  return `rgba(${rgb.r},${rgb.g},${rgb.b},0.5)`;
+}
+function buildBackgroundElement(input) {
+  const { src, slideWidth, slideHeight, slideIndex } = input;
+  return {
+    type: "image",
+    id: createElementId("background", slideIndex),
+    src,
+    width: slideWidth,
+    height: slideHeight,
+    left: 0,
+    top: 0,
+    fixedRatio: true,
+    rotate: 0,
+    imageType: "background",
+    filters: {
+      opacity: "100%"
+    }
+  };
+}
+function resolveLogoAspectRatio(width, height) {
+  if (typeof width === "number" && typeof height === "number" && width > 0 && height > 0) {
+    return width / height;
+  }
+  return DEFAULT_LOGO_ASPECT_RATIO;
+}
+function resolveLogoSize(input) {
+  const {
+    slideWidth,
+    slideHeight,
+    logoWidth,
+    logoHeight
+  } = input;
+  const aspectRatio = resolveLogoAspectRatio(logoWidth, logoHeight);
+  const maxWidth = slideWidth * LOGO_MAX_WIDTH_RATIO2;
+  const maxHeight = slideHeight * LOGO_MAX_HEIGHT_RATIO2;
+  let width = maxWidth;
+  let height = width / aspectRatio;
+  if (height > maxHeight) {
+    height = maxHeight;
+    width = height * aspectRatio;
+  }
+  return { width, height };
+}
+function buildLogoElement(input) {
+  const { src, slideWidth, slideIndex, position } = input;
+  const { width, height } = resolveLogoSize(input);
+  const left = position === "left" ? LOGO_MARGIN_X2 : Math.max(LOGO_MARGIN_X2, slideWidth - width - LOGO_MARGIN_X2);
+  return {
+    type: "image",
+    id: createElementId("logo", slideIndex),
+    src,
+    width,
+    height,
+    left,
+    top: LOGO_MARGIN_Y2,
+    fixedRatio: true,
+    rotate: 0,
+    imageType: "logo"
+  };
+}
+function replaceScopedMedia(deck, input) {
+  if (!deck.slides?.length) return deck;
+  const slideWidth = deck.width ?? FALLBACK_SLIDE_WIDTH2;
+  const slideHeight = deck.height ?? FALLBACK_SLIDE_HEIGHT2;
+  const backgroundInput = input.backgroundImage;
+  const logoInput = input.logoImage;
+  const shouldClearBackground = Boolean(input.clearBackgroundImage);
+  const shouldClearLogo = Boolean(input.clearLogoImage || shouldClearBackground);
+  if (!backgroundInput?.src && !logoInput?.src && !shouldClearBackground && !shouldClearLogo) {
+    return deck;
+  }
+  const slides = deck.slides.map((slide, slideIndex) => {
+    let nextElements = slide.elements ? [...slide.elements] : [];
+    let nextBackground = slide.background;
+    let changed = false;
+    if (shouldClearBackground) {
+      const before = nextElements.length;
+      nextElements = nextElements.filter(
+        (element) => !(element.type === "image" && element.imageType === "background")
+      );
+      if (nextElements.length !== before) {
+        changed = true;
+        if (input.backgroundColor) {
+          nextBackground = {
+            ...nextBackground ?? {},
+            type: "solid",
+            color: input.backgroundColor
+          };
+        }
+      }
+    }
+    if (shouldClearLogo) {
+      const before = nextElements.length;
+      nextElements = nextElements.filter(
+        (element) => !(element.type === "image" && element.imageType === "logo")
+      );
+      if (nextElements.length !== before) {
+        changed = true;
+      }
+    }
+    if (backgroundInput?.src && isSlideInScope(slide, backgroundInput.scope)) {
+      const withoutBackground = nextElements.filter(
+        (element) => !(element.type === "image" && element.imageType === "background")
+      );
+      nextElements = [
+        buildBackgroundElement({
+          src: backgroundInput.src,
+          slideWidth,
+          slideHeight,
+          slideIndex
+        }),
+        ...withoutBackground
+      ];
+      changed = true;
+      if (input.backgroundColor) {
+        nextBackground = {
+          ...nextBackground ?? {},
+          type: "solid",
+          color: toHalfOpacityColor(input.backgroundColor)
+        };
+      }
+    }
+    if (logoInput?.src && isSlideInScope(slide, logoInput.scope)) {
+      const withoutLogo = nextElements.filter(
+        (element) => !(element.type === "image" && element.imageType === "logo")
+      );
+      nextElements = [
+        ...withoutLogo,
+        buildLogoElement({
+          src: logoInput.src,
+          slideWidth,
+          slideHeight,
+          slideIndex,
+          position: logoInput.position,
+          logoWidth: logoInput.width,
+          logoHeight: logoInput.height
+        })
+      ];
+      changed = true;
+    }
+    if (!changed && nextBackground === slide.background) return slide;
+    return {
+      ...slide,
+      ...changed ? { elements: nextElements } : {},
+      ...nextBackground ? { background: nextBackground } : {}
+    };
+  });
+  return { ...deck, slides };
+}
+
 // src/custom-theme/mappings.ts
 function buildColorMappings(previous, next) {
   const mappings = [];
@@ -631,173 +812,6 @@ function applyTheme2Json(deck, update) {
 }
 
 // src/custom-theme/index.ts
-var FALLBACK_SLIDE_WIDTH2 = 1e3;
-var FALLBACK_SLIDE_HEIGHT2 = 562.5;
-var LOGO_MARGIN_X2 = 24;
-var LOGO_MARGIN_Y2 = 18;
-var LOGO_MAX_WIDTH_RATIO2 = 0.34;
-var LOGO_MAX_HEIGHT_RATIO2 = 0.16;
-var DEFAULT_LOGO_ASPECT_RATIO = 3.2;
-function mapSlideTypeToScopeKey(type) {
-  const normalized = type?.trim().toLowerCase();
-  if (!normalized) return null;
-  if (normalized === "cover") return "cover";
-  if (normalized === "contents" || normalized === "agenda") return "contents";
-  if (normalized === "transition" || normalized === "section") return "transition";
-  if (normalized === "content") return "content";
-  if (normalized === "end" || normalized === "ending") return "end";
-  return null;
-}
-function isSlideInScope(slide, scope) {
-  const key = mapSlideTypeToScopeKey(slide.type);
-  if (!key) return false;
-  return Boolean(scope[key]);
-}
-function createElementId(prefix, slideIndex) {
-  const random = Math.random().toString(36).slice(2, 10);
-  return `${prefix}-${slideIndex}-${random}`;
-}
-function toHalfOpacityColor(value) {
-  const rgb = parseColorToRgb(value);
-  if (!rgb) return value;
-  return `rgba(${rgb.r},${rgb.g},${rgb.b},0.5)`;
-}
-function buildBackgroundElement(src, slideWidth, slideHeight, slideIndex) {
-  return {
-    type: "image",
-    id: createElementId("background", slideIndex),
-    src,
-    width: slideWidth,
-    height: slideHeight,
-    left: 0,
-    top: 0,
-    fixedRatio: true,
-    rotate: 0,
-    imageType: "background",
-    filters: {
-      opacity: "100%"
-    }
-  };
-}
-function buildLogoElement(src, slideWidth, slideHeight, position, slideIndex, logoWidth, logoHeight) {
-  const aspectRatio = resolveLogoAspectRatio(logoWidth, logoHeight);
-  const maxWidth = slideWidth * LOGO_MAX_WIDTH_RATIO2;
-  const maxHeight = slideHeight * LOGO_MAX_HEIGHT_RATIO2;
-  let width = maxWidth;
-  let height = width / aspectRatio;
-  if (height > maxHeight) {
-    height = maxHeight;
-    width = height * aspectRatio;
-  }
-  const left = position === "left" ? LOGO_MARGIN_X2 : Math.max(LOGO_MARGIN_X2, slideWidth - width - LOGO_MARGIN_X2);
-  return {
-    type: "image",
-    id: createElementId("logo", slideIndex),
-    src,
-    width,
-    height,
-    left,
-    top: LOGO_MARGIN_Y2,
-    fixedRatio: true,
-    rotate: 0,
-    imageType: "logo"
-  };
-}
-function resolveLogoAspectRatio(width, height) {
-  if (typeof width === "number" && typeof height === "number" && width > 0 && height > 0) {
-    return width / height;
-  }
-  return DEFAULT_LOGO_ASPECT_RATIO;
-}
-function replaceScopedMedia(deck, input) {
-  if (!deck.slides?.length) return deck;
-  const slideWidth = deck.width ?? FALLBACK_SLIDE_WIDTH2;
-  const slideHeight = deck.height ?? FALLBACK_SLIDE_HEIGHT2;
-  const backgroundInput = input.backgroundImage;
-  const logoInput = input.logoImage;
-  const shouldClearBackground = Boolean(input.clearBackgroundImage);
-  const shouldClearLogo = Boolean(input.clearLogoImage || shouldClearBackground);
-  if (!backgroundInput?.src && !logoInput?.src && !shouldClearBackground && !shouldClearLogo) {
-    return deck;
-  }
-  const slides = deck.slides.map((slide, slideIndex) => {
-    let nextElements = slide.elements ? [...slide.elements] : [];
-    let nextBackground = slide.background;
-    let changed = false;
-    if (shouldClearBackground) {
-      const before = nextElements.length;
-      nextElements = nextElements.filter(
-        (element) => !(element.type === "image" && element.imageType === "background")
-      );
-      if (nextElements.length !== before) {
-        changed = true;
-        if (input.backgroundColor) {
-          nextBackground = {
-            ...nextBackground ?? {},
-            type: "solid",
-            color: input.backgroundColor
-          };
-        }
-      }
-    }
-    if (shouldClearLogo) {
-      const before = nextElements.length;
-      nextElements = nextElements.filter(
-        (element) => !(element.type === "image" && element.imageType === "logo")
-      );
-      if (nextElements.length !== before) {
-        changed = true;
-      }
-    }
-    if (backgroundInput?.src && isSlideInScope(slide, backgroundInput.scope)) {
-      const withoutBackground = nextElements.filter(
-        (element) => !(element.type === "image" && element.imageType === "background")
-      );
-      nextElements = [
-        buildBackgroundElement(
-          backgroundInput.src,
-          slideWidth,
-          slideHeight,
-          slideIndex
-        ),
-        ...withoutBackground
-      ];
-      changed = true;
-      if (input.backgroundColor) {
-        nextBackground = {
-          ...nextBackground ?? {},
-          type: "solid",
-          color: toHalfOpacityColor(input.backgroundColor)
-        };
-      }
-    }
-    if (logoInput?.src && isSlideInScope(slide, logoInput.scope)) {
-      const withoutLogo = nextElements.filter(
-        (element) => !(element.type === "image" && element.imageType === "logo")
-      );
-      nextElements = [
-        ...withoutLogo,
-        buildLogoElement(
-          logoInput.src,
-          slideWidth,
-          slideHeight,
-          logoInput.position,
-          slideIndex,
-          logoInput.width,
-          logoInput.height
-        )
-      ];
-      changed = true;
-    }
-    if (!changed && nextBackground === slide.background) return slide;
-    return {
-      ...slide,
-      ...changed ? { elements: nextElements } : {},
-      ...nextBackground ? { background: nextBackground } : {}
-    };
-  });
-  return { ...deck, slides };
-}
 function applyCustomTheme(deck, input) {
   const normalizedDeck = (0, import_json2pptx_schema2.parseDocument)(deck);
   const withColors = applyTheme2Json(normalizedDeck, input);