@wocart/theme 3.1.0 → 4.0.0

package/CHANGELOG.md

@@ -5,6 +5,27 @@ 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.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/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/types.d.ts

@@ -756,7 +756,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.0.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.0.0";

package/package.json

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