@augeo/smelt 1.2.2 → 1.3.0

package/lib/build/build.test.ts

@@ -436,6 +436,188 @@ describe("build()", () => {
 			);
 		});
 	});
+
+	describe("when a component has a mechanical block face", () => {
+		beforeEach(async () => {
+			await writeComponent(baseline, "components/image", {
+				liquid: "<img>",
+				css: ".img {}",
+			});
+		});
+		beforeEach(async () => {
+			await writeFace(baseline, "components/image", {
+				schema:
+					"export const schema = { name: 'Image', settings: [{ type: 'image_picker', id: 'src', label: 'Image' }, { type: 'checkbox', id: 'rounded', label: 'Rounded' }] };",
+			});
+		});
+		beforeEach(async () => {
+			await build({ layers: [consumer.layer, baseline.layer] });
+		});
+
+		let face: string;
+		beforeEach(async () => {
+			face = await readFile(
+				join(consumer.path, "blocks/built--components--image.liquid"),
+				"utf-8",
+			);
+		});
+
+		it("emits the face into blocks/ named after the component", () => {
+			expect(face).toBeTruthy();
+		});
+
+		it("still emits the underlying snippet", async () => {
+			const snippet = await readFile(
+				join(consumer.path, "snippets/built--components--image.liquid"),
+				"utf-8",
+			);
+			expect(snippet).toContain("<img>");
+		});
+
+		it("renders the underlying component by its built name", () => {
+			expect(face).toContain("{% render 'built--components--image',");
+		});
+
+		it("maps each setting id to a render arg of the same name", () => {
+			expect(face).toContain("src: block.settings.src,");
+			expect(face).toContain("rounded: block.settings.rounded,");
+		});
+
+		it("passes shopify_attributes through", () => {
+			expect(face).toContain("shopify_attributes: block.shopify_attributes");
+		});
+
+		it("injects the face schema", () => {
+			expect(face).toContain("{% schema %}");
+			expect(face).toContain('"name": "Image"');
+		});
+	});
+
+	describe("when a mechanical face has no underlying snippet", () => {
+		beforeEach(async () => {
+			await writeFace(baseline, "components/orphan", {
+				schema: "export const schema = { name: 'Orphan' };",
+			});
+		});
+
+		it("fails with a face-specific error, not a generic render miss", async () => {
+			await expect(
+				build({ layers: [consumer.layer, baseline.layer] }),
+			).rejects.toThrow(/no underlying snippet/);
+		});
+	});
+
+	describe("when a component has an override block face", () => {
+		beforeEach(async () => {
+			await writeComponent(baseline, "components/stack", {
+				liquid: "<div>stack</div>",
+			});
+		});
+		beforeEach(async () => {
+			await writeFace(baseline, "components/stack", {
+				liquid:
+					"{% render '@/components/stack', children: block.blocks, shopify_attributes: block.shopify_attributes %}",
+				schema: "export const schema = { name: 'Stack' };",
+				css: ".stack-block {}",
+			});
+		});
+		beforeEach(async () => {
+			await build({ layers: [consumer.layer, baseline.layer] });
+		});
+
+		let face: string;
+		beforeEach(async () => {
+			face = await readFile(
+				join(consumer.path, "blocks/built--components--stack.liquid"),
+				"utf-8",
+			);
+		});
+
+		it("uses the hand-written body verbatim (with renders rewritten)", () => {
+			expect(face).toContain("children: block.blocks");
+			expect(face).toContain("{% render 'built--components--stack',");
+		});
+
+		it("inlines the face's own css", () => {
+			expect(face).toContain(".stack-block {}");
+		});
+
+		it("injects the face schema", () => {
+			expect(face).toContain('"name": "Stack"');
+		});
+	});
+
+	describe("when a block face owns private child blocks", () => {
+		beforeEach(async () => {
+			await writeComponent(baseline, "components/tabs", {
+				liquid: "<div>tabs</div>",
+			});
+		});
+		beforeEach(async () => {
+			await writeFace(baseline, "components/tabs", {
+				liquid: "{% render '@/components/tabs', children: block.blocks %}",
+				schema: "export const schema = { name: 'Tabs' };",
+			});
+		});
+		beforeEach(async () => {
+			await writeComponent(baseline, "components/tabs/block/blocks/tab", {
+				liquid: "<div>tab</div>",
+				schema: "export const schema = { name: 'Tab' };",
+			});
+		});
+		beforeEach(async () => {
+			await build({ layers: [consumer.layer, baseline.layer] });
+		});
+
+		it("emits the child as a private block named through the face", async () => {
+			const child = await readFile(
+				join(
+					consumer.path,
+					"blocks/_built--components--tabs--blocks--tab.liquid",
+				),
+				"utf-8",
+			);
+			expect(child).toContain("<div>tab</div>");
+		});
+
+		it("auto-merges the private child into the face's blocks array", async () => {
+			const face = await readFile(
+				join(consumer.path, "blocks/built--components--tabs.liquid"),
+				"utf-8",
+			);
+			expect(face).toContain('"type": "_built--components--tabs--blocks--tab"');
+		});
+	});
+
+	describe("when a `block/` dir sits under a real block (not a snippet)", () => {
+		beforeEach(async () => {
+			await writeComponent(baseline, "blocks/promo", {
+				liquid: "<aside>promo</aside>",
+				schema: "export const schema = { name: 'Promo' };",
+			});
+		});
+		beforeEach(async () => {
+			// A face marker here would collide with promo's own type:segments key.
+			// Faces are components-only, so this must be ignored, not silently drop
+			// the block.
+			await writeFace(baseline, "blocks/promo", {
+				schema: "export const schema = { name: 'ShouldBeIgnored' };",
+			});
+		});
+		beforeEach(async () => {
+			await build({ layers: [consumer.layer, baseline.layer] });
+		});
+
+		it("still emits the block, unshadowed by a spurious face", async () => {
+			const promo = await readFile(
+				join(consumer.path, "blocks/built--blocks--promo.liquid"),
+				"utf-8",
+			);
+			expect(promo).toContain("<aside>promo</aside>");
+			expect(promo).toContain('"name": "Promo"');
+			expect(promo).not.toContain("ShouldBeIgnored");
+		});
+	});
 });
 
 async function makeFixture(tempRoot: string, name: string): Promise<Fixture> {
@@ -473,3 +655,28 @@ async function writeComponent(
 			),
 	);
 }
