@wocart/theme 1.4.0 → 1.6.0

package/dist/rich-text.d.ts

@@ -0,0 +1,31 @@
+import type { RichTextDocument, RichTextFormat } from "./types.js";
+/** Every format a rich-text field can allow, in the order an editor lists them. */
+export declare const RICH_TEXT_FORMATS: readonly RichTextFormat[];
+/** Whether a stored value is meant as one document (rather than a per-language map). */
+export declare function isRichTextDocumentShape(value: unknown): boolean;
+/**
+ * Why `value` is not a valid rich-text document under `formats`, or `null`
+ * when it is. Absent `formats` allows every format.
+ */
+export declare function richTextProblem(value: unknown, formats?: readonly RichTextFormat[]): string | null;
+/** How `richTextToHtml` writes links. */
+export interface RichTextHtmlOptions {
+    /**
+     * Turns a stored link target into the `href` to render — a theme passes its
+     * own localizing function so a site path keeps the shopper's language. The
+     * result is escaped; a target that fails the link rule never reaches it.
+     */
+    href?: (target: string) => string;
+}
+/**
+ * The document as HTML: `<p>`, `<h2>`–`<h4>`, `<ul>`/`<ol>`, `<strong>`, `<em>`,
+ * `<u>`, `<s>`, `<a href>` and `<br>`, every text and attribute escaped. Nodes
+ * outside the format and unsafe links are left out rather than trusted, so
+ * the output is safe for Astro's `set:html` even for an unchecked value.
+ */
+export declare function richTextToHtml(document: RichTextDocument, options?: RichTextHtmlOptions): string;
+/**
+ * The document's text without formatting: blocks and list items on their own
+ * lines, line breaks kept — for meta descriptions, `aria-label`s and previews.
+ */
+export declare function richTextToPlainText(document: RichTextDocument): string;

package/dist/rich-text.js

