Implement loops within application form flows by kyeah · Pull Request #355 · navapbc/strata-sdk-rails

kyeah · 2026-05-22T16:05:25Z

Changes

Enables looping functionality for a has_many association
Adds a mount_flow_routes helper
Adds a flow_record_id helper

Breaking Changes

The optional on_flow_record_invalid method must accept a single parameter: target_record

Context

This PR allows forms to insert loops that iterate over a has_many collection. For now, this only supports looping over existing records and assumes that the records are created outside of the loop.

task :prior_employment do
  loop :prior_employers do
    question_page :business_name
    question_page :role
  end
end

Looping pages create nested routes, e.g.

/leave_application_forms/:leave_application_id/employment_details/:id/edit

Testing

Unit testing
Updated the sample application
Tested in downstream starter kit application

Copilot

Pull request overview

Adds loop support to the multi-page application form flow DSL, allowing a task to iterate a set of pages over a has_many association on the flow record. Loops generate nested routes under the parent resource, and the controller layer now resolves either the parent flow record or the active child record per page. A mount_flow_routes helper and a flow_record_id helper centralize routing/controller wiring.

Changes:

New Strata::Flows::Loop model + loop DSL in ApplicationFormFlow, with all_pages, namespaced edit/update pathnames on loop QuestionPages, and loop-aware TaskEvaluator traversal.
New mount_flow_routes mapper extension that generates top-level member routes for outer pages and nested member routes under each loop's association.
Controller updates target either flow_record or @flow_task.loop_record; on_flow_update_invalid now receives target_record; dummy app, schema, factory, locales, views, docs, and a controller spec are updated to demonstrate the pattern.

Reviewed changes

Copilot reviewed 27 out of 27 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
app/models/strata/flows/application_form_flow.rb	Adds `loop` DSL, `all_pages`, loop-aware action lookup, duplicate-action detection, and mermaid filtering of Loop nodes.
app/models/strata/flows/loop.rb	New Loop model with association resolution, optional symbol/proc scope, and started/completed semantics.
app/models/strata/flows/question_page.rb	Adds `loop` attribute, `in_loop?`, and namespaced + nested-route variants of edit/update pathnames and paths.
app/models/strata/flows/task.rb	Generalizes `started?`/`completed?`/`path` to handle Loop entries; adds first-path/first-incomplete helpers (see comment on `needed?` parity).
app/models/strata/flows/task_evaluator.rb	Carries `loop_record`/`loop_page_idx`; rewrites prev/next to step within loops, between child records, and out of the loop.
app/models/strata/flows/application_form_controller.rb	Adds `flow_record_id`, threads child id into action lookup, targets loop child for update/validation/save, passes record to invalid hook.
lib/strata/flows/routing_extensions.rb	New `mount_flow_routes` mapper helper generating outer member routes and nested loop member routes.
lib/strata/engine.rb	Mixes `RoutingExtensions` into `ActionDispatch::Routing::Mapper`.
docs/multi-page-form-flows.md	Documents loop syntax, `mount_flow_routes`, and `flow_record_id` (see comments on Ruby-syntax examples and bullet capitalization).
spec/models/strata/flows/loop_spec.rb	New unit specs for Loop init, scopes, completion, started semantics.
spec/models/strata/flows/task_spec.rb	Adds task-containing-loop coverage.
spec/models/strata/flows/task_evaluator_spec.rb	Adds traversal coverage across loops, scopes, predicates, and `update_path`.
spec/models/strata/flows/question_page_spec.rb	Adds in-loop pathname and nested route helper coverage.
spec/models/strata/flows/application_form_flow_spec.rb	Adds DSL, all_pages, routes, action lookup, and collision-detection coverage.
spec/lib/strata/flows/routing_extensions_spec.rb	New routes spec for top-level + nested loop routes via the dummy app.
spec/dummy/spec/controllers/sample_application_forms/sample_application_forms_controller_prior_employer_loop_spec.rb	End-to-end controller spec for the loop flow.
spec/dummy/db/migrate/20260520120000_create_sample_employment_details.rb	Adds child table for the loop demo.
spec/dummy/db/schema.rb	Schema update for new child table.
spec/dummy/config/routes.rb	Switches to `mount_flow_routes SampleFlow`.
spec/dummy/config/locales/sample_applications/en.yml	Adds translations for the new task and loop pages.
spec/dummy/app/flows/sample_flow.rb	Adds `prior_employment` task with the loop.
spec/dummy/app/models/sample_application_form.rb	Adds `has_many :sample_employment_details`.
spec/dummy/app/models/sample_employment_detail.rb	New child model with per-page validations.
spec/dummy/app/controllers/sample_application_forms_controller.rb	Uses `flow_record_id` for parent lookup.
spec/dummy/app/views/sample_application_forms/edit_prior_employer_business_name.html.erb	New loop edit view bound to `@flow_task.loop_record`.
spec/dummy/app/views/sample_application_forms/edit_prior_employer_role.html.erb	New loop edit view bound to `@flow_task.loop_record`.
spec/dummy/spec/factories/sample_application_forms_factory.rb	Adds factory for `sample_employment_detail`.

