Current section
Files
Jump to
Current section
Files
statifier_blocks
CHANGELOG.md
CHANGELOG.md
# Changelog
All notable changes to this project will be documented in this file.
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
Entries for unreleased work are not written here directly. Each issue drops a
fragment in [`changelog.d/`](changelog.d/README.md); the fragments are assembled
into a version section at release. See that README for the format and for when a
change warrants an entry at all.
## [0.2.0] 2026-08-29
The editor ships. Campaign 014 graduated the authoring spike into the
package: `StatifierBlocks.Editor` renders from `assets/` with a documented
`--sb-*` theming surface, a drag marks the slots that accept a block and can
say why a slot refused, and a host registers its own block types through
`Palette.from_modules/2`. The `core.*` vocabulary grows by `core.invoke`,
`core.raise`, `core.assign` and `core.send`; the compiler now evaluates
predicator conditions, refuses slot-arity and undeclared-slot violations, and
adapts its findings into the shape the editor renders.
Dependency floor: `statifier ~> 2.2` (was `~> 2.0`); `predicator ~> 9.0` is
now a direct dependency.
### Added
- `core.raise` raises an event for an enclosing group's interrupt rules.
- `core.assign` writes a literal to a datamodel path.
- `docs/theming.md`: the theming guide - the three tiers of the `--sb-*`
surface, the scheme token, per-block-type accents, and a complete host
theme that sets custom properties and nothing else.
- `core.send` sends an event, now or after a delay.
- A block type may declare `slot_outcome_key` in its palette entry, naming the
config key the blocks in one of its slots carry their outcome under, so a
renderer can route an interrupt rule's escape without branching on a type
name; the declaration reaches the view model as `Slot.outcome_key` and the
resolved value as `Node.outcome`.
- `StatifierBlocks.BlockType.slot_outcome_key/2` and
`StatifierBlocks.BlockType.outcome_name/2` read that declaration totally: a
malformed declaration or value is refused rather than repaired, and reads as
no declared outcome.
- A block type may declare `accent_token`, the NAME of a `--sb-*` property,
and the editor stamps it on that type's cards and palette rows. Two rules
in the stylesheet read it; no rule and no module names a block type
(ADR-0005 amendment 14d, consumption side).
- `StatifierBlocks.Finding.severity_class/1`, and `:info` as a third
severity for advisory findings (decision 11, amended 2026-08-29). Nothing
emits one yet; only `:lint` may.
- A form whose config the gate has not accepted names the fields that are
outstanding, says why nothing is stored, and offers "Discard edits". A
draft was never a command, so it cannot be undone - it can only be thrown
away, and that gesture had nowhere to live.
- `:expression` and `:duration` controls carry a placeholder. A bare
`:string` still carries none: there is nothing a type that wide can
suggest.
- A theme audit test over the stylesheet, failing in both directions: a
`var(--sb-*)` with no declaration, and a declared token no rule reads (14e).
- `StatifierBlocks.SlotValidation`, a palette-aware whole-document check for
a block's declared slots (`:undeclared_slot`) and each declared slot's
arity (`:slot_arity_violated`).
- `StatifierBlocks.Predicates` evaluates a condition expression against a
binding context through predicator, returning a boolean or a tagged error.
- `StatifierBlocks.Predicates.TruthTable` builds a checked truth table over
fixture rows, applying first-match-wins arm ordering.
- `StatifierBlocks.Finding.from_compiler/2` and `from_compiler_all/2` adapt a
compiler finding into the presentation shape the editor renders, so a host
can route compile findings through `ViewModel.build/3`.
- `StatifierBlocks.Assignability.seam_reason/4`, `finding_reason/2` and
`seam_reasons/3` name why a data-flow seam came out the way it did:
`:not_assignable` and `{:fixable_by, block_id}` for a refusal, and
`:source_untyped` / `:target_untyped` / `:both_untyped` for a seam that
passed only because a block declared no type. `seam_reasons/3` is how a
host finds the parts of its palette it has not typed yet.
- `StatifierBlocks.Assignability.target_verdicts/4` returns every position
`valid_targets/4` enumerates with its full verdict, and
`StatifierBlocks.Edit.Targets.slot_verdicts/3` projects those to slots -
the accepting ones and the reason each refusing one gives.
- The editor stamps a refused slot's reason as `data-drop-reason` beside
`data-drop`, so a hover affordance can explain a refusal with no
round-trip and no JavaScript.
- A `core.invoke` block type: it names an invoke type for the host to run,
sends datamodel values along as `<param>`s, writes the result where its
`assign_to` names, and takes an optional `on_error` subtree entered on a
permanent invoke failure.
- `StatifierBlocks.Compiler.Context.outcome_id/2` and `outcome_event/2`, for a
block type with more than one way to finish: one `<final>` per outcome, and
the `done.outcome.<state id>.<outcome>` event a parent wires on.
- `StatifierBlocks.Palette.from_modules/2`, the registration API a host uses
to contribute its own block types: an ordered, explicit list of
`{type_name, module}` registrations, with `core: true` to sit on top of
the `core.*` vocabulary. Later entries win. It is still a value - no
global registry, no application-configuration lookup, and no discovery
pass.
- A palette entry may declare `badge`, a short chip for the card header, and
`join_label`, a one-argument function of the block's config phrasing the
join marker under a side-by-side arrangement (ADR-0002 amendment B).
`StatifierBlocks.BlockType.badge/1` and `join_label/2` read them.
- Both readers are total and **refuse rather than repair**: a chip that is
blank, carries a newline or tab, or runs past 24 characters is dropped,
not clipped, and a `join_label` that raises degrades to the editor's own
word rather than taking the canvas down.
- `accent_token`, `badge` and `join_label` are admitted keys of
`t:StatifierBlocks.BlockType.palette_entry/0`.
- The README carries a worked host example - a `myapp.risk_hold` block type
registered beside the core vocabulary, with a badge and an accent token -
and it is executed on every build rather than trusted.
### Changed
- `Compiler.compiler_version/0` (and every compilation record's
`compiler_version`) moves to `0.2.0` with the package, per ADR-0004
decision 6: a record compiled by 0.1.0 identifies itself as such.
- `--sb-drop-ok-border` moves from `#2f9e5f` to `#2c945a`. The outline that
says a slot accepts a drop was 2.93:1 on the sunken surface, under the 3:1
a mark carrying information is held to; the tint follows it.
- `predicator` is now a direct dependency (`~> 9.0`), because
`StatifierBlocks.Core.Duration` calls `Predicator.Duration.parse/1`. It
already resolved transitively through `statifier`, so the resolved version
does not move; naming it records the call.
- The editor's stylesheet carries a scoped reset, and every selector in it
matches the container through `:where(.sb-editor)` so a component rule
always wins (ADR-0005 amendment 14b).
- `--sb-color-scheme` is declared and read as `color-scheme` on the editor's
own container, so the parts of a control the browser paints - a `<select>`'s
drop-down, the scrollbars, the caret - follow the theme (14a).
- The `--sb-*` surface gains the space, type and shape scales, a third text
step, a strong border, status tints, the drag seam's drag-time height, and
the canvas sizing constants that were literals in rules.
- A `:secondary` and a `:failure` slot are both placed as attached rails,
and a container declaring either is drawn as a boundary box - the rail
partition, not the `:secondary` partition (amendments 10c and 10h).
- `--sb-drop-no-opacity` is **retired**. A drag now marks the slots that
accept the block and leaves the rest alone rather than dimming them; the
disabled-control opacity it doubled as is `--sb-disabled-opacity`.
- The compiler now refuses a document whose slots violate their declared
arity or name a slot the block type does not declare, instead of silently
dropping those children from the emission.
- Reasons change no verdict: `:unknown` stays permissive in both positions,
`Assignability.validate/3` reports exactly the findings it did before, and
neither finding tuple gained a field.
- `slot_style` admits a third value, `:failure`, for a slot whose children
are an in-band continuation taken on a bad outcome; `core.invoke` declares
it for `on_error`.
- The role namespace beginning `o_` is reserved for outcome finals;
`Context.role_id/2` now refuses such a role with a `:reserved_role` finding.
### Fixed
- The editor's root rule sets `font-family` rather than the `font`
shorthand, so `--sb-font` reaches the editor. `font: <family-list>` is not
a valid shorthand, so the whole declaration was dropped and the editor's
text did not inherit the host page's font as the token promised.
## [0.1.0] 2026-08-27
First release: the authoring layer above the
[statifier](https://hex.pm/packages/statifier) statechart engine. A block
document is the source of truth - a tree of typed blocks, each with a declared
shape - and it compiles one way to SCXML plus a provenance map that points a
runtime position back at the block that produced it. Block types are
host-pluggable: a host registers the types its own domain needs, and the
compiler and the editor work off that registry rather than a closed built-in
vocabulary. The `core.*` structural vocabulary, the compiler, the edit algebra,
and the LiveView editor shell all ship here.
The `Changed` entries below describe the shape of callbacks and metadata as
they stand at this first release; there is no earlier published version to have
changed from.
### Added
- `StatifierBlocks.Document.validate/1` checks a block document's structure:
schema version, envelope shape, per-block shape, and document-wide id
uniqueness.
- `StatifierBlocks.Document.to_json/1` encodes a document to ADR-0001's
deterministic canonical JSON: sorted object keys, no insignificant
whitespace, empty `slots`/`config`/`metadata` omitted, no floats.
- `StatifierBlocks.Document.content_hash/1` returns a `"sha256:" <> hex`
document identity over `to_json/1`'s canonical bytes.
- `StatifierBlocks.Document.from_json/1` decodes canonical JSON back into a
document, structurally and registry-free: unknown block types decode
successfully, and every refusal is one of ADR-0001's typed error arms.
- `StatifierBlocks.BlockType` behaviour: the nine-callback authoring-time
extension seam (ADR-0002), five required (`slots/1`, `config_schema/1`,
`validate_config/1`, `current_version/0`, `emit/2`) and four optional
(`io/1`, `migrate_config/2`, `fixtures/0`, `palette_entry/0`).
- `StatifierBlocks.Palette`: a caller-supplied `type_name => module` value
(ADR-0002 decision 2), with `new/1` to build one and a total `fetch/2` that
returns `{:ok, module}` or `{:error, {:unknown_block_type, type_name}}` and
never raises (ADR-0002 decision 3).
- `StatifierBlocks.Palette.resolve/2`: resolves a block through the palette and
migrates its config in memory when the stored `type_version` is below the
type's `current_version/0` (ADR-0002 decision 8). Migration is applied to the
returned struct only and never written back to a document; a stored version
above `current_version/0` hard-errors as
`{:error, {:block_type_too_new, id, version}}` rather than reading
best-effort, and a failing or missing `migrate_config/2` surfaces as
`{:error, {:migration_failed, id, reason}}`.
- The `core.*` structural block types (ADR-0002 decision 10), one
`StatifierBlocks.BlockType` module each: `StatifierBlocks.Core.Sequence`,
`.Group`, `.Branch`, `.Parallel`, `.Wait`, `.ResumableGroup` and `.OnEvent`.
`core.branch` derives one slot and one `:expression` field per declared arm,
`core.parallel` one slot per declared lane, and each type is the authority on
its own config through `validate_config/1`.
- `StatifierBlocks.Palette.core/0` and `StatifierBlocks.Palette.core_types/0`:
the core vocabulary as a palette, and as the plain `type_name => module` map
a host merges its own entries into.
- Structural placement through ADR-0003 decision 3 kind tags: `core.on_event`
declares `kinds: [:interrupt_handler]` and the group types accept only that
kind in their `interrupts` slot, so an interrupt handler is admitted there
and refused everywhere else, and an ordinary step is refused there - in both
directions, from the declarations alone, with no special-cased rule.
- `fixtures/0` on `core.branch` (an arm condition evaluated against two
datasets) and `core.on_event` (one example event payload). The bundle shape
follows an amendment to ADR-0002 decision 9 that is not yet accepted, and is
documented as provisional until it is.
- `StatifierBlocks.Assignability`: the one decision function for whether a
block may land in a slot, checking structural admission by kind tag and
data-flow compatibility by type-expression identity plus an optional
host-supplied widening relation (ADR-0003). `check/5` decides a single
candidate position; `valid_targets/4` lists every position a candidate may
occupy in a document; `validate/3` reports every finding already present in a
document; `inbound_type/4` and `assignable?/3` are the two primitives both
are built from.
- `StatifierBlocks.Assignability.Relation`: the behaviour a host implements to
widen data-flow compatibility beyond exact type-expression identity. A host
module can only grow the accepted set, never shrink it.
- `StatifierBlocks.Palette` gains an `assignability` field naming the host's
`Assignability.Relation` module, set via
`Palette.new(types, assignability: MyApp.Blocks.Types)`. Defaults to `nil`,
meaning no widening relation is declared; existing calls to `Palette.new/1`
are unaffected.
- `StatifierBlocks.Compiler`: the one-way compile (ADR-0004 decisions 1-4,
6-7). `compile/3` is a total function of `{document, palette}` returning
`{:ok, %StatifierBlocks.Compiled{}}` or
`{:error, [%StatifierBlocks.Compiler.Finding{}]}` - no process state, no
clock, no IO, and no arm that raises. The pipeline runs Document, Resolve,
Config and Emit, stopping at the first stage that produces errors and
reporting every error from that stage.
- `StatifierBlocks.Emission`: the structural representation of one SCXML
subtree a block type returns from `emit/2`, with `element/3` and the
`child_ref/1` placeholder the compiler splices its children into.
- `StatifierBlocks.Compiler.Serializer`: the deterministic serializer.
Attributes sorted, one canonical empty-element form, no incidental whitespace
at all. It is identity-bearing code - chart identity hashes source bytes
(st-ADR-0052) - and `serializer_test.exs` now enforces the whitespace
sensitivity ADR-0004 decision 6 named and left unenforced.
- `StatifierBlocks.Compiler.StateId`: `state_id/1`, `state_id/2`,
`unstate_id/1` and `done_event/1`. State ids derive from block ids
(`"s_" <> block_id`, `"__" <> role` for an auxiliary state), so they are
unique, invertible and total over generated states.
- `StatifierBlocks.Compiler.Context`: what a block type is entitled to know
while emitting - its own ids, the document id, its children's summaries
(block id, state id, done event) and the role-minting function. No palette,
and no child's emitted SCXML.
- `StatifierBlocks.Compiled` and `StatifierBlocks.CompilationRecord`: the
artifact, and the join between document identity and chart identity.
`chart_name` carries the document id and `chart_version` stays `nil`, so a
revision bump or a metadata-only edit still matches the identity a running
session holds.
- `StatifierBlocks.Core.Emit`: the SCXML shapes the `core.*` vocabulary
compiles to, and the builders a host block type follows to compose with them.
- `StatifierBlocks.Provenance`: the map from generated SCXML back to the blocks
that produced it (ADR-0004 decision 5). Keyed by state id for highlighting a
running session's configuration, and by byte span for routing findings that
carry no element reference. `owner_at/2`, `owner_of_state/2`,
`owners_of_states/2`, and canonical `to_json/1` / `from_json/1` so a host can
store the map beside the chart.
- `StatifierBlocks.Compiled` now carries all five of ADR-0004 decision 1's
fields: `provenance`, `invoke_types` and `warnings` join `scxml` and
`record`.
- `invoke_types` publishes the sorted set of invoke types the chart emits,
unconditionally, so a host can compare it against its `Statifier.Session`
registration at deploy time (ADR-0004 decision 8).
- `Compiler.compile/3` accepts `:known_invoke_types`, an opt-in lint that
**warns** - never errors - for every emitted invoke type absent from the set
the caller believes will be registered.
- `Compiler.compile/3` accepts `:entry_type`, ADR-0003 decision 4's
caller-supplied context, which the new Structure stage passes to
`StatifierBlocks.Assignability.validate/3`.
- The compiler now runs a **Structure** stage (assignability) and a **Chart**
stage (statifier's own pipeline over the generated bytes), and maps every
upstream finding back to the block that caused it.
- `StatifierBlocks.Emission.attributed_to/2`, `from_config/2` and
`attribute_from_config/3`: the hints a block type leaves so a finding lands
on the block an author would recognise, and on the config field they typed
into.
- `StatifierBlocks.Edit`: the editor's command algebra - insert, remove, move,
and update-config - as a purely structural, invertible rewrite over a
document with no palette involved (ADR-0005). `apply/2` applies one command
and returns both the new document and the command that undoes it;
`check_config/3` is the separate config-validity gate one layer up.
- `StatifierBlocks.Edit.History`: undo and redo over `Edit` commands.
`commit/4` is the one funnel a host calls - it runs `Edit.check_config/3`
before `Edit.apply/2`, then pushes the inverse and clears the redo stack, so
invalid config never reaches the document on any path, undo and redo
included.
- `StatifierBlocks.Edit.Targets`: `droppable_slots/3` and
`droppable_slots_for/3`, which slots would accept a dragged block, at slot
granularity rather than gap granularity, built as a reduction of
`StatifierBlocks.Assignability.valid_targets/4`.
- `StatifierBlocks.Finding`: the presentation finding ADR-0005 specifies,
anchored to a block, a slot, or a config field so the editor knows where to
render it. Distinct from the existing `StatifierBlocks.Compiler.Finding`,
which serves the compile pipeline.
- `StatifierBlocks.ViewModel`: the structure the editor actually renders,
derived from a document, a palette, and a list of findings. Resolves and
normalizes every block's slots, form fields, and palette presentation
metadata, and routes every finding to the position that renders it.
- `StatifierBlocks.Editor`: the LiveView editor shell (ADR-0005). A
`LiveComponent` a host embeds over a `%Document{}` and a `%Palette{}`; it is
the only stateful module in the package's rendered half, and everything it
does is translate a `phx-` event into one of `StatifierBlocks.Edit`'s four
commands. Drag is two round-trips - one at `dragstart` to enumerate valid
slots, one at `drop` - with zero per hover, because validity reaches the
client as `data-drop` markup rather than as client-side logic.
- `StatifierBlocks.Editor.Canvas`, `.BlockNode`, `.Slot`, `.ConfigForm`,
`.Field`, `.PaletteBrowser`, `.Findings`: the function components the shell
renders, each independently renderable in a test. `BlockNode` and `Slot`
recurse into each other, and there is no per-block-type component: a block
type's `layout` and `slot_style` presentation metadata is the only thing that
distinguishes a group from a set of lanes.
- `assets/js/statifier_blocks.js`: the package's entire client-side surface,
one hook named `StatifierBlocksDrag`, shipped as source. A host adds
`"statifier_blocks": "file:../deps/statifier_blocks"` to its
`assets/package.json` and imports the hook in `app.js`; this repository
bundles nothing and has no Node toolchain.
- `assets/css/statifier_blocks.css`: one stylesheet of structural CSS and no
visual opinion beyond it. Every class is prefixed `sb-`, every color, space,
radius and drag treatment is a `--sb-*` custom property with a default, and
every top-level component takes a `class` attr appended to its own.
- A headless CI job that resolves the dependency tree with `phoenix_live_view`
absent, compiles it with warnings as errors, and runs the non-LiveView suite
- the acceptance property that makes the optional dependency's guard
trustworthy rather than decorative. `STATIFIER_BLOCKS_HEADLESS=1` reproduces
it locally without disturbing the ordinary build.
- `StatifierBlocks.BlockType`: a config field declaration may now carry an
optional `value_path`, a list of keys and list indexes from the config root
down to the value it edits (ADR-0002 decision 7, amended 2026-08-27). A
declaration without one behaves exactly as before - its `key` addresses
`config[key]`. The `key` remains the field's identity in both cases: the DOM
id, the form param name, and what a `{:config, block_id, key}` finding
anchors to.
- `StatifierBlocks.BlockType.value_path/1`, `fetch_value/2` and `put_value/3`:
the reader and writer that resolve a declaration to a path and then read or
write through it. `value_path/1` answers `[key]` for a declaration that
declares none, so a caller never branches on which case it has.
`fetch_value/2` is total and answers `:error` for a path that does not
resolve. `put_value/3` writes the last segment whether or not a value was
already there - an arm with no condition yet is exactly the one an author is
about to type into - but never invents an intermediate map or list a block
type did not write.
- `StatifierBlocks.ViewModel.Field` carries `value_path`, and
`ViewModel.Field.value_path/1` reads it with the same `[key]` default.
### Changed
- `c:StatifierBlocks.BlockType.io/1`'s return type is
`StatifierBlocks.Assignability.io/0` instead of `term()`. Every core block
type already returns a value of this shape; a custom block type implementing
`io/1` should confirm its return value conforms.
- All seven `core.*` block types implement `emit/2` for real; the
`{:error, {:not_implemented, block_id}}` placeholder and
`StatifierBlocks.Core.Config.emit_deferred/1` are gone.
- `c:StatifierBlocks.BlockType.emit/2` is narrowed from
`(Block.t(), term()) :: {:ok, term()} | {:error, term()}` to
`(Block.t(), StatifierBlocks.Compiler.Context.t()) :: {:ok, StatifierBlocks.Emission.t()} | {:error, StatifierBlocks.BlockType.emit_error()}`.
A host block type that was returning something else now has a type to conform
to.
- `StatifierBlocks.Compiler.Finding` gains `path`, `severity`, `fault` and
`code`. `fault` is `:author` when a document edit fixes the finding and
`:package` when it is a bug in this package or a host's block type - which is
what lets an editor say "this cannot be fixed here" rather than blaming the
author for a generated state id.
- Findings from every stage come back in document order over blocks rather than
in the order a stage happened to collect them.
- A bad `:expression` config field now surfaces as an `:author` finding naming
the arm's config key, rather than as an unrouted upstream error.
- `c:StatifierBlocks.BlockType.palette_entry/0`'s return type is
`StatifierBlocks.BlockType.palette_entry/0` instead of `map()`. Every core
block type already returns a value of this shape; a custom block type
implementing `palette_entry/0` should confirm its return value conforms.
- `phoenix_live_view` is a declared optional dependency at `~> 1.0`, matching
statifier_ui's floor. Every module under `StatifierBlocks.Editor.*` is
compiled behind `Code.ensure_loaded?(Phoenix.LiveView)`, and no module
outside that namespace references Phoenix - so a host that only compiles
documents adds no Phoenix dependency and compiles no editor code.
- The hex package's `files:` list includes `assets`. The hook and the
stylesheet ship as source, and source that is not in the tarball is not
public API.
- Every illustrative example in the package - ADR worked examples, doc
examples, and the shipped fixture bundles - uses one of the family's two
canonical example domains: credit-card authorization and capture, or a signup
wizard with A/B testing.
- `StatifierBlocks.Core.Branch.fixtures/0` ships budget-decision datasets
(`"approved"` / `"declined"`) and the expression `"budget_remaining > amount"`.
A host rendering the bundle in a palette panel sees those names.
- The arm-slot and lane-name validation messages on `core.branch` and
`core.parallel` name `"arm_approved"` and `"capture"` as their exemplars.
### Fixed
- A `core.branch` arm's condition is now readable and editable in the editor.
`Core.Branch.config_schema/1` keys one `:expression` field per arm by the
arm's slot name, but the condition is stored at `config["arms"][i]["cond"]`;
the form previously read and wrote the slot name as a top-level config key,
so every branch condition rendered empty, no edit to one reached the arm, and
a junk `config["arm_approved"]` accumulated beside it. Each per-arm field now
declares `value_path: ["arms", i, "cond"]`, and `StatifierBlocks.ViewModel`
and `StatifierBlocks.Editor.ConfigForm` read and write through it. `i` is the
arm's index in the **stored** list rather than its index among the
well-formed ones, so a good arm below a malformed one still addresses its own
condition while an author is mid-edit.
- `StatifierBlocks.Editor`'s `field-list-add` and `field-list-remove` events
read and write the rows through the field's `value_path` as well, rather than
through the top-level key. A key naming no field in the selected block's
schema now edits nothing, matching the guard `ConfigForm.decode/3` already
applied.
- `StatifierBlocks.Assignability.check/5` and `valid_targets/4` no longer raise
a `MatchError` when the candidate is the document root.
`Document.fetch_path/2` answers `{:ok, []}` for the root, and the
vacated-seam check now reads that as what it is - the root occupies no slot,
so it leaves no seam behind - instead of calling `List.last/1` on the empty
path. `StatifierBlocks.Edit.Targets.droppable_slots/3` answers `[]` for the
root rather than crashing, so a caller no longer has to guard around it.
[0.2.0]: https://github.com/riddler/statifier_blocks/releases/tag/v0.2.0
[0.1.0]: https://github.com/riddler/statifier_blocks/releases/tag/v0.1.0