@asstio-dev/storefront 0.6.0 → 0.7.0

package/README.md

@@ -53,7 +53,7 @@ const { data: page } = await storefront.GET("/v1/products/{slugOrId}/variants",
 ```
 
 Every example in this file is compiled as part of `npm run check` — the source of them is
-[`examples/readme.ts`](examples/readme.ts), which also covers product lookup, ETag revalidation and crawling.
+[`examples/readme.ts`](examples/readme.ts), which also covers product lookup, ETag revalidation, crawling, and image formats.
 
 ### Images
 
@@ -78,6 +78,70 @@ for (const file of product?.files ?? []) console.log(file.filename, fileUrl(site
 `videoSources` returns `[]` for anything that is not a video, while `mediaUrl`/`pictureSources`/`fileUrl`/`posterUrl`
 throw `MediaUrlError` when the descriptor cannot produce that URL — branch on `kind` before calling.
 
+### Image formats
+
+A site's **formats** (`site.media.formats`: `card`, `gallery`, `thumb`, `cart`, `swatch`, `default`, plus custom
+keys) say how an image is framed: aspect, fit (`contain` · `cover` · `natural`), padding and a background per
+`bg` class. They are published with the site, so the look changes without a frontend deploy. `formatImage` turns
+a descriptor and a format key into everything a `<picture>` needs:
+
+```ts
+import { formatImage } from "@asstio-dev/storefront";
+
+const f = formatImage(site.media, product.image, "card", [
+  { media: "(min-width: 1080px)", size: "25vw" },   // your slot's width per breakpoint
+  { size: "100vw" },                                // the last one without a media condition
+]);
+// React:
+// <div className={styles.cardImage}>                                  ← your slot: your class, may be a flex/grid item
+//   <div style={f.box}>                                               ← the aspect frame, the slot's only child
+//     <canvas ref={blurhashCanvas} style={f.placeholder} />           ← optional placeholder, same rectangle as the image
+//     <picture>
+//       {f.sources.map((s) => <source key={s.type} {...s} />)}
+//       <img {...f.fallback} style={f.img} alt={alt} loading="lazy" />
+//     </picture>
+//   </div>
+// </div>
+```
+
+Plain HTML (templating):
+
+```ts
+const f = formatImage(site.media, product.image, "card", [
+  { media: "(min-width: 1080px)", size: "25vw" },
+  { media: "(min-width: 640px)", size: "50vw" },
+  { size: "100vw" },
+]);
+// alt is merchant text, not SDK output: escape it for the attribute.
+const escapeAttr = (s: string) => s.replaceAll("&", "&amp;").replaceAll('"', "&quot;").replaceAll("<", "&lt;").replaceAll(">", "&gt;");
+const alt = escapeAttr(product.image.alt["sv"] ?? product.name);
+// Your slot owns the width; box is its only child in every fit:
+const picture =
+  `<picture>${f.sources.map((s) => `<source type="${s.type}" srcset="${s.srcSet}" sizes="${s.sizes}">`).join("")}` +
+  `<img src="${f.fallback.src}" srcset="${f.fallback.srcSet}" sizes="${f.fallback.sizes}" width="${f.fallback.width}" height="${f.fallback.height}" alt="${alt}" loading="lazy" style="${styleToCss(f.img)}"></picture>`;
+const placeholder = `<canvas width="32" height="32" style="${styleToCss(f.placeholder)}"></canvas>`;
+const html = `<div class="card-image"><div style="${styleToCss(f.box)}">${placeholder}${picture}</div></div>`;
+```
+
+- **Element contract.** Your slot element owns the width (grid, flex, `className`); it may be stretched. Put the
+  `box` inside it as its only child and give the box **no** padding, border or height of its own — its inline
+  styles pin its geometry, so a stretched slot never distorts the format's aspect.
+- **One rectangle.** `img` and `placeholder` are the same absolutely positioned rectangle with `object-fit: fill`,
+  computed from the descriptor: a blurhash canvas of any decode size is stretched to exactly where the image will
+  paint. The box's `backgroundColor` shows around a `contain` image and through transparent AVIF/WebP.
+- **Natural** has a box too, at the image's own aspect and without a colour; `img` and `placeholder` fill it. So
+  the layout is reserved before load in every fit, and the placeholder sits under the image the same way.
+- **`sizes`** is your slots scaled by the image's drawn fraction with `calc()`; `srcset` keeps the real widths, so
+  the browser downloads a sharp enough rendition for a cover crop and not a wasted one for a padded packshot.
+- `formats: null` (a site without formats) or an unknown key falls back to `default`, then to `natural`; your own
+  CSS keeps working. `focal` (set per placement in Asstio) positions a `cover` crop; `showWhole` renders a cover
+  format as contain for that image. `formatImage` throws `MediaUrlError` for video descriptors, file descriptors,
+  a descriptor without `w`/`h`, a descriptor without renditions, or an empty `slots` array.
+- Plain HTML: see the templating example above, or the compiled function `productCard` in [`examples/readme.ts`](examples/readme.ts).
+  `styleToCss(f.box)` gives the `style` attribute value for any element. Escape anything that is not SDK output
+  (`alt`, product names) before it goes into markup; the React example needs no escaping because React escapes
+  attribute values.
+
 ### Product content
 
 `description` is **already sanitized** on the server: render `description.html` as-is — do not sanitize, escape or

package/dist/index.d.ts

@@ -46,4 +46,4 @@ export type FilterSelection = NonNullable<NonNullable<paths["/v1/products"]["get
  */
 export declare function filterQuery(selection: Record<string, string | string[] | undefined>): FilterSelection;
 export { decodeFilterValues, encodeFilterValues } from "./filters.js";
-export { fileUrl, mediaHash, mediaUrl, MediaUrlError, pickWidth, pictureSources, posterUrl, srcSet, videoSources, type MediaConfig, type MediaDescriptor, type PictureSources, type VideoSource, } from "./media.js";
+export { coverOffset, fileUrl, fillFactor, formatFactor, formatImage, imageRect, mediaHash, mediaUrl, MediaUrlError, pickWidth, pictureSources, posterUrl, scaledSizes, srcSet, styleToCss, videoSources, type FormatFit, type FormattedImage, type MediaConfig, type MediaDescriptor, type MediaFormat, type PictureSources, type SlotSize, type VideoSource, } from "./media.js";

package/dist/index.js

@@ -35,4 +35,4 @@ export function filterQuery(selection) {
     return out;
 }
 export { decodeFilterValues, encodeFilterValues } from "./filters.js";
-export { fileUrl, mediaHash, mediaUrl, MediaUrlError, pickWidth, pictureSources, posterUrl, srcSet, videoSources, } from "./media.js";
+export { coverOffset, fileUrl, fillFactor, formatFactor, formatImage, imageRect, mediaHash, mediaUrl, MediaUrlError, pickWidth, pictureSources, posterUrl, scaledSizes, srcSet, styleToCss, videoSources, } from "./media.js";

package/dist/media.d.ts

@@ -49,3 +49,83 @@ export declare function posterUrl(site: MediaConfig, d: MediaDescriptor, width:
 export declare function fileUrl(site: MediaConfig, d: MediaDescriptor): string;
 /** Every encoded rendition of a video, for `<source>` elements. Empty for anything that is not a video. */
 export declare function videoSources(site: MediaConfig, d: MediaDescriptor): VideoSource[];
+export type FormatFit = "contain" | "cover" | "natural";
+/** One slot size of the frontend's layout (F6): `{ media: "(min-width: 1080px)", size: "25vw" }`; the last entry
+ *  has no media condition. The SDK turns these into the `sizes` attribute. */
+export type SlotSize = {
+    media?: string;
+    size: string;
+};
+/**
+ * The image's drawn width as a fraction of the slot (spec §6 rule 4). `rBox` = format W/H, `rImg` = image w/h,
+ * `padding` a fraction of the box's width (contain only).
+ */
+export declare function fillFactor(fit: FormatFit, rBox: number, rImg: number, padding: number): number;
+/**
+ * Where a cover image sits (spec §3.3): the fractions `ox`/`oy` of the overflow placed before the box, so the
+ * focal point is as centred as possible without showing an edge. Visible fraction `v = min(rBox/rImg, rImg/rBox)`;
+ * along the overflowing axis `clamp((f − v/2) / (1 − v), 0, 1)`, the other axis 0.5. Unset focal ⇒ centre.
+ */
+export declare function coverOffset(focal: {
+    x: number | string;
+    y: number | string;
+} | null | undefined, rBox: number, rImg: number): {
+    ox: number;
+    oy: number;
+};
+/**
+ * The rectangle the image occupies, in percent of the box (spec §6 rule 3): `width = fill·100`,
+ * `height = fill·rBox/rImg·100`; contain centred (the padding inset is inside `fill`), cover placed by
+ * `coverOffset` (negative offsets; the box clips), natural the whole box (its box has the image's aspect).
+ * The `<img>` and the placeholder both use it.
+ */
+export declare function imageRect(fit: FormatFit, rBox: number, rImg: number, fill: number, offset: {
+    ox: number;
+    oy: number;
+}): {
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+};
+/** `fill` with 4 significant digits: a positive factor never rounds to 0 (review 2 #12). */
+export declare function formatFactor(fill: number): string;
+/** The `sizes` attribute: every slot's size scaled by `fill` with `calc()`, unchanged when `fill` is 1 (F10). */
+export declare function scaledSizes(slots: SlotSize[], fill: number): string;
+export type MediaFormat = components["schemas"]["MediaFormatDto"];
+export type FormattedImage = {
+    /** The format key actually used, after fallback ("default" when the site has no formats). */
+    format: string;
+    /** The effective fit, after `showWhole`. */
+    fit: FormatFit;
+    /** The aspect frame's style (camelCase CSS): the slot's only child in every fit. For natural it takes the
+     *  image's own aspect and has no colour. */
+    box: Record<string, string>;
+    /** The `<img>` style: the image's rectangle in the box. */
+    img: Record<string, string>;
+    /** The placeholder layer's style (e.g. a blurhash canvas): the same rectangle as `img`. */
+    placeholder: Record<string, string>;
+    sources: {
+        type: string;
+        srcSet: string;
+        sizes: string;
+    }[];
+    fallback: {
+        src: string;
+        srcSet: string;
+        sizes: string;
+        width: number;
+        height: number;
+    };
+};
+/**
+ * A complete, standards-conforming `<picture>` for one descriptor in one of the site's formats (spec 2026-09-23 §6).
+ * Render: your **slot** element (your className, may be a flex/grid item) → `box` (the slot's only child, in every
+ * fit) → the placeholder layer and `<picture>` with `sources` and an `<img>` carrying `fallback` and `img`.
+ * `slots` describes your layout's widths for the slot (F6); the SDK scales them into `sizes`.
+ */
+export declare function formatImage(site: MediaConfig, d: MediaDescriptor, formatKey: string, slots: SlotSize[]): FormattedImage;
+/** A camelCase style object as a `style` attribute value, for plain HTML and templating engines. Meant for
+ *  `formatImage` output, whose values are SDK-generated or a server-validated `#rrggbb`: it does not escape, so
+ *  do not pass it values of your own that could hold `"`, `;` or `<`. */
+export declare function styleToCss(style: Record<string, string>): string;

package/dist/media.js

@@ -112,3 +112,145 @@ export function videoSources(site, d) {
         name: v.name,
     }));
 }