+loop :employment_details, scope: :is_current, do ...
+loop :employment_details, scope: (employment) -> { employment.is_current }, do ...


+
+- Looping pages
+- Document upload form fields
+- form fields on associated records


+    # (where params[:id] is the loop child and params["<flow_class>_id"] is
+    # the flow record).
+    def flow_record_id
+      parent_key = "#{controller_name.singularize}_id"
+      params[parent_key] || params[:id]


+    def first_incomplete_path(record)
+      @pages.each do |item|
+        if item.is_a?(Loop)
+          item.records_for(record).each do |child|
+            incomplete = item.pages.find { |p| !p.completed?(child) }
+            return incomplete.edit_path(record, child) if incomplete
+          end
+        elsif !item.completed?(record)
+          return item.edit_path(record)
+        end
+      end
+      nil
+    end
+
+    def enter_forward(item, record)
+      if item.is_a?(Loop)
+        first_child = item.records_for(record).first
+        return nil unless first_child
+        first_page = item.pages.find { |p| p.needed?(first_child) }
+        first_page&.edit_path(record, first_child)
      else
-        @pages.find { |page| !page.completed?(record) }.edit_path(record)
+        item.needed?(record) ? item.edit_path(record) : nil
      end


MichaelCrawfordNava

A few comments.

Additionally, when going through the sample flow in the dummy app, a couple of things:

"Prior Employment" automatically completes whenever I complete "Employment". Is this intended?
When I click "Edit" under "Prior Employment", nothing happens. Is this intended?

MichaelCrawfordNava · 2026-05-27T17:48:18Z

        return nil, nil
      end

      def to_mermaid


This method is pretty large and complex. Would you mind cleaning this up a little bit and making it easier to read? Extracting logic to other private methods, etc.

MichaelCrawfordNava · 2026-05-27T17:57:24Z

      end

-      def find_page_and_task_by_action(flow_record, action)
+      def find_page_and_task_by_action(flow_record, action, id_param = nil)


This method is pretty dense and complex (ends up having a loop inside of a loop inside of a loop). Would you mind cleaning this method a little to make it more readable?

MichaelCrawfordNava · 2026-05-27T18:08:50Z

+    # or the first reachable page of a Loop.
+    def enter(item, direction)
+      if item.is_a?(Loop)
+        enter_loop(item, ordered(item.records_for(@record), direction), direction)


Mind extracting these method calls to variables? Makes it easier to debug if there are errors raised.

MichaelCrawfordNava · 2026-05-27T18:19:19Z

    t.string "leave_type"
    t.datetime "created_at", null: false
    t.datetime "updated_at", null: false
-    t.boolean "reviewed", default: false


You have this removed in your PR, however when I run migrations locally it adds this column back in. Did you intend to remove this?

MichaelCrawfordNava · 2026-05-27T18:31:49Z

+      records = loop_node.records_for(@record)
+      current_idx = records.find_index(@loop_record)


