yummies 7.11.0 → 7.13.0

package/media.cjs

@@ -1,99 +1,305 @@
-"use strict";
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const math = require("yummies/math");
+require("./chunk-CVq3Gv4J.cjs");
+let yummies_math = require("yummies/math");
+//#region src/media.ts
+/**
+* ---header-docs-section---
+* # yummies/media
+*
+* ## Description
+*
+* Binary and media helpers: Base64 data URLs, object URLs, image orientation fixes, and related
+* browser APIs wrapped in promises. Centralizes `FileReader`/`URL.createObjectURL` usage so image
+* pipelines and uploads stay consistent and easier to test or mock.
+*
+* ## Usage
+*
+* ```ts
+* import { blobToBase64 } from "yummies/media";
+* ```
+*/
+/**
+* Reads a {@link Blob} as a **data URL** string (`data:<mime>;base64,...`) using {@link FileReader#readAsDataURL}.
+*
+* Useful for previewing uploads, embedding small assets inline, or serializing binary for APIs that
+* expect Base64-in-JSON. The result includes the MIME prefix, not raw Base64 alone — use
+* {@link decodeDataUrl} if you need the payload and type separately.
+*
+* @param blob - Any `Blob` or `File` (files are blobs).
+* @returns Resolves to the data URL string; rejects if reading fails.
+*
+* @example
+* ```ts
+* const dataUrl = await blobToBase64(file);
+* previewImg.src = dataUrl;
+* ```
+*
+* @example
+* ```ts
+* const fromFetch = await fetch('/api/export').then((r) => r.blob());
+* const dataUrl = await blobToBase64(fromFetch);
+* ```
+*/
 function blobToBase64(blob) {
-  return new Promise((resolve, reject) => {
-    const reader = new FileReader();
-    reader.onloadend = () => resolve(reader.result);
-    reader.onerror = reject;
-    reader.readAsDataURL(blob);
-  });
+	return new Promise((resolve, reject) => {
+		const reader = new FileReader();
+		reader.onloadend = () => resolve(reader.result);
+		reader.onerror = reject;
+		reader.readAsDataURL(blob);
+	});
 }