+/**
+ * The image's drawn width as a fraction of the slot (spec §6 rule 4). `rBox` = format W/H, `rImg` = image w/h,
+ * `padding` a fraction of the box's width (contain only).
+ */
+export function fillFactor(fit, rBox, rImg, padding) {
+    if (fit === "natural")
+        return 1;
+    if (fit === "cover")
+        return Math.max(1, rImg / rBox);
+    return Math.min(1 - 2 * padding, (1 / rBox - 2 * padding) * rImg);
+}
+/**
+ * Where a cover image sits (spec §3.3): the fractions `ox`/`oy` of the overflow placed before the box, so the
+ * focal point is as centred as possible without showing an edge. Visible fraction `v = min(rBox/rImg, rImg/rBox)`;
+ * along the overflowing axis `clamp((f − v/2) / (1 − v), 0, 1)`, the other axis 0.5. Unset focal ⇒ centre.
+ */
+export function coverOffset(focal, rBox, rImg) {
+    const v = Math.min(rBox / rImg, rImg / rBox);
+    if (v >= 1)
+        return { ox: 0.5, oy: 0.5 };
+    const pos = (f) => Math.min(1, Math.max(0, (f - v / 2) / (1 - v)));
+    const fx = focal == null ? 0.5 : toNumber(focal.x);
+    const fy = focal == null ? 0.5 : toNumber(focal.y);
+    return rImg > rBox ? { ox: pos(fx), oy: 0.5 } : { ox: 0.5, oy: pos(fy) };
+}
+/**
+ * The rectangle the image occupies, in percent of the box (spec §6 rule 3): `width = fill·100`,
+ * `height = fill·rBox/rImg·100`; contain centred (the padding inset is inside `fill`), cover placed by
+ * `coverOffset` (negative offsets; the box clips), natural the whole box (its box has the image's aspect).
+ * The `<img>` and the placeholder both use it.
+ */
+export function imageRect(fit, rBox, rImg, fill, offset) {
+    if (fit === "natural")
+        return { left: 0, top: 0, width: 100, height: 100 };
+    const width = fill * 100;
+    const height = ((fill * rBox) / rImg) * 100;
+    if (fit === "contain")
+        return { left: (100 - width) / 2, top: (100 - height) / 2, width, height };
+    return { left: offset.ox * (100 - width), top: offset.oy * (100 - height), width, height };
+}
+/** `fill` with 4 significant digits: a positive factor never rounds to 0 (review 2 #12). */
+export function formatFactor(fill) {
+    return String(Number(fill.toPrecision(4)));
+}
+/** The `sizes` attribute: every slot's size scaled by `fill` with `calc()`, unchanged when `fill` is 1 (F10). */
+export function scaledSizes(slots, fill) {
+    if (slots.length === 0)
+        throw new MediaUrlError("formatImage: slots must not be empty");
+    return slots
+        .map((s) => {
+        const size = fill === 1 ? s.size : `calc(${s.size} * ${formatFactor(fill)})`;
+        return s.media ? `${s.media} ${size}` : size;
+    })
+        .join(", ");
+}
+const NATURAL = { aspect: null, fit: "natural", padding: 0, background: null };
+const pct = (v) => `${Number(v.toFixed(4))}%`;
+/** Rule 1: `formats[key] ?? formats.default ?? natural`. Own-property lookups: a key like "constructor" must fall
+ *  through to `default`/natural, never resolve on `Object.prototype`. */
+function resolveFormat(site, key) {
+    const formats = site.formats ?? null;
+    if (formats && Object.hasOwn(formats, key))
+        return { key, format: formats[key] };
+    if (formats && Object.hasOwn(formats, "default"))
+        return { key: "default", format: formats.default };
+    return { key: "default", format: NATURAL };
+}
+function parseAspect(aspect, key) {
+    const m = aspect == null ? null : /^(\d{1,3})\/(\d{1,3})$/.exec(aspect);
+    if (!m)
+        throw new MediaUrlError(`formatImage: format '${key}' aspect '${aspect}' is not "W/H"`);
+    return { w: Number(m[1]), h: Number(m[2]) };
+}
+/**
+ * A complete, standards-conforming `<picture>` for one descriptor in one of the site's formats (spec 2026-09-23 §6).
+ * Render: your **slot** element (your className, may be a flex/grid item) → `box` (the slot's only child, in every
+ * fit) → the placeholder layer and `<picture>` with `sources` and an `<img>` carrying `fallback` and `img`.
+ * `slots` describes your layout's widths for the slot (F6); the SDK scales them into `sizes`.
+ */
+export function formatImage(site, d, formatKey, slots) {
+    if (d.kind !== "image")
+        throw new MediaUrlError(`formatImage: kind '${d.kind}' is not an image`);
+    requireImage(d, "formatImage");
+    if (d.w == null || d.h == null)
+        throw new MediaUrlError(`formatImage: descriptor ${d.id} has no w/h`);
+    const w = toNumber(d.w);
+    const h = toNumber(d.h);
+    const { key, format } = resolveFormat(site, formatKey);
+    const rawFit = format.fit;
+    // An unknown fit falls back to natural (spec §8), so `FormattedImage.fit` is always a real FormatFit.
+    let fit = rawFit === "contain" || rawFit === "cover" ? rawFit : "natural";
+    if (fit === "cover" && d.showWhole)
+        fit = "contain";
+    // Natural gets a box too (spec §6 rule 3): the descriptor's own aspect, no colour, the image fills it.
+    const a = fit === "natural" ? { w, h } : parseAspect(format.aspect, key);
+    const rBox = a.w / a.h;
+    const rImg = w / h;
+    const padding = fit === "contain" ? toNumber(format.padding) : 0;
+    const fill = fillFactor(fit, rBox, rImg, padding);
+    const rect = imageRect(fit, rBox, rImg, fill, coverOffset(d.focal, rBox, rImg));
+    const bgClass = d.bg ?? "default";
+    const bg = fit !== "natural" && format.background
+        ? Object.hasOwn(format.background, bgClass)
+            ? format.background[bgClass]
+            : Object.hasOwn(format.background, "default")
+                ? format.background.default
+                : null
+        : null;
+    const box = {
+        display: "block", position: "relative", overflow: "hidden", width: "100%", height: "auto", aspectRatio: `${a.w} / ${a.h}`,
+        minHeight: "0", maxHeight: "none", padding: "0", border: "0", boxSizing: "content-box",
+        alignSelf: "flex-start", justifySelf: "stretch", flex: "none",
+        ...(bg ? { backgroundColor: bg } : {}),
+    };
+    const layer = {
+        position: "absolute", left: pct(rect.left), top: pct(rect.top), width: pct(rect.width), height: pct(rect.height),
+        display: "block", objectFit: "fill",
+        // A global `img { max-width: 100%; height: auto }` reset must not shrink a cover rectangle wider than the box.
+        maxWidth: "none", maxHeight: "none", minWidth: "0", minHeight: "0", margin: "0", padding: "0", border: "0",
+    };
+    const sizes = scaledSizes(slots, fill);
+    // Same rendition logic as pictureSources (sources except the last format, middle-width fallback src): delegate
+    // rather than duplicate it; formatImage keeps the real w/h it already validated for the fallback dimensions.
+    const p = pictureSources(site, d, sizes);
+    return {
+        format: key,
+        fit,
+        box,
+        img: layer,
+        placeholder: { ...layer },
+        sources: p.sources,
+        fallback: { src: p.img.src, srcSet: p.img.srcSet, sizes, width: w, height: h },
+    };
+}
+/** A camelCase style object as a `style` attribute value, for plain HTML and templating engines. Meant for
+ *  `formatImage` output, whose values are SDK-generated or a server-validated `#rrggbb`: it does not escape, so
+ *  do not pass it values of your own that could hold `"`, `;` or `<`. */
+export function styleToCss(style) {
+    return Object.entries(style)
+        .map(([k, v]) => `${k.replace(/[A-Z]/g, (c) => "-" + c.toLowerCase())}: ${v}`)
+        .join("; ");
+}

