@wocart/theme 1.1.0 → 1.2.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.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
+
+- `resolveThemeSettings` returns its values typed from the theme's
+  declaration (`InferSettings<typeof theme>`) instead of
+  `Record<string, unknown>`, as the README promised: a setting with a default
+  is a value, any other may be absent. `ThemeSettingsResult` takes the values'
+  type as an optional parameter. No runtime change.
+
 ## 1.1.0 — 2026-10-17
 
 ### Added

package/README.md

@@ -98,6 +98,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 |
 
@@ -329,7 +330,7 @@ export const theme = defineTheme({
 });
 
 const { values, issues } = resolveThemeSettings(theme, config?.themeSettings, { locales: [locale] });
-values.headerMenu; // "main-menu" — typed: InferSettings<typeof theme>
+values.headerMenu; // "main-menu" — values: InferSettings<typeof theme>, from 1.1.1
 ```
 
 - **Reading never fails.** Each setting takes the merchant's value when the

package/dist/definitions.js

@@ -4,7 +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";
+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;
@@ -358,6 +358,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, 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/settings.d.ts

@@ -1,12 +1,14 @@
-import type { ResolutionScope, ThemeDefinition, ThemeSettingsIssue, ThemeSettingsResult } from "./types.js";
+import type { InferSettings, ResolutionScope, ThemeDefinition, ThemeSettingsIssue, ThemeSettingsResult } from "./types.js";
 /**
  * The effective settings for rendering: every declared setting, from the
  * store's value when the declaration accepts it, else from the theme's
  * default. `stored` is the persisted object as it arrived (anything else —
  * null, an array — reads as no values and is reported). Translated text uses
- * `scope.locales`; text settings may default from `scope.content`.
+ * `scope.locales`; text settings may default from `scope.content`. The
+ * values are typed from the declaration (`InferSettings<typeof theme>`): a
+ * setting with a default is always there, any other may be absent.
  */
-export declare function resolveThemeSettings(theme: ThemeDefinition, stored: unknown, scope?: ResolutionScope): ThemeSettingsResult;
+export declare function resolveThemeSettings<T extends ThemeDefinition>(theme: T, stored: unknown, scope?: ResolutionScope): ThemeSettingsResult<InferSettings<T>>;
 /**
  * What a writer must check before saving a store's settings for a theme:
  * every key declared, every value accepted by its setting — in every language

package/dist/settings.js

@@ -29,7 +29,9 @@ const PAGE_TO_SETTINGS = {
  * store's value when the declaration accepts it, else from the theme's
  * default. `stored` is the persisted object as it arrived (anything else —
  * null, an array — reads as no values and is reported). Translated text uses
- * `scope.locales`; text settings may default from `scope.content`.
+ * `scope.locales`; text settings may default from `scope.content`. The
+ * values are typed from the declaration (`InferSettings<typeof theme>`): a
+ * setting with a default is always there, any other may be absent.
  */
 export function resolveThemeSettings(theme, stored, scope = {}) {
     const issues = [];

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).
  *
@@ -449,8 +460,8 @@ export interface ThemeSettingsIssue {
     message: string;
 }
 /** The effective settings: every value checked, the rest from the theme's defaults. */
-export interface ThemeSettingsResult {
-    values: Record<string, unknown>;
+export interface ThemeSettingsResult<V = Record<string, unknown>> {
+    values: V;
     issues: ThemeSettingsIssue[];
 }
 type SettingsFieldsOf<T> = T extends {
@@ -463,8 +474,7 @@ type SettingsFieldsOf<T> = T extends {
  * with a `default` is always present, any other may be absent.
  *
  * ```ts
- * const { values } = resolveThemeSettings(theme, stored);
- * const settings = values as InferSettings<typeof theme>;
+ * const { values } = resolveThemeSettings(theme, stored); // values: InferSettings<typeof theme>
  * ```
  */
 export type InferSettings<T extends ThemeDefinition> = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wocart/theme",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "The Wocart theme contract: code-owned component definitions, JSON page documents, validation and resolution, and a reference Astro renderer.",
   "keywords": [
     "wocart",