# Per-fragment fixture bundles How a reusable chart fragment carries its own executable examples, so a palette entry can show a "test this step" panel of its own rather than borrowing a whole chart's fixtures. This is the convention `sui-13q` settles. It adds no new fixture shape: everything below is the ADR-0003 bundle with ADR-0006's `datasets` and `expressions` keys, addressed by **fragment name** instead of by chart path. Read those two records for why the shapes are what they are; read this page for how one travels with a fragment. ## The problem this solves ADR-0003 pairs a bundle with a chart. A chart at `authorization.scxml` carries `authorization.fixtures.json` beside it, and every consumer downstream of the loader gets one `StatifierUI.Fixtures` struct whichever delivery path produced it. An embedder composing charts from a palette of reusable fragments has no such file to sit beside. The fragment is a module in the host's code, or an entry in a palette the host assembles at runtime, and the chart it will eventually be dropped into does not exist yet. Its examples still want to travel with it: an author picking "Authorize a card" out of a palette wants to see what that step's guard evaluates to under a transaction inside the account's budget and one over it, before committing to it and without authoring a chart first. `StatifierUI.Fixtures.Bundle` is that: a `StatifierUI.Fixtures` struct plus the fragment's name and a record of where it came from. ## The convention A fragment supplies its bundle by answering a zero-arity callback - `fixtures/0` by default - with any of four spellings. | Spelling | Recognized by | Validated through | |---|---|---| | `%StatifierUI.Fixtures{}` | the struct | already validated at construction | | `%{scenarios: ..., events: ..., datasets: ..., expressions: ...}` | **atom** top-level keys | `StatifierUI.Fixtures.new/1` | | `%{"version" => 1, "datasets" => ...}` | **string** top-level keys | `StatifierUI.Fixtures.Sidecar.from_json/2` | | `"palette/authorize.fixtures.json"` | a binary path | `StatifierUI.Fixtures.Sidecar.load/1` | The atom-versus-string top-level key is the whole discriminator. Atom keys are the Elixir spelling a host writes by hand in a module; string keys are the JSON spelling that survives a file. ADR-0003 requires both delivery paths to converge on one struct rather than one to be primary, and this keeps that true one level up. A map mixing the two is rejected as `:mixed_bundle_keys` rather than guessed at. **Unknown top-level keys behave differently by spelling, on purpose.** The JSON spelling keeps the sidecar's ignore-unknown-keys discipline (ADR-0006), so a file written by a newer producer still loads and reports what it ignored. The Elixir spelling rejects an unknown atom key, because an atom key in a host's own module is compiled code the author is looking at, and a silently ignored `:datsets` typo there is a bundle reporting zero datasets with no reason why. Forward compatibility is a property of a wire format, not of a function call. A fragment that ships no examples at all is never an error. Discovery reports it as an absence. ## Fragment names and invoke types are two namespaces A fragment name here is spelled with a **dot** - `myapp.authorize`. The family's invoke types are spelled with a **colon** - `myapp:authorize`. That is not a typo on either side, and the difference is load-bearing. The operator's ruling of 2026-08-27 settles it: > D5) two namespaces, with a documented one-to-one mapping convention. So: **two namespaces**, and this is the documented mapping convention. - A **fragment name** (`myapp.authorize`) names an entry in a palette. It is the key `Bundle.load/2` and `Bundle.discover/1` are given, the name a bundle is reported under, and - via `name_from_path/1` - the stem of a sidecar filename. It is an *authoring-surface* identifier: what an author picks out of a palette. - An **invoke type** (`myapp:authorize`) names something the engine can invoke at runtime. It is an *execution* identifier, resolved through the per-session invoke registry, and it is statifier-ex's contract, not this package's. Both spellings are ``, and the mapping between them is one to one in both directions: **swap the separator, change nothing else**. `myapp.authorize` is the palette entry for the invoke type `myapp:authorize`; `myapp:capture` is invoked by the fragment named `myapp.capture`. The namespace segment and the local name are identical character for character, so the mapping is total and mechanical - there is no lookup table, and there is nothing for a host to configure. Two consequences worth stating, because they are what the convention buys: - **A dot is the only separator a fragment name uses**, and a colon never appears in one. Filenames are why: a sidecar is named for its fragment, and a dot survives every filesystem and every archive format a palette travels through. A fragment name carrying more than one dot has no invoke counterpart under this convention. - **A fragment need not be invoke-backed at all.** A fragment that expands to ordinary SCXML rather than to an `` has a name and no invoke type, and that is not a gap - the mapping is one to one over the invoke-backed fragments, not over every palette entry. Nothing here requires a host to mint an invoke type for a fragment that does not need one. Neither namespace is derived from the other at runtime. This package never turns a fragment name into an invoke type or back; the convention is a rule for humans naming things, so that a reader seeing `myapp.authorize` in a palette and `myapp:authorize` in a trace knows without asking that they are the two faces of one step. ## Wiring a palette entry A host's fragment type - a block type, a step type, whatever the host calls it - answers the callback: The corpus below is the card-processing one, deliberately **not** the signup-wizard corpus that `test/support/fixtures/expressions.fixtures.json` carries and ADR-0006 illustrates with. A fragment's bundle is self-contained by construction (see the last bullet of this page), so a fragment gets the corpus its own domain calls for; the two are canonical example domains, not a primary and a variant. Both stay inside the family's two domains - card processing, and a signup wizard with A/B testing - and nothing here reads a chart-level corpus to build a fragment-level one. ```elixir defmodule MyApp.Blocks.Authorize do @doc "Executable examples for this palette entry." def fixtures do %{ datasets: %{ "within-budget" => %{ "transaction" => %{"amount" => 14, "currency" => "USD"}, "account" => %{"budget_remaining" => 500} }, "over-budget" => %{ "transaction" => %{"amount" => 900, "currency" => "USD"}, "account" => %{"budget_remaining" => 500} } }, expressions: %{ "exceeds-budget" => %{ "source" => "transaction.amount > account.budget_remaining", "expect" => %{"within-budget" => false, "over-budget" => true} } } } end end ``` Load one fragment's bundle directly: ```elixir {:ok, bundle} = StatifierUI.Fixtures.Bundle.load("myapp.authorize", MyApp.Blocks.Authorize.fixtures()) ``` Or discover every fragment's bundle across the palette at once: ```elixir palette = %{ "myapp.authorize" => MyApp.Blocks.Authorize, "myapp.capture" => MyApp.Blocks.Capture, "myapp.assign_variant" => MyApp.Blocks.AssignVariant, "myapp.signup" => MyApp.Blocks.Signup } discovery = StatifierUI.Fixtures.Bundle.discover(palette) discovery.bundles # loaded, sorted by name discovery.without # ["myapp.signup"] - ships no examples, which is fine discovery.errors # [{name, reason}] - meant to load, did not ``` Discovery is never all-or-nothing. One fragment's malformed bundle is reported against that fragment's name and every other fragment still loads, because a palette is exactly the setting where one bad entry hiding every good one is least useful. A callback that *raises* is caught the same way, for the same reason. ## Fragments that travel as files The other delivery path needs no host code at all. Put a directory of sidecars beside the fragments they describe, one file per fragment, named for it: ``` palette/ authorize.fixtures.json capture.fixtures.json README.md ``` ```elixir {:ok, discovery} = StatifierUI.Fixtures.Bundle.discover_dir("palette") Enum.map(discovery.bundles, & &1.name) #=> ["authorize", "capture"] ``` Each bundle is named after its file with the `.fixtures.json` suffix stripped (`StatifierUI.Fixtures.Bundle.name_from_path/1`), so a fragment named `myapp.assign_variant` is a file named `myapp.assign_variant.fixtures.json`. Files that are not sidecars are ignored rather than reported. The directory is not walked recursively: a palette directory is a flat list of fragments, and a nested one is a second palette rather than a deeper part of this one. This is the corpus and CLI half of ADR-0003's two-paths rule, and it is what lets a palette of fragments move between repositories - or to a non-Elixir consumer - with nothing but plain JSON. ## The test panel `StatifierUI.Fixtures.Bundle.Markdown.render/2` renders one bundle as its panel, and `StatifierUI.Kino.test_panel/2` wraps that for a Livebook cell: ```elixir {:ok, bundle} = StatifierUI.Fixtures.Bundle.load("myapp.authorize", MyApp.Blocks.Authorize.fixtures()) StatifierUI.Kino.test_panel(bundle) ``` The panel is deliberately both halves of the fixture contract at once: - the **truth table** (`StatifierUI.TruthTable`) - what every expression actually evaluates to under every dataset, whether or not an expectation was stated; - the **expectations** (`StatifierUI.Fixtures.Expectations`) - whether every stated `expect` value still holds. Neither alone is enough for a fragment's panel. The table without the expectations says what happens but not what was meant; the expectations without the table confirm a stated belief while staying silent about every expression that stated none. For a whole palette, `render_discovery/2` (or `StatifierUI.Kino.palette_panel/2`) prints one panel per bundle, then names every entry that failed to load. Fragments that ship no examples are not listed - a palette where most fragments carry none is the normal case, and reciting them says nothing a reader can act on. ### The summary counts rather than passes The expectations summary reports four counts and never collapses them into a pass or a fail: ``` 3 matched, 1 mismatched, 0 errored, 1 stated against a dataset this bundle does not carry. ``` That last count is not folded into the others because this package's two consumers of the same fact already disagree about it. `StatifierUI.Fixtures.Expectations.check/2` counts a dangling `expect` key as a failure, since an expectation naming no dataset was never actually checked. `StatifierUI.Fixtures.Lint` reports the same key as a warning, per ADR-0006's severity reasoning. Both are right about their own question; a panel printing one verdict would silently pick a side. Four counts let the reader see which of the two situations they are in. ## Running a palette's expectations in a suite The panel is the reading surface. The checking surface is the same one ADR-0006 already fixed - `StatifierUI.Fixtures.Expectations.check!/2` - now reachable per fragment, so a host's suite goes red naming the fragment whose examples drifted rather than naming a chart: ```elixir defmodule MyApp.PaletteFixturesTest do use ExUnit.Case, async: true alias StatifierUI.Fixtures.Bundle alias StatifierUI.Fixtures.Expectations @discovery Bundle.discover(MyApp.Palette.types()) test "no palette entry's bundle failed to load" do assert @discovery.errors == [] end for bundle <- @discovery.bundles do @bundle bundle test "#{bundle.name} fixture expectations still hold" do Expectations.check!(@bundle.fixtures) end end end ``` ## What this convention does not decide - **Matrix orientation.** `:orientation` is forwarded verbatim to `StatifierUI.TruthTable.Markdown.render/2`, whose own default stands. Nothing here states a preference between the two axes. - **Inner keys of an expression entry.** Keys beyond `"source"` and `"expect"` are preserved verbatim, exactly as the sidecar loader already preserved them. This convention adds no reading of them and no rule about them. - **The `:missing_dataset` severity split** between `Expectations.check/2` and `Fixtures.Lint`, described above. The panel shows both rather than reconciling them. - **Duration-valued datasets**, which `StatifierUI.Fixtures` rejects for the convergence reason its moduledoc gives. A bundle loaded here is validated by exactly that code and inherits exactly that answer. - **Whether a fragment's bundle may reference a chart-level one.** Every bundle here is self-contained. Sharing datasets across fragments, or overlaying a fragment's dataset on a chart's scenario, is ADR-0006's carried overlay question and is untouched by this record.