@wocart/theme 1.6.0 → 2.1.0

package/dist/manifest.js

@@ -35,9 +35,13 @@ export function themeManifest(theme) {
             label: copyData(surface.label),
             ...(surface.pageType === undefined ? {} : { pageType: surface.pageType }),
             ...(surface.document === undefined ? {} : { document: copyData(surface.document) }),
+            ...(surface.required === undefined ? {} : { required: copyData(surface.required) }),
+            ...(surface.max === undefined ? {} : { max: surface.max }),
         })),
+        areas: (theme.areas ?? []).map((area) => copyData(area)),
         locales: [...(theme.locales ?? [])],
         settings: (theme.settings ?? []).map((group) => copyData(group)),
+        ...(theme.style === undefined ? {} : { style: copyData(theme.style) }),
         content: copyData(theme.content ?? {}),
         preview: theme.preview === true,
         components: Object.fromEntries(Object.entries(theme.components).map(([key, definition]) => [
@@ -57,6 +61,9 @@ function componentSpec(definition) {
             ? {}
             : { capabilities: copyData(definition.capabilities) }),
         presets: (definition.presets ?? []).map((preset) => copyData(preset)),
+        ...(definition.placement === undefined ? {} : { placement: definition.placement }),
+        ...(definition.fixed === undefined ? {} : { fixed: copyData(definition.fixed) }),
+        ...(definition.role === undefined ? {} : { role: definition.role }),
     };
 }
 /**
@@ -75,6 +82,8 @@ const FieldCommonSchema = {
     label: LocalizedTextSchema,
     description: z.exactOptional(LocalizedTextSchema),
     required: z.exactOptional(z.boolean()),
+    // A condition's own rules are relational; `validateThemeDefinition` checks them.
+    visibleIf: z.exactOptional(z.custom((value) => isRecord(value))),
 };
 const TextFieldSchema = z.object({
     ...FieldCommonSchema,
@@ -91,6 +100,7 @@ const ScalarFieldSchemas = [
         min: z.exactOptional(z.number()),
         max: z.exactOptional(z.number()),
         step: z.exactOptional(z.number()),
+        display: z.exactOptional(z.enum(["input", "slider"])),
     }),
     z.object({
         ...FieldCommonSchema,
@@ -103,6 +113,7 @@ const ScalarFieldSchemas = [
         options: z.array(z.string()),
         optionLabels: z.exactOptional(z.record(z.string(), LocalizedTextSchema)),
         default: z.exactOptional(z.string()),
+        display: z.exactOptional(z.enum(["dropdown", "radio", "segmented"])),
     }),
     ...["url", "color", "menu", "collection", "product", "category"].map((kind) => z.object({
         ...FieldCommonSchema,
@@ -119,6 +130,26 @@ const ScalarFieldSchemas = [
         formats: z.exactOptional(z.array(z.custom((value) => typeof value === "string"))),
         // The document's own rules are relational; `validateThemeDefinition` checks them.
         default: z.exactOptional(z.custom((value) => typeof value === "object" && value !== null)),
+        inline: z.exactOptional(z.boolean()),
+    }),
+    ...["productList", "collectionList"].map((kind) => z.object({
+        ...FieldCommonSchema,
+        kind: z.literal(kind),
+        min: z.exactOptional(z.number()),
+        max: z.exactOptional(z.number()),
+        default: z.exactOptional(z.array(z.string())),
+    })),
+    z.object({
+        ...FieldCommonSchema,
+        kind: z.literal("style"),
+        panels: z.array(z.custom((value) => typeof value === "string")),
+        // Checked against the panels and the theme's sizes by `validateThemeDefinition`.
+        default: z.exactOptional(z.custom((value) => isRecord(value))),
+    }),
+    z.object({
+        ...FieldCommonSchema,
+        kind: z.literal("colorScheme"),
+        default: z.exactOptional(z.string()),
     }),
 ];
 const ItemFieldSchema = z.discriminatedUnion("kind", [...ScalarFieldSchemas]);
@@ -133,6 +164,11 @@ const FieldSchema = z.discriminatedUnion("kind", [
         default: z.exactOptional(z.array(z.object({ id: z.string(), props: z.exactOptional(z.record(z.string(), JsonValueSchema)) }))),
         itemLabel: z.exactOptional(z.string()),
     }),
+    z.object({
+        ...FieldCommonSchema,
+        kind: z.literal("colorSchemes"),
+        default: z.array(z.custom((value) => isRecord(value))),
+    }),
 ]);
 const PresetInstanceSchema = z.lazy(() => z.object({
     type: z.string(),
@@ -140,6 +176,11 @@ const PresetInstanceSchema = z.lazy(() => z.object({
     children: z.exactOptional(z.array(PresetInstanceSchema)),
     slots: z.exactOptional(z.record(z.string(), z.array(PresetInstanceSchema))),
 }));
+const RequiredBlockSchema = z.object({
+    type: z.string(),
+    min: z.exactOptional(z.number()),
+    max: z.exactOptional(z.number()),
+});
 const ComponentSpecSchema = z.object({
     type: z.string(),
     label: LocalizedTextSchema,
@@ -150,8 +191,13 @@ const ComponentSpecSchema = z.object({
         name: z.string(),
         multiple: z.exactOptional(z.boolean()),
         allow: z.exactOptional(z.array(z.string())),
+        max: z.exactOptional(z.number()),
+        required: z.exactOptional(z.array(RequiredBlockSchema)),
     }))
         .default([]),
+    placement: z.exactOptional(z.custom((value) => typeof value === "string")),
+    fixed: z.exactOptional(z.array(z.object({ name: z.string(), type: z.string(), label: z.exactOptional(LocalizedTextSchema) }))),
+    role: z.exactOptional(z.custom((value) => typeof value === "string")),
     capabilities: z.exactOptional(z.object({
         insertable: z.exactOptional(z.boolean()),
         surfaces: z.exactOptional(z.array(z.string())),
@@ -184,12 +230,27 @@ export const ThemeManifestSchema = z.object({
         pageType: z.exactOptional(z.custom((value) => typeof value === "string")),
         // A page document's own rules are checked by `validateThemeDefinition` on the probe.
         document: z.exactOptional(z.custom((value) => isRecord(value))),
+        required: z.exactOptional(z.array(RequiredBlockSchema)),
+        max: z.exactOptional(z.number()),
+    }))
+        .default([]),
+    areas: z
+        .array(z.object({
+        key: z.string(),
+        label: LocalizedTextSchema,
+        document: z.exactOptional(z.custom((value) => isRecord(value))),
+        required: z.exactOptional(z.array(RequiredBlockSchema)),
+        max: z.exactOptional(z.number()),
     }))
         .default([]),
     locales: z.array(z.string()).default([]),
     settings: z
         .array(z.object({ key: z.string(), label: LocalizedTextSchema, fields: z.array(FieldSchema) }))
         .default([]),
+    style: z.exactOptional(z.object({
+        spacing: z.exactOptional(z.record(z.string(), z.number())),
+        widths: z.exactOptional(z.record(z.string(), z.number())),
+    })),
     content: z.record(z.string(), z.record(z.string(), z.string())).default({}),
     preview: z.boolean().default(false),
     components: z.record(z.string(), ComponentSpecSchema),
@@ -247,7 +308,7 @@ function codeAt(path) {
         return "invalid-identity";
     if (path === "version")
         return "invalid-version";
-    if (path === "surfaces" || path.startsWith("surfaces["))
+    if (path === "surfaces" || path.startsWith("surfaces[") || path === "areas" || path.startsWith("areas["))
         return "invalid-surface";
     if (path === "settings" || path.startsWith("settings["))
         return "invalid-settings";
@@ -278,8 +339,10 @@ export function manifestCatalog(manifest) {
         key: manifest.key,
         version: manifest.version,
         surfaces: manifest.surfaces,
+        areas: manifest.areas,
         locales: manifest.locales,
         settings: manifest.settings,
+        ...(manifest.style === undefined ? {} : { style: manifest.style }),
         content: manifest.content,
         preview: manifest.preview,
         components: Object.fromEntries(Object.entries(manifest.components).map(([key, spec]) => [

package/dist/operations.d.ts

@@ -1,5 +1,5 @@
 import type { ComponentInstance, JsonValue, PageData, ThemeDefinition } from "./types.js";
-export type DocumentIssueCode = "invalid-document" | "invalid-instance" | "invalid-index" | "invalid-props" | "unknown-instance" | "unknown-type" | "unknown-slot" | "duplicate-id" | "not-insertable" | "not-available" | "not-allowed" | "slot-full" | "cycle";
+export type DocumentIssueCode = "invalid-document" | "invalid-instance" | "invalid-index" | "invalid-props" | "unknown-instance" | "unknown-type" | "unknown-slot" | "duplicate-id" | "not-insertable" | "not-available" | "not-allowed" | "not-placeable" | "slot-full" | "fixed-block" | "required-block" | "limit-exceeded" | "cycle";
 /** Why a document or a change is refused; `path` points into the document. */
 export interface DocumentIssue {
     path: string;
@@ -20,12 +20,19 @@ export interface InstancePlacement {
     slot?: string;
     index?: number;
 }
-/** Where an instance is: its parent (`null` at the top level), its slot and its index there. */
+/**
+ * Where an instance is: its parent (`null` at the top level) and its slot and
+ * index there — or, for a fixed block, its owner and `fixed`, the name the
+ * owner's definition gives it (`slot` is then `null`).
+ */
 export interface InstanceLocation {
     instance: ComponentInstance;
     parent: string | null;
     slot: string | null;
     index: number;
+    fixed?: string;
+    /** Levels below the top-level sections (a section is at 0). */
+    depth: number;
 }
 /**
  * A new instance id: `cmp_` and 16 random hex digits. Operations refuse an id
@@ -36,36 +43,55 @@ export declare function newInstanceId(): string;
 export declare function findInstance(page: PageData, id: string): InstanceLocation | null;
 /**
  * Insert a new instance — from `createInstance` or `instantiatePreset` — at a
- * placement. Refused when the component is not insertable or not available on
- * the document's surface, when the slot does not take it, or when any id is
- * already in the document.
+ * placement, completed with its fixed and required blocks. Refused when the
+ * component is not insertable, not available on the document's surface, not
+ * placeable there, when the list is full or already holds the most of its
+ * type, when the document would pass its caps, or when any id is already in
+ * the document.
  */
 export declare function insertInstance(theme: ThemeDefinition, page: PageData, instance: ComponentInstance, placement?: InstancePlacement): DocumentEdit;
-/** Remove an instance and everything inside it. */
+/**
+ * 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.
+ */
+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.
+ * A fixed block never moves; a required one moves only within its own list,
+ * unless enough of its type stay behind.
  */
 export declare function moveInstance(theme: ThemeDefinition, page: PageData, id: string, placement?: InstancePlacement): DocumentEdit;
 /**
  * Copy an instance and everything inside it right after the original, every
  * copied instance with an id from `newId`. List items keep their ids: they
- * are unique within their list, not the document.
+ * are unique within their list, not the document. A fixed block is never
+ * copied.
  */
 export declare function duplicateInstance(theme: ThemeDefinition, page: PageData, id: string, newId: () => string): DocumentEdit;
 /**
- * Change an instance's props: each value is checked by its field;
- * `undefined` removes the stored value, so the field falls back to its
- * content-pack text or default.
+ * Change an instance's props — a fixed block's too: each value is checked by
+ * its field; `undefined` removes the stored value, so the field falls back to
+ * its content-pack text or default.
  */
 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. */
+/**
+ * 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.
+ */
+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;
 /**
  * Everything a writer must fix before saving a document for this theme —
  * the strict counterpart of `validatePageData`: an envelope for one of the
- * theme's surfaces when it declares any, and every section a tree the
- * operations would have built. An empty list means the document may be saved.
+ * theme's surfaces when it declares any, the surface's required sections
+ * shown and its cap kept, and every section a tree the operations would have
+ * built. An empty list means the document may be saved.
  */
 export declare function checkPageData(theme: ThemeDefinition, input: unknown): DocumentIssue[];