@limetech/lime-elements 39.41.0 → 39.42.1

package/dist/collection/components/file/file.js

@@ -1,7 +1,8 @@
 import translate from "../../global/translations";
-import { h, Host } from "@stencil/core";
+import { h, Host, } from "@stencil/core";
 import { getFileBackgroundColor, getFileColor, getFileExtensionTitle, getFileIcon, } from "../../util/file-metadata";
 import { formatBytes } from "../../util/format-bytes";
+import { resizeImage as resizeImageFile, } from "../../util/image-resize";
 const DEFAULT_FILE_CHIP = {
     id: null,
     text: null,
@@ -46,6 +47,8 @@ const DEFAULT_FILE_CHIP = {
  * @exampleComponent limel-example-file-per-file-status
  * @exampleComponent limel-example-file-menu-items
  * @exampleComponent limel-example-file-accepted-types
+ * @exampleComponent limel-example-file-resize-image
+ * @exampleComponent limel-example-file-resize-mixed
  * @exampleComponent limel-example-file-composite
  */
 export class File {
@@ -85,14 +88,51 @@ export class File {
         this.dropZoneTip = () => {
             return this.getTranslation('file.drag-and-drop-tips');
         };
-        this.handleNewFiles = (event) => {
+        this.handleNewFiles = async (event) => {
             this.preventAndStop(event);
-            this.change.emit(event.detail[0]);
+            const file = event.detail[0];
+            let out = file;
+            const content = file === null || file === void 0 ? void 0 : file.fileContent;
+            // `instanceof Blob` (not `File`) guards against a value with no real
+            // binary and narrows to the DOM file type; `File` here is the class.
+            if (this.resizeImage &&
+                content instanceof Blob &&
+                this.isResizableImage(content)) {
+                // Show the selected file with a loading badge while it resizes.
+                // This object doubles as the in-flight token: if it is cleared or
+                // replaced during the await (e.g. the file is removed), the resize
+                // result is stale and must be dropped.
+                const pending = Object.assign(Object.assign({}, file), { loading: true, statusText: this.getTranslation('file.optimizing') });
+                this.resizingFile = pending;
+                try {
+                    const processed = await resizeImageFile(content, this.resizeImage);
+                    out = Object.assign(Object.assign({}, file), { filename: processed.name, size: processed.size, contentType: processed.type, fileContent: processed });
+                }
+                catch (_a) {
+                    // Best-effort: on any decode or encode failure emit the
+                    // original file unchanged.
+                }
+                // Bail if the selection changed while we were resizing, so a
+                // removed or superseded file is neither re-shown nor re-emitted.
+                if (this.resizingFile !== pending) {
+                    return;
+                }
+                // Keep the result on the same chip until `value` catches up.
+                this.resizingFile = out;
+            }
+            this.change.emit(out);
         };
         this.handleChipSetChange = (event) => {
             event.stopPropagation();
             const file = event.detail.length === 0 ? event.detail[0] : null;
             if (!file) {
+                // Removing the chip cancels any in-flight resize: drop the
+                // transient so the chip disappears immediately, and the token
+                // guard in `handleNewFiles` discards the resize result instead of
+                // re-emitting the removed file once it finishes. Without this, a
+                // removal during resize is swallowed, because `value` is already
+                // `undefined` so the `@Watch('value')` clear never fires.
+                this.resizingFile = undefined;
                 this.change.emit(file);
             }
         };
@@ -101,12 +141,23 @@ export class File {
             this.interact.emit(event.detail.id);
         };
     }
+    /** The committed `value`, or the file currently being resized. */
+    get displayedFile() {
+        var _a;
+        return (_a = this.value) !== null && _a !== void 0 ? _a : this.resizingFile;
+    }
+    // Clear the transient file once `value` reflects the selection, keeping the
+    // same chip mounted across the hand-off (see file.spec.tsx) so only its
+    // badge changes instead of the field flashing empty.
+    handleValueChange() {
+        this.resizingFile = undefined;
+    }
     render() {
-        return (h(Host, { key: 'efdeb4e071a7bf484780eb239a1117a0e0fd0472', "aria-busy": this.isBusy ? 'true' : 'false' }, h("limel-file-dropzone", { key: '88d3924f5db23d1f3b07321bc7dc35663feeac8f', disabled: this.disabled || this.readonly || !!this.value, accept: this.accept, onFilesSelected: this.handleNewFiles }, this.renderChipset()), this.renderDragAndDropTip(), this.renderSpinner()));
+        return (h(Host, { key: '3f314e0a075c61a8b1e2b4a51451193abc53e12f', "aria-busy": this.isBusy ? 'true' : 'false' }, h("limel-file-dropzone", { key: '8374175635679e2082b4f80d431686f8fd76af61', disabled: this.disabled || this.readonly || !!this.displayedFile, accept: this.accept, onFilesSelected: this.handleNewFiles }, this.renderChipset()), this.renderDragAndDropTip(), this.renderSpinner()));
     }
     get statusText() {
         var _a, _b, _c;
-        return (_c = (_b = (_a = this.value) === null || _a === void 0 ? void 0 : _a.statusText) === null || _b === void 0 ? void 0 : _b.trim()) !== null && _c !== void 0 ? _c : '';
+        return (_c = (_b = (_a = this.displayedFile) === null || _a === void 0 ? void 0 : _a.statusText) === null || _b === void 0 ? void 0 : _b.trim()) !== null && _c !== void 0 ? _c : '';
     }
     /**
      * The component is busy for any reason: its own `loading`, or a file that
@@ -117,8 +168,8 @@ export class File {
     get isBusy() {
         var _a, _b;
         return (this.loading ||
-            Boolean((_a = this.value) === null || _a === void 0 ? void 0 : _a.loading) ||
-            ((_b = this.value) === null || _b === void 0 ? void 0 : _b.progress) !== undefined);
+            Boolean((_a = this.displayedFile) === null || _a === void 0 ? void 0 : _a.loading) ||
+            ((_b = this.displayedFile) === null || _b === void 0 ? void 0 : _b.progress) !== undefined);
     }
     renderSpinner() {
         if (!this.isBusy) {
@@ -127,35 +178,47 @@ export class File {
         return h("limel-spinner", null);
     }
     renderDragAndDropTip() {
-        if (this.value || this.disabled || this.readonly || this.isBusy) {
+        if (this.displayedFile ||
+            this.disabled ||
+            this.readonly ||
+            this.isBusy) {
             return;
         }
         return (h("div", { class: "drag-and-drop-tip" }, h("span", { class: "invisible-label-mock", role: "presentation" }, this.label), h("span", { class: "tip" }, this.dropZoneTip())));
     }
+    // Cheap pre-filter; the decode inside `resizeImage` is the authoritative
+    // check and throws (caught above) for anything that does not decode.
+    isResizableImage(file) {
+        var _a;
+        return (Boolean((_a = file.type) === null || _a === void 0 ? void 0 : _a.startsWith('image/')) &&
+            file.type !== 'image/svg+xml');
+    }
     getChipArray() {
-        if (!this.value) {
+        const file = this.displayedFile;
+        if (!file) {
             return [];
         }
         return [
-            Object.assign(Object.assign({}, DEFAULT_FILE_CHIP), { text: this.value.filename, id: this.value.id, icon: {
-                    name: getFileIcon(this.value),
-                    title: getFileExtensionTitle(this.value),
-                    color: getFileColor(this.value),
-                    backgroundColor: getFileBackgroundColor(this.value),
-                }, badge: this.getBadge(), href: this.value.href, menuItems: this.value.menuItems, loading: this.value.loading, progress: this.value.progress, invalid: this.value.invalid }),
+            Object.assign(Object.assign({}, DEFAULT_FILE_CHIP), { text: file.filename, id: file.id, icon: {
+                    name: getFileIcon(file),
+                    title: getFileExtensionTitle(file),
+                    color: getFileColor(file),
+                    backgroundColor: getFileBackgroundColor(file),
+                }, badge: this.getBadge(), href: file.href, menuItems: file.menuItems, loading: file.loading, progress: file.progress, invalid: file.invalid }),
         ];
     }
     getBadge() {
+        var _a;
         if (this.statusText) {
             return this.statusText;
         }
-        if (typeof this.value.size === 'number') {
-            return formatBytes(this.value.size);
+        if (typeof ((_a = this.displayedFile) === null || _a === void 0 ? void 0 : _a.size) === 'number') {
+            return formatBytes(this.displayedFile.size);
         }
         return undefined;
     }
     renderChipset() {
-        const chipset = (h("limel-chip-set", { disabled: this.disabled, readonly: this.readonly, invalid: this.invalid, label: this.label, helperText: this.helperText, leadingIcon: "upload_to_cloud", language: this.language, onChange: this.handleChipSetChange, onInteract: this.handleChipInteract, required: this.required, type: "input", value: this.getChipArray() }));
+        const chipset = (h("limel-chip-set", { disabled: this.disabled, readonly: this.readonly, invalid: this.invalid, clearAllButton: false, label: this.label, helperText: this.helperText, leadingIcon: "upload_to_cloud", language: this.language, onChange: this.handleChipSetChange, onInteract: this.handleChipInteract, required: this.required, type: "input", value: this.getChipArray() }));
         if (this.value) {
             return chipset;
         }
@@ -364,6 +427,33 @@ export class File {
                 "attribute": "accept",
                 "defaultValue": "'*'"
             },
+            "resizeImage": {
+                "type": "unknown",
+                "mutable": false,
+                "complexType": {
+                    "original": "ResizeOptions",
+                    "resolved": "{ width?: number; height?: number; fit?: \"cover\" | \"contain\"; type?: \"image/jpeg\" | \"image/png\"; quality?: number; rename?: (originalName: string) => string; }",
+                    "references": {
+                        "ResizeOptions": {
+                            "location": "import",
+                            "path": "../../util/image-resize",
+                            "id": "src/util/image-resize.ts::ResizeOptions",
+                            "referenceLocation": "ResizeOptions"
+                        }
+                    }
+                },
+                "required": false,
+                "optional": true,
+                "docs": {
+                    "tags": [{
+                            "name": "beta",
+                            "text": undefined
+                        }],
+                    "text": "Optional client-side image resize, applied before the `change` event is\nemitted: a selected image is downscaled and re-encoded on the user's\ndevice. Only decodable raster images are resized; all other files pass\nthrough unchanged. See the examples for details and caveats."
+                },
+                "getter": false,
+                "setter": false
+            },
             "language": {
                 "type": "string",
                 "mutable": false,
@@ -393,6 +483,11 @@ export class File {
             }
         };
     }
+    static get states() {
+        return {
+            "resizingFile": {}
+        };
+    }
     static get events() {
         return [{
                 "method": "change",
@@ -433,4 +528,10 @@ export class File {
                 }
             }];
     }
+    static get watchers() {
+        return [{
+                "propName": "value",
+                "methodName": "handleValueChange"
+            }];
+    }
 }

package/dist/collection/components/profile-picture/profile-picture.js

@@ -5,6 +5,13 @@ import translate from "../../global/translations";
 import { createRandomString } from "../../util/random-string";
 import { resizeImage } from "../../util/image-resize";
 import { ImageTemplate } from "../../util/image.template";
+/**
+ * Avatar output defaults. These live in the component rather than in the shared
+ * `resizeImage` util (which is deliberately unopinionated): avatars are stored
+ * as a compact JPEG at a fixed quality. Callers can override them via `resize`.
+ */
+const AVATAR_OUTPUT_TYPE = 'image/jpeg';
+const AVATAR_JPEG_QUALITY = 0.85;
 /**
  * This component displays a profile picture, while allowing the user
  * to change it via a file input or drag-and-drop.
@@ -80,7 +87,7 @@ export class ProfilePicture {
             return (h("limel-tooltip", { elementId: this.browseButtonId, label: this.helperText }));
         };
         this.handleNewFiles = async (event) => {
-            var _a, _b;
+            var _a, _b, _c, _d;
             event.stopPropagation();
             if (this.disabled) {
                 return;
@@ -99,10 +106,10 @@ export class ProfilePicture {
             // Optional client-side resize
             if (this.resize && file.fileContent instanceof File) {
                 try {
-                    const processed = await resizeImage(file.fileContent, Object.assign(Object.assign({}, this.resize), { fit: (_b = this.resize.fit) !== null && _b !== void 0 ? _b : this.imageFit }));
+                    const processed = await resizeImage(file.fileContent, Object.assign(Object.assign({}, this.resize), { fit: (_b = this.resize.fit) !== null && _b !== void 0 ? _b : this.imageFit, type: (_c = this.resize.type) !== null && _c !== void 0 ? _c : AVATAR_OUTPUT_TYPE, quality: (_d = this.resize.quality) !== null && _d !== void 0 ? _d : AVATAR_JPEG_QUALITY }));
                     out = Object.assign(Object.assign({}, file), { filename: processed.name, size: processed.size, contentType: processed.type, fileContent: processed });
                 }
-                catch (_c) {
+                catch (_e) {
                     // Fall back to original file if resize fails
                     out = file;
                 }
@@ -542,7 +549,7 @@ export class ProfilePicture {
                 "mutable": false,
                 "complexType": {
                     "original": "ResizeOptions",
-                    "resolved": "{ width: number; height: number; fit?: \"cover\" | \"contain\"; type?: \"image/jpeg\" | \"image/png\"; quality?: number; rename?: (originalName: string) => string; }",
+                    "resolved": "{ width?: number; height?: number; fit?: \"cover\" | \"contain\"; type?: \"image/jpeg\" | \"image/png\"; quality?: number; rename?: (originalName: string) => string; }",
                     "references": {
                         "ResizeOptions": {
                             "location": "import",
@@ -556,7 +563,7 @@ export class ProfilePicture {
                 "optional": true,
                 "docs": {
                     "tags": [],
-                    "text": "Optional client-side resize before emitting the file.\nIf provided, the selected image will be resized on the client device.\n:::note\nHEIC may not decode in all browsers; when decoding fails, the original\nfile will be emitted. See the examples for more info.\n:::"
+                    "text": "Optional client-side resize before emitting the file.\nIf provided, the selected image will be resized on the client device.\nOmitted options fall back to avatar defaults: `image/jpeg`, `quality`\n`0.85`, and the component's `imageFit`.\n:::note\nHEIC may not decode in all browsers; when decoding fails, the original\nfile will be emitted. See the examples for more info.\n:::"
                 },
                 "getter": false,
                 "setter": false

package/dist/collection/translations/da.js

@@ -29,6 +29,7 @@ export default {
     'chip-set.clear-all': 'Ryd alle',
     'snackbar.dismiss': 'Luk',
     'file.drag-and-drop-tips': 'Træk & slip filen her, eller klik for at gennemse.',
+    'file.optimizing': 'Optimerer…',
     'file-viewer.message.unsupported-filetype': 'Kan ikke vise en forhåndsvisning af denne filtype.',
     'file-viewer.message.try-other-options': 'Hent filen eller åbn den i en ny fane.',
     'file-viewer.message.file-not-found': 'Filen blev ikke fundet',

package/dist/collection/translations/de.js

@@ -29,6 +29,7 @@ export default {
     'chip-set.clear-all': 'Alles löschen',
     'snackbar.dismiss': 'Schließen',
     'file.drag-and-drop-tips': 'Ziehen Sie Ihre Datei hierher oder klicken Sie, um zu durchsuchen.',
+    'file.optimizing': 'Optimieren…',
     'file-viewer.message.unsupported-filetype': 'Für diesen Dateityp kann keine Vorschau angezeigt werden.',
     'file-viewer.message.try-other-options': 'Laden Sie die Datei herunter oder öffnen Sie sie in einem neuen Tab.',
     'file-viewer.message.file-not-found': 'Datei nicht gefunden',

package/dist/collection/translations/en.js

@@ -29,6 +29,7 @@ export default {
     'chip-set.clear-all': 'Clear all',
     'snackbar.dismiss': 'Dismiss',
     'file.drag-and-drop-tips': 'Drag & drop your file here, or click to browse.',
+    'file.optimizing': 'Optimizing…',
     'file-viewer.message.unsupported-filetype': 'Cannot display a preview for this file type.',
     'file-viewer.message.try-other-options': 'Download the file or open it in a new tab.',
     'file-viewer.message.file-not-found': 'File not found',

package/dist/collection/translations/fi.js

@@ -29,6 +29,7 @@ export default {
     'chip-set.clear-all': 'Tyhjennä kaikki',
     'snackbar.dismiss': 'Sulje',
     'file.drag-and-drop-tips': 'Vedä & pudota tiedostosi tähän, tai napsauta selataksesi.',
+    'file.optimizing': 'Optimoidaan…',
     'file-viewer.message.unsupported-filetype': 'Esikatselua ei voi näyttää tälle tiedostotyypille.',
     'file-viewer.message.try-other-options': 'Lataa tiedosto tai avaa se uudessa välilehdessä.',
     'file-viewer.message.file-not-found': 'Tiedostoa ei löydy',

package/dist/collection/translations/fr.js

@@ -29,6 +29,7 @@ export default {
     'chip-set.clear-all': 'Tout effacer',
     'snackbar.dismiss': 'Fermer',
     'file.drag-and-drop-tips': 'Glissez-déposez votre fichier ici, ou cliquez pour parcourir.',
+    'file.optimizing': 'Optimisation…',
     'file-viewer.message.unsupported-filetype': "Impossible d'afficher un aperçu pour ce type de fichier.",
     'file-viewer.message.try-other-options': 'Téléchargez le fichier ou ouvrez-le dans un nouvel onglet.',
     'file-viewer.message.file-not-found': 'Fichier introuvable',

package/dist/collection/translations/nl.js

@@ -29,6 +29,7 @@ export default {
     'chip-set.clear-all': 'Alles wissen',
     'snackbar.dismiss': 'Sluiten',
     'file.drag-and-drop-tips': 'Sleep een bestand hierheen of klik om te bladeren.',
+    'file.optimizing': 'Optimaliseren…',
     'file-viewer.message.unsupported-filetype': 'Kan geen voorbeeld weergeven voor dit bestandstype.',
     'file-viewer.message.try-other-options': 'Download het bestand of open het in een nieuw tabblad.',
     'file-viewer.message.file-not-found': 'Bestand niet gevonden',

package/dist/collection/translations/no.js

@@ -28,6 +28,7 @@ export default {
     'drag-handle.drag-to-reorder': 'Dra for å omorganisere',
     'chip-set.clear-all': 'Fjern alle',
     'file.drag-and-drop-tips': 'Dra & slipp filen her, eller klikk for å bla gjennom.',
+    'file.optimizing': 'Optimaliserer…',
     'file-viewer.message.unsupported-filetype': 'Kan ikke vise en forhåndsvisning av denne filtypen.',
     'file-viewer.message.try-other-options': 'Last ned filen eller åpne den i en ny fane.',
     'file-viewer.message.file-not-found': 'Filen ble ikke funnet',

package/dist/collection/translations/sv.js

@@ -29,6 +29,7 @@ export default {
     'chip-set.clear-all': 'Rensa alla',
     'snackbar.dismiss': 'Stäng',
     'file.drag-and-drop-tips': 'Dra & släpp filen här eller klicka om du vill bläddra.',
+    'file.optimizing': 'Optimerar…',
     'file-viewer.message.unsupported-filetype': 'Kan inte visa en förhandsvisning för denna filtyp.',
     'file-viewer.message.try-other-options': 'Ladda ner filen eller öppna den i en ny flik.',
     'file-viewer.message.file-not-found': 'Filen hittades inte',

package/dist/collection/util/image-resize.js

@@ -12,15 +12,17 @@
  *
  * Why resize client-side?
  * - Faster perceived uploads and lower bandwidth usage
- * - Consistent avatar sizes and formats (e.g., JPEG 400x400)
+ * - Consistent output sizes and formats (e.g., a 400x400 thumbnail)
  * - No server-side transformation required for common cases
  *
  * Fit strategies
- * - `cover` (default): The image is scaled to cover the target rectangle, and
- *   the excess parts are center-cropped. Good for avatars.
+ * - `cover`: The image is scaled to cover the target rectangle, and the excess
+ *   parts are center-cropped. Good for avatars.
  * - `contain`: The image is scaled to fit entirely within the target rectangle
  *   without cropping, letterboxing if needed. Good when you must preserve the
  *   entire image.
+ * - omitted: scales the whole image to fit without cropping (no pixels are
+ *   discarded).
  *
  * Decoding & EXIF orientation
  * EXIF orientation is a piece of metadata stored inside image files
@@ -46,9 +48,11 @@
  *   library or WASM module; this utility intentionally avoids extra dependencies.
  *
  * Output type & quality
- * - Default output is `image/jpeg` with `quality=0.85`, which is typically
- *   appropriate for avatars. You can switch to `image/png` to preserve
- *   transparency.
+ * - When `type` is omitted the source format is kept if the canvas can encode
+ *   it: a PNG stays a PNG (preserving transparency) and everything else is
+ *   encoded as `image/jpeg`. Set `type` explicitly to force a format.
+ * - JPEG `quality` is optional; when omitted the browser's native encoding
+ *   quality is used rather than an imposed value.
  * - The output filename extension is adjusted to match the chosen MIME type by
  *   default (e.g., `.jpg` or `.png`). You can override naming via the `rename`
  *   option.
@@ -73,9 +77,9 @@
  * const processed = await resizeImage(file, {
  *   width: 400,
  *   height: 400,
- *   fit: 'cover',         // default; center-crops
- *   type: 'image/jpeg',   // default
- *   quality: 0.85,        // default
+ *   fit: 'cover',         // center-crops; omit to fit without cropping
+ *   type: 'image/jpeg',   // omit to keep the source format
+ *   quality: 0.85,        // omit to use the browser's native quality
  * });
  * // Upload `processed` instead of the original file
  * ```
@@ -104,6 +108,17 @@
  * ```
  */
 // (Removed exported ResizeFit to avoid forcing a public symbol.)
+/**
+ * The image formats the canvas can reliably encode, mapped to their filename
+ * extension. Single source of truth for what this util can output: both the
+ * output-type resolution and the output filename extension derive from it. The
+ * `ResizeOptions.type` union below mirrors these keys — keep the two in sync
+ * when adding a format.
+ */
+const ENCODABLE_TYPES = {
+    'image/jpeg': 'jpg',
+    'image/png': 'png',
+};
 /**
  * Resize an image file on the client using Canvas/OffscreenCanvas.
  * Returns a new File with the requested format and dimensions.
@@ -118,9 +133,22 @@
  * @param options - Configuration for the resize operation.
  */
 export async function resizeImage(file, options) {
-    const { width, height, fit = 'cover', type = 'image/jpeg', quality = 0.85, rename = (name) => renameWithType(name, type), } = options;
+    var _a;
+    // This shared utility carries no opinionated defaults: an omitted option
+    // preserves the source file's own property rather than imposing a value.
+    // Consumers that want a specific default (e.g. limel-profile-picture) apply
+    // it themselves. See the `ResizeOptions` doc for the per-option behavior.
+    const { fit, quality } = options;
+    // When no output type is requested, keep the source file's format if the
+    // canvas can encode it (PNG stays PNG, preserving transparency); anything
+    // else falls back to JPEG.
+    const type = resolveOutputType(file.type, options.type);
+    const rename = (_a = options.rename) !== null && _a !== void 0 ? _a : ((name) => renameWithType(name, type));
     const source = await loadSource(file);
-    const { sx, sy, sw, sh, dx, dy, dw, dh } = computeRects(source.width, source.height, width, height, fit);
+    const sourceWidth = source.width;
+    const sourceHeight = source.height;
+    const { width, height } = resolveTargetSize(sourceWidth, sourceHeight, options.width, options.height);
+    const { sx, sy, sw, sh, dx, dy, dw, dh } = computeRects(sourceWidth, sourceHeight, width, height, fit);
     const canvas = createCanvas(width, height);
     const ctx = get2dContext(canvas);
     ctx.clearRect(0, 0, width, height);
@@ -129,6 +157,43 @@ export async function resizeImage(file, options) {
     const name = rename(file.name);
     return new File([blob], name, { type });
 }
+/**
+ * Resolve the target dimensions from the requested options, falling back to the
+ * source. A missing dimension is derived from the given one to preserve the
+ * source aspect ratio; when both are missing the source size is kept, so the
+ * image is only re-encoded. Non-positive requests are treated as missing.
+ *
+ * @param sourceWidth - Decoded source width
+ * @param sourceHeight - Decoded source height
+ * @param width - Requested target width, if any
+ * @param height - Requested target height, if any
+ */
+function resolveTargetSize(sourceWidth, sourceHeight, width, height) {
+    // A dimension counts as "requested" only when it's a positive number;
+    // `undefined`, `0`, negatives and `NaN` are all treated as missing.
+    const hasWidth = typeof width === 'number' && width > 0;
+    const hasHeight = typeof height === 'number' && height > 0;
+    // Both requested: use them as-is.
+    if (hasWidth && hasHeight) {
+        return { width, height };
+    }
+    // Only width requested: derive the height to keep the aspect ratio.
+    if (hasWidth) {
+        return {
+            width,
+            height: Math.round(width * (sourceHeight / sourceWidth)),
+        };
+    }
+    // Only height requested: derive the width to keep the aspect ratio.
+    if (hasHeight) {
+        return {
+            width: Math.round(height * (sourceWidth / sourceHeight)),
+            height,
+        };
+    }
+    // Neither requested: keep the source size and only re-encode.
+    return { width: sourceWidth, height: sourceHeight };
+}
 /** Whether OffscreenCanvas is available in the current environment. */
 function supportsOffscreen() {
     try {
@@ -167,7 +232,7 @@ function get2dContext(canvas) {
  * Convert the canvas content to a Blob, supporting both canvas types.
  * @param canvas - The source canvas
  * @param type - Output MIME type
- * @param quality - JPEG quality (0..1)
+ * @param quality - JPEG quality (0..1); omit to use the browser default
  */
 function canvasToBlob(canvas, type, quality) {
     if ('convertToBlob' in canvas) {
@@ -253,7 +318,8 @@ async function loadImageElement(file) {
  * @param sh - Source height
  * @param tw - Target width
  * @param th - Target height
- * @param fit - Fit mode (cover/contain)
+ * @param fit - Fit mode; `cover` center-crops, anything else (including
+ * omitted) scales the whole image to fit without cropping
  */
 function computeRects(sw, sh, tw, th, fit) {
     const sRatio = sw / sh;
@@ -291,13 +357,30 @@ function computeRects(sw, sh, tw, th, fit) {
     const dy = (th - drawH) / 2;
     return { sx: 0, sy: 0, sw, sh, dx, dy, dw: drawW, dh: drawH };
 }
+/**
+ * Resolve the output MIME type. An explicit request wins; otherwise the source
+ * file's format is kept when the canvas can encode it (see `ENCODABLE_TYPES`),
+ * so a PNG stays a PNG (preserving transparency) while every other input
+ * (WebP, HEIC, …) falls back to JPEG.
+ *
+ * @param sourceType - MIME type of the input file
+ * @param requested - Explicitly requested output type, if any
+ */
+function resolveOutputType(sourceType, requested) {
+    if (requested) {
+        return requested;
+    }
+    // Keep the source format when the canvas can encode it; otherwise JPEG.
+    const canEncodeSource = Object.prototype.hasOwnProperty.call(ENCODABLE_TYPES, sourceType);
+    return canEncodeSource ? sourceType : 'image/jpeg';
+}
 /**
  * Update filename extension to match the desired MIME type.
  * @param name - Original filename
  * @param type - Output MIME type
  */
 function renameWithType(name, type) {
-    const ext = type === 'image/png' ? 'png' : 'jpg';
+    const ext = ENCODABLE_TYPES[type];
     const idx = name.lastIndexOf('.');
     const base = idx > 0 ? name.slice(0, idx) : name;
     return `${base}.${ext}`;