@wocart/theme 0.0.0-stage → 1.0.0

package/dist/definitions.js

@@ -0,0 +1,363 @@
+/**
+ * The code-owned side: identity helpers (inference-only) and the
+ * assembly-time validator. Definitions are typechecked code, not persisted
+ * data — the validator exists so a theme's test suite fails loudly on catalog
+ * bugs when the catalog is assembled.
+ */
+import { SURFACE_KEY_PATTERN, THEME_KEY_PATTERN, TYPE_KEY_PATTERN, isLocaleMap, isLocaleTag, isSafeLinkTarget, } from "./schemas.js";
+/** Identity helper: returns the definition unchanged so literal types survive. */
+export function defineComponent(definition) {
+    return definition;
+}
+/** Identity helper for the catalog. */
+export function defineTheme(definition) {
+    return definition;
+}
+function addIssue(issues, path, code, message) {
+    issues.push({ path, code, message });
+}
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+/**
+ * Why `value` is not valid translatable text, or `null` when it is: one
+ * string, or a map from language tags to strings that covers every language
+ * the theme declares. Labels must not be empty; defaults may be.
+ */
+function localizedTextProblem(value, locales, { allowEmpty }) {
+    if (typeof value === "string") {
+        return value.length > 0 || allowEmpty ? null : "must be a non-empty string";
+    }
+    if (!isLocaleMap(value)) {
+        return "must be a string or a map from language tags (ar, fr, ar-DZ) to strings";
+    }
+    if (!allowEmpty) {
+        const empty = Object.keys(value).filter((locale) => value[locale] === "");
+        if (empty.length > 0)
+            return `has an empty translation for ${empty.join(", ")}`;
+    }
+    const missing = locales.filter((locale) => !Object.hasOwn(value, locale));
+    return missing.length > 0 ? `is missing the theme's languages: ${missing.join(", ")}` : null;
+}
+/** The theme's declared languages, reporting malformed or repeated tags. */
+function inspectLocales(locales, issues) {
+    if (locales === undefined)
+        return [];
+    if (!Array.isArray(locales)) {
+        addIssue(issues, "locales", "invalid-theme", "`locales` must be an array of language tags");
+        return [];
+    }
+    const valid = [];
+    locales.forEach((locale, index) => {
+        if (typeof locale !== "string" || !isLocaleTag(locale)) {
+            addIssue(issues, `locales[${index}]`, "invalid-theme", `${JSON.stringify(locale)} is not a BCP 47 language tag in canonical case (ar, fr, ar-DZ)`);
+        }
+        else if (valid.includes(locale)) {
+            addIssue(issues, `locales[${index}]`, "invalid-theme", `duplicate language "${locale}"`);
+        }
+        else {
+            valid.push(locale);
+        }
+    });
+    return valid;
+}
+/** Check the whole catalog: key/type identity, field rules, slot rules. */
+export function validateThemeDefinition(theme, options = {}) {
+    const issues = [];
+    const contentKeys = options.contentKeys === undefined ? undefined : new Set(options.contentKeys);
+    if (!isRecord(theme)) {
+        addIssue(issues, "", "invalid-theme", "theme must be an object");
+        return issues;
+    }
+    if (typeof theme.key !== "string" || !THEME_KEY_PATTERN.test(theme.key)) {
+        addIssue(issues, "key", "invalid-theme", "`key` must be lowercase kebab-case, at most 64 characters");
+    }
+    if (typeof theme.version !== "string" || theme.version.length === 0) {
+        addIssue(issues, "version", "invalid-theme", "`version` must be a non-empty string");
+    }
+    if (!isRecord(theme.components)) {
+        addIssue(issues, "components", "invalid-theme", "`components` must be a record of component definitions");
+        return issues;
+    }
+    const locales = inspectLocales(theme.locales, issues);
+    // Surfaces are optional theme-level metadata for the serializable manifest
+    // (`themeManifest`). Absent means "declares none"; present entries are
+    // checked so a typo fails loudly at assembly time. Never consulted by page
+    // data parsing or resolution.
+    if (theme.surfaces !== undefined) {
+        if (!Array.isArray(theme.surfaces)) {
+            addIssue(issues, "surfaces", "invalid-theme", "`surfaces` must be an array of surface declarations");
+        }
+        else {
+            inspectSurfaces(theme.surfaces, issues, locales);
+        }
+    }
+    const rules = {
+        contentKeys,
+        catalogKeys: new Set(Object.keys(theme.components)),
+        locales,
+    };
+    for (const [key, definition] of Object.entries(theme.components)) {
+        const path = `components.${key}`;
+        if (!TYPE_KEY_PATTERN.test(key)) {
+            addIssue(issues, path, "invalid-type", `catalog key "${key}" is not lowercase kebab-case`);
+        }
+        inspectDefinition(definition, path, issues, rules);
+        if (isRecord(definition) &&
+            typeof definition.type === "string" &&
+            definition.type !== key) {
+            addIssue(issues, `${path}.type`, "type-mismatch", `definition type "${definition.type}" must equal its catalog key "${key}"`);
+        }
+    }
+    return issues;
+}
+function inspectSurfaces(surfaces, issues, locales) {
+    const seenKeys = new Set();
+    surfaces.forEach((surface, index) => {
+        const surfacePath = `surfaces[${index}]`;
+        if (!isRecord(surface)) {
+            addIssue(issues, surfacePath, "invalid-theme", "surface must be an object");
+            return;
+        }
+        if (typeof surface.key !== "string" ||
+            !SURFACE_KEY_PATTERN.test(surface.key)) {
+            addIssue(issues, `${surfacePath}.key`, "invalid-theme", "`key` must be a surface key (lowercase, starting alphanumeric, kebab/dot/colon/underscore)");
+        }
+        else if (seenKeys.has(surface.key)) {
+            addIssue(issues, `${surfacePath}.key`, "invalid-theme", `duplicate surface key "${surface.key}"`);
+        }
+        else {
+            seenKeys.add(surface.key);
+        }
+        const labelProblem = localizedTextProblem(surface.label, locales, { allowEmpty: false });
+        if (labelProblem !== null) {
+            addIssue(issues, `${surfacePath}.label`, "invalid-theme", `\`label\` ${labelProblem}`);
+        }
+    });
+}
+function inspectDefinition(definition, path, issues, rules) {
+    if (!isRecord(definition)) {
+        addIssue(issues, path, "invalid-definition", "component definition must be an object");
+        return;
+    }
+    if (typeof definition.type !== "string" || !TYPE_KEY_PATTERN.test(definition.type)) {
+        addIssue(issues, `${path}.type`, "invalid-type", "`type` must be a lowercase kebab-case string");
+    }
+    if (definition.component === undefined) {
+        addIssue(issues, `${path}.component`, "invalid-definition", "`component` must be the real component reference");
+    }
+    else if (definition.component !== null &&
+        typeof definition.component !== "object" &&
+        typeof definition.component !== "function") {
+        // `null` is allowed through: the renderer degrades it to a reported
+        // `missing-component`, same as a missing reference. A primitive (usually a
+        // string left behind instead of an import) would reach `<Component>` and
+        // fail at render time, so it fails loudly here instead. The core stays
+        // framework-neutral — it checks reference shape, never Astro internals.
+        addIssue(issues, `${path}.component`, "invalid-definition", "`component` must be the real component reference (an object or function), not a placeholder value");
+    }
+    const labelProblem = localizedTextProblem(definition.label, rules.locales, { allowEmpty: false });
+    if (labelProblem !== null) {
+        addIssue(issues, `${path}.label`, "invalid-definition", `\`label\` ${labelProblem}`);
+    }
+    if (definition.group !== undefined) {
+        const problem = localizedTextProblem(definition.group, rules.locales, { allowEmpty: false });
+        if (problem !== null) {
+            addIssue(issues, `${path}.group`, "invalid-definition", `\`group\` ${problem}`);
+        }
+    }
+    if (definition.load !== undefined && typeof definition.load !== "function") {
+        addIssue(issues, `${path}.load`, "invalid-load", "`load` must be a function");
+    }
+    if (definition.capabilities !== undefined) {
+        if (!isRecord(definition.capabilities)) {
+            addIssue(issues, `${path}.capabilities`, "invalid-capability", "`capabilities` must be an object");
+        }
+        else if (definition.capabilities.insertable !== undefined &&
+            typeof definition.capabilities.insertable !== "boolean") {
+            addIssue(issues, `${path}.capabilities.insertable`, "invalid-capability", "`insertable` must be a boolean");
+        }
+    }
+    if (definition.fields !== undefined) {
+        if (!Array.isArray(definition.fields)) {
+            addIssue(issues, `${path}.fields`, "invalid-field", "`fields` must be an array");
+        }
+        else {
+            inspectFields(definition.fields, path, issues, rules);
+        }
+    }
+    if (definition.slots !== undefined) {
+        if (!Array.isArray(definition.slots)) {
+            addIssue(issues, `${path}.slots`, "invalid-slot", "`slots` must be an array");
+        }
+        else {
+            inspectSlots(definition.slots, path, issues, rules.catalogKeys);
+        }
+    }
+}
+function inspectFields(fields, path, issues, rules) {
+    const { contentKeys, locales } = rules;
+    const seenKeys = new Set();
+    fields.forEach((field, index) => {
+        const fieldPath = `${path}.fields[${index}]`;
+        if (!isRecord(field)) {
+            addIssue(issues, fieldPath, "invalid-field", "field must be an object");
+            return;
+        }
+        if (typeof field.key !== "string" || field.key.length === 0) {
+            addIssue(issues, `${fieldPath}.key`, "invalid-field", "`key` must be a non-empty string");
+        }
+        else if (field.key === "__proto__") {
+            addIssue(issues, `${fieldPath}.key`, "invalid-field", "`__proto__` cannot be a field key: as a prop name it would set a prototype");
+        }
+        else if (seenKeys.has(field.key)) {
+            addIssue(issues, `${fieldPath}.key`, "duplicate-field-key", `duplicate field key "${field.key}"`);
+        }
+        else {
+            seenKeys.add(field.key);
+        }
+        const labelProblem = localizedTextProblem(field.label, locales, { allowEmpty: false });
+        if (labelProblem !== null) {
+            addIssue(issues, `${fieldPath}.label`, "invalid-field", `\`label\` ${labelProblem}`);
+        }
+        if (field.description !== undefined) {
+            const problem = localizedTextProblem(field.description, locales, { allowEmpty: false });
+            if (problem !== null) {
+                addIssue(issues, `${fieldPath}.description`, "invalid-field", `\`description\` ${problem}`);
+            }
+        }
+        if (field.required !== undefined && typeof field.required !== "boolean") {
+            addIssue(issues, `${fieldPath}.required`, "invalid-field", "`required` must be a boolean");
+        }
+        switch (field.kind) {
+            case "text":
+            case "textarea": {
+                const hasContentKey = field.contentKey !== undefined;
+                const hasDefault = field.default !== undefined;
+                if (hasContentKey && typeof field.contentKey !== "string") {
+                    addIssue(issues, `${fieldPath}.contentKey`, "invalid-field", "`contentKey` must be a string");
+                }
+                if (hasDefault) {
+                    const problem = localizedTextProblem(field.default, locales, { allowEmpty: true });
+                    if (problem !== null) {
+                        addIssue(issues, `${fieldPath}.default`, "invalid-field", `\`default\` ${problem}`);
+                    }
+                }
+                if (hasContentKey && hasDefault) {
+                    addIssue(issues, fieldPath, "invalid-field", "`contentKey` and `default` are mutually exclusive");
+                }
+                // Opt-in only: with no `contentKeys` supplied the validator behaves
+                // exactly as it did before this check existed.
+                if (contentKeys !== undefined &&
+                    typeof field.contentKey === "string" &&
+                    !contentKeys.has(field.contentKey)) {
+                    addIssue(issues, `${fieldPath}.contentKey`, "unknown-content-key", `"${field.contentKey}" is not a key of the supplied content pack`);
+                }
+                break;
+            }
+            case "number": {
+                for (const bound of ["default", "min", "max"]) {
+                    const value = field[bound];
+                    if (value !== undefined && (typeof value !== "number" || !Number.isFinite(value))) {
+                        addIssue(issues, `${fieldPath}.${bound}`, "invalid-field", `\`${bound}\` must be a finite number`);
+                    }
+                }
+                if (typeof field.min === "number" &&
+                    typeof field.max === "number" &&
+                    field.min > field.max) {
+                    addIssue(issues, fieldPath, "invalid-field", "`min` must be <= `max`");
+                }
+                // A default outside the declared bounds would sail through assembly
+                // and then behave incoherently at runtime (`resolveInstance` trusts
+                // authored defaults while rejecting the same out-of-range instance
+                // value). Catch the typo where it is authored, in the resolver's own
+                // vocabulary.
+                if (typeof field.default === "number" && Number.isFinite(field.default)) {
+                    if (typeof field.min === "number" && field.default < field.min) {
+                        addIssue(issues, `${fieldPath}.default`, "invalid-field", `\`default\` must be >= ${field.min}`);
+                    }
+                    if (typeof field.max === "number" && field.default > field.max) {
+                        addIssue(issues, `${fieldPath}.default`, "invalid-field", `\`default\` must be <= ${field.max}`);
+                    }
+                }
+                break;
+            }
+            case "boolean": {
+                if (field.default !== undefined && typeof field.default !== "boolean") {
+                    addIssue(issues, `${fieldPath}.default`, "invalid-field", "`default` must be a boolean");
+                }
+                break;
+            }
+            case "select": {
+                const options = field.options;
+                if (!Array.isArray(options) ||
+                    options.length === 0 ||
+                    !options.every((option) => typeof option === "string")) {
+                    addIssue(issues, `${fieldPath}.options`, "invalid-field", "`options` must be a non-empty array of strings");
+                }
+                else if (field.default !== undefined &&
+                    (typeof field.default !== "string" || !options.includes(field.default))) {
+                    addIssue(issues, `${fieldPath}.default`, "invalid-field", "`default` must be one of `options`");
+                }
+                break;
+            }
+            case "url": {
+                if (field.default !== undefined &&
+                    (typeof field.default !== "string" || !isSafeLinkTarget(field.default))) {
+                    addIssue(issues, `${fieldPath}.default`, "invalid-field", "`default` must be a site path, #fragment, ?query, or an http(s), mailto or tel URL");
+                }
+                break;
+            }
+            default:
+                addIssue(issues, `${fieldPath}.kind`, "invalid-field", `unknown field kind ${JSON.stringify(field.kind)}`);
+        }
+    });
+}
+function inspectSlots(slots, path, issues, catalogKeys) {
+    const seenNames = new Set();
+    slots.forEach((slot, index) => {
+        const slotPath = `${path}.slots[${index}]`;
+        if (!isRecord(slot)) {
+            addIssue(issues, slotPath, "invalid-slot", "slot must be an object");
+            return;
+        }
+        const name = slot.name;
+        if (typeof name !== "string" || name.length === 0) {
+            addIssue(issues, `${slotPath}.name`, "invalid-slot", "`name` must be a non-empty string");
+        }
+        else {
+            if (name !== "default" && !TYPE_KEY_PATTERN.test(name)) {
+                addIssue(issues, `${slotPath}.name`, "invalid-slot", `slot name "${name}" must be lowercase kebab-case (or "default")`);
+            }
+            if (seenNames.has(name)) {
+                addIssue(issues, `${slotPath}.name`, "duplicate-slot", `duplicate slot name "${name}"`);
+            }
+            else {
+                seenNames.add(name);
+            }
+        }
+        if (slot.multiple !== undefined && typeof slot.multiple !== "boolean") {
+            addIssue(issues, `${slotPath}.multiple`, "invalid-slot", "`multiple` must be a boolean");
+        }
+        if (slot.allow !== undefined) {
+            inspectAllow(slot.allow, `${slotPath}.allow`, issues, catalogKeys);
+        }
+    });
+}
+function inspectAllow(allow, path, issues, catalogKeys) {
+    if (!Array.isArray(allow) || allow.length === 0) {
+        addIssue(issues, path, "invalid-slot", "`allow` must be a non-empty array of component types (omit it to accept any type)");
+        return;
+    }
+    const seen = new Set();
+    allow.forEach((type, index) => {
+        const typePath = `${path}[${index}]`;
+        if (typeof type !== "string" || !catalogKeys.has(type)) {
+            addIssue(issues, typePath, "invalid-slot", `${JSON.stringify(type)} is not a component type in this catalog`);
+        }
+        else if (seen.has(type)) {
+            addIssue(issues, typePath, "invalid-slot", `duplicate allowed type "${type}"`);
+        }
+        else {
+            seen.add(type);
+        }
+    });
+}