+
+// Writes a component's block face: files named after the component but located
+// in its `block/` subdir (e.g. src/components/image/block/image.schema.ts).
+async function writeFace(
+	fixture: Fixture,
+	segments: string,
+	slots: { liquid?: string; ts?: string; css?: string; schema?: string },
+): Promise<void> {
+	const parts = segments.split("/");
+	const last = parts[parts.length - 1];
+	const directory = join(fixture.path, "src", ...parts, "block");
+	await mkdir(directory, { recursive: true });
+	await Promise.all(
+		Object.entries({
+			[`${last}.liquid`]: slots.liquid,
+			[`${last}.ts`]: slots.ts,
+			[`${last}.css`]: slots.css,
+			[`${last}.schema.ts`]: slots.schema,
+		})
+			.filter(([, content]) => content !== undefined)
+			.map(([filename, content]) =>
+				writeFile(join(directory, filename), content ?? ""),
+			),
+	);
+}

package/lib/build/build.ts

@@ -43,8 +43,15 @@ export async function build(context: BuildContext): Promise<number> {
 	const components = await resolveLayers(context.layers);
 	await cleanBuiltOutputs(outputRoot);
 
+	// Keyed by segments alone. A block face shares its snippet's segments (the
+	// `block/` marker is zero-segment), so faces are excluded here — they are
+	// never a render target (you render the underlying snippet) nor a private
+	// child, so neither consumer of this map needs them, and dropping them keeps
+	// the remaining keys unique.
 	const lookup = new Map(
-		components.map((component) => [component.segments.join("/"), component]),
+		components
+			.filter((component) => !component.face)
+			.map((component) => [component.segments.join("/"), component]),
 	);
 	await Promise.all(
 		components.map((component) =>
@@ -75,14 +82,40 @@ async function buildComponent(
 	lookup: Map<string, ResolvedComponent>,
 	outputRoot: string,
 ): Promise<void> {
-	const source = await readFile(component.liquid.path, "utf-8");
-	assertNoInlineSchema(source, component);
-	const body = rewriteRenders(source, component, lookup);
+	const schema = component.schema
+		? await loadSchema(component.schema)
+		: undefined;
 
-	const sections = [banner(component), body.trimEnd()];
+	let body: string;
+	if (component.liquid) {
+		const source = await readFile(component.liquid.path, "utf-8");
+		assertNoInlineSchema(source, component);
+		body = rewriteRenders(source, component, lookup);
+	} else {
+		// Mechanical block face: no hand-written body, so synthesize the wrapper
+		// render from the schema's settings (see docs/build-spec.md "Block faces").
+		// A mechanical face renders its underlying snippet — fail clearly here if
+		// that snippet is missing, rather than deferring to a generic
+		// "Cannot resolve render" from the alias rewrite.
+		const snippetKey = component.segments.join("/");
+		if (!lookup.has(snippetKey)) {
+			const name = component.segments[component.segments.length - 1];
+			throw new Error(
+				`Block face '${snippetKey}' has no underlying snippet to render — ` +
+					`a mechanical face wraps its component. Add ${name}.liquid, or ` +
+					`author a block/${name}.liquid override.`,
+			);
+		}
+		body = rewriteRenders(
+			generateFaceBody(component, schema),
+			component,
+			lookup,
+		);
+	}
+
+	const sections = [banner(anchorSourceOf(component)), body.trimEnd()];
 
-	if (component.schema) {
-		const schema = await loadSchema(component.schema);
+	if (schema !== undefined) {
 		const merged = mergePrivateBlocks(schema, component, lookup);
 		sections.push(renderSchemaBlock(merged));
 	}
@@ -114,7 +147,7 @@ function assertNoInlineSchema(
 	if (!/\{%-?\s*schema\s*-?%\}/.test(source)) return;
 	const last = component.segments[component.segments.length - 1];
 	throw new Error(
-		`Inline {% schema %} block in ${sourcePathForComponent(component)}. ` +
+		`Inline {% schema %} block in ${sourcePathFor(anchorSourceOf(component))}. ` +
 			`Schemas must live in a sibling ${last}.schema.ts file — import ` +
 			`{ defineSchemaSection } (or defineSchemaBlock) from "@augeo/smelt/schema".`,
 	);
@@ -207,19 +240,60 @@ function isPlainObject(value: unknown): value is Record<string, unknown> {
 	return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 
-function banner(component: ResolvedComponent): string {
+function banner(source: ComponentSource): string {
 	return `{%- comment -%}
-	GENERATED FROM ${sourcePathForComponent(component)} — do not edit this file directly.
+	GENERATED FROM ${sourcePathFor(source)} — do not edit this file directly.
 	Edit the source and run \`npm run build\`.
 {%- endcomment -%}`;
 }
 
-function sourcePathForComponent(component: ResolvedComponent): string {
-	const relativePath = relative(
-		component.liquid.layer.path,
-		component.liquid.path,
-	);
-	return `${component.liquid.layer.name}/${relativePath}`;
+function sourcePathFor(source: ComponentSource): string {
+	const relativePath = relative(source.layer.path, source.path);
+	return `${source.layer.name}/${relativePath}`;
+}
+
+/**
+ * The slot a built file traces back to: the hand-written liquid when present,
+ * else the schema (a mechanical block face is anchored on its schema alone).
+ */
+function anchorSourceOf(component: ResolvedComponent): ComponentSource {
+	const anchor = component.liquid ?? component.schema;
+	if (!anchor) {
+		throw new Error(
+			`Component '${component.segments.join("/")}' has neither a liquid nor a schema file.`,
+		);
+	}
+	return anchor;
+}
+
+/**
+ * Synthesize a block face's wrapper body: render the underlying component,
+ * mapping each schema setting to a render arg of the same name (`id == arg`)
+ * and passing `shopify_attributes` through. The `@/...` render is rewritten to
+ * the built name by the caller. For non-mechanical wrappers (derived props,
+ * `block.blocks`, …) author a `block/<name>.liquid` override instead.
+ */
+function generateFaceBody(
+	component: ResolvedComponent,
+	schema: unknown,
+): string {
+	const settings =
+		isPlainObject(schema) && Array.isArray(schema.settings)
+			? schema.settings
+			: [];
+	const settingArgs = settings
+		.filter(
+			(setting): setting is { id: string } =>
+				isPlainObject(setting) && typeof setting.id === "string",
+		)
+		.map((setting) => `\t${setting.id}: block.settings.${setting.id},`);
+	const target = `@/${component.segments.join("/")}`;
+	return [
+		`{% render '${target}',`,
+		...settingArgs,
+		"\tshopify_attributes: block.shopify_attributes",
+		"%}",
+	].join("\n");
 }
 
 function wrapEmbedded(tag: "stylesheet" | "javascript", body: string): string {
@@ -244,7 +318,7 @@ function rewriteRenders(
 			const target = lookup.get(lookupKey);
 			if (!target) {
 				throw new Error(
-					`Cannot resolve render '${importPath}' (looked up '${lookupKey}') from ${component.liquid.path}`,
+					`Cannot resolve render '${importPath}' (looked up '${lookupKey}') from ${anchorSourceOf(component).path}`,
 				);
 			}
 			return `${prefix}${builtNameOf(target)}${suffix}`;
@@ -263,7 +337,7 @@ function resolveImport(
 		// `../` is intentionally not supported — see docs/build-spec.md.
 		if (importPath.includes("../")) {
 			throw new Error(
-				`'../' is not supported in render path: '${importPath}' (in ${component.liquid.path})`,
+				`'../' is not supported in render path: '${importPath}' (in ${anchorSourceOf(component).path})`,
 			);
 		}
 		const remaining = importPath.slice(2).split("/").filter(Boolean);

package/lib/resolver.test.ts

@@ -52,7 +52,7 @@ describe("resolveLayers()", () => {
 		});
 
 		it("anchors the liquid slot against the baseline", () => {
-			expect(resolved[0].liquid.layer).toBe(baseline.layer);
+			expect(resolved[0].liquid?.layer).toBe(baseline.layer);
 		});
 
 		it("provides the ts slot from the baseline", () => {
@@ -97,6 +97,70 @@ describe("resolveLayers()", () => {
 		});
 	});
 
+	describe("with a component that has a block/ face", () => {
+		beforeEach(async () => {
+			await writeComponent(baseline, "components/image", {
+				liquid: "<img>",
+			});
+			await writeFace(baseline, "components/image", {
+				schema: "export const schema = { name: 'Image' };",
+			});
+		});
+
+		let resolved: ResolvedComponent[];
+		beforeEach(async () => {
+			resolved = await resolveLayers([baseline.layer]);
+		});
+
+		it("resolves the snippet and the face as two components", () => {
+			expect(resolved).toHaveLength(2);
+		});
+
+		it("emits the face as a blocks-typed component with the parent's segments", () => {
+			const face = resolved.find((component) => component.face);
+			expect(face?.type).toBe("blocks");
+			expect(face?.segments).toEqual(["components", "image"]);
+		});
+
+		it("anchors the mechanical face on its schema, not a liquid", () => {
+			const face = resolved.find((component) => component.face);
+			expect(face?.liquid).toBeUndefined();
+			expect(face?.schema?.layer).toBe(baseline.layer);
+		});
+
+		it("does not flag the underlying snippet as a face", () => {
+			const snippet = resolved.find(
+				(component) => component.type === "components",
+			);
+			expect(snippet?.face).toBeUndefined();
+		});
+	});
+
+	describe("with a block/ dir under a section (not a snippet)", () => {
+		beforeEach(async () => {
+			await writeComponent(baseline, "sections/hero", {
+				liquid: "<section></section>",
+			});
+			await writeFace(baseline, "sections/hero", {
+				schema: "export const schema = { name: 'Nope' };",
+			});
+		});
+
+		let resolved: ResolvedComponent[];
+		beforeEach(async () => {
+			resolved = await resolveLayers([baseline.layer]);
+		});
+
+		it("does not produce a face (faces are components-only)", () => {
+			expect(resolved.some((component) => component.face)).toBe(false);
+		});
+
+		it("leaves the section as the only resolved component", () => {
+			expect(resolved).toHaveLength(1);
+			expect(resolved[0].type).toBe("sections");
+		});
+	});
+
 	describe("with a consumer layer ahead of the baseline", () => {
 		describe("when the consumer shadows only the css slot", () => {
 			beforeEach(async () => {
@@ -119,7 +183,7 @@ describe("resolveLayers()", () => {
 			});
 
 			it("takes the liquid slot from the baseline", () => {
-				expect(button.liquid.layer).toBe(baseline.layer);
+				expect(button.liquid?.layer).toBe(baseline.layer);
 			});
 
 			it("takes the ts slot from the baseline", () => {
@@ -153,7 +217,7 @@ describe("resolveLayers()", () => {
 			});
 
 			it("takes the liquid slot from the consumer", () => {
-				expect(button.liquid.layer).toBe(consumer.layer);
+				expect(button.liquid?.layer).toBe(consumer.layer);
 			});
 
 			it("takes the ts slot from the consumer", () => {
@@ -189,7 +253,7 @@ describe("resolveLayers()", () => {
 			});
 
 			it("still anchors the liquid slot against the baseline", () => {
-				expect(button.liquid.layer).toBe(baseline.layer);
+				expect(button.liquid?.layer).toBe(baseline.layer);
 			});
 		});
 
@@ -273,3 +337,26 @@ async function writeComponent(
 			),
 	);
 }
+
+// Writes a block face: files named after the component but in its `block/`
+// subdir (e.g. src/components/image/block/image.schema.ts).
+async function writeFace(
+	fixture: Fixture,
+	segments: string,
+	slots: { liquid?: string; schema?: string },
+): Promise<void> {
+	const parts = segments.split("/");
+	const last = parts[parts.length - 1];
+	const directory = join(fixture.path, "src", ...parts, "block");
+	await mkdir(directory, { recursive: true });
+	await Promise.all(
+		Object.entries({
+			[`${last}.liquid`]: slots.liquid,
+			[`${last}.schema.ts`]: slots.schema,
+		})
+			.filter(([, content]) => content !== undefined)
+			.map(([filename, content]) =>
+				writeFile(join(directory, filename), content ?? ""),
+			),
+	);
+}