@wocart/theme 1.5.0 → 2.0.0

package/dist/astro/index.js

@@ -5,18 +5,26 @@
  * - `createReadCache` — the per-render read sharing the contract requires
  *   (one read per resource per render).
  * - `themeManifestEndpoint` — the manifest as a prerendered build artifact.
+ * - `themeStylesEndpoint` — the stylesheet of the theme's style classes, the
+ *   same way; `THEME_STYLES_PATH` and `colorSchemeCss` for `ThemeStyles.astro`.
  * - `RendererIssue` — the renderer-specific degradations, reportable via
  *   `InstanceView`'s `onIssue` prop.
- * - `resolveInstance` — re-exported so `InstanceView.astro`'s co-located
- *   import (`./index.js`) resolves identically in the dev source layout and in
- *   the published `dist/astro` layout. Same function as the
+ * - `BlocksHandle` and `hasBlocks` — what a component receives as `blocks`,
+ *   and whether one of its slots has anything to render.
+ * - `resolveInstance` and `THEME_LIMITS` — re-exported so `InstanceView.astro`'s
+ *   co-located import (`./index.js`) resolves identically in the dev source
+ *   layout and in the published `dist/astro` layout. The same values as the
  *   root export — never a second implementation.
  *
- * The renderer component itself:
- * `@wocart/theme/astro/InstanceView.astro`.
+ * The renderer components: `@wocart/theme/astro/InstanceView.astro`,
+ * `@wocart/theme/astro/Blocks.astro`, `@wocart/theme/astro/Block.astro` and
+ * `@wocart/theme/astro/ThemeStyles.astro`.
  */
 import { themeManifest, validateThemeManifest } from "../manifest.js";
+import { themeStyleSheet } from "../style.js";
 export { resolveInstance } from "../instances.js";
+export { THEME_LIMITS } from "../blocks.js";
+export { THEME_STYLES_PATH, colorSchemeCss } from "../style.js";
 export { previewEndMarker, previewStartMarker } from "../preview-protocol.js";
 /**
  * The theme's manifest as a prerendered endpoint, the file a release and an
@@ -43,6 +51,36 @@ export function themeManifestEndpoint(theme) {
     const body = JSON.stringify(manifest);
     return () => new Response(body, { headers: { "Content-Type": "application/json; charset=utf-8" } });
 }
+/**
+ * The stylesheet of the theme's style classes as a prerendered endpoint, the
+ * file `<ThemeStyles>` links (`THEME_STYLES_PATH`):
+ *
+ * ```ts
+ * // src/pages/wocart-styles.css.ts
+ * import { themeStylesEndpoint } from "@wocart/theme/astro";
+ * import { theme } from "../theme/theme";
+ * export const prerender = true;
+ * export const GET = themeStylesEndpoint(theme);
+ * ```
+ */
+export function themeStylesEndpoint(theme) {
+    const body = themeStyleSheet(theme.style);
+    return () => new Response(body, { headers: { "Content-Type": "text/css; charset=utf-8" } });
+}
+/**
+ * Whether the component renders in an editor's preview. A section with
+ * nothing to show yet — no products picked, no text written — draws a
+ * placeholder there, so a merchant can see and select it; a shopper's page
+ * never shows one.
+ */
+export function isPreview(blocks) {
+    return blocks?.render.preview === true;
+}
+/** Whether a slot holds a block that renders (not hidden), so a component can leave out an empty wrapper. */
+export function hasBlocks(blocks, slot = "default") {
+    const list = blocks !== undefined && Object.hasOwn(blocks.slots, slot) ? blocks.slots[slot] : [];
+    return list.some((instance) => instance.hidden !== true);
+}
 /**
  * The per-render `ReadCache`: the first call for a key
  * runs the loader; later calls in the same render reuse the in-flight or

package/dist/blocks.d.ts

@@ -0,0 +1,61 @@
+/**
+ * What a document holds whatever it stores: every fixed block a
+ * component's code places, every required type a slot or surface lists, and
+ * the platform's caps. One implementation serves the renderer
+ * (`resolveInstance`), the reader (`validatePageData`) and every writer
+ * (`completePage`), so what an editor shows is what renders.
+ */
+import type { ComponentDefinition, ComponentInstance, ComponentPlacement, ComponentRole, PageData, PageDataIssue, RequiredBlock, SlotDefinition, SurfaceSpec, ThemeDefinition } from "./types.js";
+/** The platform's caps: a page renders within a Worker's CPU time, and an editor's tree stays readable. */
+export declare const THEME_LIMITS: {
+    /** Instances in one slot. */
+    readonly slotInstances: 50;
+    /** Top-level sections of one surface or area. */
+    readonly sections: 50;
+    /** Instances in one document, at every depth. */
+    readonly documentInstances: 1000;
+    /** Levels of nesting below a top-level section. */
+    readonly depth: 6;
+};
+export declare const COMPONENT_PLACEMENTS: readonly ["section", "block", "both"];
+export declare const COMPONENT_ROLES: readonly ["order-form"];
+/** The surface an area's document is stored under: `area:<key>`. */
+export declare function areaSurface(key: string): string;
+/** The shipped document for a surface or an area, when the theme declares one. */
+export declare function shippedDocument(theme: ThemeDefinition, surface: string): PageData | undefined;
+/** Whether a theme composes a surface: one it declares, or one of its areas. */
+export declare function composesSurface(theme: ThemeDefinition, surface: string): boolean;
+/** The id a fixed block renders with while the document does not store it. */
+export declare function fixedBlockId(ownerId: string, name: string): string;
+/** Whether a component may be placed at the top level (`"section"`) or in a slot (`"block"`). */
+export declare function placementAllows(placement: ComponentPlacement | undefined, where: "section" | "block"): boolean;
+/**
+ * The block rules a surface's top level follows: its own `required` and
+ * `max`, each inherited from the base surface by an alternate
+ * (`product.compact` from `product`) that does not set its own.
+ */
+export declare function surfaceRules(theme: ThemeDefinition, surface: string): Pick<SurfaceSpec, "required" | "max">;
+/** A slot's or surface's cap: its own `max`, never above the platform's. */
+export declare function slotCap(slot: Pick<SlotDefinition, "max"> | undefined, platform: number): number;
+/**
+ * Every fixed block of an instance, as it renders: the stored value when its
+ * type is the code's, else the code's type with its defaults. A fixed block
+ * is never hidden. Stored entries the definition does not declare are reported.
+ */
+export declare function resolveFixed(definition: ComponentDefinition, instance: ComponentInstance, issues: PageDataIssue[]): Record<string, ComponentInstance>;
+/**
+ * A list with every required type present: hidden ones shown again first, then
+ * new instances (`{ id, type }`, values from the defaults) added at the end.
+ * `taken` keeps added ids unique in a whole document. Never mutates `list`.
+ */
+export declare function completeRequired(list: readonly ComponentInstance[], required: readonly RequiredBlock[] | undefined, owner: {
+    id: string;
+    slot: string;
+}, path: string, issues: PageDataIssue[], taken?: Set<string>): ComponentInstance[];
+/** How many instances of `role` a `type` always renders: its own, its fixed blocks', its slots' required minimums. */
+export declare function guaranteedRole(theme: ThemeDefinition, type: string, role: ComponentRole, visiting?: ReadonlySet<string>): number;
+/** The types a component always renders inside itself: fixed blocks and required types, by slot. */
+export declare function innerGuarantees(definition: ComponentDefinition): Array<{
+    type: string;
+    via: string;
+}>;

