@wocart/theme 1.2.0 → 1.4.0

package/CHANGELOG.md

@@ -5,6 +5,32 @@ All notable changes to `@wocart/theme` are recorded here. The package follows
 major version, and an export is marked `@deprecated` for at least one minor
 release before a major removes it.
 
+## 1.4.0 — 2026-10-18
+
+### Added
+
+- `@wocart/theme/image-service`: `mediaImageService(() => mediaDomain)`, an
+  Astro image service that resizes media-domain images with Cloudflare Image
+  Resizing on the media domain itself, so a storefront on Cloudflare and one
+  on Vercel get the same URLs and edge cache. Other images are served as they
+  are; the domain is read per image, so one build serves every store.
+  `mediaImageParams` maps an Astro transform to the resizing options (Astro's
+  `fit` in Cloudflare's words).
+
+### Changed
+
+- The `@wocart/storefront` peer range is now `^1.14.0` (`mediaImageUrl`).
+
+## 1.3.0 — 2026-10-17
+
+### Added
+
+- `load` is typed from the component's own fields: `defineComponent` hands it
+  `props` as `FieldValues<fields>` (a field with a default is always there,
+  any other may be absent), so a definition reads its settings — which
+  collection, how many products — without a cast. What `load` returns still
+  types the component's props (`InferProps`). Type `FieldValues`.
+
 ## 1.2.0 — 2026-10-17
 
 ### Added

package/README.md

@@ -37,6 +37,7 @@ Node 22.12 or newer.
 | `@wocart/theme` | definitions, validation, page documents, resolution, the manifest, languages and messages — framework-neutral |
 | `@wocart/theme/astro` | `createReadCache` and the `RendererIssue` type |
 | `@wocart/theme/astro/InstanceView.astro` | the reference renderer component |
+| `@wocart/theme/image-service` | `mediaImageService` — an Astro image service that resizes media-domain images on the media domain (any storefront host) |
 
 ## Use
 
@@ -89,6 +90,24 @@ props and undeclared children/slots, is reported through `onIssue` (default:
 `console.warn`). The issue contains a stable `code`, `message`, `instanceId`,
 and, for page-data resolution issues, `path`.
 
+`load` receives the instance's resolved props typed from the component's own
+fields, so a section reads its settings without a cast:
+
+```ts
+defineComponent({
+  type: "best-sellers",
+  component: BestSellers,
+  label: { ar: "الأكثر مبيعاً", fr: "Meilleures ventes" },
+  fields: [
+    { key: "collection", kind: "collection", label: { ar: "المجموعة", fr: "Collection" }, default: "best-sellers" },
+    { key: "limit", kind: "number", label: { ar: "العدد", fr: "Nombre" }, default: 8, min: 1, max: 24 },
+  ],
+  load: async ({ storefront, props }) => ({
+    products: await storefront.products.list({ collection: props.collection, limit: props.limit }),
+  }),
+});
+```
+
 ## Field kinds
 
 | Kind | Value | Rules |
@@ -426,6 +445,34 @@ migration engine, by design; what follows is the whole policy:
   stick to semver so the manifest validator stays quiet and future tooling can
   reason about upgrades.
 
+## Images
+
+`@wocart/theme/image-service` resizes every `<Image>` of a media-domain image
+with Cloudflare Image Resizing, on the media domain itself
+(`https://<media>/cdn-cgi/image/…`). The media domain is a Cloudflare zone
+wherever the storefront runs, so a storefront on Cloudflare and one on Vercel
+share the same URLs and edge cache. Any other image is served as it is; with no
+media domain, every image passes through.
+
+The domain is read on each image, not at build — one build serves every store.
+Bind it once:
+
+```ts
+// src/image-service.ts
+import { MEDIA_DOMAIN } from "astro:env/server";
+import { mediaImageService } from "@wocart/theme/image-service";
+export default mediaImageService(() => MEDIA_DOMAIN);
+```
+
+```js
+// astro.config.mjs
+image: { service: { entrypoint: "./src/image-service.ts" } },
+// @astrojs/cloudflare: imageService: "custom"   ·   @astrojs/vercel: leave imageService off
+```
+
+The media domain's zone needs Image Transformations on (Images →
+Transformations; included in the Free plan).
+
 ## Testing your theme
 
 A theme proves it honors the contract with four checks in its own test suite:

