pptx-craft 0.1.0

package/LICENSE

@@ -0,0 +1,24 @@
+MIT License
+
+Copyright (c) 2026-Present dxsun97
+
+This project is derived from PptxGenJS (https://github.com/gitbrent/PptxGenJS),
+Copyright (c) 2015-Present Brent Ely.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,166 @@
+English | [中文](./README.zh-CN.md)
+
+<p align="center">
+  <img src="docs/public/logo.svg" width="128" height="128" alt="pptx-craft logo">
+</p>
+
+<h1 align="center">pptx-craft</h1>
+
+<p align="center">
+  Lightweight, type-safe library for creating PowerPoint (.pptx) files — charts, tables, shapes, themes, and plugins out of the box, with only one runtime dependency. Works in Node.js and the browser.
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/pptx-craft"><img src="https://img.shields.io/npm/v/pptx-craft" alt="npm version"></a>
+  <a href="./LICENSE"><img src="https://img.shields.io/npm/l/pptx-craft" alt="license"></a>
+  <a href="https://www.typescriptlang.org/"><img src="https://img.shields.io/badge/TypeScript-5.6+-3178C6?logo=typescript&logoColor=white" alt="TypeScript"></a>
+  <a href="https://dxsun97.github.io/pptx-craft"><img src="https://img.shields.io/badge/docs-online-FF6B42" alt="docs"></a>
+</p>
+
+## Install
+
+```bash
+npm install pptx-craft
+```
+
+## Quick Start
+
+```typescript
+import { Presentation } from 'pptx-craft';
+
+const pptx = new Presentation();
+const slide = pptx.addSlide();
+
+slide.addText('Hello World', {
+  x: 1,
+  y: 1,
+  w: 8,
+  h: 1.5,
+  fontSize: 44,
+  color: '003366',
+  bold: true,
+  align: 'center',
+});
+
+slide.addShape('rect', { x: 1, y: 3, w: 8, h: 0.05, fill: '4472C4' });
+
+await pptx.toFile('output.pptx');
+```
+
+## Features
+
+- **Text** — font, size, color, bold/italic/underline, alignment, line spacing
+- **Images** — from file path or buffer (PNG, JPEG, etc.)
+- **Shapes** — rect, ellipse, roundRect, diamond, triangle, heart, star, arrows, and more
+- **Tables** — cell-level formatting, borders, custom column/row sizing
+- **Charts** — bar, column, line, pie, area, scatter, doughnut (native PowerPoint charts)
+- **Media** — video and audio embedding
+- **Slide Masters & Layouts** — custom backgrounds, placeholder-based layouts
+- **Themes** — full color scheme and font customization
+- **Speaker Notes** — per-slide notes
+- **Plugins** — extend with custom element types
+
+## Preview
+
+<table>
+  <tr>
+    <td><img src="docs/public/previews/quick-example-1.png" alt="Title Slide" width="400"></td>
+    <td><img src="docs/public/previews/quick-example-2.png" alt="Table" width="400"></td>
+  </tr>
+  <tr>
+    <td><img src="docs/public/previews/quick-example-3.png" alt="Chart" width="400"></td>
+    <td><img src="docs/public/previews/quick-example-4.png" alt="Shapes" width="400"></td>
+  </tr>
+</table>
+
+## Examples
+
+### Table
+
+```typescript
+slide.addTable(
+  [
+    [
+      { text: 'Name', options: { bold: true, fill: '4472C4', color: 'FFFFFF' } },
+      { text: 'Score', options: { bold: true, fill: '4472C4', color: 'FFFFFF' } },
+    ],
+    [{ text: 'Alice' }, { text: '95' }],
+    [{ text: 'Bob' }, { text: '87' }],
+  ],
+  { x: 1, y: 1, w: 6, h: 3, border: { color: 'CCCCCC', width: 1 } },
+);
+```
+
+### Chart
+
+```typescript
+slide.addChart(
+  'col',
+  {
+    categories: ['Q1', 'Q2', 'Q3', 'Q4'],
+    series: [
+      { name: '2024', values: [120, 180, 150, 210], color: '4472C4' },
+      { name: '2025', values: [140, 200, 190, 250], color: 'ED7D31' },
+    ],
+  },
+  { x: 1, y: 1, w: 8, h: 5, title: 'Revenue', showLegend: true },
+);
+```
+
+### Slide Master & Layout
+
+```typescript
+const pptx = new Presentation();
+pptx.defineSlideMaster({ name: 'Corporate', background: '003366' });
+pptx.defineLayout({
+  name: 'Title Slide',
+  type: 'titleAndContent',
+  placeholders: [
+    { type: 'title', placement: { x: 0.5, y: 0.5, w: 9, h: 1 }, idx: 0 },
+    { type: 'body', placement: { x: 0.5, y: 2, w: 9, h: 5 }, idx: 1 },
+  ],
+});
+
+const slide = pptx.addSlide('Title Slide');
+```
+
+### Plugin
+
+```typescript
+import type { IPlugin } from 'pptx-craft';
+
+const myPlugin: IPlugin = {
+  name: 'my-plugin',
+  install(registry) {
+    registry.registerElement('badge', badgeSerializer);
+  },
+};
+
+pptx.use(myPlugin);
+```
+
+## Output
+
+```typescript
+// Buffer
+const buffer = pptx.toBuffer();
+
+// File
+await pptx.toFile('presentation.pptx');
+```
+
+## Documentation
+
+Full docs available at the [documentation site](https://dxsun97.github.io/pptx-craft). Run locally:
+
+```bash
+npm run docs:dev
+```
+
+## Acknowledgments
+
+This project is derived from [PptxGenJS](https://github.com/gitbrent/PptxGenJS) by Brent Ely.
+
+## License
+
+MIT — see [LICENSE](./LICENSE) for details.

package/README.zh-CN.md

@@ -0,0 +1,166 @@
+[English](./README.md) | 中文
+
+<p align="center">
+  <img src="docs/public/logo.svg" width="128" height="128" alt="pptx-craft logo">
+</p>
+
+<h1 align="center">pptx-craft</h1>
+
+<p align="center">
+  轻量、类型安全的 PowerPoint（.pptx）生成库 — 开箱即用地支持图表、表格、形状、主题与插件，仅一个运行时依赖。同时支持 Node.js 与浏览器环境。
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/pptx-craft"><img src="https://img.shields.io/npm/v/pptx-craft" alt="npm version"></a>
+  <a href="./LICENSE"><img src="https://img.shields.io/npm/l/pptx-craft" alt="license"></a>
+  <a href="https://www.typescriptlang.org/"><img src="https://img.shields.io/badge/TypeScript-5.6+-3178C6?logo=typescript&logoColor=white" alt="TypeScript"></a>
+  <a href="https://dxsun97.github.io/pptx-craft"><img src="https://img.shields.io/badge/docs-online-FF6B42" alt="docs"></a>
+</p>
+
+## 安装
+
+```bash
+npm install pptx-craft
+```
+
+## 快速开始
+
+```typescript
+import { Presentation } from 'pptx-craft';
+
+const pptx = new Presentation();
+const slide = pptx.addSlide();
+
+slide.addText('Hello World', {
+  x: 1,
+  y: 1,
+  w: 8,
+  h: 1.5,
+  fontSize: 44,
+  color: '003366',
+  bold: true,
+  align: 'center',
+});
+
+slide.addShape('rect', { x: 1, y: 3, w: 8, h: 0.05, fill: '4472C4' });
+
+await pptx.toFile('output.pptx');
+```
+
+## 特性
+
+- **文本** — 字体、大小、颜色、粗体/斜体/下划线、对齐方式、行距
+- **图片** — 支持文件路径或 Buffer（PNG、JPEG 等）
+- **形状** — 矩形、椭圆、圆角矩形、菱形、三角形、心形、星形、箭头等
+- **表格** — 单元格级别格式化、边框、自定义列宽/行高
+- **图表** — 柱状图、条形图、折线图、饼图、面积图、散点图、环形图（原生 PowerPoint 图表）
+- **媒体** — 视频和音频嵌入
+- **母版与版式** — 自定义背景、基于占位符的版式布局
+- **主题** — 完整的配色方案和字体自定义
+- **演讲者备注** — 逐页添加备注
+- **插件** — 通过自定义元素类型进行扩展
+
+## 预览
+
+<table>
+  <tr>
+    <td><img src="docs/public/previews/quick-example-1.png" alt="标题页" width="400"></td>
+    <td><img src="docs/public/previews/quick-example-2.png" alt="表格" width="400"></td>
+  </tr>
+  <tr>
+    <td><img src="docs/public/previews/quick-example-3.png" alt="图表" width="400"></td>
+    <td><img src="docs/public/previews/quick-example-4.png" alt="形状" width="400"></td>
+  </tr>
+</table>
+
+## 示例
+
+### 表格
+
+```typescript
+slide.addTable(
+  [
+    [
+      { text: 'Name', options: { bold: true, fill: '4472C4', color: 'FFFFFF' } },
+      { text: 'Score', options: { bold: true, fill: '4472C4', color: 'FFFFFF' } },
+    ],
+    [{ text: 'Alice' }, { text: '95' }],
+    [{ text: 'Bob' }, { text: '87' }],
+  ],
+  { x: 1, y: 1, w: 6, h: 3, border: { color: 'CCCCCC', width: 1 } },
+);
+```
+
+### 图表
+
+```typescript
+slide.addChart(
+  'col',
+  {
+    categories: ['Q1', 'Q2', 'Q3', 'Q4'],
+    series: [
+      { name: '2024', values: [120, 180, 150, 210], color: '4472C4' },
+      { name: '2025', values: [140, 200, 190, 250], color: 'ED7D31' },
+    ],
+  },
+  { x: 1, y: 1, w: 8, h: 5, title: 'Revenue', showLegend: true },
+);
+```
+
+### 母版与版式
+
+```typescript
+const pptx = new Presentation();
+pptx.defineSlideMaster({ name: 'Corporate', background: '003366' });
+pptx.defineLayout({
+  name: 'Title Slide',
+  type: 'titleAndContent',
+  placeholders: [
+    { type: 'title', placement: { x: 0.5, y: 0.5, w: 9, h: 1 }, idx: 0 },
+    { type: 'body', placement: { x: 0.5, y: 2, w: 9, h: 5 }, idx: 1 },
+  ],
+});
+
+const slide = pptx.addSlide('Title Slide');
+```
+
+### 插件
+
+```typescript
+import type { IPlugin } from 'pptx-craft';
+
+const myPlugin: IPlugin = {
+  name: 'my-plugin',
+  install(registry) {
+    registry.registerElement('badge', badgeSerializer);
+  },
+};
+
+pptx.use(myPlugin);
+```
+
+## 输出
+
+```typescript
+// Buffer
+const buffer = pptx.toBuffer();
+
+// 文件
+await pptx.toFile('presentation.pptx');
+```
+
+## 文档
+
+完整文档请访问[文档站点](https://dxsun97.github.io/pptx-craft)。本地运行：
+
+```bash
+npm run docs:dev
+```
+
+## 致谢
+
+本项目基于 Brent Ely 的 [PptxGenJS](https://github.com/gitbrent/PptxGenJS) 衍生开发。
+
+## 许可证
+
+MIT — 详见 [LICENSE](./LICENSE)。