@wocart/theme 3.1.0 → 4.1.0

package/CHANGELOG.md

@@ -5,6 +5,58 @@ 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.
 
+## 4.1.0 — 2026-11-03
+
+One content policy for every theme, and the theme key rule exported.
+Additions only; works with `@wocart/storefront` 3.0.0 or newer 3.x.
+
+### Added
+
+- `resolveThemeContent(theme, locale, overrides, options?)`: the theme's
+  words for one page — its pack for the language (else the default
+  language's: `options.defaultLocale`, else the first `locales` entry, else
+  the first pack), then the merchant's edits for that language, text only and
+  only for the pack's own keys. Takes `Pick<ThemeDefinition, "content" |
+  "locales">`, so a middleware can pass the packs without the component
+  catalog. Type `ResolveThemeContentOptions`.
+- `THEME_KEY_PATTERN` from the root entry: the rule a theme's key follows
+  (lowercase kebab-case, at most 64 characters), the one `defineTheme` and
+  the platform apply, for a tool that checks a key before building a theme.
+
+### Fixed
+
+- `ComponentRole`'s comment names both page types whose surfaces must
+  guarantee an `"order-form"` component: product and landing, as
+  `validateThemeDefinition` already checks.
+
+### Theme migration
+
+- Replace a theme's own merge of its packs and `contentOverrides` with
+  `resolveThemeContent({ content, locales }, locale, config.contentOverrides?.[locale])`.
+  An edit that is not text, or names a key the pack lacks, no longer reaches
+  a page.
+
+## 4.0.0 — 2026-11-01
+
+Search and contact are platform pages a theme composes, and the theme
+operations take the theme they check. Requires `@wocart/storefront` 3.0.0.
+
+### Added
+
+- `SurfacePageType` and `PAGE_TYPES` take `search` (`/search`) and `contact`
+  (`/contact`), the storefront's new page types: a theme declares a surface
+  for each, so a merchant composes them like any page.
+
+### Removed
+
+- `removeInstance(page, id)` and `setInstanceHidden(page, id, hidden)`, the
+  forms without the theme: pass the theme first, so a required block is
+  always kept and shown.
+
+### Changed (breaking)
+
+- The peer `@wocart/storefront` is `^3.0.0`.
+
 ## 3.1.0 — 2026-10-31
 
 Landing pages are composed pages, each with its own document, and a page can

package/dist/index.d.ts

@@ -27,7 +27,10 @@ export type { DocumentEdit, DocumentIssue, DocumentIssueCode, InstanceLocation,
 export { THEME_SDK_VERSION } from "./version.js";
 export type { RichTextHtmlOptions } from "./rich-text.js";
 export { resolveThemeSettings, checkThemeSettings } from "./settings.js";
+export { resolveThemeContent } from "./theme-content.js";
+export type { ResolveThemeContentOptions } from "./theme-content.js";
 export { localize } from "./locales.js";
+export { THEME_KEY_PATTERN } from "./patterns.js";
 export { PLURAL_CATEGORIES, formatMessage, messageForms, pluralFormIssues, pluralMessageKeys } from "./messages.js";
 export type { MessageOptions, MessageValues, PluralCategory } from "./messages.js";
 export { THEME_MANIFEST_CONTRACT_VERSION, THEME_MANIFEST_PATH, manifestCatalog, themeManifest, validateThemeManifest, } from "./manifest.js";

package/dist/index.js

@@ -23,7 +23,9 @@ export { COLOR_ROLES, COLOR_SCHEMES_MAX, STYLE_BREAKPOINTS, STYLE_PANELS, STYLE_
 export { checkPageData, duplicateInstance, findInstance, insertInstance, moveInstance, newInstanceId, removeInstance, setAreaHidden, setInstanceHidden, setInstanceProps, } from "./operations.js";
 export { THEME_SDK_VERSION } from "./version.js";
 export { resolveThemeSettings, checkThemeSettings } from "./settings.js";
+export { resolveThemeContent } from "./theme-content.js";
 export { localize } from "./locales.js";
+export { THEME_KEY_PATTERN } from "./patterns.js";
 export { PLURAL_CATEGORIES, formatMessage, messageForms, pluralFormIssues, pluralMessageKeys } from "./messages.js";
 export { THEME_MANIFEST_CONTRACT_VERSION, THEME_MANIFEST_PATH, manifestCatalog, themeManifest, validateThemeManifest, } from "./manifest.js";
 export { diffThemeManifests } from "./manifest-diff.js";

package/dist/operations.d.ts

@@ -51,14 +51,10 @@ export declare function findInstance(page: PageData, id: string): InstanceLocati
  */
 export declare function insertInstance(theme: ThemeDefinition, page: PageData, instance: ComponentInstance, placement?: InstancePlacement): DocumentEdit;
 /**
- * Remove an instance and everything inside it. Refused for a fixed block and,
- * given the theme, for the last required instance of its type in its list.
- * The form without a theme is kept for writers that predate blocks: it still
- * refuses a fixed block, but cannot know a slot's required types.
+ * Remove an instance and everything inside it. Refused for a fixed block and
+ * for the last required instance of its type in its list.
  */
 export declare function removeInstance(theme: ThemeDefinition, page: PageData, id: string): DocumentEdit;
-/** @deprecated Pass the theme first, so required blocks are kept. */
-export declare function removeInstance(page: PageData, id: string): DocumentEdit;
 /**
  * Move an instance (with everything inside it) to a placement. `index` counts
  * positions in the destination after the instance has left its old place.
@@ -81,12 +77,9 @@ export declare function duplicateInstance(theme: ThemeDefinition, page: PageData
 export declare function setInstanceProps(theme: ThemeDefinition, page: PageData, id: string, changes: Readonly<Record<string, JsonValue | undefined>>): DocumentEdit;
 /**
  * Switch an instance off (kept, not rendered) or back on. A fixed block is
- * never hidden and, given the theme, neither is the last required instance of
- * its type. The form without a theme refuses only a fixed block.
+ * never hidden, and neither is the last required instance of its type.
  */
 export declare function setInstanceHidden(theme: ThemeDefinition, page: PageData, id: string, hidden: boolean): DocumentEdit;
-/** @deprecated Pass the theme first, so required blocks stay shown. */
-export declare function setInstanceHidden(page: PageData, id: string, hidden: boolean): DocumentEdit;
 /**
  * Show or leave out one of the theme's areas on this page — the header, the
  * footer — when its surface lets a page leave it out (`hideableAreas`).

package/dist/operations.js

@@ -29,7 +29,6 @@ export function newInstanceId() {
     return `cmp_${Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join("")}`;
 }
 const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
-const isTheme = (value) => isRecord(value) && isRecord(value.components);
 const definitionOf = (theme, type) => Object.hasOwn(theme.components, type) ? theme.components[type] : undefined;
 const refuse = (code, message, path = "") => ({
     ok: false,
@@ -347,8 +346,11 @@ export function insertInstance(theme, page, instance, placement = {}) {
     list.splice(placement.index ?? list.length, 0, tree);
     return { ok: true, page: next };
 }
-export function removeInstance(...args) {
-    const [theme, page, id] = isTheme(args[0]) ? args : [null, args[0], args[1]];
+/**
+ * Remove an instance and everything inside it. Refused for a fixed block and
+ * for the last required instance of its type in its list.
+ */
+export function removeInstance(theme, page, id) {
     const next = structuredClone(page);
     const location = findInstance(next, id);
     if (location === null)
@@ -360,11 +362,9 @@ export function removeInstance(...args) {
         : targetList(next, { parent: location.parent, slot: location.slot ?? "default" });
     if (list === null)
         return refuse("unknown-instance", `no instance "${location.parent}" in the document`);
-    if (theme !== null) {
-        const short = leavesRequiredShort(listRules(theme, next, location.parent, location.slot), list, location.instance);
-        if (short !== null)
-            return refuse("required-block", `"${location.instance.type}" is required here (at least ${short.min ?? 1})`);
-    }
+    const short = leavesRequiredShort(listRules(theme, next, location.parent, location.slot), list, location.instance);
+    if (short !== null)
+        return refuse("required-block", `"${location.instance.type}" is required here (at least ${short.min ?? 1})`);
     list.splice(list.findIndex((candidate) => candidate.id === id), 1);
     return { ok: true, page: next };
 }
@@ -496,17 +496,18 @@ export function setInstanceProps(theme, page, id, changes) {
         delete instance.props;
     return { ok: true, page: next };
 }
-export function setInstanceHidden(...args) {
-    const [theme, page, id, hidden] = isTheme(args[0])
-        ? args
-        : [null, args[0], args[1], args[2]];
+/**
+ * Switch an instance off (kept, not rendered) or back on. A fixed block is
+ * never hidden, and neither is the last required instance of its type.
+ */
+export function setInstanceHidden(theme, page, id, hidden) {
     const next = structuredClone(page);
     const location = findInstance(next, id);
     if (location === null)
         return refuse("unknown-instance", `no instance "${id}" in the document`);
     if (hidden && location.fixed !== undefined)
         return refuse("fixed-block", `"${id}" is placed by its component's code and cannot be hidden`);