package/dist/blocks.js

@@ -0,0 +1,144 @@
+/** The platform's caps: a page renders within a Worker's CPU time, and an editor's tree stays readable. */
+export const THEME_LIMITS = {
+    /** Instances in one slot. */
+    slotInstances: 50,
+    /** Top-level sections of one surface or area. */
+    sections: 50,
+    /** Instances in one document, at every depth. */
+    documentInstances: 1000,
+    /** Levels of nesting below a top-level section. */
+    depth: 6,
+};
+export const COMPONENT_PLACEMENTS = ["section", "block", "both"];
+export const COMPONENT_ROLES = ["order-form"];
+const AREA_PREFIX = "area:";
+/** The surface an area's document is stored under: `area:<key>`. */
+export function areaSurface(key) {
+    return `${AREA_PREFIX}${key}`;
+}
+/** The shipped document for a surface or an area, when the theme declares one. */
+export function shippedDocument(theme, surface) {
+    if (surface.startsWith(AREA_PREFIX))
+        return (theme.areas ?? []).find((area) => areaSurface(area.key) === surface)?.document;
+    return (theme.surfaces ?? []).find((spec) => spec.key === surface)?.document;
+}
+/** Whether a theme composes a surface: one it declares, or one of its areas. */
+export function composesSurface(theme, surface) {
+    return (theme.surfaces ?? []).some((spec) => spec.key === surface) || (theme.areas ?? []).some((area) => areaSurface(area.key) === surface);
+}
+/** The id a fixed block renders with while the document does not store it. */
+export function fixedBlockId(ownerId, name) {
+    return `${ownerId}~${name}`;
+}
+const requiredBlockId = (ownerId, slot, type, n) => `${ownerId}~${slot}~${type}${n > 1 ? `~${n}` : ""}`;
+/** Whether a component may be placed at the top level (`"section"`) or in a slot (`"block"`). */
+export function placementAllows(placement, where) {
+    return placement === undefined || placement === "both" || placement === where;
+}
+/**
+ * The block rules a surface's top level follows: its own `required` and
+ * `max`, each inherited from the base surface by an alternate
+ * (`product.compact` from `product`) that does not set its own.
+ */
+export function surfaceRules(theme, surface) {
+    if (surface.startsWith(AREA_PREFIX)) {
+        const area = (theme.areas ?? []).find((spec) => areaSurface(spec.key) === surface);
+        return { ...(area?.required === undefined ? {} : { required: area.required }), ...(area?.max === undefined ? {} : { max: area.max }) };
+    }
+    const surfaces = theme.surfaces ?? [];
+    const own = surfaces.find((spec) => spec.key === surface);
+    const dot = surface.indexOf(".");
+    const base = dot > 0 ? surfaces.find((spec) => spec.key === surface.slice(0, dot)) : undefined;
+    const required = own?.required ?? base?.required;
+    const max = own?.max ?? base?.max;
+    return { ...(required === undefined ? {} : { required }), ...(max === undefined ? {} : { max }) };
+}
+/** A slot's or surface's cap: its own `max`, never above the platform's. */
+export function slotCap(slot, platform) {
+    return slot?.max === undefined ? platform : Math.min(slot.max, platform);
+}
+/**
+ * Every fixed block of an instance, as it renders: the stored value when its
+ * type is the code's, else the code's type with its defaults. A fixed block
+ * is never hidden. Stored entries the definition does not declare are reported.
+ */
+export function resolveFixed(definition, instance, issues) {
+    const declared = definition.fixed ?? [];
+    const stored = instance.fixed ?? {};
+    for (const name of Object.keys(stored)) {
+        if (!declared.some((block) => block.name === name)) {
+            issues.push({ path: `fixed.${name}`, code: "unknown-fixed", message: `"${definition.type}" places no fixed block "${name}"; its value is ignored` });
+        }
+    }
+    const resolved = {};
+    for (const { name, type } of declared) {
+        const entry = Object.hasOwn(stored, name) ? stored[name] : undefined;
+        if (entry !== undefined && entry.type === type) {
+            const { hidden: _hidden, ...shown } = entry;
+            resolved[name] = shown;
+            continue;
+        }
+        if (entry !== undefined) {
+            issues.push({
+                path: `fixed.${name}.type`,
+                code: "fixed-type-mismatch",
+                message: `the fixed block "${name}" is a "${type}", not a "${entry.type}"; it renders with its defaults`,
+            });
+        }
+        resolved[name] = { id: fixedBlockId(instance.id, name), type };
+    }
+    return resolved;
+}
+/**
+ * A list with every required type present: hidden ones shown again first, then
+ * new instances (`{ id, type }`, values from the defaults) added at the end.
+ * `taken` keeps added ids unique in a whole document. Never mutates `list`.
+ */
+export function completeRequired(list, required, owner, path, issues, taken) {
+    let result = [...list];
+    for (const { type, min = 1 } of required ?? []) {
+        let shown = result.filter((instance) => instance.type === type && instance.hidden !== true).length;
+        if (shown >= min)
+            continue;
+        result = result.map((instance) => {
+            if (shown >= min || instance.type !== type || instance.hidden !== true)
+                return instance;
+            shown += 1;
+            issues.push({ path, code: "missing-required-block", message: `"${type}" is required in "${owner.slot}" and cannot be hidden; it is shown` });
+            const { hidden: _hidden, ...visible } = instance;
+            return visible;
+        });
+        for (let n = 1; shown < min; n += 1) {
+            const id = requiredBlockId(owner.id, owner.slot, type, n);
+            if (result.some((instance) => instance.id === id) || taken?.has(id) === true)
+                continue;
+            taken?.add(id);
+            result.push({ id, type });
+            shown += 1;
+            issues.push({ path, code: "missing-required-block", message: `"${type}" is required in "${owner.slot}"; one was added` });
+        }
+    }
+    return result;
+}
+/** How many instances of `role` a `type` always renders: its own, its fixed blocks', its slots' required minimums. */
+export function guaranteedRole(theme, type, role, visiting = new Set()) {
+    const definition = Object.hasOwn(theme.components, type) ? theme.components[type] : undefined;
+    if (definition === undefined || visiting.has(type))
+        return 0;
+    const inner = new Set(visiting).add(type);
+    let count = definition.role === role ? 1 : 0;
+    for (const block of definition.fixed ?? [])
+        count += guaranteedRole(theme, block.type, role, inner);
+    for (const slot of definition.slots ?? []) {
+        for (const entry of slot.required ?? [])
+            count += (entry.min ?? 1) * guaranteedRole(theme, entry.type, role, inner);
+    }
+    return count;
+}
+/** The types a component always renders inside itself: fixed blocks and required types, by slot. */
+export function innerGuarantees(definition) {
+    return [
+        ...(definition.fixed ?? []).map((block) => ({ type: block.type, via: `fixed "${block.name}"` })),
+        ...(definition.slots ?? []).flatMap((slot) => (slot.required ?? []).map((entry) => ({ type: entry.type, via: `slot "${slot.name}"` }))),
+    ];
+}