package/dist/index.d.ts

@@ -0,0 +1,19 @@
+/**
+ * `@wocart/theme` — the theme contract.
+ *
+ * Code-owned: `defineComponent` / `defineTheme` / `validateThemeDefinition`.
+ * Data-owned: `parsePageData` / `validatePageData` / `resolveInstance` /
+ * `createInstance` (+ schemas).
+ * Serializable: `themeManifest` / `validateThemeManifest`.
+ *
+ * This entry is framework-neutral. The reference Astro renderer lives in the
+ * `./astro` subpath.
+ */
+export { defineComponent, defineTheme, validateThemeDefinition } from "./definitions.js";
+export { parsePageData, validatePageData } from "./page-data.js";
+export { resolveInstance, createInstance } from "./instances.js";
+export { localize } from "./locales.js";
+export { PLURAL_CATEGORIES, formatMessage, messageForms, pluralFormIssues } from "./messages.js";
+export type { MessageOptions, MessageValues, PluralCategory } from "./messages.js";
+export { THEME_MANIFEST_CONTRACT_VERSION, themeManifest, validateThemeManifest, } from "./manifest.js";
+export type { JsonValue, JsonObject, LocaleCode, LocalizedText, ResolutionScope, FieldKind, FieldDefinition, FieldValue, InferProps, SlotDefinition, ComponentCapabilities, ComponentDefinition, ComponentSpec, SurfaceSpec, ThemeDefinition, ThemeManifest, ThemeManifestIssue, ThemeManifestIssueCode, ThemeManifestResult, ComponentInstance, PageData, ThemeRenderContext, LoadContext, LoadFn, ReadCache, PageDataIssue, PageDataIssueCode, PageDataResult, ResolvedInstance, ThemeDefinitionIssue, ThemeDefinitionIssueCode, ThemeValidationOptions, } from "./types.js";

