pptx-custom 0.3.0 → 0.3.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +94 -16
  2. package/README.zh-CN.md +131 -0
  3. package/package.json +1 -1
package/README.md CHANGED
@@ -1,10 +1,11 @@
1
1
  # pptx-custom
2
2
 
3
- Utilities to customize PPTX JSON templates in two stages:
3
+ [中文文档](./README.zh-CN.md)
4
4
 
5
- - `applyCustomContent`: replace default slide content from backend JSON text.
6
- - `applyCustomTheme`: apply user theme settings (palette/font/background).
7
- - `parseCustomContent`: parse custom content to slide data
5
+ Utilities for customizing `json2pptx` JSON decks in two stages:
6
+
7
+ - Content stage: map backend slide content into a template deck.
8
+ - Theme stage: replace theme colors/font/background and apply scoped media.
8
9
 
9
10
  ## Install
10
11
 
@@ -12,31 +13,85 @@ Utilities to customize PPTX JSON templates in two stages:
12
13
  npm i pptx-custom
13
14
  ```
14
15
 
15
- ## Usage
16
+ ## Exports
17
+
18
+ - `applyCustomContent(template, input)`
19
+ - `parseCustomContent(raw)`
20
+ - `applyCustomContentToTemplate(template, slides)`
21
+ - `applyCustomTheme(deck, themeInput)`
22
+
23
+ Types are also exported, including:
24
+ `CustomSlide`, `Deck`, `PptxCustomContentInput`, `PptxCustomThemeInput`,
25
+ `PptxCustomOptions`, `TemplateJson`, `TemplateJsonSlide`, `TemplateJsonElement`,
26
+ `TemplateJsonTheme`.
27
+
28
+ ## Quick Start
16
29
 
17
30
  ```ts
18
31
  import {
19
32
  applyCustomContent,
20
33
  applyCustomTheme,
21
34
  parseCustomContent,
35
+ applyCustomContentToTemplate
22
36
  } from 'pptx-custom'
23
37
 
24
- const deckWithContent = applyCustomContent(templateDeck, backendText)
38
+ const withContent = applyCustomContent(templateDeck, backendText)
25
39
 
