From dbc617698c471c39f423a62d91dd4f47f3d4faa9 Mon Sep 17 00:00:00 2001 From: bdeshi Date: Thu, 30 Jul 2026 10:36:16 +0600 Subject: [PATCH] record ADR-0037: a fragment receives Fragment{Args, Items} MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit gallery is the second fragment and needs a list of filenames, which the current map[string]string cannot carry. The theme contract says fields are added but never renamed, so widening the shape costs one commit today and a contract version once a theme exists — this is the last cheap moment. Naming the argument map also stops arguments and gathered data colliding: a call with a src argument beside a feature-supplied src would otherwise silently pick one. figure becomes .Args.src. --- docs/decisions.md | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/docs/decisions.md b/docs/decisions.md index cb7cc8e..5103186 100644 --- a/docs/decisions.md +++ b/docs/decisions.md @@ -461,3 +461,20 @@ template, and the escaping is the standard library's rather than ours. Expensive only. Revisit if: a shortcode needs to emit something no template can express. That is an argument for a new contract field, not for the engine writing HTML. + +## ADR-0037 — A theme fragment receives a Fragment, not a bare argument map +Date: 2026-07-30 · Status: accepted (widens ADR-0036's `Partial`, before any theme exists) +Decision: a fragment template receives `Fragment{Args, Items}` — `.Args` being the call's `key="value"` +pairs and `.Items` a list the feature gathered, such as the filenames a gallery found. So `figure` reads +`.Args.src` rather than `.src`. A feature that needs to hand over something neither string nor list of +strings is a reason to add a field here, never to reach for `any`. +Why: `gallery` is the second fragment and it needs a list, which a `map[string]string` cannot carry. The +shape had to widen either now or after a theme existed, and `theme-contract.md` says fields are added but +never renamed — so doing it before there is a theme costs one commit, and doing it later costs a contract +version. Naming the argument map keeps arguments and gathered data from colliding: a call with a `src` +argument and a feature-supplied `src` would otherwise silently pick one. +Consequence: cheap — one struct to widen when a third kind of data appears, and templates say which side of +the data they mean. Expensive — the embedded fragments and this document change together, and every future +fragment carries one extra hop (`.Args.`) for a clarity that only pays off from the second fragment on. +Revisit if: a feature needs structured items rather than strings — a gallery of images with captions and +dimensions, most likely at image derivatives. Then `Items` becomes a slice of a named struct, additively.