@wocart/theme 1.3.0 → 1.5.0

package/dist/types.d.ts

@@ -36,8 +36,12 @@ export interface ResolutionScope {
     content?: Record<string, string>;
     locales?: readonly LocaleCode[];
 }
-/** The field kinds. `color`, `menu` and `collection` were added after V1, additively. */
-export type FieldKind = "text" | "textarea" | "number" | "boolean" | "select" | "url" | "color" | "menu" | "collection";
+/**
+ * The field kinds. Every kind after `url` was added after V1, additively; a
+ * reader that meets a kind it does not know rejects the manifest rather than
+ * render a value it cannot check.
+ */
+export type FieldKind = "text" | "textarea" | "number" | "boolean" | "select" | "url" | "color" | "menu" | "collection" | "image" | "richtext" | "list" | "product" | "category";
 interface FieldDefinitionBase {
     /** The exact prop name the component expects. */
     key: string;
@@ -68,22 +72,32 @@ export interface TextFieldDefinition extends FieldDefinitionBase {
      */
     default?: LocalizedText;
 }
-/** `number`: a finite number, optionally bounded. */
+/**
+ * `number`: a finite number, optionally bounded. With `step`, a value must lie
+ * on the grid that starts at `min` (or 0) — Shopify's `range`; an editor may
+ * show a slider.
+ */
 export interface NumberFieldDefinition extends FieldDefinitionBase {
     kind: "number";
     default?: number;
     min?: number;
     max?: number;
+    step?: number;
 }
 /** `boolean`. */
 export interface BooleanFieldDefinition extends FieldDefinitionBase {
     kind: "boolean";
     default?: boolean;
 }
-/** `select`: one of a closed option list. */
+/**
+ * `select`: one of a closed option list. The stored value is the option
+ * itself; `optionLabels` gives an editor the words to show for each option,
+ * in the theme's languages (an option without a label is shown as written).
+ */
 export interface SelectFieldDefinition extends FieldDefinitionBase {
     kind: "select";
     options: readonly string[];
+    optionLabels?: Readonly<Record<string, LocalizedText>>;
     default?: string;
 }
 /**
@@ -123,7 +137,143 @@ export interface CollectionFieldDefinition extends FieldDefinitionBase {
     kind: "collection";
     default?: string;
 }
-export type FieldDefinition = TextFieldDefinition | NumberFieldDefinition | BooleanFieldDefinition | SelectFieldDefinition | UrlFieldDefinition | ColorFieldDefinition | MenuFieldDefinition | CollectionFieldDefinition;
+/**
+ * `product`: which of the store's products to show here — Shopify's `product`
+ * setting. The value is a product handle (the `/products/<handle>` segment);
+ * the theme reads it with the storefront client's `products.get(handle)`. A
+ * renamed or deleted product reads as no product.
+ */
+export interface ProductFieldDefinition extends FieldDefinitionBase {
+    kind: "product";
+    default?: string;
+}
+/**
+ * `category`: which of the store's categories to show here. The value is a
+ * category slug (the `/category/<slug>` segment); the theme finds it in the
+ * storefront client's `categories.list()`. An unknown slug reads as no category.
+ */
+export interface CategoryFieldDefinition extends FieldDefinitionBase {
+    kind: "category";
+    default?: string;
+}
+/**
+ * `image`: one image from the store's own media. The value is a
+ * `MediaReference` — the object's key in the store's media bucket is its
+ * identity; the URL is derived at render from the store's media domain. A
+ * theme cannot know a store's media, so an image field has no default: the
+ * component renders its own fallback when no image is chosen.
+ */
+export interface ImageFieldDefinition extends FieldDefinitionBase {
+    kind: "image";
+}
+/** What a rich-text field may contain. Absent `formats` allows all of them. */
+export type RichTextFormat = "bold" | "italic" | "underline" | "strike" | "link" | "heading" | "list";
+/**
+ * `richtext`: formatted text, stored as a `RichTextDocument` (or one per
+ * language) — never as HTML. `formats` narrows what the merchant may use; a
+ * stored document using anything else is invalid. Render it with
+ * `richTextToHtml`.
+ */
+export interface RichTextFieldDefinition extends FieldDefinitionBase {
+    kind: "richtext";
+    formats?: readonly RichTextFormat[];
+    default?: RichTextValue;
+}
+/** A field a list item may hold: any kind but `list` itself. */
+export type ListItemFieldDefinition = Exclude<FieldDefinition, ListFieldDefinition>;
+/**
+ * `list`: repeatable items — trust badges, questions and answers, slides. Each
+ * stored item is `{ id, props }`: the id is unique within the list, so
+ * reordering never makes one item take another's identity. Item fields resolve
+ * like a section's (per-language text included), except that they cannot
+ * default from the content pack — every item would read the same key.
+ */
+export interface ListFieldDefinition extends FieldDefinitionBase {
+    kind: "list";
+    fields: readonly ListItemFieldDefinition[];
+    min?: number;
+    max?: number;
+    default?: readonly ListItem[];
+    /** The item field (`text` or `textarea`) an editor shows as each item's title. */
+    itemLabel?: string;
+}
+export type FieldDefinition = TextFieldDefinition | NumberFieldDefinition | BooleanFieldDefinition | SelectFieldDefinition | UrlFieldDefinition | ColorFieldDefinition | MenuFieldDefinition | CollectionFieldDefinition | ProductFieldDefinition | CategoryFieldDefinition | ImageFieldDefinition | RichTextFieldDefinition | ListFieldDefinition;
+/**
+ * A stored image: the object's key in the store's media bucket
+ * (`products/3f2a….webp`), never a URL, plus what the editor knows about it.
+ * `width`/`height` are the original's pixels; `focal` is the point to keep in
+ * view when the image is cropped, from 0 to 1 on each axis.
+ */
+export interface MediaReference {
+    key: string;
+    alt?: LocalizedText;
+    width?: number;
+    height?: number;
+    focal?: {
+        x: number;
+        y: number;
+    };
+}
+/** An image as a component receives it: `alt` already in the rendered language. */
+export interface ResolvedImage {
+    key: string;
+    alt?: string;
+    width?: number;
+    height?: number;
+    focal?: {
+        x: number;
+        y: number;
+    };
+}
+/** One stored list item. */
+export interface ListItem {
+    id: string;
+    props?: JsonObject;
+}
+export type RichTextMark = "bold" | "italic" | "underline" | "strike";
+/** A run of text. `link` is a safe link target, as a `url` field's. */
+export interface RichTextText {
+    type: "text";
+    text: string;
+    marks?: readonly RichTextMark[];
+    link?: string;
+}
+/** A line break inside a block. */
+export interface RichTextBreak {
+    type: "break";
+}
+export type RichTextInline = RichTextText | RichTextBreak;
+export interface RichTextParagraph {
+    type: "paragraph";
+    content?: readonly RichTextInline[];
+}
+/** Levels 2–4: the page owns its level-1 heading. */
+export interface RichTextHeading {
+    type: "heading";
+    level: 2 | 3 | 4;
+    content?: readonly RichTextInline[];
+}
+export interface RichTextListItem {
+    content?: readonly RichTextInline[];
+}
+export interface RichTextList {
+    type: "list";
+    style: "bullet" | "ordered";
+    items: readonly RichTextListItem[];
+}
+export type RichTextBlock = RichTextParagraph | RichTextHeading | RichTextList;
+/**
+ * A rich-text value. A closed format: anything not listed here is invalid, so
+ * no stored value can carry markup, scripts or styles. `version` lets the
+ * format grow; a reader rejects a version it does not know.
+ */
+export interface RichTextDocument {
+    type: "doc";
+    version: 1;
+    content: readonly RichTextBlock[];
+}
+/** A rich-text field's stored value: one document, or one per language. */
+export type RichTextValue = RichTextDocument | Readonly<Record<LocaleCode, RichTextDocument>>;
 /**
  * One composition point a component declares (`"default"` = children).
  *
@@ -165,7 +315,35 @@ export interface SlotDefinition {
  * it exists, belongs at *insertion* time in the writer, not at render.
  */
 export interface ComponentCapabilities {
+    /** Absent or `true`: an editor may offer it. `false`: never inserted by an editor. */
     insertable?: boolean;
+    /**
+     * The surfaces it may be inserted on, by surface key. An entry also covers
+     * that surface's alternates (`product` covers `product.compact`). Absent:
+     * any surface. Like `insertable`, enforced when inserting, never at render.
+     */
+    surfaces?: readonly string[];
+}
+/** One component of a preset: like an instance, without an id — ids are given when it is inserted. */
+export interface PresetInstance {
+    type: string;
+    props?: JsonObject;
+    children?: readonly PresetInstance[];
+    slots?: Readonly<Record<string, readonly PresetInstance[]>>;
+}
+/**
+ * A ready-made configuration of a component that an editor offers when
+ * inserting it ("Hero — with image", a two-column section with its columns):
+ * props over the field defaults, and child components for its slots.
+ */
+export interface ComponentPreset {
+    /** Lowercase kebab-case, unique among the component's presets. */
+    key: string;
+    label: LocalizedText;
+    description?: LocalizedText;
+    props?: JsonObject;
+    children?: readonly PresetInstance[];
+    slots?: Readonly<Record<string, readonly PresetInstance[]>>;
 }
 /** The request facts available while rendering (formalises `Astro.locals.store` + URL). */
 export interface ThemeRenderContext {
@@ -241,8 +419,12 @@ export interface ComponentDefinition {
     slots?: readonly SlotDefinition[];
     load?: LoadFn;
     capabilities?: ComponentCapabilities;
+    presets?: readonly ComponentPreset[];
 }
-/** The value type one field resolves to. A select narrows to its option literals. */
+/**
+ * The value type one field resolves to. A select narrows to its option
+ * literals; a list resolves to its items, each `{ id }` plus its own fields.
+ */
 export type FieldValue<F extends FieldDefinition> = F extends {
     kind: "number";
 } ? number : F extends {
@@ -250,7 +432,18 @@ export type FieldValue<F extends FieldDefinition> = F extends {
 } ? boolean : F extends {
     kind: "select";
     options: readonly (infer Option)[];
-} ? Option : string;
+} ? Option : F extends {
+    kind: "image";
+} ? ResolvedImage : F extends {
+    kind: "richtext";
+} ? RichTextDocument : F extends {
+    kind: "list";
+    fields: readonly (infer Item extends FieldDefinition)[];
+} ? Array<{
+    id: string;
+} & FieldProps<{
+    fields: readonly Item[];
+}>> : string;
 type FieldsOf<D> = D extends {
     fields: readonly (infer F extends FieldDefinition)[];
 } ? F : never;
@@ -316,6 +509,18 @@ export interface ThemeDefinition {
      * with `checkThemeSettings`. Setting keys are unique across all groups.
      */
     settings?: readonly SettingsGroup[];
+    /**
+     * The theme's own text, one pack per language: what a `contentKey` field
+     * shows until the merchant edits it, and the store-wide labels a merchant
+     * may override. Declared, every `contentKey` must exist in every pack, and
+     * the manifest carries the packs so an editor shows inherited text.
+     */
+    content?: Readonly<Record<LocaleCode, Readonly<Record<string, string>>>>;
+    /**
+     * `true`: the theme serves a preview route at `THEME_PREVIEW_PATH`, so an
+     * editor can show a draft on the live storefront. Absent: no preview.
+     */
+    preview?: boolean;
     components: Record<string, ComponentDefinition>;
 }
 /** One group of theme settings, as an editor lists them ("Typography", "Header"). */
@@ -334,7 +539,21 @@ export interface SettingsGroup {
 export interface SurfaceSpec {
     key: string;
     label: LocalizedText;
+    /**
+     * The platform page type this surface renders. A page type with a resource
+     * (`product`, `category`, `collection`, `page`, `landing`) makes the surface
+     * a template: one document renders every resource of that type, and its
+     * sections read the resource from `ThemeRenderContext.params`.
+     */
+    pageType?: SurfacePageType;
+    /** The theme's shipped document for this surface: what renders before the merchant saves one. */
+    document?: PageData;
 }
+/**
+ * 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";
 /**
  * One component as data: a `ComponentDefinition` minus its runtime-only
  * implementation. `component` (the live component reference) and `load` (the
@@ -354,6 +573,7 @@ export interface ComponentSpec {
     fields: readonly FieldDefinition[];
     slots: readonly SlotDefinition[];
     capabilities?: ComponentCapabilities;
+    presets: readonly ComponentPreset[];
 }
 /**
  * The serializable theme contract.
@@ -372,14 +592,24 @@ export interface ThemeManifest {
     contractVersion: 1;
     key: string;
     version: string;
+    /**
+     * The `@wocart/theme` version that generated the manifest — the renderer the
+     * theme ships with. An editor writes a feature only for renderers that read
+     * it (a hidden section needs 1.5.0). Absent from manifests made before 1.5.0.
+     */
+    sdkVersion?: string;
     surfaces: readonly SurfaceSpec[];
     /** The languages the theme's packs cover (possibly none declared). */
     locales: readonly LocaleCode[];
     /** The theme's global settings (possibly none). */
     settings: readonly SettingsGroup[];
+    /** The theme's content packs, by language (possibly none). */
+    content: Readonly<Record<LocaleCode, Readonly<Record<string, string>>>>;
+    /** Whether the theme serves a preview route (`THEME_PREVIEW_PATH`). */
+    preview: boolean;
     components: Record<string, ComponentSpec>;
 }
-export type ThemeManifestIssueCode = "invalid-manifest" | "unsupported-contract" | "invalid-identity" | "invalid-version" | "invalid-surface" | "invalid-settings" | "invalid-component" | "type-mismatch" | "non-serializable";
+export type ThemeManifestIssueCode = "invalid-manifest" | "unsupported-contract" | "invalid-identity" | "invalid-version" | "invalid-surface" | "invalid-settings" | "invalid-component" | "invalid-content" | "type-mismatch" | "non-serializable";
 /** One reported manifest problem; `path` points into the manifest (e.g. `components.hero.fields[0].kind`). */
 export interface ThemeManifestIssue {
     path: string;
@@ -405,17 +635,22 @@ export interface ComponentInstance {
     props?: JsonObject;
     children?: ComponentInstance[];
     slots?: Record<string, ComponentInstance[]>;
+    /**
+     * `true`: kept in the document but not rendered — the merchant switched the
+     * section off. Its children are not rendered either.
+     */
+    hidden?: boolean;
 }
 /**
  * One composed surface's persisted document.
  *
  * At runtime the envelope is **forward-compatible**: `parsePageData` and
  * `PageDataSchema` carry unknown *top-level* keys through verbatim, so a later
- * writer can record metadata (catalog provenance is the intended first use)
- * without a `PageData.version` bump. Those keys are never read by the renderer,
- * which only walks `sections`, and they are deliberately **not declared here**:
- * an index signature would turn a `page.sectons` typo into `unknown` instead of
- * a compile error. The field is added when a real reader exists.
+ * writer can record metadata without a `PageData.version` bump. Those keys
+ * are never read by the renderer, which only walks `sections`, and they are
+ * deliberately **not declared here**: an index signature would turn a
+ * `page.sectons` typo into `unknown` instead of a compile error. A key is
+ * declared once it has a reader — `theme`, the document's provenance.
  *
  * Unknown keys *inside* an instance are still stripped — the envelope is
  * extensible, the instance is not.
@@ -424,8 +659,17 @@ export interface PageData {
     version: 1;
     surface: string;
     sections: ComponentInstance[];
+    /**
+     * The theme and theme version that wrote the document. A document that
+     * names another theme is reported (`theme-mismatch`): its sections were
+     * composed from another catalog.
+     */
+    theme?: {
+        key: string;
+        version: string;
+    };
 }
-export type PageDataIssueCode = "envelope-invalid" | "instance-dropped" | "duplicate-id" | "unknown-type" | "unknown-prop" | "invalid-prop" | "missing-required-prop" | "undeclared-children" | "unknown-slot" | "slot-not-multiple" | "disallowed-child";
+export type PageDataIssueCode = "envelope-invalid" | "instance-dropped" | "duplicate-id" | "unknown-type" | "unknown-prop" | "invalid-prop" | "missing-required-prop" | "undeclared-children" | "unknown-slot" | "slot-not-multiple" | "disallowed-child" | "invalid-provenance" | "theme-mismatch";
 /** One reported degradation; `path` points into the document (e.g. `sections[0].props.limit`). */
 export interface PageDataIssue {
     path: string;
@@ -444,7 +688,7 @@ export interface ResolvedInstance {
     slots: Record<string, ComponentInstance[]>;
     issues: PageDataIssue[];
 }
-export type ThemeDefinitionIssueCode = "invalid-theme" | "invalid-settings" | "invalid-definition" | "invalid-type" | "type-mismatch" | "invalid-field" | "duplicate-field-key" | "unknown-content-key" | "invalid-slot" | "duplicate-slot" | "invalid-capability" | "invalid-load";
+export type ThemeDefinitionIssueCode = "invalid-theme" | "invalid-settings" | "invalid-definition" | "invalid-type" | "type-mismatch" | "invalid-field" | "duplicate-field-key" | "unknown-content-key" | "invalid-slot" | "duplicate-slot" | "invalid-capability" | "invalid-load" | "invalid-preset" | "invalid-document" | "invalid-content";
 export interface ThemeDefinitionIssue {
     path: string;
     code: ThemeDefinitionIssueCode;

package/dist/version.d.ts

@@ -0,0 +1,7 @@
+/**
+ * The version of this package, as published. A theme's manifest records it
+ * (`ThemeManifest.sdkVersion`), so an editor knows what the theme's renderer
+ * reads. Always equal to `package.json`'s version; the package check refuses
+ * a release where they differ.
+ */
+export declare const THEME_SDK_VERSION = "1.5.0";

package/dist/version.js

@@ -0,0 +1,7 @@
+/**
+ * The version of this package, as published. A theme's manifest records it
+ * (`ThemeManifest.sdkVersion`), so an editor knows what the theme's renderer
+ * reads. Always equal to `package.json`'s version; the package check refuses
+ * a release where they differ.
+ */
+export const THEME_SDK_VERSION = "1.5.0";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wocart/theme",
-  "version": "1.3.0",
+  "version": "1.5.0",
   "description": "The Wocart theme contract: code-owned component definitions, JSON page documents, validation and resolution, and a reference Astro renderer.",
   "keywords": [
     "wocart",
@@ -38,6 +38,14 @@
       "default": "./dist/astro/index.js"
     },
     "./astro/InstanceView.astro": "./dist/astro/InstanceView.astro",
+    "./image-service": {
+      "types": "./dist/image-service.d.ts",
+      "default": "./dist/image-service.js"
+    },
+    "./preview": {
+      "types": "./dist/preview-bridge.d.ts",
+      "default": "./dist/preview-bridge.js"
+    },
     "./package.json": "./package.json"
   },
   "files": [
@@ -63,7 +71,7 @@
     "zod": "^4.4.3"
   },
   "peerDependencies": {
-    "@wocart/storefront": "^1.0.0",
+    "@wocart/storefront": "^1.14.0",
     "astro": "^7.0.0"
   },
   "peerDependenciesMeta": {
@@ -72,10 +80,11 @@
     }
   },
   "devDependencies": {
-    "@wocart/storefront": "^1.0.0",
     "@types/node": "^26.2.0",
+    "@wocart/storefront": "^1.0.0",
     "astro": "^7.3.2",
     "fast-check": "^4.6.0",
+    "happy-dom": "^20.11.6",
     "typescript": "^7.0.2",
     "vitest": "^5.0.0"
   }