@augeo/smelt 1.2.3 → 1.3.0

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 ?? ""),
+			),
+	);
+}

package/lib/resolver.ts

@@ -22,48 +22,85 @@ export interface ComponentSource {
 export interface ResolvedComponent {
 	/** Component kind — determines the output directory. */
 	type: ComponentType;
-	/** Path segments under `src/`, e.g. `["components", "button"]`. */
+	/** Path segments under `src/` for naming, e.g. `["components", "button"]`. */
 	segments: string[];
-	/** The anchor — every component has a liquid file. */
-	liquid: ComponentSource;
+	/**
+	 * The anchor liquid. Present for every authored component and for an
+	 * override block face (`block/<name>.liquid`). A *mechanical* block face —
+	 * a `block/` dir with only a `<name>.schema.ts` — has no liquid; the engine
+	 * synthesizes its body from the schema's settings.
+	 */
+	liquid?: ComponentSource;
 	/** Optional sibling slots; each may come from a different layer. */
 	ts?: ComponentSource;
 	css?: ComponentSource;
 	test?: ComponentSource;
-	/** Section schema authored in TS; executed at build time. */
+	/** Section/block schema authored in TS; executed at build time. */
 	schema?: ComponentSource;
+	/**
+	 * True when this component is the block face of another component — emitted
+	 * from a singular `block/` directory. Its `segments` are the parent's (the
+	 * `block` marker is zero-segment), but its `type` is `"blocks"`.
+	 */
+	face?: boolean;
 }
 
 const TYPE_NAMES = ["sections", "blocks", "components"] as const;
 export type ComponentType = (typeof TYPE_NAMES)[number];
 
+// A singular `block/` directory inside a `src/components/*` snippet declares
+// that snippet's block face (see docs/build-spec.md "Block faces"). It is a
+// *zero-segment* marker: it retargets the type to "blocks" and reroots file
+// lookup inside `block/`, but contributes nothing to the naming segments.
+// Distinct from the plural `blocks/` type marker, which holds private child
+// blocks. Faces are components-only — see the guard in walkType.
+const FACE_MARKER = "block";
+
+/**
+ * Internal walk result. `dir` is the real path under `src/` (it includes face
+ * markers); `segments` is the naming key (it does not). For everything except
+ * faces and their descendants the two are identical.
+ */
+interface Descriptor {
+	type: ComponentType;
+	segments: string[];
+	dir: string[];
+	face: boolean;
+}
+
 export async function resolveLayers(
 	layers: Layer[],
 ): Promise<ResolvedComponent[]> {
 	const perLayerComponents = await Promise.all(layers.map(walkLayer));
-	const allKeys = new Map<
-		string,
-		{ type: ComponentType; segments: string[] }
-	>();
-	perLayerComponents.flat().forEach(({ type, segments }) => {
-		const key = `${type}:${segments.join("/")}`;
+	const allKeys = new Map<string, Descriptor>();
+	perLayerComponents.flat().forEach((descriptor) => {
+		const key = `${descriptor.type}:${descriptor.segments.join("/")}`;
 		if (!allKeys.has(key)) {
-			allKeys.set(key, { type, segments });
+			allKeys.set(key, descriptor);
 		}
 	});
 
 	const resolved = await Promise.all(
 		Array.from(allKeys.values()).map(
-			async ({ type, segments }): Promise<ResolvedComponent | undefined> => {
+			async (descriptor): Promise<ResolvedComponent | undefined> => {
+				const anchor = descriptor.segments[descriptor.segments.length - 1];
 				const [liquid, ts, css, test, schema] = await Promise.all([
-					firstExisting(layers, segments, ".liquid"),
-					firstExisting(layers, segments, ".ts"),
-					firstExisting(layers, segments, ".css"),
-					firstExisting(layers, segments, ".test.ts"),
-					firstExisting(layers, segments, ".schema.ts"),
+					firstExisting(layers, descriptor.dir, anchor, ".liquid"),
+					firstExisting(layers, descriptor.dir, anchor, ".ts"),
+					firstExisting(layers, descriptor.dir, anchor, ".css"),
+					firstExisting(layers, descriptor.dir, anchor, ".test.ts"),
+					firstExisting(layers, descriptor.dir, anchor, ".schema.ts"),
 				]);
-				if (!liquid) return undefined;
-				const component: ResolvedComponent = { type, segments, liquid };
+				// A normal component needs a liquid anchor. A block face may instead
+				// be anchored on its schema alone (the mechanical case) — the engine
+				// generates the wrapper body from it.
+				if (!liquid && !(descriptor.face && schema)) return undefined;
+				const component: ResolvedComponent = {
+					type: descriptor.type,
+					segments: descriptor.segments,
+				};
+				if (descriptor.face) component.face = true;
+				if (liquid) component.liquid = liquid;
 				if (ts) component.ts = ts;
 				if (css) component.css = css;
 				if (test) component.test = test;
@@ -78,16 +115,14 @@ export async function resolveLayers(
 	);
 }
 
-async function walkLayer(
-	layer: Layer,
-): Promise<Array<{ type: ComponentType; segments: string[] }>> {
+async function walkLayer(layer: Layer): Promise<Descriptor[]> {
 	const sourceRoot = join(layer.path, "src");
 	if (!(await exists(sourceRoot))) return [];
 	const perType = await Promise.all(
 		TYPE_NAMES.map(async (type) => {
 			const typeDir = join(sourceRoot, type);
 			if (!(await exists(typeDir))) return [];
-			return walkType(typeDir, type, [type]);
+			return walkType(typeDir, type, [type], [type]);
 		}),
 	);
 	return perType.flat();
@@ -97,30 +132,80 @@ async function walkType(
 	directory: string,
 	type: ComponentType,
 	segments: string[],
-): Promise<Array<{ type: ComponentType; segments: string[] }>> {
+	dir: string[],
+): Promise<Descriptor[]> {
 	const entries = await readdir(directory, { withFileTypes: true });
 	const directories = entries.filter((entry) => entry.isDirectory());
+	// We're "inside a component" (rather than at a type root) when the last
+	// segment names a component rather than a type. Only there is `block/` a
+	// face marker — at a type root it's just a component literally named "block".
+	const inComponentContext = !(TYPE_NAMES as readonly string[]).includes(
+		segments[segments.length - 1] ?? "",
+	);
 
 	const nested = await Promise.all(
 		directories.map(async (entry) => {
 			const subdirectory = join(directory, entry.name);
 
-			// Nested type marker (e.g. `components/` under a section) shifts type
-			// and namespace.
+			// Nested type marker (e.g. `components/` under a section, or the plural
+			// `blocks/` holding private children) shifts type and namespace.
 			if ((TYPE_NAMES as readonly string[]).includes(entry.name)) {
-				return walkType(subdirectory, entry.name as ComponentType, [
-					...segments,
-					entry.name,
-				]);
+				return walkType(
+					subdirectory,
+					entry.name as ComponentType,
+					[...segments, entry.name],
+					[...dir, entry.name],
+				);
+			}
+
+			// Singular `block/` face marker: zero-segment. Retarget type to
+			// "blocks" and reroot file lookup inside `block/`, but leave the naming
+			// segments alone. Empty `block/` dirs resolve to nothing and are dropped.
+			// Only snippets (`type === "components"`) get a face — a section or
+			// block sprouting one would share its parent's `type:segments` key and
+			// collide. (At a type root `inComponentContext` is false, so this can't
+			// fire on a top-level component literally named "block".)
+			if (
+				entry.name === FACE_MARKER &&
+				inComponentContext &&
+				type === "components"
+			) {
+				const face: Descriptor = {
+					type: "blocks",
+					segments: [...segments],
+					dir: [...dir, entry.name],
+					face: true,
+				};
+				const deeper = await walkType(
+					subdirectory,
+					type,
+					[...segments],
+					[...dir, entry.name],
+				);
+				return [face, ...deeper];
 			}
 
+			// Nested component.
 			const componentSegments = [...segments, entry.name];
+			const componentDir = [...dir, entry.name];
 			const liquidPath = join(subdirectory, `${entry.name}.liquid`);
-			const here = (await exists(liquidPath))
-				? [{ type, segments: componentSegments }]
+			const here: Descriptor[] = (await exists(liquidPath))
+				? [
+						{
+							type,
+							segments: componentSegments,
+							dir: componentDir,
+							face: false,
+						},
+					]
 				: [];
 
-			const deeper = await walkType(subdirectory, type, componentSegments);
+			const deeper = await walkType(
+				subdirectory,
+				type,
+				componentSegments,
+				componentDir,
+			);
 			return [...here, ...deeper];
 		}),
 	);
@@ -130,11 +215,11 @@ async function walkType(
 
 async function firstExisting(
 	layers: Layer[],
-	segments: string[],
+	dir: string[],
+	anchor: string,
 	extension: string,
 ): Promise<ComponentSource | undefined> {
-	const last = segments[segments.length - 1];
-	const relativePath = join("src", ...segments, `${last}${extension}`);
+	const relativePath = join("src", ...dir, `${anchor}${extension}`);
 	const candidates = await Promise.all(
 		layers.map(async (layer) => ({
 			layer,

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@augeo/smelt",
-	"version": "1.2.3",
+	"version": "1.3.0",
 	"description": "Library + CLI for building Shopify themes from a colocated component tree",
 	"license": "MIT",
 	"type": "module",