dom-to-pptx 1.0.2 → 1.0.4

package/CHANGELOG.md

@@ -0,0 +1,18 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [1.0.4] - 2025-12-06
+### Added
+- Standalone UMD bundle `dist/dom-to-pptx.bundle.js` which includes runtime dependencies for single-script usage.
+- `SUPPORTED.md` listing common supported HTML elements and CSS features.
+
+### Fixed
+- Rounded corner math: decreased false-positive circle detection and capped `rectRadius` to avoid pill-shaped elements becoming full circles.
+- Partial border-radius clipping: elements inside `overflow:hidden` are now correctly rendered with clipping preserved.
+- Very small elements (sub-pixel) rendering: lowered threshold to include tiny decorative elements (e.g., 2x2 dots).
+- Backdrop blur support: simulated `backdrop-filter: blur()` using html2canvas snapshotting.
+- CORS canvas errors: replaced fragile foreignObject rendering with safer SVG + canvas or html2canvas-based capture where appropriate.
+
+## [1.0.3] - Previous
+- Minor fixes and optimizations.

package/Readme.md

@@ -1,180 +1,249 @@
-# dom-to-pptx
-
-**The High-Fidelity HTML to PowerPoint Converter (v1.0.2).**
-
-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).
-
-**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.
-
-## Features
-
-### 🎨 Advanced Visual Fidelity
-
-- **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.
-- **Mathematically Accurate Shadows:** Converts CSS Cartesian shadows (`x`, `y`, `blur`) into PowerPoint's Polar coordinate system (`angle`, `distance`) for 1:1 depth matching.
-- **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.
-- **Soft Edges/Blurs:** Accurately translates CSS `filter: blur()` into PowerPoint's soft-edge effects, preserving visual depth.
-
-### 📐 Smart Layout & Typography
-
-- **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.
-- **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.
-- **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.
-- **Text Transformations:** Supports CSS `text-transform: uppercase/lowercase` and `letter-spacing` (converted to PT).
-
-### ⚡ Technical Capabilities
-
-- **Z-Index Handling:** Respects DOM order for correct layering of elements.
-- **Border Radius Math:** Calculates perfect corner rounding percentages based on element dimensions.
-- **Client-Side:** Runs entirely in the browser. No server required.
-
-## Installation
-
-```bash
-npm install dom-to-pptx
-```
-
-## Usage
-
-This library is intended for use in the browser (React, Vue, Svelte, Vanilla JS, etc.).
-
-### 1. Basic Example
-
-```javascript
-import { exportToPptx } from 'dom-to-pptx';
-
-document.getElementById('download-btn').addEventListener('click', async () => {
-  // Pass the CSS selector of the container you want to turn into a slide
-  await exportToPptx('#slide-container', {
-    fileName: 'dashboard-report.pptx',
-  });
-});
-```
-
-### 2. Multi-Slide Example
-
-To export multiple HTML elements as separate slides, pass an array of elements or selectors:
-
-```javascript
-import { exportToPptx } from 'dom-to-pptx';
-
-document.getElementById('export-btn').addEventListener('click', async () => {
-  const slideElements = document.querySelectorAll('.slide');
-  await exportToPptx(Array.from(slideElements), {
-    fileName: 'multi-slide-presentation.pptx',
-  });
-});
-```
-
-### 3. Direct Browser Usage (via Script Tag)
-
-For direct inclusion in a web page using a `<script>` tag, you can use the UMD bundle:
-
-```html
-<script src="https://cdn.jsdelivr.net/npm/dom-to-pptx@latest/dist/dom-to-pptx.min.js"></script>
-<script>
-  document.getElementById('download-btn').addEventListener('click', async () => {
-    // The library is available globally as `domToPptx`
-    await domToPptx.exportToPptx('#slide-container', {
-      fileName: 'dashboard-report.pptx',
-    });
-  });
-</script>
-```
-
-### 4. Recommended HTML Structure
-
-### Recommended HTML Structure
-
-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.
-
-```html
-<!-- Container (16:9 Aspect Ratio) -->
-<!-- The library will capture this background color/gradient automatically -->
-<div
-  id="slide-container"
-  class="slide w-[1000px] h-[562px] bg-white mx-auto shadow-xl relative overflow-hidden rounded-lg flex items-center justify-center p-10"
->
-  <div
-    class="w-full max-w-3xl bg-white rounded-2xl shadow-xl overflow-hidden grid md:grid-cols-2 items-center 
-border-l-2 border-indigo-500"
-  >
-    <div class="p-12">
-      <h2 class="text-xl font-semibold text-indigo-500 uppercase tracking-wide mb-2">
-        Core Concept
-      </h2>
-      <h3 class="text-4xl font-bold text-slate-800 mb-6">From Bit to Qubit</h3>
-      <div class="space-y-6 text-slate-600">
-        <div class="flex items-start gap-4">
-          <div
-            class="flex-shrink-0 w-8 h-8 bg-slate-200 rounded-full flex items-center justify-center font-bold text-slate-700"
-          >
-            B
-          </div>
-          <div>
-            <h4 class="font-bold text-slate-700">Classical Bit</h4>
-            <p>
-              A fundamental unit of information that is either
-              <span class="font-semibold text-indigo-600">0</span> or
-              <span class="font-semibold text-indigo-600">1</span>.
-            </p>
-          </div>
-        </div>
-        <div class="flex items-start gap-4">
-          <div
-            class="flex-shrink-0 w-8 h-8 bg-indigo-200 rounded-full flex items-center justify-center font-bold text-indigo-700"
-          >
-            Q
-          </div>
-          <div>
-            <h4 class="font-bold text-slate-700">Quantum Bit (Qubit)</h4>
-            <p>
-              Can be <span class="font-semibold text-indigo-600">0</span>,
-              <span class="font-semibold text-indigo-600">1</span>, or a
-              <span class="font-semibold text-indigo-600">superposition</span>
-              of both states simultaneously.
-            </p>
-          </div>
-        </div>
-      </div>
-    </div>
-    <div class="h-64 md:h-full">
-      <img
-        src="https://picsum.photos/800/600?random=2"
-        alt="Stylized representation of a qubit"
-        class="w-full h-full object-cover"
-      />
-    </div>
-  </div>
-</div>
-```
-
-## API
-
-### `exportToPptx(elementOrSelector, options)`
-
-| Parameter           | Type                                                        | Description                                                                                                        |
-| :------------------ | :---------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------- |
-| `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. |
-| `options`           | `object`                                                    | Configuration object.                                                                                              |
-
-**Options Object:**
-
-| Key               | Type     | Default        | Description                                   |
-| :---------------- | :------- | :------------- | :-------------------------------------------- |
-| `fileName`        | `string` | `"slide.pptx"` | The name of the downloaded file.              |
-| `backgroundColor` | `string` | `null`         | Force a background color for the slide (hex). |
-
-## Important Notes
-
-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.
-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.
-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.
-
-## License
-
-MIT © [Atharva Dharmendra Jagtap](https://github.com/atharva9167j) and `dom-to-pptx` contributors.
-
-## Acknowledgements
-
-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.
+# dom-to-pptx
+
+**The High-Fidelity HTML to PowerPoint Converter (v1.0.4).**
+
+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).
+
+**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.
+
+## Features
+
+### 🎨 Advanced Visual Fidelity
+
+- **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.
+- **Mathematically Accurate Shadows:** Converts CSS Cartesian shadows (`x`, `y`, `blur`) into PowerPoint's Polar coordinate system (`angle`, `distance`) for 1:1 depth matching.
+- **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.
+- **Soft Edges/Blurs:** Accurately translates CSS `filter: blur()` into PowerPoint's soft-edge effects, preserving visual depth.
+
+### 📐 Smart Layout & Typography
+
+- **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.
+- **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.
+- **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.
+- **Text Transformations:** Supports CSS `text-transform: uppercase/lowercase` and `letter-spacing` (converted to PT).
+
+### ⚡ Technical Capabilities
+
+- **Z-Index Handling:** Respects DOM order for correct layering of elements.
+- **Border Radius Math:** Calculates perfect corner rounding percentages based on element dimensions.
+- **Client-Side:** Runs entirely in the browser. No server required.
+
+## Installation
+
+```bash
+npm install dom-to-pptx
+```
+
+## Usage
+
+This library is intended for use in the browser (React, Vue, Svelte, Vanilla JS, etc.).
+
+### 1. Basic Example
+
+```javascript
+import { exportToPptx } from 'dom-to-pptx';
+
+// Note: If you are using a module bundler, it is recommended to import pptxgenjs
+// directly into your project to ensure tree-shaking and optimal bundle size.
+// import PptxGenJS from 'pptxgenjs'; // Uncomment and use if needed for your setup
+
+document.getElementById('download-btn').addEventListener('click', async () => {
+  // Pass the CSS selector of the container you want to turn into a slide
+  await exportToPptx('#slide-container', {
+    fileName: 'slide-presentation.pptx',
+  });
+});
+```
+
+### 2. Multi-Slide Example
+
+To export multiple HTML elements as separate slides, pass an array of elements or selectors:
+
+```javascript
+import { exportToPptx } from 'dom-to-pptx'; // ESM or CJS import
+
+document.getElementById('export-btn').addEventListener('click', async () => {
+  const slideElements = document.querySelectorAll('.slide');
+  await exportToPptx(Array.from(slideElements), {
+    fileName: 'multi-slide-presentation.pptx',
+  });
+});
+```
+
+### 3. Browser Usage (single-file bundle or legacy setup)
+
+You can use `dom-to-pptx` directly in the browser in two ways:
+
+- Recommended — Single-file bundle (includes runtime deps):
+
+```html
+<!-- Single script that contains dom-to-pptx + pptxgenjs + html2canvas -->
+<script src="/node_modules/dom-to-pptx/dist/dom-to-pptx.bundle.js"></script>
+<script>
+  document.getElementById('download-btn').addEventListener('click', async () => {
+    // The library is available globally as `domToPptx`
+    await domToPptx.exportToPptx('#slide-container', { fileName: 'slide-presentation.pptx' });
+  });
+</script>
+```
+
+You can also load the bundle from a CDN (unpkg/jsdelivr):
+
+```html
+<script src="https://unpkg.com/dom-to-pptx@latest/dist/dom-to-pptx.bundle.js"></script>
+```
+
+- Legacy — Explicit runtime includes (smaller dom-to-pptx file, you manage deps):
+
+```html
+<!-- Load pptxgenjs first -->
+<script src="https://cdn.jsdelivr.net/npm/pptxgenjs@latest/dist/pptxgen.bundle.js"></script>
+<!-- html2canvas is required by the legacy dom-to-pptx build for backdrop-filter and canvas image processing -->
+<script src="https://cdn.jsdelivr.net/npm/html2canvas@1.4.1/dist/html2canvas.min.js"></script>
+<!-- Then load the legacy dom-to-pptx file that expects the above libs -->
+<script src="/node_modules/dom-to-pptx/dist/dom-to-pptx.min.js"></script>
+<script>
+  document.getElementById('download-btn').addEventListener('click', async () => {
+    await domToPptx.exportToPptx('#slide-container', { fileName: 'slide-presentation.pptx' });
+  });
+</script>
+```
+
+Notes:
+
+- The standalone `dist/dom-to-pptx.bundle.js` includes `pptxgenjs` and `html2canvas`, so you only need one script tag.
+- If you prefer a smaller payload and already have `pptxgenjs` on the page, use the legacy `dist/dom-to-pptx.min.js` and load `pptxgenjs` first.
+
+### 4. Recommended HTML Structure
+
+### Recommended HTML Structure
+
+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.
+
+```html
+<!-- Container (16:9 Aspect Ratio) -->
+<!-- The library will capture this background color/gradient automatically -->
+<div
+  id="slide-container"
+  class="slide w-[1000px] h-[562px] bg-white mx-auto shadow-xl relative overflow-hidden rounded-lg flex items-center justify-center p-10"
+>
+  <div
+    class="w-full max-w-3xl bg-white rounded-2xl shadow-xl overflow-hidden grid md:grid-cols-2 items-center 
+border-l-2 border-indigo-500"
+  >
+    <div class="p-12">
+      <h2 class="text-xl font-semibold text-indigo-500 uppercase tracking-wide mb-2">
+        Core Concept
+      </h2>
+      <h3 class="text-4xl font-bold text-slate-800 mb-6">From Bit to Qubit</h3>
+      <div class="space-y-6 text-slate-600">
+        <div class="flex items-start gap-4">
+          <div
+            class="flex-shrink-0 w-8 h-8 bg-slate-200 rounded-full flex items-center justify-center font-bold text-slate-700"
+          >
+            B
+          </div>
+          <div>
+            <h4 class="font-bold text-slate-700">Classical Bit</h4>
+            <p>
+              A fundamental unit of information that is either
+              <span class="font-semibold text-indigo-600">0</span> or
+              <span class="font-semibold text-indigo-600">1</span>.
+            </p>
+          </div>
+        </div>
+        <div class="flex items-start gap-4">
+          <div
+            class="flex-shrink-0 w-8 h-8 bg-indigo-200 rounded-full flex items-center justify-center font-bold text-indigo-700"
+          >
+            Q
+          </div>
+          <div>
+            <h4 class="font-bold text-slate-700">Quantum Bit (Qubit)</h4>
+            <p>
+              Can be <span class="font-semibold text-indigo-600">0</span>,
+              <span class="font-semibold text-indigo-600">1</span>, or a
+              <span class="font-semibold text-indigo-600">superposition</span>
+              of both states simultaneously.
+            </p>
+          </div>
+        </div>
+      </div>
+    </div>
+    <div class="h-64 md:h-full">
+      <img
+        src="https://picsum.photos/800/600?random=2"
+        alt="Stylized representation of a qubit"
+        class="w-full h-full object-cover"
+      />
+    </div>
+  </div>
+</div>
+```
+
+## API
+
+### `exportToPptx(elementOrSelector, options)`
+
+| Parameter           | Type                                                        | Description                                                                                                        |
+| :------------------ | :---------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------- |
+| `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. |
+| `options`           | `object`                                                    | Configuration object.                                                                                              |
+
+**Options Object:**
+
+| Key               | Type     | Default        | Description                                   |
+| :---------------- | :------- | :------------- | :-------------------------------------------- |
+| `fileName`        | `string` | `"slide.pptx"` | The name of the downloaded file.              |
+| `backgroundColor` | `string` | `null`         | Force a background color for the slide (hex). |
+
+## Important Notes
+
+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.
+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.
+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.
+
+## License
+
+MIT © [Atharva Dharmendra Jagtap](https://github.com/atharva9167j) and `dom-to-pptx` contributors.
+
+## Acknowledgements
+
+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.
+
+## Bundle & Dependencies
+
+Starting with v1.0.4 `dom-to-pptx` ships a standalone browser bundle that includes runtime dependencies (for convenience).
+
+- If you use npm / a bundler, run:
+
+```bash
+npm install dom-to-pptx
+```
+
+- For direct browser usage (single script tag), use the bundled file that already includes `pptxgenjs` and `html2canvas`:
+
+```html
+<script src="/node_modules/dom-to-pptx/dist/dom-to-pptx.bundle.js"></script>
+<script>
+  domToPptx.exportToPptx('#slide-container', { fileName: 'report.pptx' });
+</script>
+```
+
+If you prefer to manage `pptxgenjs` yourself (smaller bundle), the legacy `dist/dom-to-pptx.min.js` remains available and expects `pptxgenjs` to be loaded separately.
+
+Legacy usage note:
+
+```html
+<!-- Load pptxgenjs first -->
+<script src="https://cdn.jsdelivr.net/npm/pptxgenjs@latest/dist/pptxgen.bundle.js"></script>
+<!-- html2canvas is required by the legacy dom-to-pptx build for backdrop-filter and canvas image processing -->
+<script src="https://cdn.jsdelivr.net/npm/html2canvas@1.4.1/dist/html2canvas.min.js"></script>
+<!-- Then load the legacy dom-to-pptx file that expects the above libs -->
+<script src="/node_modules/dom-to-pptx/dist/dom-to-pptx.min.js"></script>
+<script>
+  document.getElementById('download-btn').addEventListener('click', async () => {
+    await domToPptx.exportToPptx('#slide-container', { fileName: 'dashboard-report.pptx' });
+  });
+</script>
+```

package/SUPPORTED.md

@@ -0,0 +1,50 @@
+# Supported CSS & HTML
+
+This document lists the common CSS features, Tailwind-like utility classes, and HTML elements that dom-to-pptx understands and maps to PowerPoint shapes/text.
+
+Note: The library measures computed layout from the browser (getBoundingClientRect) and maps positions/sizes precisely to PPTX inches. If a CSS feature is not listed below it may still work because the browser computes layout and visual styles — the mapping focuses on visual fidelity.
+
+## Supported HTML elements
+
+- div, span, p, h1-h6
+- img, svg
+- ul, ol, li
+- a
+- button
+- section, article, header, footer
+- input (text), textarea (simple text extraction)
+- figure, figcaption
+
+## Supported CSS properties (rendered visually)
+
+- background-color, background-image (linear-gradient)
+- background-position, background-size (basic handling in gradients)
+- color, opacity
+- border, border-*-color, border-*-width, border-radius (per-corner)
+- box-shadow (outer shadows mapped to PPTX outer shadows)
+- filter: blur() (soft-edge rendering via SVG)
+- backdrop-filter: blur() (simulated via html2canvas snapshot)
+- transform: rotate() (extraction of rotation angle)
+- display, position, width, height, padding, margin
+- text-align, vertical-align, white-space, text-transform
+- font-family, font-size, font-weight, font-style, line-height
+
+## Common utility/Tailwind-like classes (recognized by visual result)
+
+These classes are examples; dom-to-pptx reads computed styles, so any combination that results in the same computed value will be supported.
+
+- `rounded`, `rounded-sm`, `rounded-md`, `rounded-lg`, `rounded-xl`, `rounded-full`, `rounded-tr-*`, `rounded-bl-full`, etc.
+- `bg-white`, `bg-slate-50`, `bg-indigo-50`, `bg-gradient-to-r`, `from-indigo-400`, `to-cyan-400`, etc. (linear-gradients are parsed)
+- `shadow`, `shadow-md`, `shadow-lg`, `shadow-2xl` (box-shadow)
+- `flex`, `grid`, `items-center`, `justify-center`, `gap-*`
+- `p-4`, `px-6`, `py-2`, `m-4`
+- `w-*`, `h-*` (fixed pixel/percentage/wrappers — computed width/height are used)
+- `text-xs`, `text-sm`, `text-lg`, `font-bold`, `uppercase`, `italic`, `tracking-wide`
+
+## Limitations
+
+- Complex CSS animations/transitions are not exported — only the current computed visual state is captured.
+- Some advanced CSS features (CSS variables used as colors, filters beyond blur) may not map 1:1.
+- For images to be processed via canvas (rounded images), the source must be CORS-accessible (`Access-Control-Allow-Origin` header) or the image will be skipped or rendered as-is.
+
+If a style or element is critical and you find it not behaving as expected, open an issue with a minimal repro and I'll add support or provide a workaround.