V46, feature stories: Spray's Features layer in a LiveView app

October 2, 2026 · ALA · V46 · LiveView · features · wiring · checklist

Reading Spray’s §2.2 again showed me that this project’s LiveView variants never had his Features layer. Their Features modules are state and rules with ports. Spray’s features hold wiring, the same as the application: “Each feature creates instances of domain abstractions, configures the instances with feature specific details, and connects them together as needed to express the feature or user story” (§2.2). A feature’s UI goes with it. The layout and “the bindings of the UI elements to data” are “kept together, encapsulated inside a feature. Instead, the UI is composed from Domain UI abstractions” (§7.14). He adds the layer once the application is too big: “it is the application that will go over the 500 line complexity limit” (§2.2).

V45’s cart page was 484 lines with its template, right at that limit. Under the stricter reading of 2026-10-02 it also lost 1.5 points: a point for the FormComponent that phx.gen.live generated, a contained sub-component, and half a point for calling its state modules features. V46 fixes both and adds the layer. It started from V45, and it keeps zero message hops and every behaviour the shared acceptance tests check.

Stories, not features of state

The cart page now composes five stories: EditCart, UndoRemoval, SaveForLater, KeepWishlist and CheckOut. The portal composes EditOrder, BrowseCatalog, SubmitOrder and the same UndoRemoval, configured with its own window. Each story is a module in a real Features layer (GoodDealWeb.Stories). It instantiates its parts, wires their ports to each other and to its view with one wire/4 clause per part port, declares ports of its own, and lays out its view from domain UI components.

defmodule GoodDealWeb.Stories.UndoRemoval do
  @behaviour GoodDealWeb.Paradigms.Story
  def parts, do: %{undo: Undo}
  def ports, do: %{in: [capture: :item, expire: :item], out: [restored: :item, expired: :item_id]}

  def new(opts),
    do:
      Story.new(__MODULE__, %{undo: Undo.new([])},
        timers: %{undo: {Keyword.fetch!(opts, :window_ms), :expire}},
        view: [pending: false]
      )

  def input(s, me, :capture, item), do: Story.run(s, me, :undo, &Undo.capture(&1, item))
  def event(s, me, "undo_remove", _), do: Story.run(s, me, :undo, &Undo.restore(&1, nil))

  def wire(s, me, :undo, {:captured, item}),
    do: s |> Story.show(me, :pending, true) |> Story.start_timer(me, :undo, item)

  def wire(s, me, :undo, {:restored, item}),
    do: s |> Sinks.stop_timer(:undo) |> Story.show(me, :pending, false) |> Story.send_out(me, :restored, item)
  # ...
end

The modules that used to be called features are now GoodDeal.State: stateful domain abstractions, in Spray’s terms. Undo would serve any app in the domain, and Cart is a storefront’s cart. Nothing about them changed but the name, which is the point. Spray’s word now means his thing.

The page wires stories

The cart page’s wire/3 has 15 clauses. Twelve link one story to another, and three land a count or the active tab on the page.

defp wire(s, :edit_cart, {:removed, item}), do: Story.input(s, :undo, :capture, item)
defp wire(s, :undo, {:restored, item}),
  do: s |> Story.input(:edit_cart, :receive, item) |> put_flash(:info, "Item restored")
defp wire(s, :wishlist, {:ids, ids}), do: Story.input(s, :edit_cart, :wishlist_ids, ids)
defp wire(s, :check_out, {:pay_requested, _}), do: Story.input(s, :edit_cart, :request_checkout, nil)

V45 had nine cross-feature wires on this page. The other three were there too, but hidden. The checkout’s view read the cart’s summary from a page assign, the cart’s rows read the wishlist’s ids from another, and the checkout’s Pay button sent an event the cart handled. A story owns its view, so each of those had to become a wire the page can be read for. Splitting by story surfaced connections the single page had blurred.

Browser events go to the story whose view emits them: the page’s one generic handle_event/3 asks the Story runner, which finds the story whose events/0 lists the name. A story’s timer reports to one of its own inputs, and so does its async task, so the page has one generic clause for each and knows no timer or task name. In V45 the page matched {:timer, :undo, ...} and handle_async(:payment, ...), a name shared with the code that started them.

A record form instead of FormComponent

The product pages place a generic record_form domain UI component: fields, words and event names come in as attributes, and it keeps no state. A RecordEdit state (open, validate, submit, saved) holds which record is being edited, and the page wires its submit to SaveProduct and the outcome back:

defp wire(s, :product_form, {:submit, request}),
  do: Steps.feed(s, :product_form, &RecordEdit.saved/2, &SaveProduct.save/1, request, &wire/3)

defp wire(s, :product_form, {:saved, {action, product}}),
  do: s |> stream_insert(:products, product) |> put_flash(:info, @saved[action]) |> push_patch(to: ~p"/products")

Nothing page-specific has its own state or handlers any more, which is what Spray’s “no analog of a sub-module or sub-component” (§2.2) asks.

Checked one level in

Wiring.gaps/1 still checks each page’s clauses against its stories’ output ports. Wiring.story_gaps/1 does the same one level in: each story’s wire/4 heads against its parts’ ports, its input/4 heads against its own input ports, and its event/4 heads against the events its view emits. Wiring.event_clashes/1 checks that no two stories on a page claim one event. A fixture story with a missing clause in each place proves the check fails when it should.