package/dist/definitions.d.ts

@@ -1,7 +1,27 @@
-import type { ComponentDefinition, ThemeDefinition, ThemeDefinitionIssue, ThemeValidationOptions } from "./types.js";
-/** Identity helper: returns the definition unchanged so literal types survive. */
-export declare function defineComponent<const T extends ComponentDefinition>(definition: T): T;
+import type { ComponentDefinition, FieldDefinition, FieldValues, LoadContext, ThemeDefinition, ThemeDefinitionIssue, ThemeValidationOptions } from "./types.js";
+/**
+ * Identity helper: returns the definition unchanged so literal types survive.
+ * `load` receives the component's props typed from its own `fields`, so a
+ * definition reads its settings without a cast, and what it returns types the
+ * component's props (`InferProps`).
+ */
+export declare function defineComponent<const T extends ComponentBase, Loaded extends Record<string, unknown>, const Fields extends readonly FieldDefinition[] = readonly []>(definition: T & {
+    fields?: Fields;
+    load: (context: LoadContext<FieldValues<Fields>>) => Promise<Loaded>;
+}): T & FieldsPart<Fields> & {
+    load: (context: LoadContext) => Promise<Loaded>;
+};
+export declare function defineComponent<const T extends ComponentBase, const Fields extends readonly FieldDefinition[] = readonly []>(definition: T & {
+    fields?: Fields;
+    load?: undefined;
+}): T & FieldsPart<Fields>;
+type ComponentBase = Omit<ComponentDefinition, "fields" | "load">;
+/** The field literals a definition declared, when it declared any. */
+type FieldsPart<Fields extends readonly FieldDefinition[]> = [Fields] extends [readonly []] ? {} : {
+    fields: Fields;
+};
 /** Identity helper for the catalog. */
 export declare function defineTheme<const T extends ThemeDefinition>(definition: T): T;
 /** Check the whole catalog: key/type identity, field rules, slot rules. */
 export declare function validateThemeDefinition(theme: ThemeDefinition, options?: ThemeValidationOptions): ThemeDefinitionIssue[];
+export {};

package/dist/definitions.js

@@ -5,7 +5,6 @@
  * bugs when the catalog is assembled.
  */
 import { COLOR_PATTERN, MENU_HANDLE_PATTERN, COLLECTION_HANDLE_PATTERN, SURFACE_KEY_PATTERN, THEME_KEY_PATTERN, TYPE_KEY_PATTERN, isLocaleMap, isLocaleTag, isSafeLinkTarget, } from "./schemas.js";
-/** Identity helper: returns the definition unchanged so literal types survive. */
 export function defineComponent(definition) {
     return definition;
 }

package/dist/image-service.d.ts

@@ -0,0 +1,39 @@
+/**
+ * An Astro image service for Wocart storefronts: every `<Image>` and
+ * `getImage()` of a media-domain image is resized by Cloudflare Image Resizing
+ * on the media domain itself (`https://<media>/cdn-cgi/image/…/<path>`).
+ *
+ * The media domain is always a Cloudflare zone, wherever the storefront runs,
+ * so a storefront on Cloudflare and one on Vercel get the same URLs, the same
+ * edge cache and no second image bill. Any other image — another host, a file
+ * imported into the theme — is served as it is. Without a media domain (local
+ * development, a store without one) every image passes through unchanged.
+ *
+ * The domain is read per call, not at build: one theme build serves every
+ * store. Bind it once, in the theme, to wherever the store's media domain
+ * lives:
+ *
+ * ```ts
+ * // src/image-service.ts
+ * import { MEDIA_DOMAIN } from "astro:env/server";
+ * import { mediaImageService } from "@wocart/theme/image-service";
+ * export default mediaImageService(() => MEDIA_DOMAIN);
+ * ```
+ *
+ * ```js
+ * // astro.config.mjs — and the adapter keeps it:
+ * //   @astrojs/cloudflare: imageService: "custom";  @astrojs/vercel: no imageService
+ * image: { service: { entrypoint: "./src/image-service.ts" } },
+ * ```
+ */
+import type { ExternalImageService, ImageTransform } from "astro";
+import { type MediaImageParams } from "@wocart/storefront";
+/** The Cloudflare resizing options an Astro image transform asks for. */
+export declare function mediaImageParams(options: ImageTransform): MediaImageParams;
+/**
+ * The image service, bound to the store's media domain.
+ *
+ * @param mediaDomain - Read on every image (e.g. `() => MEDIA_DOMAIN`): the
+ *   store's media domain, or `undefined` to pass every image through.
+ */
+export declare function mediaImageService(mediaDomain: () => string | undefined): ExternalImageService;