26
- const deckWithTheme = applyCustomTheme(deckWithContent, {
40
+ const withTheme = applyCustomTheme(withContent, {
27
41
  themeColors: ['#111111', '#333333', '#555555', '#777777', '#999999', '#BBBBBB'],
28
42
  fontColor: '#222222',
29
- backgroundColor: '#FFFFFF'
43
+ backgroundColor: '#FFFFFF',
44
+ backgroundImage: {
45
+ src: 'https://example.com/background.png',
46
+ scope: {
47
+ cover: false,
48
+ contents: true,
49
+ transition: true,
50
+ content: true,
51
+ end: false
52
+ }
53
+ },
54
+ logoImage: {
55
+ src: 'https://example.com/logo.png',
56
+ position: 'right',
57
+ scope: {
58
+ cover: true,
59
+ contents: true,
60
+ transition: true,
61
+ content: true,
62
+ end: true
63
+ }
64
+ }
30
65
  })
31
66
 
32
67
  const slides = parseCustomContent(backendText)
33
- const deckFromSlides = applyCustomContentToTemplate(templateDeck, slides)
34
-
68
+ const withContentDirect = applyCustomContentToTemplate(templateDeck, slides)
35
69
  ```
36
70
 
37
- ## Custom Content Format
71
+ ## Custom Content Input
72
+
73
+ `parseCustomContent` and `applyCustomContent` support:
74
+
75
+ 1. NDJSON (one slide per line)
76
+ 2. JSON array of slides
77
+ 3. JSON object with a `slides` array
78
+ 4. JSON object containing a single slide (with `type`)
79
+
80
+ Supported slide types:
38
81
 
39
- `applyCustomContent` and `parseCustomContent` accept NDJSON-style lines or JSON arrays/objects of slides:
82
+ - `cover`
83
+ - `contents`
84
+ - `transition`
85
+ - `content`
86
+ - `end`
87
+
88
+ Legacy aliases accepted in input:
89
+
90
+ - `agenda` -> `contents`
91
+ - `section` -> `transition`
92
+ - `ending` -> `end`
93
+
94
+ Example NDJSON:
40
95
 
41
96
  ```json
42
97
  {"type":"cover","data":{"title":"Title","text":"Subtitle"}}
@@ -46,8 +101,31 @@ const deckFromSlides = applyCustomContentToTemplate(templateDeck, slides)
46
101
  {"type":"end"}
47
102
  ```
48
103
 
49
- ## Exported APIs
104
+ ## Theme Input
50
105
 
51
- - `applyCustomContent(template, input)`
52
- - `parseCustomContent(raw)`
53
- - `applyCustomTheme(deck, themeUpdate)`
106
+ `applyCustomTheme` accepts `PptxCustomThemeInput`:
107
+
108
+ - `themeColors: string[]` (uses first 6)
109
+ - `fontColor: string`
110
+ - `backgroundColor?: string`
111
+ - `backgroundImage?: { src, scope, width?, height? }`
112
+ - `logoImage?: { src, scope, position, width?, height? }`
113
+ - `clearBackgroundImage?: boolean`
114
+ - `clearLogoImage?: boolean`
115
+
116
+ `scope` keys:
117
+ `cover | contents | transition | content | end`
118
+
119
+ ## Behavior Notes
120
+
121
+ - Both `applyCustomContent` and `applyCustomTheme` run through `json2pptx-schema`
122
+ parsing/normalization before returning.
123
+ - `applyCustomContent` selects template slides by `type`, and for `contents/content`
124
+ prefers layouts with the closest capacity to the requested item count.
125
+ - `applyCustomContent` normalizes logo elements (`imageType: "logo"`) to stay within
126
+ top margins and removes logo clipping.
127
+ - `applyCustomTheme` inserts scoped background images as slide elements with
128
+ `imageType: "background"` and logo images with `imageType: "logo"`.
129
+ - When both `backgroundImage` and `backgroundColor` are provided, background color is
130
+ applied as a 50% alpha overlay color on targeted slides.
131
+ - `clearBackgroundImage` also clears logo images in current behavior.
package/README.zh-CN.md ADDED
@@ -0,0 +1,131 @@
1
+ # pptx-custom
2
+
3
+ [English](./README.md)
4
+
5
+ 用于对 `json2pptx` JSON deck 进行两阶段定制：
6
+
7
+ - 内容阶段：将后端内容映射到模板 deck。
8
+ - 主题阶段：替换主题色/字体/背景，并按范围应用媒体资源。
9
+
10
+ ## 安装
11
+
12
+ ```bash
13
+ npm i pptx-custom
14
+ ```
15
+
16
+ ## 导出 API
17
+
18
+ - `applyCustomContent(template, input)`
19
+ - `parseCustomContent(raw)`
20
+ - `applyCustomContentToTemplate(template, slides)`
21
+ - `applyCustomTheme(deck, themeInput)`
22
+
23
+ 同时导出类型，包括：
24
+ `CustomSlide`、`Deck`、`PptxCustomContentInput`、`PptxCustomThemeInput`、
25
+ `PptxCustomOptions`、`TemplateJson`、`TemplateJsonSlide`、`TemplateJsonElement`、
26
+ `TemplateJsonTheme`。
27
+
28
+ ## 快速开始
29
+
30
+ ```ts
31
+ import {
32
+ applyCustomContent,
33
+ applyCustomTheme,
34
+ parseCustomContent,
35
+ applyCustomContentToTemplate
36
+ } from 'pptx-custom'
37
+
38
+ const withContent = applyCustomContent(templateDeck, backendText)
39
+
40
+ const withTheme = applyCustomTheme(withContent, {
41
+ themeColors: ['#111111', '#333333', '#555555', '#777777', '#999999', '#BBBBBB'],
42
+ fontColor: '#222222',
43
+ backgroundColor: '#FFFFFF',
44
+ backgroundImage: {
45
+ src: 'https://example.com/background.png',
46
+ scope: {
47
+ cover: false,
48
+ contents: true,
49
+ transition: true,
50
+ content: true,
51
+ end: false
52
+ }
53
+ },
54
+ logoImage: {
55
+ src: 'https://example.com/logo.png',
56
+ position: 'right',
57
+ scope: {
58
+ cover: true,
59
+ contents: true,
60
+ transition: true,
61
+ content: true,
62
+ end: true
63
+ }
64
+ }
65
+ })
66
+
67
+ const slides = parseCustomContent(backendText)
68
+ const withContentDirect = applyCustomContentToTemplate(templateDeck, slides)
69
+ ```
70
+
71
+ ## 自定义内容输入格式
72
+
73
+ `parseCustomContent` 和 `applyCustomContent` 支持：
74
+
75
+ 1. NDJSON（每行一个 slide）
76
+ 2. JSON slide 数组
77
+ 3. 带 `slides` 字段的 JSON 对象
78
+ 4. 单个 slide JSON 对象（包含 `type`）
79
+
80
+ 支持的 slide 类型：
81
+
82
+ - `cover`
83
+ - `contents`
84
+ - `transition`
85
+ - `content`
86
+ - `end`
87
+
88
+ 兼容的历史别名：
89
+
90
+ - `agenda` -> `contents`
91
+ - `section` -> `transition`
92
+ - `ending` -> `end`
93
+
94
+ NDJSON 示例：
95
+
96
+ ```json
97
+ {"type":"cover","data":{"title":"Title","text":"Subtitle"}}
98
+ {"type":"contents","data":{"items":["Part A","Part B"]}}
99
+ {"type":"transition","data":{"title":"Part A","text":"Section intro"}}
100
+ {"type":"content","data":{"title":"Topic","items":[{"title":"Point","text":"Detail"}]}}
101
+ {"type":"end"}
102
+ ```
103
+
104
+ ## 主题输入
105
+
106
+ `applyCustomTheme` 接收 `PptxCustomThemeInput`：
107
+
108
+ - `themeColors: string[]`（最多使用前 6 个）
109
+ - `fontColor: string`
110
+ - `backgroundColor?: string`
111
+ - `backgroundImage?: { src, scope, width?, height? }`
112
+ - `logoImage?: { src, scope, position, width?, height? }`
113
+ - `clearBackgroundImage?: boolean`
114
+ - `clearLogoImage?: boolean`
115
+
116
+ `scope` 可选键：
117
+ `cover | contents | transition | content | end`
118
+
119
+ ## 行为说明
120
+
121
+ - `applyCustomContent` 与 `applyCustomTheme` 都会在返回前经过
122
+ `json2pptx-schema` 的解析与规范化。
123
+ - `applyCustomContent` 按 `type` 选模板页；对 `contents/content` 会优先选择
124
+ 与输入条目数容量最接近的布局。
125
+ - `applyCustomContent` 会规范化 logo 元素（`imageType: "logo"`）：
126
+ 保持在顶部边距内，并移除 logo 裁剪配置。
127
+ - `applyCustomTheme` 会将背景图以元素形式写入（`imageType: "background"`），
128
+ 并将 logo 以 `imageType: "logo"` 写入。
129
+ - 当同时提供 `backgroundImage` 与 `backgroundColor` 时，会在目标页应用
130
+ 50% 透明度的背景色叠加效果。
131
+ - 当前行为下，`clearBackgroundImage` 也会同时清除 logo 图片。
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "pptx-custom",
3
- "version": "0.3.0",
3
+ "version": "0.3.1",
4
4
  "description": "Custom content and theme utilities for PPTX JSON templates.",
5
5
  "license": "MIT",
6
6
  "main": "dist/index.cjs",