dom-to-pptx 1.0.1 → 1.0.3
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.
- package/.prettierrc +6 -0
- package/CONTRIBUTING.md +72 -0
- package/Readme.md +204 -110
- package/dist/dom-to-pptx.cjs +1038 -0
- package/dist/dom-to-pptx.min.js +1042 -0
- package/dist/dom-to-pptx.mjs +1017 -0
- package/eslint.config.js +17 -0
- package/package.json +55 -37
- package/rollup.config.js +33 -0
- package/src/image-processor.js +48 -48
- package/src/index.js +409 -160
- package/src/utils.js +477 -256
- package/code_context.txt +0 -346
package/.prettierrc
ADDED
package/CONTRIBUTING.md
ADDED
|
@@ -0,0 +1,72 @@
|
|
|
1
|
+
# Contributing to dom-to-pptx
|
|
2
|
+
|
|
3
|
+
We welcome contributions to `dom-to-pptx`! To ensure a smooth and effective collaboration, please follow these guidelines.
|
|
4
|
+
|
|
5
|
+
## How to Contribute
|
|
6
|
+
|
|
7
|
+
1. **Fork the Repository:** Start by forking the `dom-to-pptx` repository to your GitHub account.
|
|
8
|
+
2. **Clone Your Fork:** Clone the forked repository to your local machine:
|
|
9
|
+
|
|
10
|
+
```bash
|
|
11
|
+
git clone https://github.com/atharva9167j/dom-to-pptx.git
|
|
12
|
+
cd dom-to-pptx
|
|
13
|
+
```
|
|
14
|
+
|
|
15
|
+
3. **Create a New Branch:** Create a new branch for your feature or bug fix:
|
|
16
|
+
|
|
17
|
+
```bash
|
|
18
|
+
git checkout -b feature/your-feature-name
|
|
19
|
+
# or
|
|
20
|
+
git checkout -b bugfix/issue-description
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
4. **Install Dependencies:** Install the project dependencies:
|
|
24
|
+
|
|
25
|
+
```bash
|
|
26
|
+
npm install
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
5. **Make Your Changes:** Implement your feature or bug fix. Ensure your code adheres to the project's coding style and passes all tests.
|
|
30
|
+
|
|
31
|
+
6. **Run Tests:** Before submitting, run the tests to ensure everything is working correctly:
|
|
32
|
+
|
|
33
|
+
```bash
|
|
34
|
+
npm test
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
7. **Lint and Format:** Ensure your code is properly linted and formatted:
|
|
38
|
+
|
|
39
|
+
```bash
|
|
40
|
+
npm run lint
|
|
41
|
+
npm run format
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
8. **Commit Your Changes:** Commit your changes with a clear and concise commit message. We follow the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) specification.
|
|
45
|
+
|
|
46
|
+
```bash
|
|
47
|
+
git commit -m "feat: Add new feature"
|
|
48
|
+
# or
|
|
49
|
+
git commit -m "fix: Fix a bug"
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
9. **Push to Your Fork:** Push your changes to your forked repository:
|
|
53
|
+
|
|
54
|
+
```bash
|
|
55
|
+
git push origin feature/your-feature-name
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
10. **Create a Pull Request:** Open a pull request from your fork to the `master` branch of the `dom-to-pptx` repository. Provide a detailed description of your changes.
|
|
59
|
+
|
|
60
|
+
## Code Style
|
|
61
|
+
|
|
62
|
+
We use ESLint for linting and Prettier for code formatting. Please ensure your code passes linting and formatting checks before submitting a pull request.
|
|
63
|
+
|
|
64
|
+
## Reporting Bugs
|
|
65
|
+
|
|
66
|
+
If you find a bug, please open an issue on the [GitHub Issues](https://github.com/atharva9167j/dom-to-pptx/issues) page. Provide as much detail as possible, including steps to reproduce the bug, expected behavior, and actual behavior.
|
|
67
|
+
|
|
68
|
+
## Feature Requests
|
|
69
|
+
|
|
70
|
+
If you have a feature request, please open an issue on the [GitHub Issues](https://github.com/atharva9167j/dom-to-pptx/issues) page. Describe your idea clearly and explain why it would be beneficial to the project.
|
|
71
|
+
|
|
72
|
+
Thank you for contributing!
|
package/Readme.md
CHANGED
|
@@ -1,110 +1,204 @@
|
|
|
1
|
-
# dom-to-pptx
|
|
2
|
-
|
|
3
|
-
**The High-Fidelity HTML to PowerPoint Converter.**
|
|
4
|
-
|
|
5
|
-
Most HTML-to-PPTX libraries fail when faced with modern web design. They break on gradients, misalign text, ignore rounded corners, or simply take a screenshot (which isn't editable).
|
|
6
|
-
|
|
7
|
-
**dom-to-pptx** is different. It is a **Coordinate Scraper & Style Engine** that traverses your DOM, calculates the exact computed styles of every element (Flexbox/Grid positions, complex gradients, shadows), and mathematically maps them to native PowerPoint shapes and text boxes. The result is a fully editable, vector-sharp presentation that looks exactly like your web view.
|
|
8
|
-
|
|
9
|
-
## Features
|
|
10
|
-
|
|
11
|
-
### 🎨 Advanced Visual Fidelity
|
|
12
|
-
|
|
13
|
-
- **
|
|
14
|
-
- **
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
- **
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
- **
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
1
|
+
# dom-to-pptx
|
|
2
|
+
|
|
3
|
+
**The High-Fidelity HTML to PowerPoint Converter (v1.0.2).**
|
|
4
|
+
|
|
5
|
+
Most HTML-to-PPTX libraries fail when faced with modern web design. They break on gradients, misalign text, ignore rounded corners, or simply take a screenshot (which isn't editable).
|
|
6
|
+
|
|
7
|
+
**dom-to-pptx** is different. It is a **Coordinate Scraper & Style Engine** that traverses your DOM, calculates the exact computed styles of every element (Flexbox/Grid positions, complex gradients, shadows), and mathematically maps them to native PowerPoint shapes and text boxes. The result is a fully editable, vector-sharp presentation that looks exactly like your web view.
|
|
8
|
+
|
|
9
|
+
## Features
|
|
10
|
+
|
|
11
|
+
### 🎨 Advanced Visual Fidelity
|
|
12
|
+
|
|
13
|
+
- **Complex Gradients:** Includes a built-in CSS Gradient Parser that converts `linear-gradient` strings (with multiple stops, angles, and transparency) into vector SVGs for perfect rendering. This now also supports `text-fill-color` gradients, falling back to the first color for broad compatibility.
|
|
14
|
+
- **Mathematically Accurate Shadows:** Converts CSS Cartesian shadows (`x`, `y`, `blur`) into PowerPoint's Polar coordinate system (`angle`, `distance`) for 1:1 depth matching.
|
|
15
|
+
- **Anti-Halo Image Processing:** Uses off-screen HTML5 Canvas with `source-in` composite masking to render rounded images without the ugly white "halo" artifacts found in other libraries.
|
|
16
|
+
- **Soft Edges/Blurs:** Accurately translates CSS `filter: blur()` into PowerPoint's soft-edge effects, preserving visual depth.
|
|
17
|
+
|
|
18
|
+
### 📐 Smart Layout & Typography
|
|
19
|
+
|
|
20
|
+
- **Auto-Scaling Engine:** Build your slide in HTML at **1920x1080** (or any aspect ratio). The library automatically calculates the scaling factor to fit it perfectly into a standard 16:9 PowerPoint slide (10 x 5.625 inches) with auto-centering.
|
|
21
|
+
- **Rich Text Blocks:** Handles mixed-style text (e.g., **bold** spans inside a normal paragraph) while sanitizing HTML source code whitespace (newlines/tabs) to prevent jagged text alignment.
|
|
22
|
+
- **Font Stack Normalization:** Automatically maps web-only fonts (like `ui-sans-serif`, `system-ui`) to safe system fonts (`Arial`, `Calibri`) to ensure the file opens correctly on any computer.
|
|
23
|
+
- **Text Transformations:** Supports CSS `text-transform: uppercase/lowercase` and `letter-spacing` (converted to PT).
|
|
24
|
+
|
|
25
|
+
### ⚡ Technical Capabilities
|
|
26
|
+
|
|
27
|
+
- **Z-Index Handling:** Respects DOM order for correct layering of elements.
|
|
28
|
+
- **Border Radius Math:** Calculates perfect corner rounding percentages based on element dimensions.
|
|
29
|
+
- **Client-Side:** Runs entirely in the browser. No server required.
|
|
30
|
+
|
|
31
|
+
## Installation
|
|
32
|
+
|
|
33
|
+
```bash
|
|
34
|
+
npm install dom-to-pptx
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
## Usage
|
|
38
|
+
|
|
39
|
+
This library is intended for use in the browser (React, Vue, Svelte, Vanilla JS, etc.).
|
|
40
|
+
|
|
41
|
+
### 1. Basic Example
|
|
42
|
+
|
|
43
|
+
```javascript
|
|
44
|
+
import { exportToPptx } from 'dom-to-pptx'; // ESM or CJS import
|
|
45
|
+
|
|
46
|
+
// Note: If you are using a module bundler, it is recommended to import pptxgenjs
|
|
47
|
+
// directly into your project to ensure tree-shaking and optimal bundle size.
|
|
48
|
+
// import PptxGenJS from 'pptxgenjs'; // Uncomment and use if needed for your setup
|
|
49
|
+
|
|
50
|
+
document.getElementById('download-btn').addEventListener('click', async () => {
|
|
51
|
+
// Pass the CSS selector of the container you want to turn into a slide
|
|
52
|
+
await exportToPptx('#slide-container', {
|
|
53
|
+
fileName: 'dashboard-report.pptx',
|
|
54
|
+
});
|
|
55
|
+
});
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
### 2. Multi-Slide Example
|
|
59
|
+
|
|
60
|
+
To export multiple HTML elements as separate slides, pass an array of elements or selectors:
|
|
61
|
+
|
|
62
|
+
```javascript
|
|
63
|
+
import { exportToPptx } from 'dom-to-pptx'; // ESM or CJS import
|
|
64
|
+
|
|
65
|
+
document.getElementById('export-btn').addEventListener('click', async () => {
|
|
66
|
+
const slideElements = document.querySelectorAll('.slide');
|
|
67
|
+
await exportToPptx(Array.from(slideElements), {
|
|
68
|
+
fileName: 'multi-slide-presentation.pptx',
|
|
69
|
+
});
|
|
70
|
+
});
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
### 3. Direct Browser Usage (via Script Tag)
|
|
74
|
+
|
|
75
|
+
For direct inclusion in a web page using a `<script>` tag, you can use the UMD bundle:
|
|
76
|
+
|
|
77
|
+
```html
|
|
78
|
+
<!-- include pptxgenjs UMD bundle first -->
|
|
79
|
+
<script src="https://cdn.jsdelivr.net/npm/pptxgenjs@latest/dist/pptxgen.bundle.js"></script>
|
|
80
|
+
|
|
81
|
+
<!-- then include dom-to-pptx UMD bundle -->
|
|
82
|
+
<script src="https://cdn.jsdelivr.net/npm/dom-to-pptx@latest/dist/dom-to-pptx.min.js"></script>
|
|
83
|
+
<script>
|
|
84
|
+
document.getElementById('download-btn').addEventListener('click', async () => {
|
|
85
|
+
// The library is available globally as `domToPptx`
|
|
86
|
+
await domToPptx.exportToPptx('#slide-container', {
|
|
87
|
+
fileName: 'dashboard-report.pptx',
|
|
88
|
+
});
|
|
89
|
+
});
|
|
90
|
+
</script>
|
|
91
|
+
```
|
|
92
|
+
|
|
93
|
+
### 4. Recommended HTML Structure
|
|
94
|
+
|
|
95
|
+
### Recommended HTML Structure
|
|
96
|
+
|
|
97
|
+
For the best results, treat your container as a fixed-size canvas. We recommend building your slide at **1920x1080px**. The library will handle the downscaling.
|
|
98
|
+
|
|
99
|
+
```html
|
|
100
|
+
<!-- Container (16:9 Aspect Ratio) -->
|
|
101
|
+
<!-- The library will capture this background color/gradient automatically -->
|
|
102
|
+
<div
|
|
103
|
+
id="slide-container"
|
|
104
|
+
class="slide w-[1000px] h-[562px] bg-white mx-auto shadow-xl relative overflow-hidden rounded-lg flex items-center justify-center p-10"
|
|
105
|
+
>
|
|
106
|
+
<div
|
|
107
|
+
class="w-full max-w-3xl bg-white rounded-2xl shadow-xl overflow-hidden grid md:grid-cols-2 items-center
|
|
108
|
+
border-l-2 border-indigo-500"
|
|
109
|
+
>
|
|
110
|
+
<div class="p-12">
|
|
111
|
+
<h2 class="text-xl font-semibold text-indigo-500 uppercase tracking-wide mb-2">
|
|
112
|
+
Core Concept
|
|
113
|
+
</h2>
|
|
114
|
+
<h3 class="text-4xl font-bold text-slate-800 mb-6">From Bit to Qubit</h3>
|
|
115
|
+
<div class="space-y-6 text-slate-600">
|
|
116
|
+
<div class="flex items-start gap-4">
|
|
117
|
+
<div
|
|
118
|
+
class="flex-shrink-0 w-8 h-8 bg-slate-200 rounded-full flex items-center justify-center font-bold text-slate-700"
|
|
119
|
+
>
|
|
120
|
+
B
|
|
121
|
+
</div>
|
|
122
|
+
<div>
|
|
123
|
+
<h4 class="font-bold text-slate-700">Classical Bit</h4>
|
|
124
|
+
<p>
|
|
125
|
+
A fundamental unit of information that is either
|
|
126
|
+
<span class="font-semibold text-indigo-600">0</span> or
|
|
127
|
+
<span class="font-semibold text-indigo-600">1</span>.
|
|
128
|
+
</p>
|
|
129
|
+
</div>
|
|
130
|
+
</div>
|
|
131
|
+
<div class="flex items-start gap-4">
|
|
132
|
+
<div
|
|
133
|
+
class="flex-shrink-0 w-8 h-8 bg-indigo-200 rounded-full flex items-center justify-center font-bold text-indigo-700"
|
|
134
|
+
>
|
|
135
|
+
Q
|
|
136
|
+
</div>
|
|
137
|
+
<div>
|
|
138
|
+
<h4 class="font-bold text-slate-700">Quantum Bit (Qubit)</h4>
|
|
139
|
+
<p>
|
|
140
|
+
Can be <span class="font-semibold text-indigo-600">0</span>,
|
|
141
|
+
<span class="font-semibold text-indigo-600">1</span>, or a
|
|
142
|
+
<span class="font-semibold text-indigo-600">superposition</span>
|
|
143
|
+
of both states simultaneously.
|
|
144
|
+
</p>
|
|
145
|
+
</div>
|
|
146
|
+
</div>
|
|
147
|
+
</div>
|
|
148
|
+
</div>
|
|
149
|
+
<div class="h-64 md:h-full">
|
|
150
|
+
<img
|
|
151
|
+
src="https://picsum.photos/800/600?random=2"
|
|
152
|
+
alt="Stylized representation of a qubit"
|
|
153
|
+
class="w-full h-full object-cover"
|
|
154
|
+
/>
|
|
155
|
+
</div>
|
|
156
|
+
</div>
|
|
157
|
+
</div>
|
|
158
|
+
```
|
|
159
|
+
|
|
160
|
+
## API
|
|
161
|
+
|
|
162
|
+
### `exportToPptx(elementOrSelector, options)`
|
|
163
|
+
|
|
164
|
+
| Parameter | Type | Description |
|
|
165
|
+
| :------------------ | :---------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------- |
|
|
166
|
+
| `elementOrSelector` | `string` \| `HTMLElement` \| `Array<string \| HTMLElement>` | The DOM node(s) or ID selector(s) to convert. Can be a single element/selector or an array for multi-slide export. |
|
|
167
|
+
| `options` | `object` | Configuration object. |
|
|
168
|
+
|
|
169
|
+
**Options Object:**
|
|
170
|
+
|
|
171
|
+
| Key | Type | Default | Description |
|
|
172
|
+
| :---------------- | :------- | :------------- | :-------------------------------------------- |
|
|
173
|
+
| `fileName` | `string` | `"slide.pptx"` | The name of the downloaded file. |
|
|
174
|
+
| `backgroundColor` | `string` | `null` | Force a background color for the slide (hex). |
|
|
175
|
+
|
|
176
|
+
## Important Notes
|
|
177
|
+
|
|
178
|
+
1. **CORS Images:** Because this library uses HTML5 Canvas to process rounded images, any external images must be served with `Access-Control-Allow-Origin: *` headers. If an image is "tainted" (CORS blocked), the browser will refuse to read its data, and it may appear blank in the PPTX.
|
|
179
|
+
2. **Layout System:** The library does not "read" Flexbox or Grid definitions directly. Instead, it lets the browser render the layout, measures the final `x, y, width, height` (BoundingBox) of every element, and places them absolutely on the slide. This ensures 100% visual accuracy regardless of the layout method used.
|
|
180
|
+
3. **Fonts:** PPTX files use the fonts installed on the viewer's OS. If you use a web font like "Inter", and the user doesn't have it installed, PowerPoint will fallback to Arial.
|
|
181
|
+
|
|
182
|
+
## License
|
|
183
|
+
|
|
184
|
+
MIT © [Atharva Dharmendra Jagtap](https://github.com/atharva9167j) and `dom-to-pptx` contributors.
|
|
185
|
+
|
|
186
|
+
## Acknowledgements
|
|
187
|
+
|
|
188
|
+
This project is built on top of [PptxGenJS](https://github.com/gitbrent/PptxGenJS). Huge thanks to the PptxGenJS maintainers and all contributors — dom-to-pptx leverages and extends their excellent work on PPTX generation.
|
|
189
|
+
|
|
190
|
+
## Peer Dependencies
|
|
191
|
+
|
|
192
|
+
`dom-to-pptx` relies on `pptxgenjs` as a peer dependency. You need to install it separately in your project:
|
|
193
|
+
|
|
194
|
+
```bash
|
|
195
|
+
npm install pptxgenjs
|
|
196
|
+
```
|
|
197
|
+
|
|
198
|
+
## Peer Dependencies
|
|
199
|
+
|
|
200
|
+
`dom-to-pptx` relies on `pptxgenjs` as a peer dependency. You need to install it separately in your project:
|
|
201
|
+
|
|
202
|
+
```bash
|
|
203
|
+
npm install pptxgenjs
|
|
204
|
+
```
|