@zumer/snapdom 1.3.0 → 1.8.0

package/README.md

@@ -7,7 +7,21 @@
 </p>
 
 <p align="center">
-  <a href="https://www.npmjs.com/package/@zumer/snapdom"><img src="https://img.shields.io/github/package-json/v/zumerlab/snapdom"></a>
+ <a href="https://www.npmjs.com/package/@zumer/snapdom">
+    <img alt="NPM version" src="https://img.shields.io/npm/v/@zumer/snapdom?style=flat-square&label=Version">
+  </a>
+  <a href="https://github.com/zumerlab/snapdom/graphs/contributors">
+    <img alt="GitHub contributors" src="https://img.shields.io/github/contributors/zumerlab/snapdom?style=flat-square&label=Contributors">
+  </a>
+  <a href="https://github.com/zumerlab/snapdom/stargazers">
+    <img alt="GitHub stars" src="https://img.shields.io/github/stars/zumerlab/snapdom?style=flat-square&label=Stars">
+  </a>
+  <a href="https://github.com/zumerlab/snapdom/network/members">
+    <img alt="GitHub forks" src="https://img.shields.io/github/forks/zumerlab/snapdom?style=flat-square&label=Forks">
+  </a>
+  <a href="https://github.com/zumerlab/snapdom/blob/main/LICENSE">
+    <img alt="License" src="https://img.shields.io/github/license/zumerlab/snapdom?style=flat-square">
+  </a>
 </p>
 
 **snapDOM** is a fast and accurate DOM-to-image capture tool built for **Zumly**, a zoom-based view transition framework.
@@ -122,14 +136,74 @@ Returns an object with reusable export methods:
 
 All capture methods accept an `options` object:
 
-| Option            | Type    | Default  | Description                                |
-| ----------------- | ------- | -------- | ------------------------------------------ |
-| `compress`        | boolean | `true`   | Removes redundant styles                   |
-| `fast`            | boolean | `true`   | Skips idle delay for faster results        |
-| `embedFonts`      | boolean | `false`  | Inlines fonts (icon fonts always embedded) |
-| `scale`           | number  | `1`      | Output scale multiplier                    |
-| `backgroundColor` | string  | `"#fff"` | Fallback color for JPG/WebP                |
-| `quality`         | number  | `1`      | Quality for JPG/WebP (0 to 1)              |
+| Option            | Type     | Default  | Description                                |
+| ----------------- | -------- | -------- | ------------------------------------------ |
+| `compress`        | boolean  | `true`   | Removes redundant styles                   |
+| `fast`            | boolean  | `true`   | Skips idle delay for faster results        |
+| `embedFonts`      | boolean  | `false`  | Inlines fonts (icon fonts always embedded) |
+| `scale`           | number   | `1`      | Output scale multiplier                    |
+| `width`           | number   | -        | Output specific width size                 |
+| `height`          | number   | -        | Output specific height size                |
+| `backgroundColor` | string   | `"#fff"` | Fallback color for JPG/WebP                |
+| `quality`         | number   | `1`      | Quality for JPG/WebP (0 to 1)              |
+| `crossOrigin`     | function | -        | Function to determine CORS mode per image URL |
+
+### Setting custom dimensions with width and height options
+
+Use the `width` and `height` options to generate an image with specific dimensions.
+
+**Examples:**
+
+**1. Fixed width (proportional Hhight)**
+Sets a specific width while maintaining the aspect ratio. Height adjusts proportionally.
+
+```js
+const result = await snapdom(element, {
+  width: 400 // Outputs a 400px-wide image with auto-scaled height
+});
+```
+
+**2. Fixed height (proportional width)**
+Sets a specific height while maintaining the aspect ratio. Width adjusts proportionally.
+
+```js
+const result = await snapdom(element, {
+  height: 200 // Outputs a 200px-tall image with auto-scaled width
+});
+```
+
+**3. Fixed width and height (may distort image)**
+Forces exact dimensions, potentially distorting the image if the aspect ratio differs.
+
+```js
+const result = await snapdom(element, {
+  width: 800,  // Outputs an 800px × 200px image (may stretch/squish content)
+  height: 200  
+});
+```
+
+**Note:** If `scale` is different from  1, it takes priority over width and height.
+Example: `{ scale: 3, width: 500 }` ignores width and scales the image 3x instead.
+
+
+### Cross-Origin Images
+
+By default, snapDOM loads images with `crossOrigin="anonymous"`. You can customize this behavior using the `crossOrigin` option:
+
+```js
+const result = await snapdom(element, {
+  crossOrigin: (url) => {
+    // Use credentials for same-origin images
+    if (url.startsWith(window.location.origin)) {
+      return "use-credentials";
+    }
+    // Use anonymous for cross-origin images
+    return "anonymous";
+  }
+});
+```
+
+This is useful when your images require authentication or when dealing with credentialed requests.
 
 ### Download options
 
