@wocart/theme 0.0.0-stage → 1.1.0

package/dist/schemas.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Zod schemas for the persistence boundary — the only place runtime input is
+ * validated. Definitions are typechecked code; page data is parsed data.
+ */
+import { z } from "zod";
+import type { ComponentInstance, JsonValue } from "./types.js";
+/**
+ * A theme's key: lowercase kebab-case, at most 64 characters. The platform
+ * stores a merchant's text edits under it, so it is the theme's identity on the
+ * platform, and the server applies the same rule.
+ */
+export declare const THEME_KEY_PATTERN: RegExp;
+/** Type keys are lowercase kebab-case. */
+export declare const TYPE_KEY_PATTERN: RegExp;
+/**
+ * The page-document **surface** key — the address of a composed page
+ * (`home` today; `page:<slug>` / `lp:<slug>` are reserved conventions).
+ *
+ * The server applies the same pattern. Module-level on purpose: it is part of
+ * the persisted-data contract,
+ * not of the package's curated public surface (`src/index.ts`).
+ */
+export declare const SURFACE_KEY_PATTERN: RegExp;
+/** A `color` field's value: a hex color, `#rgb` or `#rrggbb`. */
+export declare const COLOR_PATTERN: RegExp;
+/**
+ * A `menu` field's value: the handle of one of the store's menus
+ * (`main-menu`, `footer`). The server applies the same pattern to menu
+ * handles; a menu that does not exist reads as no menu.
+ */
+export declare const MENU_HANDLE_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 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
+ * `javascript:`/`data:` and every other scheme, protocol-relative `//host`,
+ * backslashes (browsers read `/\host` as `//host`), whitespace and control
+ * characters, and anything over 2048 characters.
+ */
+export declare function isSafeLinkTarget(value: string): boolean;
+export declare const JsonValueSchema: z.ZodType<JsonValue>;
+export declare const ComponentInstanceSchema: z.ZodType<ComponentInstance>;
+/**
+ * The envelope schema. **Loose on purpose**: unknown top-level keys
+ * survive `.parse`, matching `parsePageData` — a writer that records metadata
+ * must not have it stripped by whichever reader runs first.
+ */
+export declare const PageDataSchema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    surface: z.ZodString;
+    sections: z.ZodArray<z.ZodType<ComponentInstance, unknown, z.core.$ZodTypeInternals<ComponentInstance, unknown>>>;
+}, z.core.$loose>;

package/dist/schemas.js

