@augeo/smelt 1.2.2 → 1.3.0

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/lib/schema.ts

@@ -13,25 +13,23 @@ import type { ThemeBlockSchema } from "./schema-block.generated.ts";
 import type { SectionSchema } from "./schema-section.generated.ts";
 
 /**
- * Identity helper for authoring a Shopify section schema. The `const T`
- * parameter preserves literal types so the schema author gets autocomplete
- * for setting `type` values, `id`s, etc.
+ * Identity helper for authoring a Shopify section schema. Typing the parameter
+ * as `SectionSchema` directly (rather than a generic `<const T>`) gives the
+ * author both autocomplete for `type` values, `id`s, etc. and excess-property
+ * checking — a bare type parameter would silently accept unknown keys.
  *
  * Use in `<name>.schema.ts` files under `src/sections/`.
  */
-export function defineSchemaSection<const T extends SectionSchema>(
-	schema: T,
-): T {
+export function defineSchemaSection(schema: SectionSchema): SectionSchema {
 	return schema;
 }
 
 /**
- * Identity helper for authoring a Shopify theme-block schema.
+ * Identity helper for authoring a Shopify theme-block schema. See
+ * {@link defineSchemaSection} for why the parameter is typed directly.
  *
  * Use in `<name>.schema.ts` files under `src/blocks/`.
  */
-export function defineSchemaBlock<const T extends ThemeBlockSchema>(
-	schema: T,
-): T {
+export function defineSchemaBlock(schema: ThemeBlockSchema): ThemeBlockSchema {
 	return schema;
 }

package/package.json

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