@wocart/theme 1.1.1 → 1.3.0

package/CHANGELOG.md

@@ -5,6 +5,24 @@ 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.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
+
+- Field kind `collection`: a collection handle (`best-sellers`), so the
+  merchant picks which curated list a section shows — Shopify's `collection`
+  setting. Type `CollectionFieldDefinition`.
+
 ## 1.1.1 — 2026-10-17
 
 ### Fixed

package/README.md

@@ -89,6 +89,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 |
@@ -98,6 +116,7 @@ and, for page-data resolution issues, `path`.
 | `boolean` | boolean | |
 | `select` | one of `options` | `default` must be one of the options |
 | `color` | `#rgb` or `#rrggbb` | anything else (a color name, `url(…)`) is rejected at assembly and reported on read |
+| `collection` | a collection handle (`best-sellers`) | lowercase letters, digits and hyphens; its products are listed with `@wocart/storefront`'s `products.list({ collection })`, in the merchant's order |
 | `menu` | a menu handle (`main-menu`) | lowercase letters, digits and hyphens; the store's menu is read with `@wocart/storefront`'s `menus.get(handle)` |
 | `url` | a link target | a site path (`/products`), `#fragment`, `?query`, `http(s)://`, `mailto:` or `tel:`; `javascript:`, `data:`, `//host` and backslash tricks are rejected at assembly and reported on read |
 

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

@@ -4,8 +4,7 @@
  * data — the validator exists so a theme's test suite fails loudly on catalog
  * bugs when the catalog is assembled.
  */
-import { COLOR_PATTERN, MENU_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. */
+import { COLOR_PATTERN, MENU_HANDLE_PATTERN, COLLECTION_HANDLE_PATTERN, SURFACE_KEY_PATTERN, THEME_KEY_PATTERN, TYPE_KEY_PATTERN, isLocaleMap, isLocaleTag, isSafeLinkTarget, } from "./schemas.js";
 export function defineComponent(definition) {
     return definition;
 }
@@ -358,6 +357,12 @@ function inspectFields(fields, path, issues, rules) {
                 }
                 break;
             }