Heads-up on performance once this meets a real ActiveRecord relation: records_for issues the association query, then find_index enumerates the relation in Ruby and ==-compares each loaded row against @loop_record. That's an O(n) row load + object instantiation on every page transition inside a loop — fine for the sample app's two-row fixtures, but it'll show up if a downstream app ever loops over a relation with hundreds of children (e.g. a long employment history, dependents, line items on a claim).

A cheaper variant that avoids loading the rows:

ids = records.pluck(:id) current_idx = ids.index(@loop_record.id) return nil unless current_idx next_id = direction == :forward ? ids[current_idx + 1] : ids[current_idx - 1] if current_idx > 0 || direction == :forward next_child = next_id && records.find(next_id)

…or, since the loop position is really just "which child are we on," you could sidestep the lookup entirely by carrying the child's index (not the record) on the evaluator and resolving the record lazily.

Not blocking — flagging it because the symptom (a noticeably slow "Next" click deep in a long loop) is the kind of thing that's easy to miss in dev and annoying to debug later.

…ooping-flows

kyeah · 2026-05-29T18:52:48Z

Thanks for the feedback @MichaelCrawfordNava! Heads up that I'm going to continue focusing on the paidleave app updates next week, but I will revisit this PR to refine the solution for the SDK shortly after. So you may not see activity in the next few days but it's on my list to come back to.

…ooping-flows

kyeah added 8 commits May 20, 2026 22:05

WIP

533ccbb

Add scope option

2ca89b5

Fix route generation

bd7ccf9

pass the target record into optional hook

3c37064

Ensure validation errors are displayed for loop records

759d42a

Pass in looping param ID directly

56a68a4

clean up

9744abe

Update docs

a16dcfd

kyeah requested review from MichaelCrawfordNava and lamroger-nava May 25, 2026 18:05

kyeah marked this pull request as ready for review May 25, 2026 18:06

MichaelCrawfordNava requested a review from Copilot May 27, 2026 17:43

Copilot started reviewing on behalf of MichaelCrawfordNava May 27, 2026 17:43 View session

Copilot AI reviewed May 27, 2026

View reviewed changes

MichaelCrawfordNava reviewed May 27, 2026

View reviewed changes

Merge branch 'main' of github.com:navapbc/strata-sdk-rails into kev/l…

65c132d

…ooping-flows

Merge branch 'main' of github.com:navapbc/strata-sdk-rails into kev/l…

96bfc4a

…ooping-flows

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Implement loops within application form flows#355

Implement loops within application form flows#355
kyeah wants to merge 10 commits into
mainfrom
kev/looping-flows

kyeah commented May 22, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

MichaelCrawfordNava left a comment •

edited

Loading

Uh oh!

MichaelCrawfordNava May 27, 2026

Uh oh!

MichaelCrawfordNava May 27, 2026

Uh oh!

MichaelCrawfordNava May 27, 2026

Uh oh!

MichaelCrawfordNava May 27, 2026

Uh oh!

MichaelCrawfordNava May 27, 2026

Uh oh!

kyeah commented May 29, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

		loop :employment_details, scope: :is_current, do ...
		loop :employment_details, scope: (employment) -> { employment.is_current }, do ...

		records = loop_node.records_for(@record)
		current_idx = records.find_index(@loop_record)

Uh oh!

Conversation

kyeah commented May 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Changes

Breaking Changes

Context

Testing

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

MichaelCrawfordNava left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

MichaelCrawfordNava May 27, 2026

Choose a reason for hiding this comment

Uh oh!

MichaelCrawfordNava May 27, 2026

Choose a reason for hiding this comment

Uh oh!

MichaelCrawfordNava May 27, 2026

Choose a reason for hiding this comment

Uh oh!

MichaelCrawfordNava May 27, 2026

Choose a reason for hiding this comment

Uh oh!

MichaelCrawfordNava May 27, 2026

Choose a reason for hiding this comment

Uh oh!

kyeah commented May 29, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

kyeah commented May 22, 2026 •

edited

Loading

MichaelCrawfordNava left a comment •

edited

Loading