@@ -0,0 +1,233 @@
+/**
+ * Rich text: a closed JSON format, checked on read and on write, rendered to
+ * escaped HTML or to plain text here — a theme never walks the nodes itself.
+ *
+ * The format has no way to carry markup: text is always text, links pass the
+ * `url` field's rule, and every node and key outside the format makes the
+ * value invalid. Rendering re-checks what it emits, so a value that skipped
+ * validation still cannot produce markup.
+ */
+import { isSafeLinkTarget } from "./schemas.js";
+/** Every format a rich-text field can allow, in the order an editor lists them. */
+export const RICH_TEXT_FORMATS = [
+    "bold",
+    "italic",
+    "underline",
+    "strike",
+    "link",
+    "heading",
+    "list",
+];
+const MARKS = ["bold", "italic", "underline", "strike"];
+const MARK_TAGS = { bold: "strong", italic: "em", underline: "u", strike: "s" };
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+function unexpectedKey(value, allowed) {
+    return Object.keys(value).find((key) => !allowed.includes(key));
+}
+/** Whether a stored value is meant as one document (rather than a per-language map). */
+export function isRichTextDocumentShape(value) {
+    return isRecord(value) && Object.hasOwn(value, "type");
+}
+/**
+ * Why `value` is not a valid rich-text document under `formats`, or `null`
+ * when it is. Absent `formats` allows every format.
+ */
+export function richTextProblem(value, formats) {
+    const allowed = new Set(formats ?? RICH_TEXT_FORMATS);
+    if (!isRecord(value))
+        return "must be a rich-text document";
+    const extra = unexpectedKey(value, ["type", "version", "content"]);
+    if (extra !== undefined)
+        return `has an unknown key "${extra}"`;
+    if (value.type !== "doc")
+        return 'must have type "doc"';
+    if (value.version !== 1)
+        return `has unsupported version ${JSON.stringify(value.version ?? null)}; this SDK reads version 1`;
+    if (!Array.isArray(value.content))
+        return "must have a `content` array";
+    for (const [index, block] of value.content.entries()) {
+        const problem = blockProblem(block, allowed);
+        if (problem !== null)
+            return `content[${index}] ${problem}`;
+    }
+    return null;
+}
+function blockProblem(block, allowed) {
+    if (!isRecord(block))
+        return "must be a block";
+    switch (block.type) {
+        case "paragraph": {
+            const extra = unexpectedKey(block, ["type", "content"]);
+            if (extra !== undefined)
+                return `has an unknown key "${extra}"`;
+            return inlinesProblem(block.content, allowed);
+        }
+        case "heading": {
+            if (!allowed.has("heading"))
+                return "is a heading, which this field does not allow";
+            const extra = unexpectedKey(block, ["type", "level", "content"]);
+            if (extra !== undefined)
+                return `has an unknown key "${extra}"`;
+            if (block.level !== 2 && block.level !== 3 && block.level !== 4)
+                return "must have level 2, 3 or 4";
+            return inlinesProblem(block.content, allowed);
+        }
+        case "list": {
+            if (!allowed.has("list"))
+                return "is a list, which this field does not allow";
+            const extra = unexpectedKey(block, ["type", "style", "items"]);
+            if (extra !== undefined)
+                return `has an unknown key "${extra}"`;
+            if (block.style !== "bullet" && block.style !== "ordered")
+                return 'must have style "bullet" or "ordered"';
+            if (!Array.isArray(block.items) || block.items.length === 0)
+                return "must have at least one item";
+            for (const [index, item] of block.items.entries()) {
+                if (!isRecord(item))
+                    return `items[${index}] must be an object`;
+                const itemExtra = unexpectedKey(item, ["content"]);
+                if (itemExtra !== undefined)
+                    return `items[${index}] has an unknown key "${itemExtra}"`;
+                const problem = inlinesProblem(item.content, allowed);
+                if (problem !== null)
+                    return `items[${index}] ${problem}`;
+            }
+            return null;
+        }
+        default:
+            return `has unknown block type ${JSON.stringify(block.type ?? null)}`;
+    }
+}
+function inlinesProblem(content, allowed) {
+    if (content === undefined)
+        return null;
+    if (!Array.isArray(content))
+        return "must have a `content` array";
+    for (const [index, inline] of content.entries()) {
+        const problem = inlineProblem(inline, allowed);
+        if (problem !== null)
+            return `content[${index}] ${problem}`;
+    }
+    return null;
+}
+function inlineProblem(inline, allowed) {
+    if (!isRecord(inline))
+        return "must be a text or break node";
+    if (inline.type === "break") {
+        const extra = unexpectedKey(inline, ["type"]);
+        return extra === undefined ? null : `has an unknown key "${extra}"`;
+    }
+    if (inline.type !== "text")
+        return `has unknown inline type ${JSON.stringify(inline.type ?? null)}`;
+    const extra = unexpectedKey(inline, ["type", "text", "marks", "link"]);
+    if (extra !== undefined)
+        return `has an unknown key "${extra}"`;
+    if (typeof inline.text !== "string" || inline.text.length === 0)
+        return "must have non-empty `text`";
+    if (inline.marks !== undefined) {
+        if (!Array.isArray(inline.marks))
+            return "`marks` must be an array";
+        const seen = new Set();
+        for (const mark of inline.marks) {
+            if (!MARKS.includes(mark))
+                return `has unknown mark ${JSON.stringify(mark)}`;
+            if (!allowed.has(mark))
+                return `uses "${String(mark)}", which this field does not allow`;
+            if (seen.has(mark))
+                return `repeats mark "${String(mark)}"`;
+            seen.add(mark);
+        }
+    }
+    if (inline.link !== undefined) {
+        if (!allowed.has("link"))
+            return "has a link, which this field does not allow";
+        if (typeof inline.link !== "string" || !isSafeLinkTarget(inline.link)) {
+            return "`link` must be a site path, #fragment, ?query, or an http(s), mailto or tel URL";
+        }
+    }
+    return null;
+}
+const escapeHtml = (text) => text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&#39;");
+/**
+ * The document as HTML: `<p>`, `<h2>`–`<h4>`, `<ul>`/`<ol>`, `<strong>`, `<em>`,
+ * `<u>`, `<s>`, `<a href>` and `<br>`, every text and attribute escaped. Nodes
+ * outside the format and unsafe links are left out rather than trusted, so
+ * the output is safe for Astro's `set:html` even for an unchecked value.
+ */
+export function richTextToHtml(document, options = {}) {
+    if (!isRecord(document) || !Array.isArray(document.content))
+        return "";
+    return document.content.map((block) => blockHtml(block, options)).join("");
+}
+function blockHtml(block, options) {
+    if (!isRecord(block))
+        return "";
+    switch (block.type) {
+        case "paragraph":
+            return `<p>${inlinesHtml(block.content, options)}</p>`;
+        case "heading": {
+            const level = block.level === 3 || block.level === 4 ? block.level : 2;
+            return `<h${level}>${inlinesHtml(block.content, options)}</h${level}>`;
+        }
+        case "list": {
+            const tag = block.style === "ordered" ? "ol" : "ul";
+            const items = Array.isArray(block.items) ? block.items : [];
+            return `<${tag}>${items.map((item) => `<li>${inlinesHtml(isRecord(item) ? item.content : undefined, options)}</li>`).join("")}</${tag}>`;
+        }
+        default:
+            return "";
+    }
+}
+function inlinesHtml(content, options) {
+    if (!Array.isArray(content))
+        return "";
+    return content.map((inline) => inlineHtml(inline, options)).join("");
+}
+function inlineHtml(inline, options) {
+    if (!isRecord(inline))
+        return "";
+    if (inline.type === "break")
+        return "<br>";
+    if (inline.type !== "text" || typeof inline.text !== "string")
+        return "";
+    let html = escapeHtml(inline.text);
+    const marks = Array.isArray(inline.marks) ? inline.marks : [];
+    for (const mark of [...MARKS].reverse()) {
+        if (marks.includes(mark))
+            html = `<${MARK_TAGS[mark]}>${html}</${MARK_TAGS[mark]}>`;
+    }
+    if (typeof inline.link === "string" && isSafeLinkTarget(inline.link)) {
+        const href = options.href ? options.href(inline.link) : inline.link;
+        html = `<a href="${escapeHtml(href)}">${html}</a>`;
+    }
+    return html;
+}
+/**
+ * The document's text without formatting: blocks and list items on their own
+ * lines, line breaks kept — for meta descriptions, `aria-label`s and previews.
+ */
+export function richTextToPlainText(document) {
+    if (!isRecord(document) || !Array.isArray(document.content))
+        return "";
+    const lines = [];
+    for (const block of document.content) {
+        if (!isRecord(block))
+            continue;
+        if (block.type === "list") {
+            for (const item of Array.isArray(block.items) ? block.items : []) {
+                lines.push(inlinesText(isRecord(item) ? item.content : undefined));
+            }
+        }
+        else if (block.type === "paragraph" || block.type === "heading") {
+            lines.push(inlinesText(block.content));
+        }
+    }
+    return lines.join("\n");
+}
+function inlinesText(content) {
+    if (!Array.isArray(content))
+        return "";
+    return content
+        .map((inline) => (!isRecord(inline) ? "" : inline.type === "break" ? "\n" : inline.type === "text" && typeof inline.text === "string" ? inline.text : ""))
+        .join("");
+}

