@augeo/smelt 1.2.3 → 1.3.0

package/docs/js-modules-plan.md

@@ -0,0 +1,278 @@
+---
+status: draft
+---
+
+# JavaScript Module Delivery
+
+Plan for how a component's JavaScript reaches the browser as **shared ES
+modules** instead of per-component inlined bundles, so a dependency used by N
+components ships once. Companion to [`build-spec.md`](./build-spec.md) (which
+describes today's `{% javascript %}` inlining) and a direct answer to its
+standing TODO, _"Utility deduplication across component bundles."_
+
+This doc is deliberately scoped to the **JS delivery strategy** — modules,
+import maps, deduplication, and load placement. It is **not** about web
+components, which are an optional authoring style that rides on top of
+everything here and stays out of scope (see [Out of Scope](#out-of-scope)). The
+two are orthogonal: every byte-level win below comes from modules + import maps,
+not from custom elements.
+
+## The problem this solves
+
+Today `bundleJs` (`lib/build/build.ts`) runs each component's `<name>.ts`
+through esbuild with `bundle: true`, format `iife`, and inlines the result into
+a `{% javascript %}` block. esbuild does not distinguish a `src/utilities/`
+import from a `node_modules` import — it inlines **both** into that component's
+IIFE. So:
+
+- Two components importing `debounce` from `lodash-es` each ship their own copy.
+- The same is true for any shared `src/utilities/` helper.
+
+Crucially, **Shopify does not rescue us here.** Its `{% javascript %}`
+deduplication is keyed on the _file_, not the _content_: `{% javascript %}`
+blocks are concatenated into one bundle per file type (`scripts.js` /
+`block-scripts.js` / `snippet-scripts.js`), and _"bundled assets are only
+injected once for each section, block or snippet file, not for each instance of
+that file."_ That dedupes **instances of one component**, but two **different**
+built files with byte-identical content produce two copies in the concatenated
+bundle. The duplication is real and grows linearly with no platform relief.
+
+## Goal
+
+Let a component author write the most boring thing possible —
+
+```ts
+import { debounce } from "lodash-es";
+import { formatMoney } from "@/utilities/money";
+```
+
+— and have the build deliver `lodash-es` and `money` as **shared module assets
+imported by URL**, so the browser fetches and caches each exactly once across
+every component that uses it. The colocated authoring model
+(`button/{button.liquid,button.ts,button.css}`), the layer/resolver system, and
+the `@/` alias all stay exactly as they are. Only the _packaging and delivery_
+of the compiled JS changes.
+
+## The shape
+
+### 1. Each component's JS compiles to a module asset
+
+`<name>.ts` is bundled as an **ES module** written to `assets/`, named with the
+same `built--<segments>` scheme used everywhere else:
+
+```
+src/components/button/button.ts
+  → assets/built--components--button.js
+```
+
+The component's `.liquid` no longer carries an inlined `{% javascript %}` block;
+its behavior lives in the module asset and is loaded as
+`<script type="module" src="{{ 'built--components--button.js' | asset_url }}">`
+(see [Load placement](#3-load-placement--scoped-vs-global)).
+
+### 2. Shared code is imported, not inlined — and an import map dedupes it
+
+Shared `src/utilities/*` and external `node_modules` packages are marked
+`external` to esbuild (not inlined). They become real `import` statements
+resolved at runtime through a generated **import map**. Because the browser
+caches modules by resolved URL, a utility imported by ten components is fetched,
+parsed, and evaluated **once**.
+
+The import map is the runtime twin of Smelt's build-time `@/` alias — the same
+move Shopify's flagship Horizon theme makes with its `@theme/` alias. The build
+emits a snippet, e.g. `snippets/built--scripts.liquid`:
+
+```liquid
+<script type="importmap">
+	{
+		"imports": {
+			"@/utilities/money": "{{ 'built--utilities--money.js' | asset_url }}",
+			"lodash-es": "{{ 'built--vendor--lodash-es.js' | asset_url }}"
+		}
+	}
+</script>
+```
+
+The consumer renders that snippet once. Thanks to Shopify's
+[resilient import maps](https://shopify.engineering/resilient-import-maps) work,
+**multiple import maps merge and are loading-order independent**, so Smelt's
+generated map coexists with a consumer's (or Horizon's) without owning a single
+canonical `<head>` slot — and Shopify auto-injects the `es-module-shims`
+polyfill for browsers lacking native support. This is what keeps the approach
+**additive**: we emit a `built--` snippet, we never edit the consumer's
+`layout/`.
+
+### 3. Load placement — scoped vs global
+
+Import maps resolve specifiers to URLs; they do **not** decide _which_ module
+script tags a given page includes. That is a separate, important choice:
+
+- **Global registry** (Horizon's default): one snippet lists every component's
+  `<script type="module">`, included on every page. Simple, fully robust against
+  the merchant composing any component into any section at runtime — but it
+  **downloads, parses, and evaluates the JS for unused components on every
+  page.** (A web-component definition's `connectedCallback` won't _run_ without
+  its tag present, but the module is still shipped, parsed, and registered. WC
+  saves execution, not loading.)
+- **Section-scoped loading** (recommended — Smelt's compiler edge): because the
+  build rewrites every `{% render %}`, it knows which components a section pulls
+  in. Emit a component's `<script type="module">` **with the section/snippet
+  that renders it**, so the module loads only on pages where that section is
+  present. Page weight tracks components _actually rendered_, not the total
+  catalog.
+
+The safe granularity for scoping is **"section/block presence," not "page"** —
+runtime composition (theme editor adding blocks) means the build can prove "this
+section renders a button" but not "this rendered page has no button." Scoping to
+the rendering unit stays correct under dynamic composition.
+
+These are not mutually exclusive — a global registry for a small core plus
+section-scoped loading for the rest mirrors what Horizon actually ships.
+
+### 4. Tree-shaking comes from the build, not the import map
+
+An import map only maps specifier → URL; it neither bundles nor shakes. Real
+dead-code elimination and shared-chunk extraction come from running esbuild with
+`format: "esm"` and `splitting: true` over the component graph, so the **union**
+of used exports lands in shared chunks and unused code is dropped. Shipping
+whole-package vendor modules is the acceptable first cut; splitting is the
+optimization when measured weight justifies it.
+
+### 5. External npm packages use the same path
+
+There is no separate mechanism for third-party modules. A `node_modules` package
+is externalized, emitted (or referenced) as a module asset, and mapped in the
+import map — exactly like a `src/utilities/` helper. A package can even map
+straight to a vendor CDN URL (Horizon maps `@shopify/events` to a
+`cdn.shopify.com` URL this way) when self-hosting isn't wanted.
+
+## How this interacts with `{% javascript %}`
+
+`{% javascript %}` content is a classic IIFE; an import map only governs
+**module** resolution. Static `import` is illegal in that context, so the two do
+not mix at the statement level. **Mix at the component boundary instead:**
+
+- A component with **no shared dependency** can stay an inlined
+  `{% javascript %}` block (today's model — simple, no asset proliferation).
+- A component that **imports a shared utility or external package** graduates to
+  a module asset.
+
+The switch is the _presence of a shared import_. Do not try to make a single
+component half-classic / half-module — that forces transforming static imports
+into awaited dynamic `import()` and silently makes init async. Keep each
+component wholly one or the other.
+
+## Design Decisions
+
+### Modules + import map over a shared global or per-utility snippet guard
+
+The build-spec TODO lists three candidates: a single
+`assets/built--utilities.js` on a global, ES modules via an import map, and
+per-utility snippet guards. This plan selects **ES modules via an import map**.
+
+- **Why:** the browser dedupes by URL natively (execute-once-per-URL), import
+  order is resolved by the module graph rather than by a fragile load-order
+  convention, scoping is clean, and it is the idiomatic modern-Shopify path
+  (Horizon is built on it). The global-bundle option pollutes a namespace and
+  couples load order; the snippet-guard option leans on a `window.__smelt`
+  namespace plus a `DOMContentLoaded` discipline.
+- **Cost:** component init becomes async-_loaded_ (gated on the import graph),
+  and the approach depends on Shopify's recent resilient-import-maps platform
+  work. Ordering, by contrast, becomes a module-system _guarantee_ rather than a
+  discipline — a net improvement on the axis we care about.
+
+### Delivery is build-internal; the authoring contract is not
+
+Moving from inlined IIFE to module asset is a change to **how the build packages
+the same source** — the author's `.ts` is unchanged for plain "enhance-the-DOM"
+code. That makes this migration cheap, reversible, and deferrable. The
+expensive, distributed change is anything that touches the **public authoring
+contract** (e.g. mandating web components). Keep delivery swappable and the
+authoring contract deliberate.
+
+- **Why:** preserves the option to adopt — or never adopt — web components
+  without a rewrite.
+- **Cost:** none today; it is a constraint on how we _describe_ the contract.
+
+### Keep component JS idempotent DOM enhancement
+
+Author component JS as side-effect-light, presence-checking, idempotent DOM
+enhancement (find my elements, enhance them) rather than "run once at load,
+mutate globals."
+
+- **Why:** that single habit slots cleanly into a section-scoped plain-module
+  world _and_ a web-component (`connectedCallback`) world later, with no
+  rewrite. It is also what survives theme-editor section re-renders.
+- **Cost:** a mild authoring discipline, already implied by "no Liquid inside
+  `{% javascript %}`" (component JS is already Liquid-free and
+  attribute-driven).
+
+## Out of Scope
+
+- **Web components.** Custom elements are an optional authoring style layered on
+  top of this. They buy ergonomics (auto-hydrate by tag presence, editor-safe
+  re-init) — **not** the byte/cache/dedup wins, which are all delivered here.
+  They are a separate decision with its own (public, breaking) contract cost.
+- **CSS deduplication.** `{% stylesheet %}` has the same per-file model; whether
+  shared CSS wants the same module-style treatment is its own discussion.
+- **Lazy / dynamic `import()` on interaction or visibility.** A real further win
+  for avoiding unused-component load, but a separate strategy from static module
+  delivery. Note and defer.
+- **`props.ts` runtime validation** and other open `build-spec.md` questions.
+
+## Implementation Outline
+
+Concrete-but-not-final list of where changes land:
+
+1. **`lib/resolver.ts`** — utilities (and externalized vendor packages) need to
+   be addressable as emittable module assets, not only as inlined imports.
+   Likely a utility slot that produces output, plus a way to enumerate the
+   external packages referenced across the component graph.
+2. **`lib/build/build.ts`**
+   - **`bundleJs`** — switch the component path from `format: "iife"` inlined
+     string to `format: "esm"` written to `assets/built--<segments>.js`, with
+     `external` covering `@/utilities/*` and bare `node_modules` specifiers.
+     Consider one `splitting: true` invocation over all module entry points for
+     cross-component tree-shaking + shared chunks.
+   - **`buildComponent`** — stop appending `{% javascript %}` for module
+     components; instead record the component's module asset + import-map entry,
+     and (for section-scoped loading) emit its `<script type="module">` into the
+     rendering unit.
+   - **import-map generation** — new step producing
+     `snippets/built--scripts.liquid` from the resolved utility + vendor set.
+   - **`cleanBuiltOutputs`** — extend the `/^_?built--/` sweep to `assets/` for
+     emitted `.js` (overlaps with [`assets-plan.md`](./assets-plan.md)).
+3. **`docs/build-spec.md`** — note that component JS may be delivered as a
+   module asset; cross-reference this plan from the dedup TODO.
+4. **`example/`** — two components importing the same `lodash-es` function plus
+   a shared `src/utilities/*` helper; verify the dep lands once in `assets/`,
+   appears once in the import map, theme-check passes, and assay browser tests
+   resolve the module assets.
+5. **Tests** — `lib/build/build.test.ts`: module-asset emission, import-map
+   contents, externalized-vs-inlined import handling, and the
+   `{% javascript %}`-vs-module component-boundary switch. Testing harness note:
+   assay/liquidjs must resolve module assets via `assetsPath` / the import map —
+   see [`TESTING.md`](./TESTING.md).
+
+## Open Questions
+
+- **De-risk the externalization first.** The keystone is esbuild's handling of
+  `external` packages in module output and how the import-map entry resolves
+  them at runtime. Worth a throwaway prototype against `example/` before
+  committing — confirm a shared dep rewrites cleanly and lands once.
+- **Whole-package vs union tree-shaking for vendors.** Ship the whole package
+  entry first, or compute the union of used exports across components from the
+  start? Whole-entry is simpler; union preserves shaking. Lean simple, measure,
+  optimize.
+- **Default load placement.** Global registry (simplest, robust) vs
+  section-scoped (lighter pages, needs compiler wiring) vs a hybrid. Likely
+  hybrid, but the default and the authoring surface for opting in need a
+  decision.
+- **Multiple versions of one package.** If two deps pin different versions of
+  the same package, one import-map specifier collides. Assume one version per
+  name in v1 and **fail loudly** if violated rather than silently serving the
+  wrong one (consistent with the no-silent-overwrite stance).
+- **Uniform vs mixed output.** Is it acceptable for some components to emit
+  inlined `{% javascript %}` and others module assets, based on whether they
+  import shared code? More powerful, but a consumer debugging built output sees
+  two shapes. Uniformity has its own value.

package/example/blocks/built--components--card.liquid

@@ -0,0 +1,34 @@
+{%- comment -%}
+	GENERATED FROM consumer/src/components/card/block/card.schema.ts — do not edit this file directly.
+	Edit the source and run `npm run build`.
+{%- endcomment -%}
+
+{% render 'built--components--card',
+	title: block.settings.title,
+	body: block.settings.body,
+	shopify_attributes: block.shopify_attributes
+%}
+
+{% schema %}
+{
+  "name": "Card",
+  "settings": [
+    {
+      "type": "text",
+      "id": "title",
+      "label": "Title",
+      "default": "Untitled"
+    },
+    {
+      "type": "textarea",
+      "id": "body",
+      "label": "Body"
+    }
+  ],
+  "presets": [
+    {
+      "name": "Card"
+    }
+  ]
+}
+{% endschema %}

package/example/snippets/built--components--card.liquid

@@ -8,7 +8,7 @@
 	assign body = body | default: ''
 -%}
 
-<article class="tr-card">
+<article class="tr-card" {{ shopify_attributes }}>
 	<h3 class="tr-card__title">{{ title }}</h3>
 	<p class="tr-card__body">{{ body }}</p>
 </article>

package/example/src/components/card/block/card.schema.ts

@@ -0,0 +1,14 @@
+import { defineSchemaBlock } from "@augeo/smelt/schema";
+
+// A mechanical block face: no `card.liquid` override here, so the build
+// synthesizes the wrapper render from these settings (id → render arg) and
+// passes `shopify_attributes` through. The card snippet stays reusable via
+// `{% render '@/components/card' %}`; this just also exposes it in the editor.
+export const schema = defineSchemaBlock({
+	name: "Card",
+	settings: [
+		{ type: "text", id: "title", label: "Title", default: "Untitled" },
+		{ type: "textarea", id: "body", label: "Body" },
+	],
+	presets: [{ name: "Card" }],
+});

package/example/src/components/card/card.liquid

@@ -3,7 +3,7 @@
 	assign body = body | default: ''
 -%}
 
-<article class="tr-card">
+<article class="tr-card" {{ shopify_attributes }}>
 	<h3 class="tr-card__title">{{ title }}</h3>
 	<p class="tr-card__body">{{ body }}</p>
 </article>

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