V46, feature stories: Spray's Features layer in a LiveView app
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
| V45 | V46 | |
|---|---|---|
| Full checklist, by hand (2026-10-02 readings) | 99 | 100 |
ala_lint default / --strict / --super-strict | 100 / 100 / 99 | 100 / 100 / 99 |
Checklist rules met under --strict (of 10 checked) | 9 | 10 |
| Message hops per cross-feature effect | 0 | 0 |
| Tests (shared acceptance tests included) | 116 | 124 |
| Mean / median time per test | 4.8 / 0.9 ms | 6.0 / 1.2 ms |
Non-blank lines in lib/ | 4,254 | 4,868 |
| Cart page | 484 lines | 270 lines |
| Familiarity | 4 of 5 | 3 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
- Familiarity drops a point. A story has four kinds of clause (
input,event,wire, a view), a behaviour, and a runner to learn. V45’s page was one module a Phoenix developer reads top to bottom. - More code. About 600 more non-blank lines than V45: eight story modules, a 146-line runner and the record form. The cart page shrank from 484 lines to 270.
- Slower tests, a little. The mean test is about 1.2 ms slower, from the extra function calls per event. It’s not a concern at this size, but it’s measurable.
- Not yet needed here. V45’s page was just under Spray’s limit. V46 shows the split works and where it cuts. A page twice the size is where it would pay.
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.