package/dist/schema.d.ts

@@ -441,6 +441,7 @@ export interface components {
             /** Format: int32 */
             duration: number | null | string;
             filename: null | string;
+            focal: null | components["schemas"]["MediaFocalDto"];
             formats: string[];
             /** Format: int32 */
             h: number | null | string;
@@ -454,6 +455,7 @@ export interface components {
             /** Format: int32 */
             recipe: number | string;
             role: string;
+            showWhole: boolean;
             variants: components["schemas"]["MediaVideoVariantDto"][] | null;
             view: null | string;
             /** Format: int32 */
@@ -462,8 +464,26 @@ export interface components {
         };
         MediaDto: {
             baseUrl: string;
+            formats: null | {
+                [key: string]: components["schemas"]["MediaFormatDto"];
+            };
             templates: components["schemas"]["MediaTemplatesDto"];
         };
+        MediaFocalDto: {
+            /** Format: double */
+            x: number | string;
+            /** Format: double */
+            y: number | string;
+        };
+        MediaFormatDto: {
+            aspect: null | string;
+            background: null | {
+                [key: string]: string;
+            };
+            fit: string;
+            /** Format: double */
+            padding: number | string;
+        };
         MediaPosterDto: {
             formats: string[];
             widths: (number | string)[];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@asstio-dev/storefront",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Typed client for the Asstio Storefront API (generated from OpenAPI).",
   "repository": {
     "type": "git",
@@ -19,13 +19,15 @@
     "typecheck-examples": "tsc -p tsconfig.examples.json",
     "build": "npm run generate && tsc -p tsconfig.json && node -e \"require('node:fs').copyFileSync('src/schema.d.ts','dist/schema.d.ts')\" && npm run typecheck-examples && npm run smoke",
     "test": "vitest run",
+    "test:browser": "playwright test -c browser/playwright.config.ts",
     "check": "npm run generate && npm run typecheck-examples && npm test && git diff --exit-code -- src/schema.d.ts && test -z \"$(git status --porcelain -- src/schema.d.ts)\"",
-    "smoke": "node --input-type=module -e \"import(\\\"./dist/index.js\\\").then(m => { for (const f of [\\\"createStorefrontClient\\\", \\\"filterQuery\\\", \\\"encodeFilterValues\\\", \\\"decodeFilterValues\\\", \\\"pictureSources\\\", \\\"mediaUrl\\\"]) if (typeof m[f] !== \\\"function\\\") throw new Error(\\\"missing export \\\" + f) })\""
+    "smoke": "node --input-type=module -e \"import(\\\"./dist/index.js\\\").then(m => { for (const f of [\\\"createStorefrontClient\\\", \\\"filterQuery\\\", \\\"encodeFilterValues\\\", \\\"decodeFilterValues\\\", \\\"pictureSources\\\", \\\"mediaUrl\\\", \\\"formatImage\\\", \\\"styleToCss\\\"]) if (typeof m[f] !== \\\"function\\\") throw new Error(\\\"missing export \\\" + f) })\""
   },
   "dependencies": {
     "openapi-fetch": "0.17.0"
   },
   "devDependencies": {
+    "@playwright/test": "1.63.0",
     "openapi-typescript": "7.13.0",
     "typescript": "5.9.3",
     "vitest": "3.2.7"

package/src/schema.d.ts

@@ -441,6 +441,7 @@ export interface components {
             /** Format: int32 */
             duration: number | null | string;
             filename: null | string;
+            focal: null | components["schemas"]["MediaFocalDto"];
             formats: string[];
             /** Format: int32 */
             h: number | null | string;
@@ -454,6 +455,7 @@ export interface components {
             /** Format: int32 */
             recipe: number | string;
             role: string;
+            showWhole: boolean;
             variants: components["schemas"]["MediaVideoVariantDto"][] | null;
             view: null | string;
             /** Format: int32 */
@@ -462,8 +464,26 @@ export interface components {
         };
         MediaDto: {
             baseUrl: string;
+            formats: null | {
+                [key: string]: components["schemas"]["MediaFormatDto"];
+            };
             templates: components["schemas"]["MediaTemplatesDto"];
         };
+        MediaFocalDto: {
+            /** Format: double */
+            x: number | string;
+            /** Format: double */
+            y: number | string;
+        };
+        MediaFormatDto: {
+            aspect: null | string;
+            background: null | {
+                [key: string]: string;
+            };
+            fit: string;
+            /** Format: double */
+            padding: number | string;
+        };
         MediaPosterDto: {
             formats: string[];
             widths: (number | string)[];