-    if (hidden && theme !== null) {
+    if (hidden) {
         const list = location.parent === null ? next.sections : (slotLists(findInstance(next, location.parent).instance).find(([name]) => name === (location.slot ?? "default"))?.[1] ?? []);
         const short = leavesRequiredShort(listRules(theme, next, location.parent, location.slot), list, location.instance);
         if (short !== null)

package/dist/patterns.d.ts

@@ -17,7 +17,7 @@ export declare const TYPE_KEY_PATTERN: RegExp;
  */
 export declare const SURFACE_KEY_PATTERN: RegExp;
 /** The platform page types a surface can render (`SurfacePageType`), mirrored from the storefront's page types. */
-export declare const PAGE_TYPES: readonly ["home", "catalog", "category", "collection", "product", "page", "landing", "checkout", "thankYou", "trackOrder"];
+export declare const PAGE_TYPES: readonly ["home", "catalog", "category", "collection", "product", "page", "landing", "checkout", "thankYou", "trackOrder", "search", "contact"];
 /** A `color` field's value: a hex color, `#rgb` or `#rrggbb`. */
 export declare const COLOR_PATTERN: RegExp;
 /**

package/dist/patterns.js

@@ -28,6 +28,8 @@ export const PAGE_TYPES = [
     "checkout",
     "thankYou",
     "trackOrder",
+    "search",
+    "contact",
 ];
 /** A `color` field's value: a hex color, `#rgb` or `#rrggbb`. */
 export const COLOR_PATTERN = /^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6})$/;