What it scores

V45V46
Full checklist, by hand (2026-10-02 readings)99100
ala_lint default / --strict / --super-strict100 / 100 / 99100 / 100 / 99
Checklist rules met under --strict (of 10 checked)910
Message hops per cross-feature effect00
Tests (shared acceptance tests included)116124
Mean / median time per test4.8 / 0.9 ms6.0 / 1.2 ms
Non-blank lines in lib/4,2544,868
Cart page484 lines270 lines
Familiarity4 of 53 of 5

The lint score can’t tell V45 from V46. Both round to 100, because one finding in about 5,000 lines is a small density. The new count of rules met can: V45 leaves R11 unmet with its FormComponent, and V46 meets all ten. Super-strict’s one finding in both is the shared Cart aggregate, the judgement call every storefront variant makes the same way.

The walk finds nothing to deduct. The stories hold only instances, configuration and wiring (R11 now applies to them, and the linter checks it). Their words and step paths are feature-specific details, which Spray puts in a feature. No story calls another (R1). Two paradigm modules depend on a third, Story and Steps both using Sinks, a knowledge dependency on something more general.

What it costs

When to reach for it

When one page outgrows what a reader can hold, split it along its user stories, not along files. If you already use V45’s clauses, V46 is that split. The cut it made was clean: twelve links between five stories, and every one touches the cart. V47 makes the same split with wiring held as typed values that are checked when a page mounts, for teams that want the diagram to be a value.

The cart page and a story, drawn from their clauses

Paradigms.Drawing.mermaid/1 reads the page’s wire/3 clauses: each Story.input is an arrow from one story to another. mermaid_story/1 reads one story’s input/4 and wire/4 clauses: its inputs, the parts they run, and what it sends out, shows or asks for. The page:

flowchart LR
  ui -.->|"tab"| page_assign["page: assign"]
  edit_cart -.->|"summary"| page_assign["page: assign"]
  edit_cart -->|"summary → summary"| check_out
  edit_cart -->|"removed → capture"| undo
  edit_cart -->|"saved → stash"| saved
  edit_cart -.->|"saved"| page_put_flash["page: put_flash"]
  edit_cart -->|"line → toggle"| wishlist
  edit_cart -->|"checkout_started → start"| check_out
  edit_cart -->|"checkout_requested → pay"| check_out
  undo -->|"restored → receive"| edit_cart
  undo -.->|"restored"| page_put_flash["page: put_flash"]
  undo -->|"expired → confirm_removal"| edit_cart
  saved -.->|"count"| page_assign["page: assign"]
  saved -->|"moved → receive"| edit_cart
  saved -.->|"moved"| page_put_flash["page: put_flash"]
  wishlist -.->|"count"| page_assign["page: assign"]
  wishlist -->|"ids → wishlist_ids"| edit_cart
  wishlist -->|"added_to_cart → receive"| edit_cart
  check_out -->|"pay_requested → request_checkout"| edit_cart

The checkout story inside:

flowchart LR
  in_mounted((mounted)) -->|"mounted → show_form"| checkout
  in_start((start)) -->|"start → start"| checkout
  in_summary((summary)) -.->|"summary"| view_show["view: show"]
  in_pay((pay)) -->|"pay → pay"| checkout
  in_goto((goto)) -->|"goto → goto"| checkout
  in_succeeded((succeeded)) -->|"succeeded → succeeded"| checkout
  in_failed((failed)) -->|"failed → failed"| checkout
  checkout -.->|"step"| view_show["view: show"]
  checkout -.->|"step"| view_patch["view: patch"]
  checkout -.->|"form"| view_show["view: show"]
  checkout -.->|"address"| view_show["view: show"]
  checkout -.->|"blocked"| view_put_flash["view: put_flash"]
  checkout -.->|"ready_to_pay"| task_charge["task charge"]
  checkout -.->|"done"| call_settle["call settle"]
  checkout -.->|"done"| view_push_navigate["view: push_navigate"]

Rescored 2026-10-03: 99

Spray’s §6.17.2 is now read strictly under R10. The small fix is in: checkout gets the cart’s id and stored lines, {cart_id, items}, not the cart, and owns the readiness rule. What remains is the shared entity: the portal’s order lines are built on the storefront’s cart, which carries promo, gift-wrap and shipping state, one use case’s data in a struct another use case shares (−1). The fix is to split the storefront’s concerns out of the struct the portal uses; no variant has done that yet. 100 becomes 99. Lint under --strict is 99, meeting 9 of 10 rules: the linter now scores the shared aggregate from --strict up.

Rescored 2026-10-03 (later): 100

The shared entity is gone. The portal’s OrderLines has its own struct and pricing (subtotal, volume tier, shipping), and builds, like the storefront’s cart, on a new Lines domain abstraction: plain functions over a list of stored order lines (find, add, change a quantity, remove, set stock), holding no prices, codes or flags of any use case. The cart lost set_discount/2, which its own doc said was “added for the portal consumer”. With checkout already getting only {cart_id, items}, R10 is met, and 99 becomes 100. Lint under --strict is 100, meeting 10 of 10 rules. The linter needed one correction to read it: a story that only builds the cart (Cart.new) creates an instance, which a Spray feature does (§2.2), and doesn’t know its data, so it no longer counts as a reader.

The code is in ala_variants_elixir/v46-feature-stories.

← all posts