@@ -0,0 +1,108 @@
+/**
+ * Zod schemas for the persistence boundary — the only place runtime input is
+ * validated. Definitions are typechecked code; page data is parsed data.
+ */
+import { z } from "zod";
+/**
+ * A theme's key: lowercase kebab-case, at most 64 characters. The platform
+ * stores a merchant's text edits under it, so it is the theme's identity on the
+ * platform, and the server applies the same rule.
+ */
+export const THEME_KEY_PATTERN = /^(?=.{1,64}$)[a-z][a-z0-9]*(-[a-z0-9]+)*$/;
+/** Type keys are lowercase kebab-case. */
+export const TYPE_KEY_PATTERN = /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/;
+/**
+ * The page-document **surface** key — the address of a composed page
+ * (`home` today; `page:<slug>` / `lp:<slug>` are reserved conventions).
+ *
+ * The server applies the same pattern. Module-level on purpose: it is part of
+ * the persisted-data contract,
+ * not of the package's curated public surface (`src/index.ts`).
+ */
+export const SURFACE_KEY_PATTERN = /^[a-z0-9][a-z0-9._:-]{0,63}$/;
+/** 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})$/;
+/**
+ * A `menu` field's value: the handle of one of the store's menus
+ * (`main-menu`, `footer`). The server applies the same pattern to menu
+ * handles; a menu that does not exist reads as no menu.
+ */
+export const MENU_HANDLE_PATTERN = /^[a-z0-9][a-z0-9-]{0,63}$/;
+/**
+ * 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`,
+ * `ar-DZ`, `zh-Hant-TW`, `es-419`). Canonical case keeps map keys unique:
+ * `fr` and `FR` can never both be present.
+ */
+const LOCALE_TAG_PATTERN = /^[a-z]{2,3}(?:-[A-Z][a-z]{3})?(?:-(?:[A-Z]{2}|\d{3}))?$/;
+export function isLocaleTag(value) {
+    return LOCALE_TAG_PATTERN.test(value);
+}
+/**
+ * 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 function isLocaleMap(value) {
+    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"));
+}
+/**
+ * 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
+ * `javascript:`/`data:` and every other scheme, protocol-relative `//host`,
+ * backslashes (browsers read `/\host` as `//host`), whitespace and control
+ * characters, and anything over 2048 characters.
+ */
+export function isSafeLinkTarget(value) {
+    if (value.length === 0 || value.length > 2048)
+        return false;
+    if (/[\s\\\u0000-\u001f\u007f]/.test(value))
+        return false;
+    if (value.startsWith("/"))
+        return !value.startsWith("//");
+    if (value.startsWith("#") || value.startsWith("?"))
+        return true;
+    const scheme = /^([a-z][a-z0-9+.-]*):/i.exec(value)?.[1]?.toLowerCase();
+    if (scheme === "http" || scheme === "https") {
+        return /^https?:\/\/[a-z0-9.-]+(:\d{1,5})?([/?#]|$)/i.test(value);
+    }
+    if (scheme === "mailto" || scheme === "tel")
+        return value.length > scheme.length + 1;
+    return false;
+}
+export const JsonValueSchema = z.lazy(() => z.union([
+    z.string(),
+    z
+        .number()
+        .refine(Number.isFinite, { message: "numbers must be finite" })
+        // JSON has no -0: it serializes as 0, so keeping it would break round-trips.
+        .transform((value) => (Object.is(value, -0) ? 0 : value)),
+    z.boolean(),
+    z.null(),
+    z.array(JsonValueSchema),
+    z.record(z.string(), JsonValueSchema),
+]));
+export const ComponentInstanceSchema = z.lazy(() => z.object({
+    id: z.string().min(1),
+    type: z
+        .string()
+        .regex(TYPE_KEY_PATTERN, "type keys are lowercase kebab-case"),
+    props: z.exactOptional(z.record(z.string(), JsonValueSchema)),
+    children: z.exactOptional(z.array(ComponentInstanceSchema)),
+    slots: z.exactOptional(z.record(z.string(), z.array(ComponentInstanceSchema))),
+}));
+/**
+ * The envelope schema. **Loose on purpose**: unknown top-level keys
+ * survive `.parse`, matching `parsePageData` — a writer that records metadata
+ * must not have it stripped by whichever reader runs first.
+ */
+export const PageDataSchema = z.looseObject({
+    version: z.literal(1),
+    surface: z
+        .string()
+        .regex(SURFACE_KEY_PATTERN, "surface keys are lowercase, start alphanumeric, and use kebab/dot/colon/underscore"),
+    sections: z.array(ComponentInstanceSchema),
+});

package/dist/settings.d.ts

@@ -0,0 +1,15 @@
+import type { ResolutionScope, ThemeDefinition, ThemeSettingsIssue, ThemeSettingsResult } from "./types.js";
+/**
+ * The effective settings for rendering: every declared setting, from the
+ * store's value when the declaration accepts it, else from the theme's
+ * default. `stored` is the persisted object as it arrived (anything else —
+ * null, an array — reads as no values and is reported). Translated text uses
+ * `scope.locales`; text settings may default from `scope.content`.
+ */
+export declare function resolveThemeSettings(theme: ThemeDefinition, stored: unknown, scope?: ResolutionScope): ThemeSettingsResult;
+/**
+ * What a writer must check before saving a store's settings for a theme:
+ * every key declared, every value accepted by its setting — in every language
+ * for a translated one. An empty list means the values may be saved.
+ */
+export declare function checkThemeSettings(theme: ThemeDefinition, values: unknown): ThemeSettingsIssue[];

package/dist/settings.js

@@ -0,0 +1,80 @@
+/**
+ * A store's theme settings: the merchant's values for the settings a theme
+ * declares (`ThemeDefinition.settings`), read against that declaration.
+ *
+ * Values are stored flat by setting key, for one theme (a value is only
+ * meaningful against the theme that declared it). Reading never fails: a
+ * value the declaration does not accept — a setting since removed, a color
+ * that is not a color, an option no longer offered — is reported and the
+ * setting falls back to the theme's default, exactly as a page document's
+ * field does. Precedence: the merchant's value → the theme's default (or its
+ * content pack, for text) → absent.
+ */
+import { checkStoredValue, ownValue, resolveField } from "./instances.js";
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+function declaredSettings(theme) {
+    const fields = new Map();
+    for (const group of theme.settings ?? [])
+        for (const field of group.fields)
+            if (!fields.has(field.key))
+                fields.set(field.key, field);
+    return fields;
+}
+const PAGE_TO_SETTINGS = {
+    "invalid-prop": "invalid-setting",
+    "missing-required-prop": "missing-required-setting",
+};
+/**
+ * The effective settings for rendering: every declared setting, from the
+ * store's value when the declaration accepts it, else from the theme's
+ * default. `stored` is the persisted object as it arrived (anything else —
+ * null, an array — reads as no values and is reported). Translated text uses
+ * `scope.locales`; text settings may default from `scope.content`.
+ */
+export function resolveThemeSettings(theme, stored, scope = {}) {
+    const issues = [];
+    const declared = declaredSettings(theme);
+    let values = {};
+    if (stored !== undefined && stored !== null && !isRecord(stored)) {
+        issues.push({ path: "settings", code: "invalid-settings", message: "stored settings must be an object; the theme's defaults apply" });
+    }
+    else if (isRecord(stored)) {
+        values = stored;
+    }
+    for (const key of Object.keys(values)) {
+        if (!declared.has(key))
+            issues.push({ path: `settings.${key}`, code: "unknown-setting", message: `"${key}" is not a setting of "${theme.key}"; ignored` });
+    }
+    const resolved = {};
+    const fieldIssues = [];
+    for (const [key, field] of declared) {
+        const value = resolveField(field, ownValue(values, key), scope.content ?? {}, scope.locales ?? [], fieldIssues, "settings");
+        if (value !== undefined)
+            resolved[key] = value;
+    }
+    for (const issue of fieldIssues)
+        issues.push({ path: issue.path, code: PAGE_TO_SETTINGS[issue.code] ?? "invalid-setting", message: issue.message });
+    return { values: resolved, issues };
+}
+/**
+ * What a writer must check before saving a store's settings for a theme:
+ * every key declared, every value accepted by its setting — in every language
+ * for a translated one. An empty list means the values may be saved.
+ */
+export function checkThemeSettings(theme, values) {
+    if (!isRecord(values))
+        return [{ path: "settings", code: "invalid-settings", message: "settings must be an object" }];
+    const declared = declaredSettings(theme);
+    const issues = [];
+    for (const [key, value] of Object.entries(values)) {
+        const field = declared.get(key);
+        if (field === undefined) {
+            issues.push({ path: `settings.${key}`, code: "unknown-setting", message: `"${key}" is not a setting of "${theme.key}"` });
+            continue;
+        }
+        const checked = checkStoredValue(field, value);
+        if (!checked.ok)
+            issues.push({ path: `settings.${key}`, code: "invalid-setting", message: `"${key}" ${checked.message}` });
+    }
+    return issues;
+}