@wocart/theme 1.5.0 → 2.0.0

package/dist/style.js

@@ -0,0 +1,248 @@
+/**
+ * Style: how a section or block sits on the page and which colors it wears,
+ * stored as steps and choices — never CSS — and turned into CSS by the SDK.
+ *
+ * - A `style` value holds the platform's step names (`s0`…`s12`) and closed
+ *   choices per breakpoint; `styleClasses` gives its classes, and
+ *   `themeStyleSheet` makes the one stylesheet those classes come from, out of
+ *   the sizes the theme gives the steps. A value can therefore never carry a
+ *   property, a selector or a size the theme did not declare.
+ * - Colors come from the store's color schemes; `colorSchemeCss` writes them
+ *   as custom properties on `.wc-scheme-<id>`, dropping anything that is not
+ *   a scheme id and a hex color.
+ */
+import { COLOR_PATTERN, isLocaleMap } from "./schemas.js";
+/** The platform's breakpoints, phone first, with the width each starts at. */
+export const STYLE_BREAKPOINTS = [
+    ["base", 0],
+    ["md", 768],
+    ["lg", 1024],
+];
+export const STYLE_STEPS = ["s0", "s1", "s2", "s3", "s4", "s5", "s6", "s7", "s8", "s9", "s10", "s11", "s12"];
+export const STYLE_WIDTHS = ["wide", "content", "narrow"];
+export const STYLE_PANELS = ["spacing", "layout", "size"];
+export const COLOR_ROLES = ["background", "text", "heading", "accent", "button", "buttonText", "border"];
+/** A color scheme's id: what a `colorScheme` value names. */
+export const COLOR_SCHEME_ID_PATTERN = /^[a-z0-9][a-z0-9-]{0,31}$/;
+/** The most color schemes a store keeps. */
+export const COLOR_SCHEMES_MAX = 24;
+/** Where a built theme serves the stylesheet of its style classes (`themeStylesEndpoint`). */
+export const THEME_STYLES_PATH = "/wocart-styles.css";
+const px = (size) => (size === undefined ? null : `${size}px`);
+const step = (property) => (value, style) => {
+    const size = px(style.spacing?.[value]);
+    return size === null ? null : `${property}:${size}`;
+};
+const choice = (property, map) => (value) => `${property}:${map[String(value)]}`;
+const PROPERTIES = {
+    spacing: {
+        paddingBlockStart: { prefix: "pbs", values: STYLE_STEPS, css: step("padding-block-start") },
+        paddingBlockEnd: { prefix: "pbe", values: STYLE_STEPS, css: step("padding-block-end") },
+        paddingInline: { prefix: "pi", values: STYLE_STEPS, css: step("padding-inline") },
+        marginBlockStart: { prefix: "mbs", values: STYLE_STEPS, css: step("margin-block-start") },
+        marginBlockEnd: { prefix: "mbe", values: STYLE_STEPS, css: step("margin-block-end") },
+        gap: { prefix: "gap", values: STYLE_STEPS, css: step("gap") },
+    },
+    layout: {
+        direction: { prefix: "dir", values: ["row", "column"], css: choice("flex-direction", { row: "row", column: "column" }) },
+        align: {
+            prefix: "items",
+            values: ["start", "center", "end", "stretch"],
+            css: choice("align-items", { start: "flex-start", center: "center", end: "flex-end", stretch: "stretch" }),
+        },
+        justify: {
+            prefix: "justify",
+            values: ["start", "center", "end", "between"],
+            css: choice("justify-content", { start: "flex-start", center: "center", end: "flex-end", between: "space-between" }),
+        },
+        wrap: { prefix: "wrap", values: [true, false], css: choice("flex-wrap", { true: "wrap", false: "nowrap" }) },
+    },
+    size: {
+        width: {
+            prefix: "w",
+            values: ["full", ...STYLE_WIDTHS],
+            css: (value, style) => {
+                if (value === "full")
+                    return "width:100%;max-width:none";
+                const size = px(style.widths?.[value]);
+                return size === null ? null : `width:100%;max-width:${size};margin-inline:auto`;
+            },
+        },
+        minHeight: { prefix: "mh", values: STYLE_STEPS, css: step("min-height") },
+    },
+};
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const token = (value) => (value === true ? "on" : value === false ? "off" : value);
+const className = (breakpoint, prefix, value) => `wc-${breakpoint === "base" ? "" : `${breakpoint}-`}${prefix}-${token(value)}`;
+/** Why `value` is not a style value a field offering `panels` may hold, or `null`. */
+export function styleValueProblem(panels, value) {
+    if (!isRecord(value))
+        return "must be a style value: { spacing?, layout?, size? }";
+    for (const [panel, properties] of Object.entries(value)) {
+        if (!STYLE_PANELS.includes(panel) || !panels.includes(panel)) {
+            return `"${panel}" is not a panel this field offers (${panels.join(", ")})`;
+        }
+        if (!isRecord(properties))
+            return `\`${panel}\` must be an object of properties`;
+        const known = PROPERTIES[panel];
+        for (const [name, responsive] of Object.entries(properties)) {
+            const property = Object.hasOwn(known, name) ? known[name] : undefined;
+            if (property === undefined)
+                return `"${name}" is not a ${panel} property`;
+            if (!isRecord(responsive) || !Object.hasOwn(responsive, "base"))
+                return `\`${panel}.${name}\` must be { base, md?, lg? }`;
+            for (const [breakpoint, choice] of Object.entries(responsive)) {
+                if (!STYLE_BREAKPOINTS.some(([name]) => name === breakpoint))
+                    return `"${breakpoint}" is not a breakpoint (base, md, lg)`;
+                if (!property.values.includes(choice))
+                    return `\`${panel}.${name}.${breakpoint}\` must be one of ${property.values.join(", ")}`;
+            }
+        }
+    }
+    return null;
+}
+/**
+ * Why a theme's sizes leave part of a style value without a style: a step or
+ * width the theme does not size. What a writer stores must be sized; a
+ * reader renders an unsized value as no style.
+ */
+export function styleSizeProblem(style, value) {
+    for (const [panel, properties] of Object.entries(value)) {
+        for (const [name, responsive] of Object.entries(properties ?? {})) {
+            const property = PROPERTIES[panel]?.[name];
+            if (property === undefined)
+                continue;
+            for (const choice of Object.values(responsive)) {
+                if (property.css(choice, style ?? {}) === null)
+                    return `"${String(choice)}" is not a size this theme gives (${panel}.${name})`;
+            }
+        }
+    }
+    return null;
+}
+/** The classes that give an element its style value, from the theme's stylesheet (`themeStyleSheet`). */
+export function styleClasses(value) {
+    if (!isRecord(value))
+        return "";
+    const classes = [];
+    for (const panel of STYLE_PANELS) {
+        const properties = value[panel];
+        if (!isRecord(properties))
+            continue;
+        let used = false;
+        for (const [name, property] of Object.entries(PROPERTIES[panel])) {
+            const responsive = properties[name];
+            if (!isRecord(responsive) || !Object.hasOwn(responsive, "base"))
+                continue;
+            for (const [breakpoint] of STYLE_BREAKPOINTS) {
+                const choice = responsive[breakpoint];
+                if (choice === undefined || !property.values.includes(choice))
+                    continue;
+                classes.push(className(breakpoint, property.prefix, choice));
+                used = true;
+            }
+        }
+        if (panel === "layout" && used)
+            classes.unshift("wc-flex");
+    }
+    return classes.join(" ");
+}
+/**
+ * Every class a theme's sizes allow, phone first: the base rules, then each
+ * wider breakpoint in its media query. A step or width the theme does not
+ * size has no class.
+ */
+export function themeStyleSheet(style) {
+    const sizes = style ?? {};
+    const rules = (breakpoint) => {
+        const out = breakpoint === "base" ? [".wc-flex{display:flex}"] : [];
+        for (const panel of STYLE_PANELS) {
+            for (const property of Object.values(PROPERTIES[panel])) {
+                for (const value of property.values) {
+                    const css = property.css(value, sizes);
+                    if (css !== null)
+                        out.push(`.${className(breakpoint, property.prefix, value)}{${css}}`);
+                }
+            }
+        }
+        return out.join("");
+    };
+    return STYLE_BREAKPOINTS.map(([breakpoint, from]) => (from === 0 ? rules(breakpoint) : `@media (min-width:${from}px){${rules(breakpoint)}}`)).join("");
+}
+/** Why `value` is not a list of color schemes, or `null`. */
+export function colorSchemesProblem(value) {
+    if (!Array.isArray(value) || value.length === 0)
+        return "must be a non-empty list of color schemes";
+    if (value.length > COLOR_SCHEMES_MAX)
+        return `holds at most ${COLOR_SCHEMES_MAX} color schemes`;
+    const ids = new Set();
+    for (const [index, scheme] of value.entries()) {
+        if (!isRecord(scheme))
+            return `scheme ${index} must be { id, name, colors }`;
+        const extra = Object.keys(scheme).find((key) => key !== "id" && key !== "name" && key !== "colors");
+        if (extra !== undefined)
+            return `scheme ${index} has an unknown key "${extra}"`;
+        if (typeof scheme.id !== "string" || !COLOR_SCHEME_ID_PATTERN.test(scheme.id))
+            return `scheme ${index} needs an \`id\` of lowercase letters, digits and dashes`;
+        if (ids.has(scheme.id))
+            return `scheme ${index} repeats the id "${scheme.id}"`;
+        ids.add(scheme.id);
+        const name = scheme.name;
+        if (!((typeof name === "string" && name.length > 0) || isLocaleMap(name)))
+            return `scheme "${scheme.id}" needs a \`name\``;
+        if (!isRecord(scheme.colors))
+            return `scheme "${scheme.id}" needs \`colors\``;
+        for (const role of COLOR_ROLES) {
+            const color = scheme.colors[role];
+            if (typeof color !== "string" || !COLOR_PATTERN.test(color))
+                return `scheme "${scheme.id}" needs a hex color for "${role}"`;
+        }
+        const unknown = Object.keys(scheme.colors).find((role) => !COLOR_ROLES.includes(role));
+        if (unknown !== undefined)
+            return `scheme "${scheme.id}" has an unknown role "${unknown}"`;
+    }
+    return null;
+}
+/** The class that gives an element a color scheme, or `""` for what is not a scheme id. */
+export function schemeClass(id) {
+    return typeof id === "string" && COLOR_SCHEME_ID_PATTERN.test(id) ? `wc-scheme-${id}` : "";
+}
+const roleProperty = (role) => `--wc-color-${role.replace(/[A-Z]/g, (letter) => `-${letter.toLowerCase()}`)}`;
+/**
+ * The store's color schemes as CSS: each scheme's roles as custom properties
+ * (`--wc-color-background`, `--wc-color-button-text`, …) with its background
+ * and text applied, on `.wc-scheme-<id>`. A scheme with a malformed id or
+ * color is left out whole.
+ */
+export function colorSchemeCss(schemes) {
+    return (schemes ?? [])
+        .filter((scheme) => isRecord(scheme) &&
+        typeof scheme.id === "string" &&
+        COLOR_SCHEME_ID_PATTERN.test(scheme.id) &&
+        isRecord(scheme.colors) &&
+        COLOR_ROLES.every((role) => typeof scheme.colors[role] === "string" && COLOR_PATTERN.test(scheme.colors[role])))
+        .map((scheme) => {
+        const roles = COLOR_ROLES.map((role) => `${roleProperty(role)}:${scheme.colors[role]}`).join(";");
+        return `.wc-scheme-${scheme.id}{${roles};background-color:var(--wc-color-background);color:var(--wc-color-text)}`;
+    })
+        .join("");
+}
+const channel = (value) => {
+    const unit = value / 255;
+    return unit <= 0.03928 ? unit / 12.92 : ((unit + 0.055) / 1.055) ** 2.4;
+};
+function luminance(hex) {
+    const digits = hex.length === 4 ? [...hex.slice(1)].map((digit) => digit + digit).join("") : hex.slice(1);
+    const [r, g, b] = [0, 2, 4].map((at) => parseInt(digits.slice(at, at + 2), 16));
+    return 0.2126 * channel(r) + 0.7152 * channel(g) + 0.0722 * channel(b);
+}
+/**
+ * The WCAG contrast ratio of two hex colors, from 1 to 21. Text needs 4.5 to
+ * meet AA; an editor warns below it. `NaN` for what is not a hex color.
+ */
+export function contrastRatio(a, b) {
+    if (!COLOR_PATTERN.test(a) || !COLOR_PATTERN.test(b))
+        return Number.NaN;
+    const [light, dark] = [luminance(a), luminance(b)].sort((x, y) => y - x);
+    return (light + 0.05) / (dark + 0.05);
+}

