Merge remote-tracking branch 'origin/main' into cael/uswds-button-adoption

# Conflicts:
#	app/components/strata/flows/task_list_component.html.erb
#	app/components/strata/flows/task_section_component.rb
#	app/components/strata/us/card_component.rb
#	app/previews/strata/us/button_group_component_preview.rb
#	app/previews/strata/us/card_component_preview.rb
#	app/previews/strata/us/card_group_component_preview.rb
#	app/views/strata/application_forms/index.html.erb
#	app/views/strata/shared/_form_buttons.html.erb
#	app/views/strata/tasks/index.html.erb
#	docs/strata-view-helpers.md
#	docs/uswds-components.md
#	spec/dummy/app/views/passport_application_forms/show.html.erb
#	spec/dummy/app/views/sample_application_forms/_form_buttons.html.erb
#	spec/dummy/app/views/sample_application_forms/new.html.erb
#	spec/dummy/app/views/sample_application_forms/review.html.erb
#	spec/dummy/app/views/tasks/details/_passport_photo_task.html.erb
#	spec/dummy/app/views/tasks/details/_passport_verify_info_task.html.erb
#	spec/dummy/app/views/tasks/show.html.erb

Author: github-actions[bot]

app/previews/strata/us/button_group_component_preview.rb

@@ -7,31 +7,12 @@ class ButtonGroupComponentPreview < Lookbook::Preview
       layout "strata/component_preview"
 
       # @label Default
-      def default
-        render Strata::US::ButtonGroupComponent.new do |group|
-          group.with_item do
-            %(<button class="#{Strata::US::ButtonComponent.css_classes}">Save</button>).html_safe
-          end
-          group.with_item do
-            %(<button class="#{Strata::US::ButtonComponent.css_classes(variant: :outline)}">Cancel</button>).html_safe
-          end
-        end
-      end
+      # Renders via the sibling `default.html.erb` template — nested `render` calls don't work inside slot blocks in a Lookbook preview method.
+      def default; end
 
       # @label Segmented
-      def segmented
-        render Strata::US::ButtonGroupComponent.new(segmented: true) do |group|
-          group.with_item do
-            %(<button class="#{Strata::US::ButtonComponent.css_classes}">Map</button>).html_safe
-          end
-          group.with_item do
-            %(<button class="#{Strata::US::ButtonComponent.css_classes}">Satellite</button>).html_safe
-          end
-          group.with_item do
-            %(<button class="#{Strata::US::ButtonComponent.css_classes}">Hybrid</button>).html_safe
-          end
-        end
-      end
+      # Renders via the sibling `segmented.html.erb` template — nested `render` calls don't work inside slot blocks in a Lookbook preview method.
+      def segmented; end
     end
   end
 end

app/previews/strata/us/button_group_component_preview/default.html.erb

@@ -0,0 +1,8 @@
+<%= render Strata::US::ButtonGroupComponent.new do |group| %>
+  <% group.with_item do %>
+    <%= render(Strata::US::ButtonComponent.new) { "Save" } %>
+  <% end %>
+  <% group.with_item do %>
+    <%= render(Strata::US::ButtonComponent.new(variant: :outline)) { "Cancel" } %>
+  <% end %>
+<% end %>

app/previews/strata/us/button_group_component_preview/segmented.html.erb

@@ -0,0 +1,11 @@
+<%= render Strata::US::ButtonGroupComponent.new(segmented: true) do |group| %>
+  <% group.with_item do %>
+    <%= render(Strata::US::ButtonComponent.new) { "Map" } %>
+  <% end %>
+  <% group.with_item do %>
+    <%= render(Strata::US::ButtonComponent.new) { "Satellite" } %>
+  <% end %>
+  <% group.with_item do %>
+    <%= render(Strata::US::ButtonComponent.new) { "Hybrid" } %>
+  <% end %>
+<% end %>

docs/strata-view-helpers.md

@@ -2,7 +2,7 @@
 
 Strata ships a small set of Rails view helpers that wrap common Rails primitives and apply USWDS-aware styling. They're auto-included in any view rendered through Strata-using controllers (via `Strata::ApplicationHelper`), so you can use them without explicit `include` calls.
 
-## Components
+## Helpers
 
 1. [`strata_link_to`](#strata_link_to) — Rails `link_to` with opt-in styling treatments
 2. [`strata_button_to`](#strata_button_to) — Rails `button_to` with USWDS button styling

docs/uswds-components.md

@@ -164,9 +164,16 @@ Any other keyword arguments are forwarded as HTML attributes on the rendered ele
 
 ### Helpers and `css_classes`
 
-For Rails-rendered tags (`link_to`, `button_to`, `form.button`, `f.submit`), use the Strata view helpers — `strata_link_to ..., as: :button` and `strata_button_to` — instead of rendering this component. See [strata-view-helpers.md](./strata-view-helpers.md).
+For `link_to` and `button_to` call sites, use the Strata view helpers — `strata_link_to ..., as: :button` and `strata_button_to` — instead of rendering this component. See [strata-view-helpers.md](./strata-view-helpers.md).
 
-The class-method helper `Strata::US::ButtonComponent.css_classes(variant:, size:, inverse:)` returns the bare USWDS class string and is the single source of truth used by all of the above. Reach for it when neither the component nor the view helpers fit.
+For `form.button`, a non-Strata `f.submit`, or any other call site where Rails owns the tag and no helper fits, use the class-method helper `Strata::US::ButtonComponent.css_classes(variant:, size:, inverse:)` directly. It returns the bare USWDS class string and is the single source of truth used by the component, the helpers, and `FormBuilder#submit`.
+
+The Strata form builder's `f.submit` already delegates to this helper internally and accepts the same `:variant` and `:big` options:
+
+```erb
+<%= f.submit "Save draft", variant: :outline %>
+<%= f.submit "Apply", big: true %>
+```
 
 ---