package/dist/theme-content.d.ts

@@ -0,0 +1,19 @@
+/**
+ * The theme's words for one page: its own pack for the page's language, with
+ * the merchant's edits for that same language over it. One policy for every
+ * theme: an edit counts only when it is text and names a word the pack has,
+ * so a stale key, another theme's key or a value of the wrong kind never
+ * reaches a page, and another language's edits never mix in.
+ */
+import type { LocaleCode, ThemeDefinition } from "./types.js";
+export interface ResolveThemeContentOptions {
+    /** The pack used for a language the theme has none for. Default: the theme's first `locales` entry, else its first pack. */
+    defaultLocale?: LocaleCode;
+}
+/**
+ * The words a page renders in `locale`: the theme's pack for it (else the
+ * default language's), then `overrides` — the store's
+ * `contentOverrides[locale]` — for the pack's own keys, text only. Empty
+ * when the theme declares no content.
+ */
+export declare function resolveThemeContent(theme: Pick<ThemeDefinition, "content" | "locales">, locale: LocaleCode, overrides: unknown, options?: ResolveThemeContentOptions): Record<string, string>;

package/dist/theme-content.js

@@ -0,0 +1,19 @@
+/**
+ * The words a page renders in `locale`: the theme's pack for it (else the
+ * default language's), then `overrides` — the store's
+ * `contentOverrides[locale]` — for the pack's own keys, text only. Empty
+ * when the theme declares no content.
+ */
+export function resolveThemeContent(theme, locale, overrides, options = {}) {
+    const packs = theme.content ?? {};
+    const fallback = options.defaultLocale ?? theme.locales?.[0] ?? Object.keys(packs)[0];
+    const pack = (Object.hasOwn(packs, locale) ? packs[locale] : fallback !== undefined && Object.hasOwn(packs, fallback) ? packs[fallback] : undefined) ?? {};
+    const words = { ...pack };
+    if (overrides === null || typeof overrides !== "object")
+        return words;
+    for (const [key, value] of Object.entries(overrides)) {
+        if (typeof value === "string" && Object.hasOwn(pack, key))
+            words[key] = value;
+    }
+    return words;
+}