@@ -164,6 +238,7 @@ import { snapdom, preCache } from './snapdom.mjs';
 
 * `embedFonts` *(boolean, default: true)* — Inlines non-icon fonts during preload.
 * `reset` *(boolean, default: false)* — Clears all existing internal caches.
+* `crossOrigin` *(function)* — Function to determine CORS mode per image URL during preload.
 
 
 ## Features
@@ -177,15 +252,15 @@ import { snapdom, preCache } from './snapdom.mjs';
 
 ## Limitations
 
-* External images must be CORS-accessible
+* External images must be CORS-accessible (use `crossOrigin` option for credentialed requests)
 * Iframes are not supported
 * When WebP format is used on Safari, it will fallback to PNG rendering.
+* `@font-face` CSS rule is well supported, but if need to use JS `FontFace()`, see this workaround [`#43`](https://github.com/zumerlab/snapdom/issues/43)
 
 ## Benchmarks
 
 `snapDOM` is not only highly accurate — it’s **extremely fast**.
 
-
 Latest benchmarks show significant performance improvements against other libraries:
 
 | Scenario                         | vs. `modern-screenshot` | vs. `html2canvas` |
@@ -215,6 +290,45 @@ npm run test:benchmark
 
 They execute in **headless Chromium** using real DOM nodes.
 
+## Development
+
+To contribute or build snapDOM locally:
+
+```sh
+# Clone the repository
+git clone https://github.com/zumerlab/snapdom.git
+cd snapdom
+
+# Install dependencies
+npm install
+
+# Compile the library (ESM, CJS, and minified versions)
+npm run compile
+
+# Run tests
+npm test
+
+# Run Benchmarks
+npm run test:benchmark
+```
+
+The main entry point is in `src/`, and output bundles are generated in the `dist/` folder.
+
+For detailed contribution guidelines, please see [CONTRIBUTING](https://github.com/zumerlab/snapdom/blob/main/CONTRIBUTING.md).
+
+
+## Contributors 🙌
+
+<!-- CONTRIBUTORS:START -->
+<p>
+<a href="https://github.com/tinchox5" title="tinchox5"><img src="https://avatars.githubusercontent.com/u/11557901?v=4&s=100" style="border-radius:10px; width:60px; height:60px; object-fit:cover; margin:5px;" alt="tinchox5"/></a>
+<a href="https://github.com/pedrocateexte" title="pedrocateexte"><img src="https://avatars.githubusercontent.com/u/207524750?v=4&s=100" style="border-radius:10px; width:60px; height:60px; object-fit:cover; margin:5px;" alt="pedrocateexte"/></a>
+<a href="https://github.com/domialex" title="domialex"><img src="https://avatars.githubusercontent.com/u/4694217?v=4&s=100" style="border-radius:10px; width:60px; height:60px; object-fit:cover; margin:5px;" alt="domialex"/></a>
+<a href="https://github.com/elliots" title="elliots"><img src="https://avatars.githubusercontent.com/u/622455?v=4&s=100" style="border-radius:10px; width:60px; height:60px; object-fit:cover; margin:5px;" alt="elliots"/></a>
+<a href="https://github.com/jswhisperer" title="jswhisperer"><img src="https://avatars.githubusercontent.com/u/1177690?v=4&s=100" style="border-radius:10px; width:60px; height:60px; object-fit:cover; margin:5px;" alt="jswhisperer"/></a>
+<a href="https://github.com/jhbae200" title="jhbae200"><img src="https://avatars.githubusercontent.com/u/20170610?v=4&s=100" style="border-radius:10px; width:60px; height:60px; object-fit:cover; margin:5px;" alt="jhbae200"/></a>
+</p>
+<!-- CONTRIBUTORS:END -->
 
 ## License