package/dist/image-service.js

@@ -0,0 +1,73 @@
+/**
+ * An Astro image service for Wocart storefronts: every `<Image>` and
+ * `getImage()` of a media-domain image is resized by Cloudflare Image Resizing
+ * on the media domain itself (`https://<media>/cdn-cgi/image/…/<path>`).
+ *
+ * The media domain is always a Cloudflare zone, wherever the storefront runs,
+ * so a storefront on Cloudflare and one on Vercel get the same URLs, the same
+ * edge cache and no second image bill. Any other image — another host, a file
+ * imported into the theme — is served as it is. Without a media domain (local
+ * development, a store without one) every image passes through unchanged.
+ *
+ * The domain is read per call, not at build: one theme build serves every
+ * store. Bind it once, in the theme, to wherever the store's media domain
+ * lives:
+ *
+ * ```ts
+ * // src/image-service.ts
+ * import { MEDIA_DOMAIN } from "astro:env/server";
+ * import { mediaImageService } from "@wocart/theme/image-service";
+ * export default mediaImageService(() => MEDIA_DOMAIN);
+ * ```
+ *
+ * ```js
+ * // astro.config.mjs — and the adapter keeps it:
+ * //   @astrojs/cloudflare: imageService: "custom";  @astrojs/vercel: no imageService
+ * image: { service: { entrypoint: "./src/image-service.ts" } },
+ * ```
+ */
+import { baseService } from "astro/assets";
+import { mediaImageUrl } from "@wocart/storefront";
+/** Astro's `fit` (CSS object-fit) in Cloudflare's words; a value Cloudflare also knows passes as it is. */
+const CLOUDFLARE_FIT = {
+    cover: "cover",
+    contain: "contain",
+    fill: "squeeze",
+    "scale-down": "scale-down",
+    crop: "crop",
+    pad: "pad",
+    squeeze: "squeeze",
+};
+/** The Cloudflare resizing options an Astro image transform asks for. */
+export function mediaImageParams(options) {
+    const params = {};
+    if (options.width)
+        params.width = options.width;
+    if (options.height)
+        params.height = options.height;
+    if (options.format)
+        params.format = options.format;
+    if (typeof options.quality === "number")
+        params.quality = options.quality;
+    const fit = options.fit ? CLOUDFLARE_FIT[options.fit] : undefined;
+    if (fit)
+        params.fit = fit;
+    return params;
+}
+/**
+ * The image service, bound to the store's media domain.
+ *
+ * @param mediaDomain - Read on every image (e.g. `() => MEDIA_DOMAIN`): the
+ *   store's media domain, or `undefined` to pass every image through.
+ */
+export function mediaImageService(mediaDomain) {
+    return {
+        ...baseService,
+        getURL(options) {
+            const src = options.src;
+            if (typeof src !== "string")
+                return src.src;
+            return mediaImageUrl(src, mediaImageParams(options), mediaDomain()) ?? src;
+        },
+    };
+}

package/dist/index.d.ts

@@ -17,4 +17,4 @@ export { localize } from "./locales.js";
 export { PLURAL_CATEGORIES, formatMessage, messageForms, pluralFormIssues } from "./messages.js";
 export type { MessageOptions, MessageValues, PluralCategory } from "./messages.js";
 export { THEME_MANIFEST_CONTRACT_VERSION, themeManifest, validateThemeManifest, } from "./manifest.js";