package/dist/types.d.ts

@@ -460,7 +460,8 @@ export interface FixedBlockDefinition {
 }
 /**
  * What a component is to the platform. `"order-form"`: it places orders —
- * every product surface must guarantee one (`validateThemeDefinition`).
+ * every product and landing surface must guarantee one
+ * (`validateThemeDefinition`, `order-form-not-guaranteed`).
  */
 export type ComponentRole = "order-form";
 /**
@@ -756,7 +757,7 @@ export interface AreaSpec {
  * The storefront's page types — what a URL means, with the paths the platform
  * owns. The same names as `StorefrontPageType` in `@wocart/storefront`.
  */
-export type SurfacePageType = "home" | "catalog" | "category" | "collection" | "product" | "page" | "landing" | "checkout" | "thankYou" | "trackOrder";
+export type SurfacePageType = "home" | "catalog" | "category" | "collection" | "product" | "page" | "landing" | "checkout" | "thankYou" | "trackOrder" | "search" | "contact";
 /**
  * One component as data: a `ComponentDefinition` minus its runtime-only
  * implementation. `component` (the live component reference) and `load` (the

package/dist/version.d.ts

@@ -4,4 +4,4 @@
  * reads. Always equal to `package.json`'s version; the package check refuses
  * a release where they differ.
  */
-export declare const THEME_SDK_VERSION = "3.1.0";
+export declare const THEME_SDK_VERSION = "4.1.0";

package/dist/version.js

@@ -4,4 +4,4 @@
  * reads. Always equal to `package.json`'s version; the package check refuses
  * a release where they differ.
  */
-export const THEME_SDK_VERSION = "3.1.0";
+export const THEME_SDK_VERSION = "4.1.0";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wocart/theme",
-  "version": "3.1.0",
+  "version": "4.1.0",
   "description": "The Wocart theme contract: code-owned component definitions, JSON page documents, validation and resolution, and a reference Astro renderer.",
   "keywords": [
     "wocart",
@@ -82,7 +82,7 @@
     "zod": "^4.4.3"
   },
   "peerDependencies": {
-    "@wocart/storefront": "^2.0.0",
+    "@wocart/storefront": "^3.0.0",
     "astro": "^7.0.0"
   },
   "peerDependenciesMeta": {
@@ -92,7 +92,7 @@
   },
   "devDependencies": {
     "@types/node": "^26.2.0",
-    "@wocart/storefront": "^2.0.0",
+    "@wocart/storefront": "^3.0.0",
     "astro": "^7.3.2",
     "fast-check": "^4.6.0",
     "happy-dom": "^20.11.6",