package/dist/index.js

@@ -0,0 +1,17 @@
+/**
+ * `@wocart/theme` — the theme contract.
+ *
+ * Code-owned: `defineComponent` / `defineTheme` / `validateThemeDefinition`.
+ * Data-owned: `parsePageData` / `validatePageData` / `resolveInstance` /
+ * `createInstance` (+ schemas).
+ * Serializable: `themeManifest` / `validateThemeManifest`.
+ *
+ * This entry is framework-neutral. The reference Astro renderer lives in the
+ * `./astro` subpath.
+ */
+export { defineComponent, defineTheme, validateThemeDefinition } from "./definitions.js";
+export { parsePageData, validatePageData } from "./page-data.js";
+export { resolveInstance, createInstance } from "./instances.js";
+export { localize } from "./locales.js";
+export { PLURAL_CATEGORIES, formatMessage, messageForms, pluralFormIssues } from "./messages.js";
+export { THEME_MANIFEST_CONTRACT_VERSION, themeManifest, validateThemeManifest, } from "./manifest.js";

package/dist/instances.d.ts

@@ -0,0 +1,22 @@
+import type { ComponentDefinition, ComponentInstance, JsonObject, ResolutionScope, ResolvedInstance } from "./types.js";
+/**
+ * Gate one instance for rendering: field values through the chain, children
+ * and named slots gated against the declared slots, every degradation
+ * reported. The instance (and page data) is never modified.
+ */
+export declare function resolveInstance(definition: ComponentDefinition, instance: ComponentInstance, scope?: ResolutionScope): ResolvedInstance;
+/**
+ * Create a new instance with insertion-time defaults:
+ * materialises `field.default` values only — content-keyed fields stay unset
+ * until a merchant overrides them. Throws on programmer errors (empty id,
+ * unknown keys, wrong-typed values, a required field with nothing to fill
+ * it); the storefront never calls this. A required field with a `contentKey`
+ * is filled from the content pack at render, so it may be left unset here.
+ *
+ * Authored defaults are validated exactly like provided values: a default that
+ * fails its field's rules (out-of-range number, off-list select option) is an
+ * authoring bug, and `validateThemeDefinition` reports it at assembly time —
+ * baking it into an instance silently here would let the writer and the reader
+ * disagree.
+ */
+export declare function createInstance(definition: ComponentDefinition, id: string, props?: JsonObject): ComponentInstance;