@decocms/blocks 7.50.0 → 7.51.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decocms/blocks",
-  "version": "7.50.0",
+  "version": "7.51.0",
   "type": "module",
   "engines": {
     "node": ">=24"

package/src/hooks/Image.test.ts

@@ -1,5 +1,11 @@
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
-import { getOptimizedMediaUrl, getSrcSet } from "./Image";
+import {
+	getImageQuality,
+	getOptimizedMediaUrl,
+	getSrcSet,
+	type ImageQuality,
+	registerImageQuality,
+} from "./Image";
 
 describe("getOptimizedMediaUrl", () => {
 	let warnSpy: ReturnType<typeof vi.spyOn>;
@@ -98,3 +104,82 @@ describe("getSrcSet", () => {
 		expect(result).toContain("foo.jpg");
 	});
 });
+
+describe("registerImageQuality", () => {
+	// Module-level setter, so every test has to put it back or it leaks into
+	// the rest of the file.
+	afterEach(() => {
+		registerImageQuality(undefined);
+	});
+
+	it("emits no quality param by default", () => {
+		// The guarantee that makes this safe to land: every site that does not
+		// opt in keeps byte-identical URLs, so no CDN cache is invalidated.
+		expect(getImageQuality()).toBeUndefined();
+		const result = getOptimizedMediaUrl({
+			originalSrc: "https://cdn.example.com/foo.jpg",
+			width: 200,
+			fit: "cover",
+		});
+		expect(result).not.toContain("quality");
+	});
+
+	it("emits the registered quality for CDN-routed images", () => {
+		registerImageQuality("high");
+		const result = getOptimizedMediaUrl({
+			originalSrc: "https://cdn.example.com/foo.jpg",
+			width: 200,
+			fit: "cover",
+		});
+		expect(result).toContain("quality=high");
+	});
+	it("pins the exact URL, param order included", () => {
+		// Param ORDER is part of the CDN cache key, and `toContain` cannot see
+		// it: reordering the params would keep every other assertion here green
+		// while cold-caching every image on every site. It is also the property
+		// that lets a site swap its node_modules patch for this setter without a
+		// cache flush, so it needs a real equality check.
+		registerImageQuality("high");
+		expect(
+			getOptimizedMediaUrl({
+				originalSrc: "https://cdn.example.com/foo.jpg",
+				width: 200,
+				height: 300,
+				fit: "cover",
+			}),
+		).toBe(
+			"https://decoims.com/image?fit=cover&width=200&height=300&quality=high&src=https://cdn.example.com/foo.jpg",
+		);
+	});
+
+	it("carries the quality into every srcset entry", () => {
+		registerImageQuality("high");
+		const result = getSrcSet("https://cdn.example.com/foo.jpg", 100);
+		const entries = result?.split(", ") ?? [];
+		expect(entries.length).toBeGreaterThan(1);
+		for (const entry of entries) {
+			expect(entry).toContain("quality=high");
+		}
+	});
+
+	it("leaves VTEX sources alone — they resize via their own path syntax", () => {
+		registerImageQuality("high");
+		const result = getOptimizedMediaUrl({
+			originalSrc:
+				"https://acme.vtexassets.com/arquivos/ids/123456/product.jpg?v=1",
+			width: 200,
+			height: 300,
+			fit: "cover",
+		});
+		expect(result).toContain("/arquivos/ids/123456-200-300/");
+		expect(result).not.toContain("quality");
+	});
+
+	it("treats an empty string as unset, for untyped callers", () => {
+		// Unreachable from TypeScript now that the parameter is a union, but a
+		// value read from env or CMS config arrives as a plain string, so the
+		// runtime guard still earns its keep.
+		registerImageQuality("" as unknown as ImageQuality);
+		expect(getImageQuality()).toBeUndefined();
+	});
+});

package/src/hooks/Image.tsx

@@ -31,6 +31,61 @@ export function getImageCdnDomain(): string {
 	return imageCdnDomain;
 }
 
+// -------------------------------------------------------------------------
+// Configurable image quality
+// -------------------------------------------------------------------------
+
+/**
+ * Quality levels the Deco image CDN accepts as a site-wide default.
+ *
+ * The CDN maps these to 60% / 70% / 80%. It also accepts `original` (100%),
+ * deliberately excluded here: a global 100% default hurts performance on
+ * every page, which is the same call `DefaultQualityOptions` makes in the
+ * Fresh implementation this file was ported from (deco-cx/apps,
+ * website/components/Image.tsx).
+ *
+ * A union rather than `string` because the CDN **fails silently** on
+ * anything else: it answers 200 and serves its 60% default. So the obvious
+ * `registerImageQuality("80")` — quality means 1-100 in Cloudflare Images,
+ * next/image and imgix — would quietly serve the LOWEST quality while
+ * changing the cache key on every image. Measured against production
+ * decoims.com on one asset: no param 2911 B, `low` 2911, `medium` 3235,
+ * `high` 5189, and `"80"` / `"HIGH"` / garbage all 2911.
+ */
+export type ImageQuality = "low" | "medium" | "high";
+
+let imageQuality: ImageQuality | undefined;
+
+/**
+ * Register the quality level `getOptimizedMediaUrl` asks the image CDN for.
+ *
+ * Call once at module scope in your site's setup, NOT from a loader, action or
+ * anything else on the request path. This is module-level state shared by every
+ * request in a Worker isolate: setting it per-request would leak across
+ * concurrent requests, and setting it on only one of the SSR/hydration paths
+ * would produce mismatched `src`/`srcSet` and re-download every image.
+ *
+ * Unset by default, which emits no `quality` param and leaves the CDN on its
+ * 60% default — so existing sites are byte-for-byte unaffected and no CDN
+ * cache is invalidated. Set it when a site's art direction needs fidelity over
+ * bytes: on fashion/editorial catalogues the default compression visibly
+ * softens fabric texture and print detail.
+ *
+ * Applies to every URL built by `getOptimizedMediaUrl` — `Image`, `getSrcSet`
+ * and also `Video` when it is given `forceOptimizedSrc`. It does NOT apply to
+ * VTEX- or Shopify-hosted sources: those are resized through their own native
+ * URL syntax (`optimizeVTEX` / `optimizeShopify`), which returns before the
+ * query-param block. On a VTEX storefront that means product imagery is
+ * untouched and only CMS/banner assets are affected.
+ */
+export function registerImageQuality(quality: ImageQuality | undefined) {
+	imageQuality = quality || undefined;
+}
+
+export function getImageQuality(): ImageQuality | undefined {
+	return imageQuality;
+}
+
 // -------------------------------------------------------------------------
 // Fit options & optimization types
 // -------------------------------------------------------------------------
@@ -126,6 +181,7 @@ export function getOptimizedMediaUrl(opts: OptimizationOptions): string {
 	params.set("fit", fit);
 	params.set("width", `${width}`);
 	if (height) params.set("height", `${height}`);
+	if (imageQuality) params.set("quality", imageQuality);
 
 	return `https://${imageCdnDomain}/image?${params}&src=${imageSource}`;
 }

package/src/hooks/index.ts

@@ -8,10 +8,13 @@ export {
 	default as Image,
 	registerImageCdnDomain,
 	getImageCdnDomain,
+	registerImageQuality,
+	getImageQuality,
 	getOptimizedMediaUrl,
 	getSrcSet,
 	FACTORS,
 	type ImageProps,
+	type ImageQuality,
 	type FitOptions,
 } from "./Image";
 export { Picture, Source, type PictureProps, type SourceProps } from "./Picture";