package/dist/schemas.d.ts

@@ -21,6 +21,8 @@ export declare const TYPE_KEY_PATTERN: RegExp;
  * not of the package's curated public surface (`src/index.ts`).
  */
 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"];
 /** A `color` field's value: a hex color, `#rgb` or `#rrggbb`. */
 export declare const COLOR_PATTERN: RegExp;
 /**
@@ -30,12 +32,31 @@ export declare const COLOR_PATTERN: RegExp;
  */
 export declare const MENU_HANDLE_PATTERN: RegExp;
 export declare const COLLECTION_HANDLE_PATTERN: RegExp;
+/**
+ * A `product` or `category` value: a handle or slug as the store's URLs use
+ * it. Merchants may type their own, so the rule only keeps out what cannot be
+ * one URL path segment: whitespace, control characters, `/`, `\`, `?`, `#`
+ * and `%`, and anything over 255 characters.
+ */
+export declare const RESOURCE_HANDLE_PATTERN: RegExp;
+/**
+ * A media object key in the store's bucket: a namespace and a name
+ * (`products/3f2a9c.webp`), segments of letters, digits, `.`, `_` and `-`
+ * that never start with a dot — so no `..`, no leading slash, no empty
+ * segment — and at most 512 characters.
+ */
+export declare const MEDIA_KEY_PATTERN: RegExp;
 export declare function isLocaleTag(value: string): boolean;
 /**
  * Whether `value` is a per-language map (`{ ar: "…", fr: "…" }`): a plain
  * object with at least one entry, every key a locale tag, every value a string.
  */
 export declare function isLocaleMap(value: unknown): value is Readonly<Record<string, string>>;