package/dist/conditions.d.ts

@@ -0,0 +1,21 @@
+/**
+ * When a field applies (`visibleIf`): a closed JSON condition on the values of
+ * the fields beside it, evaluated the same way by every editor. Conditions
+ * only decide what an editor shows; the renderer ignores them, and a hidden
+ * field keeps its value.
+ */
+import type { FieldDefinition } from "./types.js";
+/** How deep `all`, `any` and `not` may nest. */
+export declare const CONDITION_DEPTH = 4;
+/**
+ * Whether an editor shows `field`, given the current values of the fields
+ * beside it — what is stored, else the default. A field with no value
+ * compares as `null`.
+ */
+export declare function isFieldVisible(field: FieldDefinition, values: Readonly<Record<string, unknown>>): boolean;
+/**
+ * Why `condition` is not one a field named `self` may carry, or `null`: one
+ * of the five shapes, naming only fields in `siblings` other than itself,
+ * comparing with JSON scalars, nested at most `CONDITION_DEPTH` deep.
+ */
+export declare function conditionProblem(condition: unknown, siblings: ReadonlySet<string>, self: string, depth?: number): string | null;

package/dist/conditions.js

@@ -0,0 +1,65 @@
+/** How deep `all`, `any` and `not` may nest. */
+export const CONDITION_DEPTH = 4;
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const isConditionValue = (value) => value === null || typeof value === "string" || typeof value === "boolean" || (typeof value === "number" && Number.isFinite(value));
+/**
+ * Whether an editor shows `field`, given the current values of the fields
+ * beside it — what is stored, else the default. A field with no value
+ * compares as `null`.
+ */
+export function isFieldVisible(field, values) {
+    return field.visibleIf === undefined || holds(field.visibleIf, values);
+}
+function holds(condition, values) {
+    if ("all" in condition)
+        return condition.all.every((inner) => holds(inner, values));
+    if ("any" in condition)
+        return condition.any.some((inner) => holds(inner, values));
+    if ("not" in condition)
+        return !holds(condition.not, values);
+    const value = Object.hasOwn(values, condition.field) ? values[condition.field] : undefined;
+    const actual = value === undefined ? null : value;
+    if ("equals" in condition)
+        return actual === condition.equals;
+    return condition.in.includes(actual);
+}
+/**
+ * Why `condition` is not one a field named `self` may carry, or `null`: one
+ * of the five shapes, naming only fields in `siblings` other than itself,
+ * comparing with JSON scalars, nested at most `CONDITION_DEPTH` deep.
+ */
+export function conditionProblem(condition, siblings, self, depth = 1) {
+    if (depth > CONDITION_DEPTH)
+        return `nests more than ${CONDITION_DEPTH} levels`;
+    if (!isRecord(condition))
+        return "must be a condition: { field, equals }, { field, in }, { all }, { any } or { not }";
+    const keys = Object.keys(condition).sort().join(",");
+    if (keys === "all" || keys === "any") {
+        const list = condition[keys];
+        if (!Array.isArray(list) || list.length === 0)
+            return `\`${keys}\` must be a non-empty array of conditions`;
+        for (const inner of list) {
+            const problem = conditionProblem(inner, siblings, self, depth + 1);
+            if (problem !== null)
+                return problem;
+        }
+        return null;
+    }
+    if (keys === "not")
+        return conditionProblem(condition.not, siblings, self, depth + 1);
+    if (keys !== "equals,field" && keys !== "field,in") {
+        return "must be a condition: { field, equals }, { field, in }, { all }, { any } or { not }";
+    }
+    const field = condition.field;
+    if (typeof field !== "string" || !siblings.has(field))
+        return `${JSON.stringify(field)} is not a field beside this one`;
+    if (field === self)
+        return "a field cannot depend on itself";
+    if (keys === "equals,field")
+        return isConditionValue(condition.equals) ? null : "`equals` must be a string, a number, a boolean or null";
+    const options = condition.in;
+    if (!Array.isArray(options) || options.length === 0 || !options.every(isConditionValue)) {
+        return "`in` must be a non-empty array of strings, numbers, booleans or null";
+    }
+    return null;
+}