@shop-on/theme-contract 0.5.0 → 0.7.0

package/dist/editor-tools/recipes.d.ts

@@ -0,0 +1,122 @@
+import { EditorScope } from "./digest.js";
+import { z } from "zod";
+//#region src/editor-tools/recipes.d.ts
+/** What a theme may ship under `src/ai/` (and Rails accepts at upload): see `aiManifest`. */
+export declare const MAX_RECIPES = 20;
+export declare const MAX_RECIPE_BYTES: number;
+export declare const MAX_GUIDE_BYTES: number;
+export declare const RECIPE_HANDLE_RE: RegExp;
+export interface RecipeBlock {
+  type: string;
+  settings?: Record<string, string | number | boolean>;
+  blocks?: RecipeBlock[];
+}
+export declare const RecipeSchema: z.ZodObject<{
+  name: z.ZodString;
+  description: z.ZodOptional<z.ZodString>;
+  params: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+    type: z.ZodEnum<{
+      collection: "collection";
+      image: "image";
+      number: "number";
+      product: "product";
+      text: "text";
+      url: "url";
+    }>;
+    label: z.ZodString;
+    required: z.ZodOptional<z.ZodBoolean>;
+    default: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+  }, z.core.$strict>>>;
+  position: z.ZodOptional<z.ZodEnum<{
+    append: "append";
+    prepend: "prepend";
+    replace: "replace";
+  }>>;
+  sections: z.ZodArray<z.ZodObject<{
+    type: z.ZodString;
+    settings: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>>;
+    blocks: z.ZodOptional<z.ZodArray<z.ZodType<RecipeBlock, unknown, z.core.$ZodTypeInternals<RecipeBlock, unknown>>>>;
+  }, z.core.$strict>>;
+}, z.core.$strict>;
+export type Recipe = z.infer<typeof RecipeSchema>;
+/** A recipe as a host holds it: its file name is its handle. */
+export type LoadedRecipe = Recipe & {
+  handle: string;
+};
+export interface RecipeCheckSchemas {
+  sections: readonly {
+    type?: string;
+    settings?: {
+      id?: string;
+    }[];
+    blocks?: {
+      type: string;
+      static?: boolean;
+    }[];
+    enabled_on?: {
+      groups?: string[];
+      templates?: string[];
+    };
+    disabled_on?: {
+      groups?: string[];
+      templates?: string[];
+    };
+  }[];
+  blocks: readonly {
+    type?: string;
+    source?: "app";
+    settings?: {
+      id?: string;
+    }[];
+    blocks?: {
+      type: string;
+      static?: boolean;
+    }[];
+  }[];
+}
+/**
+ * The first thing wrong with a recipe against a theme's schemas, or null: an
+ * unknown section or block type, a setting the type doesn't have, a
+ * placeholder no param declares, a child its container doesn't allow, and,
+ * given a scope, a section that scope can't hold. The build runs it without a
+ * scope; the engine with the call's.
+ */
+export declare function checkRecipe(recipe: Recipe, schemas: RecipeCheckSchemas, scope?: EditorScope): string | null;
+/** One entry under a theme's `ai/` dir: its `/`-separated path relative to
+ *  it, and whether it is a regular file, a directory or anything else (a
+ *  symlink, a device). */
+export interface AiEntry {
+  path: string;
+  kind: "file" | "dir" | "other";
+  bytes: number;
+}
+export interface AiManifest {
+  guide?: AiEntry;
+  recipes: AiEntry[];
+  refused: {
+    path: string;
+    reason: string;
+  }[];
+}
+/**
+ * The one rule for what a theme's `ai/` dir holds, applied by the build, the
+ * upload and every host that reads it: `guide.md` (at most MAX_GUIDE_BYTES)
+ * and `recipes/<handle>.json` (each at most MAX_RECIPE_BYTES, at most
+ * MAX_RECIPES of them, in path order), regular files only. The `recipes`
+ * directory itself is allowed; every other entry is refused.
+ */
+export declare function aiManifest(entries: readonly AiEntry[]): AiManifest;
+/**
+ * Parses recipe files, keyed by file name (`<handle>.json`), each on its own:
+ * a file that isn't valid JSON or a valid recipe is skipped with its reason
+ * and the others still load. The caps are `aiManifest`'s, checked before a
+ * file is read.
+ */
+export declare function loadRecipes(files: Record<string, string>): {
+  recipes: LoadedRecipe[];
+  skipped: {
+    name: string;
+    reason: string;
+  }[];
+};
+//#endregion

package/dist/editor-tools/recipes.js