package/dist/surface-document.d.ts

@@ -0,0 +1,49 @@
+import type { ComponentInstance, PageData, PageDataIssue, ResolutionScope, ThemeDefinition } from "./types.js";
+/**
+ * The document with everything it must hold: the surface's required sections,
+ * each component's fixed blocks (stored, with an id derived from its owner and
+ * name) and each slot's required blocks — a hidden required or fixed block is
+ * shown again. Added ids are unique in the document. What was added or
+ * corrected is reported.
+ */
+export declare function completePage(theme: ThemeDefinition, page: PageData): {
+    page: PageData;
+    issues: PageDataIssue[];
+};
+/**
+ * An instance tree with its fixed and required blocks, as an editor inserts
+ * it: added ids are unique against `taken`, which receives every id of the
+ * tree. Never changes `instance`.
+ */
+export declare function completeInstance(theme: ThemeDefinition, instance: ComponentInstance, taken: Set<string>): ComponentInstance;
+/** Why the theme's default document rendered instead of the saved one. */
+export type SurfaceDocumentReason = 
+/** The store saved none. */
+"absent"
+/** What was saved is not a page document this SDK reads. */
+ | "invalid"
+/** The saved document is for another surface. */
+ | "other-surface"
+/** The saved document was composed for another theme. */
+ | "other-theme"
+/** None of the saved sections is in this theme's catalog. */
+ | "no-overlap";
+export interface SurfaceDocument {
+    /** The document to render, completed. */
+    page: PageData;
+    source: "saved" | "default";
+    /** `null` when the saved document rendered. */
+    reason: SurfaceDocumentReason | null;
+    /** The saved document's issues, then the default's when it rendered instead. */
+    issues: PageDataIssue[];
+}
+/**
+ * The page a surface or area renders: the saved document when this theme can
+ * render it, else the theme's default (`SurfaceSpec.document` or
+ * `AreaSpec.document`, or an empty page). A saved document that names another theme, or whose sections
+ * this catalog knows none of, renders the default — a theme switch must not
+ * leave an empty page. A deliberately emptied document renders empty. The
+ * result is completed (`completePage`), so required and fixed blocks render
+ * whatever was saved.
+ */
+export declare function resolveSurfaceDocument(theme: ThemeDefinition, surface: string, saved: unknown, scope?: ResolutionScope): SurfaceDocument;

