@augeo/smelt 1.2.2 → 1.3.0

package/docs/build-spec.md

@@ -117,10 +117,10 @@ aliases (modeled on Next.js / TypeScript path conventions):
 
 <!-- prettier-ignore -->
 ```liquid
-{# inside src/sections/hero/hero.liquid: #}
+{% # inside src/sections/hero/hero.liquid: %}
 
-{% render './components/foo' %}        {# nested child of hero       #}
-{% render '@/components/button' %}     {# top-level shared component #}
+{% render './components/foo' %}        {% # nested child of hero %}
+{% render '@/components/button' %}     {% # top-level shared component %}
 ```
 
 Both rewrite to namespaced output names:
@@ -133,7 +133,8 @@ Both rewrite to namespaced output names:
 Hand-written snippets remain referenceable by their bare name as usual:
 
 ```liquid
-{% render 'icon-cart' %} {# unchanged — resolves to snippets/icon-cart.liquid #}
+{% render 'icon-cart' %}
+{% # unchanged — resolves to snippets/icon-cart.liquid %}
 ```
 
 ### TS / CSS — colocated and implicit
@@ -249,6 +250,97 @@ The parent section or block's schema auto-merges these private children into its
 prepended, any blocks the author explicitly lists (e.g. globally-shared block
 types) appended after. No helper call required.
 
+### Block faces — nested `block/`
+
+A `src/components/*` component is a snippet — reusable through
+`{% render '@/components/...' %}`, but invisible to the theme editor. A **block
+face** exposes that same component as a theme block a merchant can add, without
+duplicating it. It's declared structurally: a singular `block/` directory nested
+inside the component.
+
+```
+src/components/image/
+├── image.liquid              # the reusable snippet
+├── image.css
+└── block/
+    └── image.schema.ts       # the block face's schema
+```
+
+Compiles to **both**:
+
+```
+snippets/built--components--image.liquid   # the snippet, unchanged
+blocks/built--components--image.liquid     # the block face
+```
+
+`block/` is a **zero-segment marker**. Unlike the plural `blocks/` type marker
+(which contributes a `blocks` segment and holds private children), singular
+`block/` contributes nothing to the naming segments — it only retargets the
+component's type to `blocks` and reroots file lookup inside `block/`. That's why
+the face is named `built--components--image` (after the parent), not
+`…--image--block`, and why it lands in `blocks/` rather than `snippets/`. The
+face's anchor files are named after the **parent** component (`image.liquid`,
+`image.schema.ts`), so the source basename still equals the output token, as
+everywhere else.
+
+> Note the singular/plural distinction: `block/` (one face) vs `blocks/` (many
+> private children). They can nest — see the `tabs` example below.
+
+The face's schema is authored exactly like any block schema — a sibling
+`image.schema.ts` exporting `schema` (via `defineSchemaBlock`). It needs no new
+concepts; the `block/` directory is the only signal.
+
+**Mechanical vs. override.** Two ways to author the face body:
+
+- **Mechanical (schema only).** With just `block/<name>.schema.ts` and no
+  `block/<name>.liquid`, the engine **synthesizes** the wrapper: it renders the
+  underlying component, mapping each schema setting to a render arg of the same
+  name (`id == arg`) and passing `shopify_attributes` through. This covers the
+  common case where every setting maps 1:1 to a prop.
+
+  ```liquid
+  {%- comment -%} GENERATED … {%- endcomment -%}
+  {% render 'built--components--image',
+  	src: block.settings.src,
+  	shopify_attributes: block.shopify_attributes
+  %}
+  {% schema %}…{% endschema %}
+  ```
+
+  Because the mechanism is `id == arg`, **name the component's props to match
+  the setting ids.** There is no mapping table.
+
+- **Override (`block/<name>.liquid`).** When the wrapper isn't mechanical —
+  derived props, conditional logic, or passing `children: block.blocks` — drop a
+  `block/<name>.liquid` and the engine uses it as the body verbatim (rewriting
+  its `@/...` renders, stamping the banner, injecting the schema). The face is
+  then just a normal block component living in `block/`, so it may also carry
+  its own `block/<name>.ts` / `block/<name>.css`.
+
+**Private children of a face.** Because private children belong to the block —
+not the snippet — they nest under the face via the plural `blocks/` marker:
+
+```
+src/components/tabs/
+├── tabs.liquid
+└── block/
+    ├── tabs.liquid           # override — renders children: block.blocks
+    ├── tabs.schema.ts
+    └── blocks/
+        └── tab/
+            ├── tab.liquid
+            └── tab.schema.ts
+```
+
+The singular `block/` adds no segment and the plural `blocks/` adds `blocks`, so
+the child resolves to `_built--components--tabs--blocks--tab` and auto-merges
+into the face's `blocks: [...]` — the existing private-block machinery,
+unchanged.
+
+A mechanical face requires the underlying snippet to exist (it renders it); if
+the snippet is missing the render won't resolve. A thing that is purely a block
+with no reusable-snippet angle should just live in `src/blocks/`.
+
 ## Build Pipeline
 
 The engine lives in `lib/build/build.ts` and is invoked by `lib/cli.ts` (a citty
@@ -266,8 +358,11 @@ rebuilds the bin and `npm run test:all` runs the full integration chain against
    `sections/`, `snippets/`, and `blocks/`. Output is regenerated from scratch
    on every build, so removed source components disappear cleanly. Hand-written
    files without the prefix are untouched.
-3. **For each component** (anything with a `.liquid`):
-   - Prepend a `{%- comment -%}` banner naming the source file, for tracing.
+3. **For each component** (anything with a `.liquid`, plus mechanical block
+   faces anchored on a schema alone — see
+   [Block faces](#block-faces--nested-block)):
+   - Prepend a `{%- comment -%}` banner naming the source file (the `.liquid`,
+     or for a mechanical face its `.schema.ts`), for tracing.
    - Bundle `<name>.ts` (esbuild, IIFE, utilities inlined) → string.
    - Read `<name>.css` as-is (no transform today — see TODO).
    - Execute `<name>.schema.ts` — esbuild → `data:` URL → dynamic `import()`,
@@ -277,7 +372,10 @@ rebuilds the bin and `npm run test:all` runs the full integration chain against
    - Auto-merge any immediate private `blocks/` children into the loaded
      schema's `blocks: [...]` array (see
      [Private blocks](#private-blocks--nested-blocks)).
-   - Transform `<name>.liquid`:
+   - Produce the body — either the source `<name>.liquid`, or, for a mechanical
+     block face (no `.liquid`), a synthesized wrapper that renders the
+     underlying component with each schema setting mapped to a render arg and
+     `shopify_attributes` passed through. Then:
      - **Error** if the source `.liquid` contains an inline `{% schema %}` block
        — schemas must live in `<name>.schema.ts`.
      - Rewrite `{% render '@/...' %}` and `{% render './...' %}` to namespaced

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>