-export type { JsonValue, JsonObject, LocaleCode, LocalizedText, ResolutionScope, FieldKind, FieldDefinition, FieldValue, InferProps, SlotDefinition, ComponentCapabilities, ComponentDefinition, ComponentSpec, SurfaceSpec, ThemeDefinition, SettingsGroup, InferSettings, ThemeSettingsIssue, ThemeSettingsIssueCode, ThemeSettingsResult, ColorFieldDefinition, MenuFieldDefinition, CollectionFieldDefinition, ThemeManifest, ThemeManifestIssue, ThemeManifestIssueCode, ThemeManifestResult, ComponentInstance, PageData, ThemeRenderContext, LoadContext, LoadFn, ReadCache, PageDataIssue, PageDataIssueCode, PageDataResult, ResolvedInstance, ThemeDefinitionIssue, ThemeDefinitionIssueCode, ThemeValidationOptions, } from "./types.js";
+export type { JsonValue, JsonObject, LocaleCode, LocalizedText, ResolutionScope, FieldKind, FieldDefinition, FieldValue, InferProps, FieldValues, SlotDefinition, ComponentCapabilities, ComponentDefinition, ComponentSpec, SurfaceSpec, ThemeDefinition, SettingsGroup, InferSettings, ThemeSettingsIssue, ThemeSettingsIssueCode, ThemeSettingsResult, ColorFieldDefinition, MenuFieldDefinition, CollectionFieldDefinition, ThemeManifest, ThemeManifestIssue, ThemeManifestIssueCode, ThemeManifestResult, ComponentInstance, PageData, ThemeRenderContext, LoadContext, LoadFn, ReadCache, PageDataIssue, PageDataIssueCode, PageDataResult, ResolvedInstance, ThemeDefinitionIssue, ThemeDefinitionIssueCode, ThemeValidationOptions, } from "./types.js";

package/dist/types.d.ts

@@ -204,7 +204,7 @@ export interface ReadCache {
     get<T>(key: string, load: () => T | Promise<T>): Promise<T>;
 }
 /** What a `load` hook receives. Server-only; reads go through the storefront SDK. */
-export interface LoadContext {
+export interface LoadContext<P = Record<string, unknown>> {
     storefront: StoreClient;
     context: ThemeRenderContext;
     /**
@@ -215,11 +215,16 @@ export interface LoadContext {
      * the same name. A definition whose component reads a prop from `load` should
      * keep that name out of `fields`.
      */
-    props: Record<string, unknown>;
+    props: P;
     reads: ReadCache;
 }
-/** Server-side data fetch for one component definition. */
-export type LoadFn = (context: LoadContext) => Promise<Record<string, unknown>>;
+/**
+ * Server-side data fetch for one component definition. Through
+ * `defineComponent`, `props` is typed from the definition's own fields
+ * (`FieldValues`): a field with a default is always there, any other may be
+ * absent.
+ */
+export type LoadFn<P = Record<string, unknown>> = (context: LoadContext<P>) => Promise<Record<string, unknown>>;
 /**
  * Code-owned description of one reusable component. `component` is the real
  * component reference — opaque here so the core stays framework-neutral; the
@@ -249,6 +254,13 @@ export type FieldValue<F extends FieldDefinition> = F extends {
 type FieldsOf<D> = D extends {
     fields: readonly (infer F extends FieldDefinition)[];
 } ? F : never;
+/**
+ * The resolved values of a list of fields, as `load` and the component receive
+ * them: a field with a `default` is always present, any other may be absent.
+ */
+export type FieldValues<Fields extends readonly FieldDefinition[]> = FieldProps<{
+    fields: Fields;
+}>;
 type FieldProps<D> = {
     [F in FieldsOf<D> as F extends {
         default: unknown;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wocart/theme",
-  "version": "1.2.0",
+  "version": "1.4.0",
   "description": "The Wocart theme contract: code-owned component definitions, JSON page documents, validation and resolution, and a reference Astro renderer.",
   "keywords": [
     "wocart",
@@ -38,6 +38,10 @@
       "default": "./dist/astro/index.js"
     },
     "./astro/InstanceView.astro": "./dist/astro/InstanceView.astro",
+    "./image-service": {
+      "types": "./dist/image-service.d.ts",
+      "default": "./dist/image-service.js"
+    },
     "./package.json": "./package.json"
   },
   "files": [
@@ -63,7 +67,7 @@
     "zod": "^4.4.3"
   },
   "peerDependencies": {
-    "@wocart/storefront": "^1.0.0",
+    "@wocart/storefront": "^1.14.0",
     "astro": "^7.0.0"
   },
   "peerDependenciesMeta": {