+/**
+ * Whether `value` is a per-language map whose entries pass `isEntry`: a plain
+ * object with at least one entry, every key a locale tag.
+ */
+export declare function isLocaleMapOf<T>(value: unknown, isEntry: (entry: unknown) => entry is T): value is Readonly<Record<string, T>>;
 /**
  * Whether a `url` field value is safe to render as an `href`: a site path,
  * fragment or query, or an `http(s)`, `mailto` or `tel` URL. Rejects

package/dist/schemas.js

@@ -20,6 +20,18 @@ export const TYPE_KEY_PATTERN = /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/;
  * not of the package's curated public surface (`src/index.ts`).
  */
 export const SURFACE_KEY_PATTERN = /^[a-z0-9][a-z0-9._:-]{0,63}$/;
+/** The platform page types a surface can render (`SurfacePageType`), mirrored from the storefront's page types. */
+export const PAGE_TYPES = [
+    "home",
+    "catalog",
+    "category",
+    "collection",
+    "product",
+    "page",
+    "landing",
+    "checkout",
+    "thankYou",
+];
 /** 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})$/;
 /**
@@ -29,6 +41,20 @@ export const COLOR_PATTERN = /^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6})$/;
  */
 export const MENU_HANDLE_PATTERN = /^[a-z0-9][a-z0-9-]{0,63}$/;
 export const COLLECTION_HANDLE_PATTERN = /^[a-z0-9][a-z0-9-]{0,63}$/;
+/**
+ * A `product` or `category` value: a handle or slug as the store's URLs use
+ * it. Merchants may type their own, so the rule only keeps out what cannot be
+ * one URL path segment: whitespace, control characters, `/`, `\`, `?`, `#`
+ * and `%`, and anything over 255 characters.
+ */
+export const RESOURCE_HANDLE_PATTERN = /^[^\s/\\?#%\u0000-\u001f\u007f]{1,255}$/u;
+/**
+ * A media object key in the store's bucket: a namespace and a name
+ * (`products/3f2a9c.webp`), segments of letters, digits, `.`, `_` and `-`
+ * that never start with a dot — so no `..`, no leading slash, no empty
+ * segment — and at most 512 characters.
+ */
+export const MEDIA_KEY_PATTERN = /^(?=.{3,512}$)[A-Za-z0-9][A-Za-z0-9._-]*(?:\/[A-Za-z0-9][A-Za-z0-9._-]*)+$/;
 /**
  * A BCP 47 language tag in canonical case: a 2–3 letter language, an optional
  * 4-letter script, an optional 2-letter or 3-digit region (`ar`, `zgh`,
@@ -44,11 +70,17 @@ export function isLocaleTag(value) {
  * object with at least one entry, every key a locale tag, every value a string.
  */
 export function isLocaleMap(value) {
+    return isLocaleMapOf(value, (entry) => typeof entry === "string");
+}
+/**
+ * Whether `value` is a per-language map whose entries pass `isEntry`: a plain
+ * object with at least one entry, every key a locale tag.
+ */
+export function isLocaleMapOf(value, isEntry) {
     if (typeof value !== "object" || value === null || Array.isArray(value))
         return false;
     const entries = Object.entries(value);
-    return (entries.length > 0 &&
-        entries.every(([key, text]) => isLocaleTag(key) && typeof text === "string"));
+    return entries.length > 0 && entries.every(([key, entry]) => isLocaleTag(key) && isEntry(entry));
 }
 /**
  * Whether a `url` field value is safe to render as an `href`: a site path,
@@ -94,6 +126,7 @@ export const ComponentInstanceSchema = z.lazy(() => z.object({
     props: z.exactOptional(z.record(z.string(), JsonValueSchema)),
     children: z.exactOptional(z.array(ComponentInstanceSchema)),
     slots: z.exactOptional(z.record(z.string(), z.array(ComponentInstanceSchema))),
+    hidden: z.exactOptional(z.boolean()),
 }));
 /**
  * The envelope schema. **Loose on purpose**: unknown top-level keys