-const blobToUrl = (urlOrBlob) => urlOrBlob instanceof Blob ? URL.createObjectURL(urlOrBlob) : urlOrBlob;
-const fileToBlob = (file) => {
-  return new Blob([file], { type: file.type });
+/**
+* If `urlOrBlob` is already a string, returns it unchanged. If it is a {@link Blob}, returns
+* `URL.createObjectURL(blob)` — a short-lived `blob:` URL valid in this document until
+* {@link URL.revokeObjectURL} is called.
+*
+* Pair with {@link renderImage} or `<img src>` without re-fetching binary data. **Remember to
+* `revokeObjectURL`** when the URL is no longer needed to avoid retaining blob memory.
+*
+* @param urlOrBlob - Remote/http(s) URL string, data URL, or a `Blob` / `File`.
+* @returns A string suitable for `HTMLImageElement.src` or similar.
+*
+* @example
+* ```ts
+* const src = blobToUrl(uploadedFile);
+* img.src = src;
+* // when done:
+* URL.revokeObjectURL(src);
+* ```
+*
+* @example
+* ```ts
+* blobToUrl('https://cdn.example.com/logo.png'); // passed through as-is
+* ```
+*/
+var blobToUrl = (urlOrBlob) => urlOrBlob instanceof Blob ? URL.createObjectURL(urlOrBlob) : urlOrBlob;
+/**
+* Creates a new {@link Blob} from a {@link File}, copying the bytes and keeping `file.type` as
+* the blob’s MIME type. Handy when an API accepts `Blob` but you only have `File`, or you want a
+* plain blob without the `File` name/lastModified metadata.
+*
+* @param file - Source file from an `<input type="file">` or drag-and-drop.
+* @returns A `Blob` with the same content and `type` as the file.
+*
+* @example
+* ```ts
+* const blob = fileToBlob(fileFromInput);
+* await uploadEndpoint(blob);
+* ```
+*
+* @example
+* ```ts
+* const blob = fileToBlob(imageFile);
+* const url = URL.createObjectURL(blob);
+* ```
+*/
+var fileToBlob = (file) => {
+	return new Blob([file], { type: file.type });
 };
-const imageToBlob = (imageElement, mimeType = "image/png") => {
-  const canvas = document.createElement("canvas");
-  canvas.width = imageElement.naturalWidth || 300;
-  canvas.height = imageElement.naturalHeight || 300;
-  canvas.getContext("2d").drawImage(imageElement, 0, 0);
-  const dataUri = canvas.toDataURL(mimeType, 1);
-  const base64data = dataUri.split(",")[1];
-  const base64MimeType = dataUri.split(";")[0].slice(5);
-  const bytes = globalThis.atob(base64data);
-  const buf = new ArrayBuffer(bytes.length);
-  const array = new Uint8Array(buf);
-  for (let index = 0; index < bytes.length; index++) {
-    array[index] = bytes.charCodeAt(index);
-  }
-  const blob = new Blob([array], { type: base64MimeType });
-  return blob;
+/**
+* Draws an {@link HTMLImageElement} onto an offscreen canvas, then builds a {@link Blob} from the
+* raster (via `canvas.toDataURL` + binary decode). Dimensions use `naturalWidth` / `naturalHeight`,
+* falling back to `300×300` if those are zero (e.g. not yet decoded).
+*
+* **CORS:** if the image is cross-origin without proper CORS headers, the canvas may be
+* *tainted* and `toDataURL` can throw — same browser rules as any canvas export.
+*
+* @param imageElement - Loaded image (`complete` / decoded recommended).
+* @param mimeType - Output MIME type, e.g. `'image/png'` (default) or `'image/jpeg'`. Encoder support is browser-dependent.
+* @returns Encoded image as a `Blob` with a matching `type` when possible.
+*
+* @example
+* ```ts
+* const img = await renderImage('/photo.jpg');
+* const jpegBlob = imageToBlob(img, 'image/jpeg');
+* ```
+*
+* @example
+* ```ts
+* const pngBlob = imageToBlob(cachedImg); // default image/png
+* ```
+*/
+var imageToBlob = (imageElement, mimeType = "image/png") => {
+	const canvas = document.createElement("canvas");
+	canvas.width = imageElement.naturalWidth || 300;
+	canvas.height = imageElement.naturalHeight || 300;
+	canvas.getContext("2d").drawImage(imageElement, 0, 0);
+	const dataUri = canvas.toDataURL(mimeType, 1);
+	const base64data = dataUri.split(",")[1];
+	const base64MimeType = dataUri.split(";")[0].slice(5);
+	const bytes = globalThis.atob(base64data);
+	const buf = new ArrayBuffer(bytes.length);
+	const array = new Uint8Array(buf);
+	for (let index = 0; index < bytes.length; index++) array[index] = bytes.charCodeAt(index);
+	return new Blob([array], { type: base64MimeType });
 };
-const renderImage = (urlOrBlob) => new Promise((resolve, reject) => {
-  const image = new Image();
-  image.src = blobToUrl(urlOrBlob);
-  image.onload = () => resolve(image);
-  image.onerror = () => reject();
+/**
+* Loads a resource into a new `HTMLImageElement`: `src` is set via {@link blobToUrl} (so blobs get
+* object URLs, strings are used directly). Resolves on `load` with the same element; rejects on
+* `error` (e.g. bad URL, network failure, corrupt image) **with no rejection value**.
+*
+* Does not add the node to the DOM — use the returned element for canvas, measuring, or
+* {@link imageToBlob}.
+*
+* @param urlOrBlob - Remote URL, data URL, or `Blob` / `File`.
+* @returns Promise that fulfills with the loaded `HTMLImageElement`.
+*
+* @example
+* ```ts
+* const img = await renderImage('https://example.com/pic.png');
+* document.body.appendChild(img);
+* ```
+*
+* @example
+* ```ts
+* const img = await renderImage(pickedFile);
+* const blob = imageToBlob(img, 'image/webp');
+* ```
+*/
+var renderImage = (urlOrBlob) => new Promise((resolve, reject) => {
+	const image = new Image();
+	image.src = blobToUrl(urlOrBlob);
+	image.onload = () => resolve(image);
+	image.onerror = () => reject();
 });
 function cropImageFromCanvas(context) {
-  const canvas = context.canvas;
-  let w = canvas.width;
-  let h = canvas.height;
-  const pix = { x: [], y: [] };
-  const imageData = context.getImageData(0, 0, canvas.width, canvas.height);
-  let x;
-  let y;
-  let index;
-  for (y = 0; y < h; y++) {
-    for (x = 0; x < w; x++) {
-      index = (y * w + x) * 4;
-      if (imageData.data[index + 3] > 0) {
-        pix.x.push(x);
-        pix.y.push(y);
-      }
-    }
-  }
-  pix.x.sort((a, b) => a - b);
-  pix.y.sort((a, b) => a - b);
-  const n = pix.x.length - 1;
-  w = 1 + pix.x[n] - pix.x[0];
-  h = 1 + pix.y[n] - pix.y[0];
-  const cut = context.getImageData(pix.x[0], pix.y[0], w, h);
-  canvas.width = w;
-  canvas.height = h;
-  context.putImageData(cut, 0, 0);
-  return canvas;
+	const canvas = context.canvas;
+	let w = canvas.width;
+	let h = canvas.height;
+	const pix = {
+		x: [],
+		y: []
+	};
+	const imageData = context.getImageData(0, 0, canvas.width, canvas.height);
+	let x;
+	let y;
+	let index;
+	for (y = 0; y < h; y++) for (x = 0; x < w; x++) {
+		index = (y * w + x) * 4;
+		if (imageData.data[index + 3] > 0) {
+			pix.x.push(x);
+			pix.y.push(y);
+		}
+	}
+	pix.x.sort((a, b) => a - b);
+	pix.y.sort((a, b) => a - b);
+	const n = pix.x.length - 1;
+	w = 1 + pix.x[n] - pix.x[0];
+	h = 1 + pix.y[n] - pix.y[0];
+	const cut = context.getImageData(pix.x[0], pix.y[0], w, h);
+	canvas.width = w;
+	canvas.height = h;
+	context.putImageData(cut, 0, 0);
+	return canvas;
 }
-const rotateImage = (image, angle) => {
-  const maxSize = Math.max(image.width, image.height);
-  const canvas = document.createElement("canvas");
-  canvas.width = maxSize;
-  canvas.height = maxSize;
-  const context = canvas.getContext("2d");
-  context.save();
-  context.translate(canvas.width / 2, canvas.height / 2);
-  context.rotate(math.degToRad(angle));
-  context.drawImage(image, -image.width / 2, -image.height / 2);
-  context.restore();
-  cropImageFromCanvas(context);
-  return renderImage(canvas.toDataURL("image/png"));
+/**
+* Rotates `image` around its center on a square canvas (side = max(width, height)), then **crops**
+* transparent margins by trimming to the bounding box of pixels with non-zero alpha.
+* Returns a **new** loaded `HTMLImageElement` (PNG data URL under the hood via {@link renderImage}).
+*
+* `angle` is in **degrees**; converted with {@link degToRad} from `yummies/math`.
+*
+* Very large sources can stress memory on some mobile browsers (known iPhone issues — see TODO in source).
+*
+* @param image - Source image (should be decoded; uses `width` / `height`).
+* @param angle - Rotation in degrees (e.g. `90` for quarter turn).
+* @returns Promise of a new `HTMLImageElement` showing the rotated, cropped result.
+*
+* @example
+* ```ts
+* const upright = await rotateImage(landscapeImg, 90);
+* ```
+*
+* @example
+* ```ts
+* const fixed = await rotateImage(await renderImage(file), -15);
+* ```
+*/
+var rotateImage = (image, angle) => {
+	const maxSize = Math.max(image.width, image.height);
+	const canvas = document.createElement("canvas");
+	canvas.width = maxSize;
+	canvas.height = maxSize;
+	const context = canvas.getContext("2d");
+	context.save();
+	context.translate(canvas.width / 2, canvas.height / 2);
+	context.rotate((0, yummies_math.degToRad)(angle));
+	context.drawImage(image, -image.width / 2, -image.height / 2);
+	context.restore();
+	cropImageFromCanvas(context);
+	return renderImage(canvas.toDataURL("image/png"));
 };
+/**
+* Parses a `data:` URL of the form `data:<mime>;base64,<payload>` into its MIME type and raw
+* Base64 body (without the `data:...;base64,` prefix). Non-matching strings yield `undefined`
+* fields in the result object.
+*
+* @param url - Full data URL string.
+* @returns `{ mimeType, data }` — both optional when the regex does not match.
+*
+* @example
+* ```ts
+* const { mimeType, data } = decodeDataUrl('data:image/png;base64,iVBORw0KGgo=');
+* // mimeType === 'image/png', data === 'iVBORw0KGgo='
+* ```
+*
+* @example
+* ```ts
+* decodeDataUrl('not-a-data-url'); // { mimeType: undefined, data: undefined }
+* ```
+*/
 function decodeDataUrl(url) {
-  const regex = /^data:(.*);base64,\s?(.*)$/;
-  const matches = new RegExp(regex).exec(url);
-  return {
-    mimeType: matches?.[1],
-    data: matches?.[2]
-  };
+	const matches = (/* @__PURE__ */ new RegExp(/^data:(.*);base64,\s?(.*)$/)).exec(url);
+	return {
+		mimeType: matches?.[1],
+		data: matches?.[2]
+	};
 }
-const isHttpUrl = (url) => {
-  return url.startsWith("https://") || url.startsWith("http://");
+/**
+* Returns `true` if `url` starts with `https://` or `http://` (case-sensitive, as in
+* `String#startsWith`). Does not validate that the rest is a well-formed URL — only the scheme
+* prefix. `blob:`, `data:`, and relative paths return `false`.
+*
+* @param url - String to test (often a user-provided or configured href).
+*
+* @example
+* ```ts
+* isHttpUrl('https://example.com/path'); // true
+* isHttpUrl('http://localhost:3000'); // true
+* ```
+*
+* @example
+* ```ts
+* isHttpUrl('//cdn.example.com'); // false — no explicit http(s) prefix
+* isHttpUrl('/assets/logo.png'); // false — relative path
+* ```
+*/
+var isHttpUrl = (url) => {
+	return url.startsWith("https://") || url.startsWith("http://");
 };
-const isBase64Image = (str) => {
-  const { mimeType, data } = decodeDataUrl(str);
-  return !!(data && mimeType?.startsWith("image/"));
+/**
+* Returns `true` when `str` is a data URL that {@link decodeDataUrl} can parse **and** the MIME
+* type starts with `image/` (e.g. `image/png`, `image/jpeg`). Requires both a non-empty Base64
+* payload and an image MIME — arbitrary `data:text/plain;base64,...` is `false`.
+*
+* @param str - Candidate string (often `img.src` or API payload).
+*
+* @example
+* ```ts
+* isBase64Image('data:image/png;base64,iVBORw0KGgo='); // true
+* ```
+*
+* @example
+* ```ts
+* isBase64Image('https://example.com/x.png'); // false
+* isBase64Image('data:text/plain;base64,SGk='); // false
+* ```
+*/
+var isBase64Image = (str) => {
+	const { mimeType, data } = decodeDataUrl(str);
+	return !!(data && mimeType?.startsWith("image/"));
 };
+//#endregion
 exports.blobToBase64 = blobToBase64;
 exports.blobToUrl = blobToUrl;
 exports.decodeDataUrl = decodeDataUrl;
@@ -103,4 +309,5 @@ exports.isBase64Image = isBase64Image;
 exports.isHttpUrl = isHttpUrl;
 exports.renderImage = renderImage;
 exports.rotateImage = rotateImage;
-//# sourceMappingURL=media.cjs.map
+
+//# sourceMappingURL=media.cjs.map

package/media.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"media.cjs","sources":["../src/media.ts"],"sourcesContent":["import { degToRad } from 'yummies/math';\n\nexport function blobToBase64(blob: Blob): Promise<string> {\n  return new Promise((resolve, reject) => {\n    const reader = new FileReader();\n    reader.onloadend = () => resolve(reader.result as string);\n    reader.onerror = reject;\n    reader.readAsDataURL(blob);\n  });\n}\n\nexport const blobToUrl = (urlOrBlob: string | Blob) =>\n  urlOrBlob instanceof Blob ? URL.createObjectURL(urlOrBlob) : urlOrBlob;\n\nexport const fileToBlob = (file: File) => {\n  return new Blob([file], { type: file.type });\n};\n\nexport const imageToBlob = (\n  imageElement: HTMLImageElement,\n  mimeType: string = 'image/png',\n) => {\n  const canvas = document.createElement('canvas');\n\n  canvas.width = imageElement.naturalWidth || 300;\n  canvas.height = imageElement.naturalHeight || 300;\n\n  canvas.getContext('2d')!.drawImage(imageElement, 0, 0);\n\n  const dataUri = canvas.toDataURL(mimeType, 1);\n  const base64data = dataUri.split(',')[1];\n  const base64MimeType = dataUri.split(';')[0].slice(5);\n\n  const bytes = globalThis.atob(base64data);\n  const buf = new ArrayBuffer(bytes.length);\n  const array = new Uint8Array(buf);\n\n  for (let index = 0; index < bytes.length; index++) {\n    array[index] = bytes.charCodeAt(index);\n  }\n\n  const blob = new Blob([array], { type: base64MimeType });\n\n  return blob;\n};\n\n/**\n * Loads and renders an image using `Image`.\n *\n * @returns {Promise<HTMLImageElement>}\n */\nexport const renderImage = (urlOrBlob: Blob | string) =>\n  new Promise<HTMLImageElement>((resolve, reject) => {\n    const image = new Image();\n    image.src = blobToUrl(urlOrBlob);\n    image.onload = () => resolve(image);\n    image.onerror = () => reject();\n  });\n\nfunction cropImageFromCanvas(context: CanvasRenderingContext2D) {\n  const canvas = context.canvas;\n  let w = canvas.width;\n  let h = canvas.height;\n  const pix: { x: number[]; y: number[] } = { x: [], y: [] };\n  const imageData = context.getImageData(0, 0, canvas.width, canvas.height);\n  let x: number;\n  let y: number;\n  let index: number;\n\n  for (y = 0; y < h; y++) {\n    for (x = 0; x < w; x++) {\n      index = (y * w + x) * 4;\n      if (imageData.data[index + 3] > 0) {\n        pix.x.push(x);\n        pix.y.push(y);\n      }\n    }\n  }\n  pix.x.sort((a, b) => a - b);\n  pix.y.sort((a, b) => a - b);\n  const n = pix.x.length - 1;\n\n  w = 1 + pix.x[n] - pix.x[0];\n  h = 1 + pix.y[n] - pix.y[0];\n  const cut = context.getImageData(pix.x[0], pix.y[0], w, h);\n\n  canvas.width = w;\n  canvas.height = h;\n  context.putImageData(cut, 0, 0);\n  return canvas;\n}\n\n// TODO: ломает iphone с огромными изображениями\nexport const rotateImage = (image: HTMLImageElement, angle: number) => {\n  const maxSize = Math.max(image.width, image.height);\n  const canvas = document.createElement('canvas');\n  canvas.width = maxSize;\n  canvas.height = maxSize;\n  const context = canvas.getContext('2d')!;\n  context.save();\n  context.translate(canvas.width / 2, canvas.height / 2);\n  context.rotate(degToRad(angle));\n  context.drawImage(image, -image.width / 2, -image.height / 2);\n  context.restore();\n  cropImageFromCanvas(context);\n  return renderImage(canvas.toDataURL('image/png'));\n};\n\ninterface DecodedDataUrl {\n  mimeType?: string;\n  data?: string;\n}\n\n/*\n * Returning object which contains base64 data and mime type of passed data url string.\n * */\nexport function decodeDataUrl(url: string): DecodedDataUrl {\n  const regex = /^data:(.*);base64,\\s?(.*)$/;\n  const matches = new RegExp(regex).exec(url);\n\n  return {\n    mimeType: matches?.[1],\n    data: matches?.[2],\n  };\n}\n\nexport const isHttpUrl = (url: string): boolean => {\n  return url.startsWith('https://') || url.startsWith('http://');\n};\n\nexport const isBase64Image = (str: string): boolean => {\n  const { mimeType, data } = decodeDataUrl(str);\n  return !!(data && mimeType?.startsWith('image/'));\n};\n"],"names":["degToRad"],"mappings":";;;AAEO,SAAS,aAAa,MAA6B;AACxD,SAAO,IAAI,QAAQ,CAAC,SAAS,WAAW;AACtC,UAAM,SAAS,IAAI,WAAA;AACnB,WAAO,YAAY,MAAM,QAAQ,OAAO,MAAgB;AACxD,WAAO,UAAU;AACjB,WAAO,cAAc,IAAI;AAAA,EAC3B,CAAC;AACH;AAEO,MAAM,YAAY,CAAC,cACxB,qBAAqB,OAAO,IAAI,gBAAgB,SAAS,IAAI;AAExD,MAAM,aAAa,CAAC,SAAe;AACxC,SAAO,IAAI,KAAK,CAAC,IAAI,GAAG,EAAE,MAAM,KAAK,MAAM;AAC7C;AAEO,MAAM,cAAc,CACzB,cACA,WAAmB,gBAChB;AACH,QAAM,SAAS,SAAS,cAAc,QAAQ;AAE9C,SAAO,QAAQ,aAAa,gBAAgB;AAC5C,SAAO,SAAS,aAAa,iBAAiB;AAE9C,SAAO,WAAW,IAAI,EAAG,UAAU,cAAc,GAAG,CAAC;AAErD,QAAM,UAAU,OAAO,UAAU,UAAU,CAAC;AAC5C,QAAM,aAAa,QAAQ,MAAM,GAAG,EAAE,CAAC;AACvC,QAAM,iBAAiB,QAAQ,MAAM,GAAG,EAAE,CAAC,EAAE,MAAM,CAAC;AAEpD,QAAM,QAAQ,WAAW,KAAK,UAAU;AACxC,QAAM,MAAM,IAAI,YAAY,MAAM,MAAM;AACxC,QAAM,QAAQ,IAAI,WAAW,GAAG;AAEhC,WAAS,QAAQ,GAAG,QAAQ,MAAM,QAAQ,SAAS;AACjD,UAAM,KAAK,IAAI,MAAM,WAAW,KAAK;AAAA,EACvC;AAEA,QAAM,OAAO,IAAI,KAAK,CAAC,KAAK,GAAG,EAAE,MAAM,gBAAgB;AAEvD,SAAO;AACT;AAOO,MAAM,cAAc,CAAC,cAC1B,IAAI,QAA0B,CAAC,SAAS,WAAW;AACjD,QAAM,QAAQ,IAAI,MAAA;AAClB,QAAM,MAAM,UAAU,SAAS;AAC/B,QAAM,SAAS,MAAM,QAAQ,KAAK;AAClC,QAAM,UAAU,MAAM,OAAA;AACxB,CAAC;AAEH,SAAS,oBAAoB,SAAmC;AAC9D,QAAM,SAAS,QAAQ;AACvB,MAAI,IAAI,OAAO;AACf,MAAI,IAAI,OAAO;AACf,QAAM,MAAoC,EAAE,GAAG,CAAA,GAAI,GAAG,CAAA,EAAC;AACvD,QAAM,YAAY,QAAQ,aAAa,GAAG,GAAG,OAAO,OAAO,OAAO,MAAM;AACxE,MAAI;AACJ,MAAI;AACJ,MAAI;AAEJ,OAAK,IAAI,GAAG,IAAI,GAAG,KAAK;AACtB,SAAK,IAAI,GAAG,IAAI,GAAG,KAAK;AACtB,eAAS,IAAI,IAAI,KAAK;AACtB,UAAI,UAAU,KAAK,QAAQ,CAAC,IAAI,GAAG;AACjC,YAAI,EAAE,KAAK,CAAC;AACZ,YAAI,EAAE,KAAK,CAAC;AAAA,MACd;AAAA,IACF;AAAA,EACF;AACA,MAAI,EAAE,KAAK,CAAC,GAAG,MAAM,IAAI,CAAC;AAC1B,MAAI,EAAE,KAAK,CAAC,GAAG,MAAM,IAAI,CAAC;AAC1B,QAAM,IAAI,IAAI,EAAE,SAAS;AAEzB,MAAI,IAAI,IAAI,EAAE,CAAC,IAAI,IAAI,EAAE,CAAC;AAC1B,MAAI,IAAI,IAAI,EAAE,CAAC,IAAI,IAAI,EAAE,CAAC;AAC1B,QAAM,MAAM,QAAQ,aAAa,IAAI,EAAE,CAAC,GAAG,IAAI,EAAE,CAAC,GAAG,GAAG,CAAC;AAEzD,SAAO,QAAQ;AACf,SAAO,SAAS;AAChB,UAAQ,aAAa,KAAK,GAAG,CAAC;AAC9B,SAAO;AACT;AAGO,MAAM,cAAc,CAAC,OAAyB,UAAkB;AACrE,QAAM,UAAU,KAAK,IAAI,MAAM,OAAO,MAAM,MAAM;AAClD,QAAM,SAAS,SAAS,cAAc,QAAQ;AAC9C,SAAO,QAAQ;AACf,SAAO,SAAS;AAChB,QAAM,UAAU,OAAO,WAAW,IAAI;AACtC,UAAQ,KAAA;AACR,UAAQ,UAAU,OAAO,QAAQ,GAAG,OAAO,SAAS,CAAC;AACrD,UAAQ,OAAOA,cAAS,KAAK,CAAC;AAC9B,UAAQ,UAAU,OAAO,CAAC,MAAM,QAAQ,GAAG,CAAC,MAAM,SAAS,CAAC;AAC5D,UAAQ,QAAA;AACR,sBAAoB,OAAO;AAC3B,SAAO,YAAY,OAAO,UAAU,WAAW,CAAC;AAClD;AAUO,SAAS,cAAc,KAA6B;AACzD,QAAM,QAAQ;AACd,QAAM,UAAU,IAAI,OAAO,KAAK,EAAE,KAAK,GAAG;AAE1C,SAAO;AAAA,IACL,UAAU,UAAU,CAAC;AAAA,IACrB,MAAM,UAAU,CAAC;AAAA,EAAA;AAErB;AAEO,MAAM,YAAY,CAAC,QAAyB;AACjD,SAAO,IAAI,WAAW,UAAU,KAAK,IAAI,WAAW,SAAS;AAC/D;AAEO,MAAM,gBAAgB,CAAC,QAAyB;AACrD,QAAM,EAAE,UAAU,SAAS,cAAc,GAAG;AAC5C,SAAO,CAAC,EAAE,QAAQ,UAAU,WAAW,QAAQ;AACjD;;;;;;;;;;"}
+{"version":3,"file":"media.cjs","names":[],"sources":["../src/media.ts"],"sourcesContent":["/**\n * ---header-docs-section---\n * # yummies/media\n *\n * ## Description\n *\n * Binary and media helpers: Base64 data URLs, object URLs, image orientation fixes, and related\n * browser APIs wrapped in promises. Centralizes `FileReader`/`URL.createObjectURL` usage so image\n * pipelines and uploads stay consistent and easier to test or mock.\n *\n * ## Usage\n *\n * ```ts\n * import { blobToBase64 } from \"yummies/media\";\n * ```\n */\n\nimport { degToRad } from 'yummies/math';\n\n/**\n * Reads a {@link Blob} as a **data URL** string (`data:<mime>;base64,...`) using {@link FileReader#readAsDataURL}.\n *\n * Useful for previewing uploads, embedding small assets inline, or serializing binary for APIs that\n * expect Base64-in-JSON. The result includes the MIME prefix, not raw Base64 alone — use\n * {@link decodeDataUrl} if you need the payload and type separately.\n *\n * @param blob - Any `Blob` or `File` (files are blobs).\n * @returns Resolves to the data URL string; rejects if reading fails.\n *\n * @example\n * ```ts\n * const dataUrl = await blobToBase64(file);\n * previewImg.src = dataUrl;\n * ```\n *\n * @example\n * ```ts\n * const fromFetch = await fetch('/api/export').then((r) => r.blob());\n * const dataUrl = await blobToBase64(fromFetch);\n * ```\n */\nexport function blobToBase64(blob: Blob): Promise<string> {\n  return new Promise((resolve, reject) => {\n    const reader = new FileReader();\n    reader.onloadend = () => resolve(reader.result as string);\n    reader.onerror = reject;\n    reader.readAsDataURL(blob);\n  });\n}\n\n/**\n * If `urlOrBlob` is already a string, returns it unchanged. If it is a {@link Blob}, returns\n * `URL.createObjectURL(blob)` — a short-lived `blob:` URL valid in this document until\n * {@link URL.revokeObjectURL} is called.\n *\n * Pair with {@link renderImage} or `<img src>` without re-fetching binary data. **Remember to\n * `revokeObjectURL`** when the URL is no longer needed to avoid retaining blob memory.\n *\n * @param urlOrBlob - Remote/http(s) URL string, data URL, or a `Blob` / `File`.\n * @returns A string suitable for `HTMLImageElement.src` or similar.\n *\n * @example\n * ```ts\n * const src = blobToUrl(uploadedFile);\n * img.src = src;\n * // when done:\n * URL.revokeObjectURL(src);\n * ```\n *\n * @example\n * ```ts\n * blobToUrl('https://cdn.example.com/logo.png'); // passed through as-is\n * ```\n */\nexport const blobToUrl = (urlOrBlob: string | Blob) =>\n  urlOrBlob instanceof Blob ? URL.createObjectURL(urlOrBlob) : urlOrBlob;\n\n/**\n * Creates a new {@link Blob} from a {@link File}, copying the bytes and keeping `file.type` as\n * the blob’s MIME type. Handy when an API accepts `Blob` but you only have `File`, or you want a\n * plain blob without the `File` name/lastModified metadata.\n *\n * @param file - Source file from an `<input type=\"file\">` or drag-and-drop.\n * @returns A `Blob` with the same content and `type` as the file.\n *\n * @example\n * ```ts\n * const blob = fileToBlob(fileFromInput);\n * await uploadEndpoint(blob);\n * ```\n *\n * @example\n * ```ts\n * const blob = fileToBlob(imageFile);\n * const url = URL.createObjectURL(blob);\n * ```\n */\nexport const fileToBlob = (file: File) => {\n  return new Blob([file], { type: file.type });\n};\n\n/**\n * Draws an {@link HTMLImageElement} onto an offscreen canvas, then builds a {@link Blob} from the\n * raster (via `canvas.toDataURL` + binary decode). Dimensions use `naturalWidth` / `naturalHeight`,\n * falling back to `300×300` if those are zero (e.g. not yet decoded).\n *\n * **CORS:** if the image is cross-origin without proper CORS headers, the canvas may be\n * *tainted* and `toDataURL` can throw — same browser rules as any canvas export.\n *\n * @param imageElement - Loaded image (`complete` / decoded recommended).\n * @param mimeType - Output MIME type, e.g. `'image/png'` (default) or `'image/jpeg'`. Encoder support is browser-dependent.\n * @returns Encoded image as a `Blob` with a matching `type` when possible.\n *\n * @example\n * ```ts\n * const img = await renderImage('/photo.jpg');\n * const jpegBlob = imageToBlob(img, 'image/jpeg');\n * ```\n *\n * @example\n * ```ts\n * const pngBlob = imageToBlob(cachedImg); // default image/png\n * ```\n */\nexport const imageToBlob = (\n  imageElement: HTMLImageElement,\n  mimeType: string = 'image/png',\n) => {\n  const canvas = document.createElement('canvas');\n\n  canvas.width = imageElement.naturalWidth || 300;\n  canvas.height = imageElement.naturalHeight || 300;\n\n  canvas.getContext('2d')!.drawImage(imageElement, 0, 0);\n\n  const dataUri = canvas.toDataURL(mimeType, 1);\n  const base64data = dataUri.split(',')[1];\n  const base64MimeType = dataUri.split(';')[0].slice(5);\n\n  const bytes = globalThis.atob(base64data);\n  const buf = new ArrayBuffer(bytes.length);\n  const array = new Uint8Array(buf);\n\n  for (let index = 0; index < bytes.length; index++) {\n    array[index] = bytes.charCodeAt(index);\n  }\n\n  const blob = new Blob([array], { type: base64MimeType });\n\n  return blob;\n};\n\n/**\n * Loads a resource into a new `HTMLImageElement`: `src` is set via {@link blobToUrl} (so blobs get\n * object URLs, strings are used directly). Resolves on `load` with the same element; rejects on\n * `error` (e.g. bad URL, network failure, corrupt image) **with no rejection value**.\n *\n * Does not add the node to the DOM — use the returned element for canvas, measuring, or\n * {@link imageToBlob}.\n *\n * @param urlOrBlob - Remote URL, data URL, or `Blob` / `File`.\n * @returns Promise that fulfills with the loaded `HTMLImageElement`.\n *\n * @example\n * ```ts\n * const img = await renderImage('https://example.com/pic.png');\n * document.body.appendChild(img);\n * ```\n *\n * @example\n * ```ts\n * const img = await renderImage(pickedFile);\n * const blob = imageToBlob(img, 'image/webp');\n * ```\n */\nexport const renderImage = (urlOrBlob: Blob | string) =>\n  new Promise<HTMLImageElement>((resolve, reject) => {\n    const image = new Image();\n    image.src = blobToUrl(urlOrBlob);\n    image.onload = () => resolve(image);\n    image.onerror = () => reject();\n  });\n\nfunction cropImageFromCanvas(context: CanvasRenderingContext2D) {\n  const canvas = context.canvas;\n  let w = canvas.width;\n  let h = canvas.height;\n  const pix: { x: number[]; y: number[] } = { x: [], y: [] };\n  const imageData = context.getImageData(0, 0, canvas.width, canvas.height);\n  let x: number;\n  let y: number;\n  let index: number;\n\n  for (y = 0; y < h; y++) {\n    for (x = 0; x < w; x++) {\n      index = (y * w + x) * 4;\n      if (imageData.data[index + 3] > 0) {\n        pix.x.push(x);\n        pix.y.push(y);\n      }\n    }\n  }\n  pix.x.sort((a, b) => a - b);\n  pix.y.sort((a, b) => a - b);\n  const n = pix.x.length - 1;\n\n  w = 1 + pix.x[n] - pix.x[0];\n  h = 1 + pix.y[n] - pix.y[0];\n  const cut = context.getImageData(pix.x[0], pix.y[0], w, h);\n\n  canvas.width = w;\n  canvas.height = h;\n  context.putImageData(cut, 0, 0);\n  return canvas;\n}\n\n// TODO: ломает iphone с огромными изображениями\n/**\n * Rotates `image` around its center on a square canvas (side = max(width, height)), then **crops**\n * transparent margins by trimming to the bounding box of pixels with non-zero alpha.\n * Returns a **new** loaded `HTMLImageElement` (PNG data URL under the hood via {@link renderImage}).\n *\n * `angle` is in **degrees**; converted with {@link degToRad} from `yummies/math`.\n *\n * Very large sources can stress memory on some mobile browsers (known iPhone issues — see TODO in source).\n *\n * @param image - Source image (should be decoded; uses `width` / `height`).\n * @param angle - Rotation in degrees (e.g. `90` for quarter turn).\n * @returns Promise of a new `HTMLImageElement` showing the rotated, cropped result.\n *\n * @example\n * ```ts\n * const upright = await rotateImage(landscapeImg, 90);\n * ```\n *\n * @example\n * ```ts\n * const fixed = await rotateImage(await renderImage(file), -15);\n * ```\n */\nexport const rotateImage = (image: HTMLImageElement, angle: number) => {\n  const maxSize = Math.max(image.width, image.height);\n  const canvas = document.createElement('canvas');\n  canvas.width = maxSize;\n  canvas.height = maxSize;\n  const context = canvas.getContext('2d')!;\n  context.save();\n  context.translate(canvas.width / 2, canvas.height / 2);\n  context.rotate(degToRad(angle));\n  context.drawImage(image, -image.width / 2, -image.height / 2);\n  context.restore();\n  cropImageFromCanvas(context);\n  return renderImage(canvas.toDataURL('image/png'));\n};\n\ninterface DecodedDataUrl {\n  mimeType?: string;\n  data?: string;\n}\n\n/**\n * Parses a `data:` URL of the form `data:<mime>;base64,<payload>` into its MIME type and raw\n * Base64 body (without the `data:...;base64,` prefix). Non-matching strings yield `undefined`\n * fields in the result object.\n *\n * @param url - Full data URL string.\n * @returns `{ mimeType, data }` — both optional when the regex does not match.\n *\n * @example\n * ```ts\n * const { mimeType, data } = decodeDataUrl('data:image/png;base64,iVBORw0KGgo=');\n * // mimeType === 'image/png', data === 'iVBORw0KGgo='\n * ```\n *\n * @example\n * ```ts\n * decodeDataUrl('not-a-data-url'); // { mimeType: undefined, data: undefined }\n * ```\n */\nexport function decodeDataUrl(url: string): DecodedDataUrl {\n  const regex = /^data:(.*);base64,\\s?(.*)$/;\n  const matches = new RegExp(regex).exec(url);\n\n  return {\n    mimeType: matches?.[1],\n    data: matches?.[2],\n  };\n}\n\n/**\n * Returns `true` if `url` starts with `https://` or `http://` (case-sensitive, as in\n * `String#startsWith`). Does not validate that the rest is a well-formed URL — only the scheme\n * prefix. `blob:`, `data:`, and relative paths return `false`.\n *\n * @param url - String to test (often a user-provided or configured href).\n *\n * @example\n * ```ts\n * isHttpUrl('https://example.com/path'); // true\n * isHttpUrl('http://localhost:3000'); // true\n * ```\n *\n * @example\n * ```ts\n * isHttpUrl('//cdn.example.com'); // false — no explicit http(s) prefix\n * isHttpUrl('/assets/logo.png'); // false — relative path\n * ```\n */\nexport const isHttpUrl = (url: string): boolean => {\n  return url.startsWith('https://') || url.startsWith('http://');\n};\n\n/**\n * Returns `true` when `str` is a data URL that {@link decodeDataUrl} can parse **and** the MIME\n * type starts with `image/` (e.g. `image/png`, `image/jpeg`). Requires both a non-empty Base64\n * payload and an image MIME — arbitrary `data:text/plain;base64,...` is `false`.\n *\n * @param str - Candidate string (often `img.src` or API payload).\n *\n * @example\n * ```ts\n * isBase64Image('data:image/png;base64,iVBORw0KGgo='); // true\n * ```\n *\n * @example\n * ```ts\n * isBase64Image('https://example.com/x.png'); // false\n * isBase64Image('data:text/plain;base64,SGk='); // false\n * ```\n */\nexport const isBase64Image = (str: string): boolean => {\n  const { mimeType, data } = decodeDataUrl(str);\n  return !!(data && mimeType?.startsWith('image/'));\n};\n"],"mappings":"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"}

package/media.d.ts

@@ -1,20 +1,222 @@
+/**
+ * ---header-docs-section---
+ * # yummies/media
+ *
+ * ## Description
+ *
+ * Binary and media helpers: Base64 data URLs, object URLs, image orientation fixes, and related
+ * browser APIs wrapped in promises. Centralizes `FileReader`/`URL.createObjectURL` usage so image
+ * pipelines and uploads stay consistent and easier to test or mock.
+ *
+ * ## Usage
+ *
+ * ```ts
+ * import { blobToBase64 } from "yummies/media";
+ * ```
+ */
+/**
+ * Reads a {@link Blob} as a **data URL** string (`data:<mime>;base64,...`) using {@link FileReader#readAsDataURL}.
+ *
+ * Useful for previewing uploads, embedding small assets inline, or serializing binary for APIs that
+ * expect Base64-in-JSON. The result includes the MIME prefix, not raw Base64 alone — use
+ * {@link decodeDataUrl} if you need the payload and type separately.
+ *
+ * @param blob - Any `Blob` or `File` (files are blobs).
+ * @returns Resolves to the data URL string; rejects if reading fails.
+ *
+ * @example
+ * ```ts
+ * const dataUrl = await blobToBase64(file);
+ * previewImg.src = dataUrl;
+ * ```
+ *
+ * @example
+ * ```ts
+ * const fromFetch = await fetch('/api/export').then((r) => r.blob());
+ * const dataUrl = await blobToBase64(fromFetch);
+ * ```
+ */
 declare function blobToBase64(blob: Blob): Promise<string>;
+/**
+ * If `urlOrBlob` is already a string, returns it unchanged. If it is a {@link Blob}, returns
+ * `URL.createObjectURL(blob)` — a short-lived `blob:` URL valid in this document until
+ * {@link URL.revokeObjectURL} is called.
+ *
+ * Pair with {@link renderImage} or `<img src>` without re-fetching binary data. **Remember to
+ * `revokeObjectURL`** when the URL is no longer needed to avoid retaining blob memory.
+ *
+ * @param urlOrBlob - Remote/http(s) URL string, data URL, or a `Blob` / `File`.
+ * @returns A string suitable for `HTMLImageElement.src` or similar.
+ *
+ * @example
+ * ```ts
+ * const src = blobToUrl(uploadedFile);
+ * img.src = src;
+ * // when done:
+ * URL.revokeObjectURL(src);
+ * ```
+ *
+ * @example
+ * ```ts
+ * blobToUrl('https://cdn.example.com/logo.png'); // passed through as-is
+ * ```
+ */
 declare const blobToUrl: (urlOrBlob: string | Blob) => string;
+/**
+ * Creates a new {@link Blob} from a {@link File}, copying the bytes and keeping `file.type` as
+ * the blob’s MIME type. Handy when an API accepts `Blob` but you only have `File`, or you want a
+ * plain blob without the `File` name/lastModified metadata.
+ *
+ * @param file - Source file from an `<input type="file">` or drag-and-drop.
+ * @returns A `Blob` with the same content and `type` as the file.
+ *
+ * @example
+ * ```ts
+ * const blob = fileToBlob(fileFromInput);
+ * await uploadEndpoint(blob);
+ * ```
+ *
+ * @example
+ * ```ts
+ * const blob = fileToBlob(imageFile);
+ * const url = URL.createObjectURL(blob);
+ * ```
+ */
 declare const fileToBlob: (file: File) => Blob;
+/**
+ * Draws an {@link HTMLImageElement} onto an offscreen canvas, then builds a {@link Blob} from the
+ * raster (via `canvas.toDataURL` + binary decode). Dimensions use `naturalWidth` / `naturalHeight`,
+ * falling back to `300×300` if those are zero (e.g. not yet decoded).
+ *
+ * **CORS:** if the image is cross-origin without proper CORS headers, the canvas may be
+ * *tainted* and `toDataURL` can throw — same browser rules as any canvas export.
+ *
+ * @param imageElement - Loaded image (`complete` / decoded recommended).
+ * @param mimeType - Output MIME type, e.g. `'image/png'` (default) or `'image/jpeg'`. Encoder support is browser-dependent.
+ * @returns Encoded image as a `Blob` with a matching `type` when possible.
+ *
+ * @example
+ * ```ts
+ * const img = await renderImage('/photo.jpg');
+ * const jpegBlob = imageToBlob(img, 'image/jpeg');
+ * ```
+ *
+ * @example
+ * ```ts
+ * const pngBlob = imageToBlob(cachedImg); // default image/png
+ * ```
+ */
 declare const imageToBlob: (imageElement: HTMLImageElement, mimeType?: string) => Blob;
 /**
- * Loads and renders an image using `Image`.
+ * Loads a resource into a new `HTMLImageElement`: `src` is set via {@link blobToUrl} (so blobs get
+ * object URLs, strings are used directly). Resolves on `load` with the same element; rejects on
+ * `error` (e.g. bad URL, network failure, corrupt image) **with no rejection value**.
+ *
+ * Does not add the node to the DOM — use the returned element for canvas, measuring, or
+ * {@link imageToBlob}.
+ *
+ * @param urlOrBlob - Remote URL, data URL, or `Blob` / `File`.
+ * @returns Promise that fulfills with the loaded `HTMLImageElement`.
  *
- * @returns {Promise<HTMLImageElement>}
+ * @example
+ * ```ts
+ * const img = await renderImage('https://example.com/pic.png');
+ * document.body.appendChild(img);
+ * ```
+ *
+ * @example
+ * ```ts
+ * const img = await renderImage(pickedFile);
+ * const blob = imageToBlob(img, 'image/webp');
+ * ```
  */
 declare const renderImage: (urlOrBlob: Blob | string) => Promise<HTMLImageElement>;
+/**
+ * Rotates `image` around its center on a square canvas (side = max(width, height)), then **crops**
+ * transparent margins by trimming to the bounding box of pixels with non-zero alpha.
+ * Returns a **new** loaded `HTMLImageElement` (PNG data URL under the hood via {@link renderImage}).
+ *
+ * `angle` is in **degrees**; converted with {@link degToRad} from `yummies/math`.
+ *
+ * Very large sources can stress memory on some mobile browsers (known iPhone issues — see TODO in source).
+ *
+ * @param image - Source image (should be decoded; uses `width` / `height`).
+ * @param angle - Rotation in degrees (e.g. `90` for quarter turn).
+ * @returns Promise of a new `HTMLImageElement` showing the rotated, cropped result.
+ *
+ * @example
+ * ```ts
+ * const upright = await rotateImage(landscapeImg, 90);
+ * ```
+ *
+ * @example
+ * ```ts
+ * const fixed = await rotateImage(await renderImage(file), -15);
+ * ```
+ */
 declare const rotateImage: (image: HTMLImageElement, angle: number) => Promise<HTMLImageElement>;
 interface DecodedDataUrl {
     mimeType?: string;
     data?: string;
 }
+/**
+ * Parses a `data:` URL of the form `data:<mime>;base64,<payload>` into its MIME type and raw
+ * Base64 body (without the `data:...;base64,` prefix). Non-matching strings yield `undefined`
+ * fields in the result object.
+ *
+ * @param url - Full data URL string.
+ * @returns `{ mimeType, data }` — both optional when the regex does not match.
+ *
+ * @example
+ * ```ts
+ * const { mimeType, data } = decodeDataUrl('data:image/png;base64,iVBORw0KGgo=');
+ * // mimeType === 'image/png', data === 'iVBORw0KGgo='
+ * ```
+ *
+ * @example
+ * ```ts
+ * decodeDataUrl('not-a-data-url'); // { mimeType: undefined, data: undefined }
+ * ```
+ */
 declare function decodeDataUrl(url: string): DecodedDataUrl;
+/**
+ * Returns `true` if `url` starts with `https://` or `http://` (case-sensitive, as in
+ * `String#startsWith`). Does not validate that the rest is a well-formed URL — only the scheme
+ * prefix. `blob:`, `data:`, and relative paths return `false`.
+ *
+ * @param url - String to test (often a user-provided or configured href).
+ *
+ * @example
+ * ```ts
+ * isHttpUrl('https://example.com/path'); // true
+ * isHttpUrl('http://localhost:3000'); // true
+ * ```
+ *
+ * @example
+ * ```ts
+ * isHttpUrl('//cdn.example.com'); // false — no explicit http(s) prefix
+ * isHttpUrl('/assets/logo.png'); // false — relative path
+ * ```
+ */
 declare const isHttpUrl: (url: string) => boolean;
+/**
+ * Returns `true` when `str` is a data URL that {@link decodeDataUrl} can parse **and** the MIME
+ * type starts with `image/` (e.g. `image/png`, `image/jpeg`). Requires both a non-empty Base64
+ * payload and an image MIME — arbitrary `data:text/plain;base64,...` is `false`.
+ *
+ * @param str - Candidate string (often `img.src` or API payload).
+ *
+ * @example
+ * ```ts
+ * isBase64Image('data:image/png;base64,iVBORw0KGgo='); // true
+ * ```
+ *
+ * @example
+ * ```ts
+ * isBase64Image('https://example.com/x.png'); // false
+ * isBase64Image('data:text/plain;base64,SGk='); // false
+ * ```
+ */
 declare const isBase64Image: (str: string) => boolean;
 
 export { blobToBase64, blobToUrl, decodeDataUrl, fileToBlob, imageToBlob, isBase64Image, isHttpUrl, renderImage, rotateImage };