@wocart/theme 4.0.0 → 4.1.0

package/CHANGELOG.md

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

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/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";
 /**

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 = "4.0.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 = "4.0.0";
+export const THEME_SDK_VERSION = "4.1.0";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wocart/theme",
-  "version": "4.0.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",