@wocart/theme 1.2.0 → 1.3.0

package/CHANGELOG.md

@@ -5,6 +5,16 @@ 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

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 |

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/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.3.0",
   "description": "The Wocart theme contract: code-owned component definitions, JSON page documents, validation and resolution, and a reference Astro renderer.",
   "keywords": [
     "wocart",