@@ -0,0 +1,192 @@
+import "../document.js";
+import "../template-limits.js";
+import { isSectionAddableInGroup, isSectionEnabledOnTemplate } from "../section-scope.js";
+import { allowedChildBlockTypes } from "../block-allowlist.js";
+import { EditorId, MAX_TEXT_PARAM_BYTES } from "./args.js";
+import { z } from "zod";
+//#region src/editor-tools/recipes.ts
+/** What a theme may ship under `src/ai/` (and Rails accepts at upload): see `aiManifest`. */
+const MAX_RECIPES = 20;
+const MAX_RECIPE_BYTES = 32768;
+const MAX_GUIDE_BYTES = 16384;
+const RECIPE_HANDLE_RE = /^[a-z0-9-]{1,64}$/;
+const RecipeValue = z.union([
+	z.string().max(MAX_RECIPE_BYTES),
+	z.number(),
+	z.boolean()
+]);
+const SettingMap = z.record(EditorId, RecipeValue);
+const RecipeBlockSchema = z.lazy(() => z.object({
+	type: EditorId,
+	settings: SettingMap.optional(),
+	blocks: z.array(RecipeBlockSchema).max(50).optional()
+}).strict());
+const RecipeParam = z.object({
+	type: z.enum([
+		"text",
+		"product",
+		"collection",
+		"image",
+		"url",
+		"number"
+	]),
+	label: z.string().min(1).max(120),
+	required: z.boolean().optional(),
+	default: z.union([z.string().max(MAX_TEXT_PARAM_BYTES), z.number()]).optional()
+}).strict();
+const RecipeSchema = z.object({
+	name: z.string().min(1).max(120),
+	description: z.string().max(1e3).optional(),
+	params: z.record(EditorId, RecipeParam).optional(),
+	position: z.enum([
+		"append",
+		"prepend",
+		"replace"
+	]).optional(),
+	sections: z.array(z.object({
+		type: EditorId,
+		settings: SettingMap.optional(),
+		blocks: z.array(RecipeBlockSchema).max(50).optional()
+	}).strict()).min(1).max(25)
+}).strict();
+const PLACEHOLDER_RE = /\{\{\s*([^{}\s]+)\s*\}\}/g;
+function findBlockSchema(schemas, type) {
+	return schemas.blocks.find((b) => b.type === type) ?? schemas.blocks.find((b) => b.type === type.replace(/^_/, ""));
+}
+function checkSettings(where, settings, schemaSettings, params) {
+	for (const [id, value] of Object.entries(settings ?? {})) {
+		if (!schemaSettings?.some((s) => s.id === id)) return `${where}: unknown setting ${id}`;
+		if (typeof value !== "string") continue;
+		for (const [, name] of value.matchAll(PLACEHOLDER_RE)) if (!Object.hasOwn(params, name)) return `${where}.settings.${id}: unknown param ${name}`;
+	}
+	return null;
+}
+function checkBlocks(where, blocks, container, depth, schemas, params) {
+	if (!blocks?.length) return null;
+	if (depth >= 8) return `${where}: blocks nest deeper than 8`;
+	const allowed = allowedChildBlockTypes(container, schemas.blocks, { depth });
+	for (const [i, block] of blocks.entries()) {
+		const at = `${where}.blocks[${i}]`;
+		if (block.type === "@app" || !allowed.includes(block.type)) return `${at}: block type ${block.type} is not allowed here`;
+		const schema = findBlockSchema(schemas, block.type);
+		if (!schema) return `${at}: unknown block type ${block.type}`;
+		const bad = checkSettings(at, block.settings, schema.settings, params) ?? checkBlocks(at, block.blocks, schema, depth + 1, schemas, params);
+		if (bad) return bad;
+	}
+	return null;
+}
+/**
+* The first thing wrong with a recipe against a theme's schemas, or null: an
+* unknown section or block type, a setting the type doesn't have, a
+* placeholder no param declares, a child its container doesn't allow, and,
+* given a scope, a section that scope can't hold. The build runs it without a
+* scope; the engine with the call's.
+*/
+function checkRecipe(recipe, schemas, scope) {
+	const params = recipe.params ?? {};
+	for (const [i, section] of recipe.sections.entries()) {
+		const at = `sections[${i}]`;
+		const schema = schemas.sections.find((s) => s.type === section.type);
+		if (!schema) return `${at}: unknown section type ${section.type}`;
+		if (scope && "template_id" in scope && !isSectionEnabledOnTemplate(schema, scope.template_id)) return `${at}: section type ${section.type} is not allowed on template ${scope.template_id}`;
+		if (scope && "group" in scope && !isSectionAddableInGroup(schema, scope.group)) return `${at}: section type ${section.type} is not allowed in group ${scope.group}`;
+		const bad = checkSettings(at, section.settings, schema.settings, params) ?? checkBlocks(at, section.blocks, schema, 0, schemas, params);
+		if (bad) return bad;
+	}
+	return null;
+}
+const RECIPE_PATH_RE = /^recipes\/([^/]+)\.json$/;
+/**
+* The one rule for what a theme's `ai/` dir holds, applied by the build, the
+* upload and every host that reads it: `guide.md` (at most MAX_GUIDE_BYTES)
+* and `recipes/<handle>.json` (each at most MAX_RECIPE_BYTES, at most
+* MAX_RECIPES of them, in path order), regular files only. The `recipes`
+* directory itself is allowed; every other entry is refused.
+*/
+function aiManifest(entries) {
+	const out = {
+		recipes: [],
+		refused: []
+	};
+	const refuse = (path, reason) => out.refused.push({
+		path,
+		reason
+	});
+	for (const entry of [...entries].sort((a, b) => a.path < b.path ? -1 : 1)) {
+		const { path, kind, bytes } = entry;
+		if (path === "recipes" && kind === "dir") continue;
+		const handle = RECIPE_PATH_RE.exec(path)?.[1];
+		if (!(path === "guide.md" || handle !== void 0 && RECIPE_HANDLE_RE.test(handle))) refuse(path, `${path}: ai/ holds only guide.md and recipes/<handle>.json, handle [a-z0-9-]`);
+		else if (kind !== "file") refuse(path, `${path} is not a regular file`);
+		else if (path === "guide.md") {
+			if (bytes > 16384) refuse(path, `${path} is over ${MAX_GUIDE_BYTES} bytes`);
+			else out.guide = entry;
+		} else if (bytes > 32768) refuse(path, `${path} is over ${MAX_RECIPE_BYTES} bytes`);
+		else if (out.recipes.length >= 20) refuse(path, `${path}: more than 20 recipes`);
+		else out.recipes.push(entry);
+	}
+	return out;
+}
+/**
+* Parses recipe files, keyed by file name (`<handle>.json`), each on its own:
+* a file that isn't valid JSON or a valid recipe is skipped with its reason
+* and the others still load. The caps are `aiManifest`'s, checked before a
+* file is read.
+*/
+function loadRecipes(files) {
+	const recipes = [];
+	const skipped = [];
+	for (const name of Object.keys(files).sort()) {
+		const handle = name.replace(/\.json$/, "");
+		if (!name.endsWith(".json") || !RECIPE_HANDLE_RE.test(handle)) {
+			skipped.push({
+				name,
+				reason: `${name}: a recipe file is <handle>.json, handle [a-z0-9-]`
+			});
+			continue;
+		}
+		let raw;
+		try {
+			raw = JSON.parse(files[name]);
+		} catch {
+			skipped.push({
+				name,
+				reason: `${name} is not valid JSON`
+			});
+			continue;
+		}
+		const parsed = RecipeSchema.safeParse(raw);
+		if (!parsed.success) {
+			const issue = parsed.error.issues[0];
+			skipped.push({
+				name,
+				reason: `${name}: ${issue.path.join(".")}: ${issue.message}`
+			});
+			continue;
+		}
+		recipes.push({
+			...parsed.data,
+			handle
+		});
+	}
+	return {
+		recipes,
+		skipped
+	};
+}
+/** `{{name}}` in a recipe string, replaced by the param's value. */
+function substituteParams(value, params) {
+	return value.replace(PLACEHOLDER_RE, (_m, name) => params[name] ?? "");
+}
+function recipeSummary(recipe) {
+	return {
+		handle: recipe.handle,
+		name: recipe.name,
+		...recipe.description ? { description: recipe.description } : {},
+		position: recipe.position ?? "append",
+		params: recipe.params ?? {},
+		sections: recipe.sections.map((s) => s.type)
+	};
+}
+//#endregion
+export { MAX_GUIDE_BYTES, MAX_RECIPES, MAX_RECIPE_BYTES, RECIPE_HANDLE_RE, RecipeSchema, aiManifest, checkRecipe, loadRecipes, recipeSummary, substituteParams };