package/dist/surface-document.js

@@ -0,0 +1,162 @@
+/**
+ * From what a store saved to the page that renders, for any surface or area
+ * (an area's document is the surface `area:<key>`):
+ * which document wins (the saved one, or the theme's default), and that
+ * document completed with every fixed and required block. A theme
+ * renders `resolveSurfaceDocument(...).page`; an editor edits
+ * `completePage(...).page`. Both are pure and never change their input.
+ */
+import { THEME_LIMITS, completeRequired, fixedBlockId, shippedDocument, slotCap, surfaceRules } from "./blocks.js";
+import { parsePageData, validatePageData } from "./page-data.js";
+/**
+ * The document with everything it must hold: the surface's required sections,
+ * each component's fixed blocks (stored, with an id derived from its owner and
+ * name) and each slot's required blocks — a hidden required or fixed block is
+ * shown again. Added ids are unique in the document. What was added or
+ * corrected is reported.
+ */
+export function completePage(theme, page) {
+    const next = structuredClone(page);
+    const issues = [];
+    const taken = new Set();
+    const collect = (node) => {
+        taken.add(node.id);
+        for (const child of node.children ?? [])
+            collect(child);
+        for (const list of Object.values(node.slots ?? {}))
+            for (const child of list)
+                collect(child);
+        for (const block of Object.values(node.fixed ?? {}))
+            collect(block);
+    };
+    next.sections.forEach(collect);
+    const spec = surfaceRules(theme, next.surface);
+    next.sections = completeRequired(next.sections, spec?.required, { id: next.surface, slot: "sections" }, "sections", issues, taken);
+    next.sections.forEach((section, index) => completeTree(theme, section, `sections[${index}]`, issues, taken, 0));
+    return { page: next, issues };
+}
+/**
+ * An instance tree with its fixed and required blocks, as an editor inserts
+ * it: added ids are unique against `taken`, which receives every id of the
+ * tree. Never changes `instance`.
+ */
+export function completeInstance(theme, instance, taken) {
+    const next = structuredClone(instance);
+    const collect = (node) => {
+        taken.add(node.id);
+        for (const child of node.children ?? [])
+            collect(child);
+        for (const list of Object.values(node.slots ?? {}))
+            for (const child of list)
+                collect(child);
+        for (const block of Object.values(node.fixed ?? {}))
+            collect(block);
+    };
+    collect(next);
+    completeTree(theme, next, "instance", [], taken, 0);
+    return next;
+}
+function uniqueId(base, taken) {
+    let id = base;
+    for (let n = 2; taken.has(id); n += 1)
+        id = `${base}~${n}`;
+    taken.add(id);
+    return id;
+}
+function completeTree(theme, node, path, issues, taken, depth) {
+    const definition = Object.hasOwn(theme.components, node.type) ? theme.components[node.type] : undefined;
+    if (definition === undefined || depth > THEME_LIMITS.depth)
+        return;
+    const declared = definition.fixed ?? [];
+    const stored = node.fixed ?? {};
+    for (const name of Object.keys(stored)) {
+        if (!declared.some((block) => block.name === name)) {
+            issues.push({ path: `${path}.fixed.${name}`, code: "unknown-fixed", message: `"${node.type}" places no fixed block "${name}"; removed` });
+        }
+    }
+    if (declared.length > 0) {
+        const fixed = {};
+        for (const { name, type } of declared) {
+            const entry = Object.hasOwn(stored, name) ? stored[name] : undefined;
+            if (entry !== undefined && entry.type === type) {
+                delete entry.hidden;
+                fixed[name] = entry;
+                continue;
+            }
+            if (entry !== undefined) {
+                issues.push({ path: `${path}.fixed.${name}.type`, code: "fixed-type-mismatch", message: `the fixed block "${name}" is a "${type}", not a "${entry.type}"; replaced by one with its defaults` });
+            }
+            fixed[name] = { id: uniqueId(fixedBlockId(node.id, name), taken), type };
+        }
+        node.fixed = fixed;
+    }
+    else if (node.fixed !== undefined) {
+        delete node.fixed;
+    }
+    for (const slot of definition.slots ?? []) {
+        if ((slot.required ?? []).length === 0)
+            continue;
+        const before = issues.length;
+        if (slot.name === "default") {
+            const list = [...(node.children ?? []), ...(node.slots?.default ?? [])];
+            const done = completeRequired(list, slot.required, { id: node.id, slot: "default" }, `${path}.children`, issues, taken);
+            if (issues.length === before)
+                continue;
+            node.children = done;
+            if (node.slots?.default !== undefined) {
+                delete node.slots.default;
+                if (Object.keys(node.slots).length === 0)
+                    delete node.slots;
+            }
+        }
+        else {
+            const list = node.slots !== undefined && Object.hasOwn(node.slots, slot.name) ? node.slots[slot.name] : [];
+            const done = completeRequired(list, slot.required, { id: node.id, slot: slot.name }, `${path}.slots.${slot.name}`, issues, taken);
+            if (issues.length === before)
+                continue;
+            node.slots = { ...node.slots, [slot.name]: done };
+        }
+    }
+    (node.children ?? []).forEach((child, index) => completeTree(theme, child, `${path}.children[${index}]`, issues, taken, depth + 1));
+    for (const [name, list] of Object.entries(node.slots ?? {})) {
+        list.forEach((child, index) => completeTree(theme, child, `${path}.slots.${name}[${index}]`, issues, taken, depth + 1));
+    }
+    for (const [name, block] of Object.entries(node.fixed ?? {}))
+        completeTree(theme, block, `${path}.fixed.${name}`, issues, taken, depth + 1);
+}
+/**
+ * The page a surface or area renders: the saved document when this theme can
+ * render it, else the theme's default (`SurfaceSpec.document` or
+ * `AreaSpec.document`, or an empty page). A saved document that names another theme, or whose sections
+ * this catalog knows none of, renders the default — a theme switch must not
+ * leave an empty page. A deliberately emptied document renders empty. The
+ * result is completed (`completePage`), so required and fixed blocks render
+ * whatever was saved.
+ */
+export function resolveSurfaceDocument(theme, surface, saved, scope = {}) {
+    const fallback = (reason, savedIssues) => {
+        const shipped = parsePageData(shippedDocument(theme, surface) ?? { version: 1, surface, sections: [] });
+        const page = shipped.page ?? { version: 1, surface, sections: [] };
+        return { page: completePage(theme, page).page, source: "default", reason, issues: [...savedIssues, ...shipped.issues] };
+    };
+    if (saved === null || saved === undefined)
+        return fallback("absent", []);
+    const checked = validatePageData(theme, saved, scope);
+    if (checked.page === null)
+        return fallback("invalid", checked.issues);
+    if (checked.page.surface !== surface) {
+        return fallback("other-surface", [
+            ...checked.issues,
+            { path: "surface", code: "envelope-invalid", message: `the saved document is for "${checked.page.surface}", not "${surface}"` },
+        ]);
+    }
+    if (checked.page.theme !== undefined && checked.page.theme.key !== theme.key)
+        return fallback("other-theme", checked.issues);
+    const sections = checked.page.sections;
+    if (sections.length > 0 && sections.every((section) => !Object.hasOwn(theme.components, section.type))) {
+        return fallback("no-overlap", checked.issues);
+    }
+    const cap = slotCap(surfaceRules(theme, surface), THEME_LIMITS.sections);
+    const renderable = { ...checked.page, sections: sections.slice(0, cap) };
+    return { page: completePage(theme, renderable).page, source: "saved", reason: null, issues: checked.issues };
+}