+            case "collection": {
+                if (field.default !== undefined && (typeof field.default !== "string" || !COLLECTION_HANDLE_PATTERN.test(field.default))) {
+                    addIssue(issues, `${fieldPath}.default`, "invalid-field", "`default` must be a collection handle: lowercase letters, digits and dashes");
+                }
+                break;
+            }
             case "url": {
                 if (field.default !== undefined &&
                     (typeof field.default !== "string" || !isSafeLinkTarget(field.default))) {

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, 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/instances.js

@@ -9,7 +9,7 @@
  * default applies last).
  */
 import { localize } from "./locales.js";
-import { COLOR_PATTERN, MENU_HANDLE_PATTERN, isLocaleMap, isSafeLinkTarget } from "./schemas.js";
+import { COLLECTION_HANDLE_PATTERN, COLOR_PATTERN, MENU_HANDLE_PATTERN, isLocaleMap, isSafeLinkTarget } from "./schemas.js";
 /** Field kinds whose values may differ per language. Numbers, toggles and choices are shared. */
 const TRANSLATABLE_KINDS = new Set(["text", "textarea", "url"]);
 const isTranslatable = (field) => TRANSLATABLE_KINDS.has(field.kind);
@@ -211,6 +211,10 @@ function checkFieldValue(field, value) {
             return typeof value === "string" && MENU_HANDLE_PATTERN.test(value)
                 ? { ok: true, value }
                 : { ok: false, message: "must be a menu handle" };
+        case "collection":
+            return typeof value === "string" && COLLECTION_HANDLE_PATTERN.test(value)
+                ? { ok: true, value }
+                : { ok: false, message: "must be a collection handle" };
         case "select":
             return typeof value === "string" && field.options.includes(value)
                 ? { ok: true, value }

package/dist/manifest.d.ts

@@ -92,6 +92,13 @@ export declare const ThemeManifestSchema: z.ZodObject<{
             required: z.ZodExactOptional<z.ZodBoolean>;
             kind: z.ZodLiteral<"menu">;
             default: z.ZodExactOptional<z.ZodString>;
+        }, z.core.$strip>, z.ZodObject<{
+            key: z.ZodString;
+            label: z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodString>]>;
+            description: z.ZodExactOptional<z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodString>]>>;
+            required: z.ZodExactOptional<z.ZodBoolean>;
+            kind: z.ZodLiteral<"collection">;
+            default: z.ZodExactOptional<z.ZodString>;
         }, z.core.$strip>], "kind">>;
     }, z.core.$strip>>>;
     components: z.ZodRecord<z.ZodString, z.ZodObject<{
@@ -159,6 +166,13 @@ export declare const ThemeManifestSchema: z.ZodObject<{
             required: z.ZodExactOptional<z.ZodBoolean>;
             kind: z.ZodLiteral<"menu">;
             default: z.ZodExactOptional<z.ZodString>;
+        }, z.core.$strip>, z.ZodObject<{
+            key: z.ZodString;
+            label: z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodString>]>;
+            description: z.ZodExactOptional<z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodString>]>>;
+            required: z.ZodExactOptional<z.ZodBoolean>;
+            kind: z.ZodLiteral<"collection">;
+            default: z.ZodExactOptional<z.ZodString>;
         }, z.core.$strip>], "kind">>>;
         slots: z.ZodDefault<z.ZodArray<z.ZodObject<{
             name: z.ZodString;

package/dist/manifest.js

@@ -103,6 +103,11 @@ const FieldSchema = z.discriminatedUnion("kind", [
         kind: z.literal("menu"),
         default: z.exactOptional(z.string()),
     }),
+    z.object({
+        ...FieldCommonSchema,
+        kind: z.literal("collection"),
+        default: z.exactOptional(z.string()),
+    }),
 ]);
 const ComponentSpecSchema = z.object({
     type: z.string(),

package/dist/schemas.d.ts

@@ -29,6 +29,7 @@ export declare const COLOR_PATTERN: RegExp;
  * handles; a menu that does not exist reads as no menu.
  */
 export declare const MENU_HANDLE_PATTERN: RegExp;
+export declare const COLLECTION_HANDLE_PATTERN: RegExp;
 export declare function isLocaleTag(value: string): boolean;
 /**
  * Whether `value` is a per-language map (`{ ar: "…", fr: "…" }`): a plain

package/dist/schemas.js

@@ -28,6 +28,7 @@ export const COLOR_PATTERN = /^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6})$/;
  * handles; a menu that does not exist reads as no menu.
  */
 export const MENU_HANDLE_PATTERN = /^[a-z0-9][a-z0-9-]{0,63}$/;
+export const COLLECTION_HANDLE_PATTERN = /^[a-z0-9][a-z0-9-]{0,63}$/;
 /**
  * A BCP 47 language tag in canonical case: a 2–3 letter language, an optional
  * 4-letter script, an optional 2-letter or 3-digit region (`ar`, `zgh`,

package/dist/types.d.ts

@@ -36,8 +36,8 @@ export interface ResolutionScope {
     content?: Record<string, string>;
     locales?: readonly LocaleCode[];
 }
-/** The field kinds. `color` and `menu` were added after V1, additively. */
-export type FieldKind = "text" | "textarea" | "number" | "boolean" | "select" | "url" | "color" | "menu";
+/** The field kinds. `color`, `menu` and `collection` were added after V1, additively. */
+export type FieldKind = "text" | "textarea" | "number" | "boolean" | "select" | "url" | "color" | "menu" | "collection";
 interface FieldDefinitionBase {
     /** The exact prop name the component expects. */
     key: string;
@@ -112,7 +112,18 @@ export interface MenuFieldDefinition extends FieldDefinitionBase {
     kind: "menu";
     default?: string;
 }
-export type FieldDefinition = TextFieldDefinition | NumberFieldDefinition | BooleanFieldDefinition | SelectFieldDefinition | UrlFieldDefinition | ColorFieldDefinition | MenuFieldDefinition;
+/**
+ * `collection`: which of the store's collections to show here — Shopify's
+ * `collection` setting. The value is a collection handle (`best-sellers`); the
+ * theme lists its products with the storefront client's
+ * `products.list({ collection })`, in the merchant's order. An unknown handle
+ * lists nothing.
+ */
+export interface CollectionFieldDefinition extends FieldDefinitionBase {
+    kind: "collection";
+    default?: string;
+}
+export type FieldDefinition = TextFieldDefinition | NumberFieldDefinition | BooleanFieldDefinition | SelectFieldDefinition | UrlFieldDefinition | ColorFieldDefinition | MenuFieldDefinition | CollectionFieldDefinition;
 /**
  * One composition point a component declares (`"default"` = children).
  *
@@ -193,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;
     /**
@@ -204,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
@@ -238,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.1.1",
+  "version": "1.3.0",
   "description": "The Wocart theme contract: code-owned component definitions, JSON page documents, validation and resolution, and a reference Astro renderer.",
   "keywords": [
     "wocart",