package/dist/fonts.d.ts

@@ -0,0 +1,9 @@
+import { GOOGLE_FONTS, GoogleFontEntry } from "./google-fonts.generated.js";
+//#region src/fonts.d.ts
+/** The families a `font_picker` offers that load from no file. */
+export declare const SYSTEM_FONT_FAMILIES: readonly ["system-ui"];
+/** Whether a `font_picker` value names a family of the editor's catalog. An
+ *  uploaded family's node id is not one. */
+export declare function isCatalogFontFamily(family: string): boolean;
+//#endregion
+export { GOOGLE_FONTS, type GoogleFontEntry };

package/dist/fonts.js

@@ -0,0 +1,11 @@
+import { GOOGLE_FONTS } from "./google-fonts.generated.js";
+//#region src/fonts.ts
+/** The families a `font_picker` offers that load from no file. */
+const SYSTEM_FONT_FAMILIES = ["system-ui"];
+/** Whether a `font_picker` value names a family of the editor's catalog. An
+*  uploaded family's node id is not one. */
+function isCatalogFontFamily(family) {
+	return SYSTEM_FONT_FAMILIES.includes(family) || GOOGLE_FONTS.some((f) => f.family === family);
+}
+//#endregion
+export { GOOGLE_FONTS, SYSTEM_FONT_FAMILIES, isCatalogFontFamily };

package/dist/google-fonts.generated.d.ts

@@ -0,0 +1,7 @@
+//#region src/google-fonts.generated.d.ts
+export interface GoogleFontEntry {
+  family: string;
+  category: string;
+}
+export declare const GOOGLE_FONTS: GoogleFontEntry[];
+//#endregion