Support array values in checkbox component

Checkbox now detects three modes:
- Boolean: field value is scalar, renders hidden+checkbox (unchanged)
- Collection: field is inside a FieldCollection, renders with field value
- Array: field value is an Array, computes checked from inclusion

This lets users build checkbox groups with full HTML control:

  Role.all.each do |role|
    label do
      Field(:role_ids).checkbox(value: role.id)
      whitespace
      plain role.name
    end
  end

Author: bradgessler

README.md

@@ -404,14 +404,15 @@ class SignupForm < Components::Form
       Field(:agreement).checkbox(checked: true)
     end
 
-    # Checkbox and radio groups use collections. The collection handles
-    # naming (including []) and data binding. You control the HTML structure.
+    # Checkbox groups: loop over all possible options. Superform handles
+    # the name (with []), value, and checked state. You control the HTML.
     fieldset do
-      legend { "Select your roles" }
-      Field(:role_ids).collection.each do |role|
+      legend { "Roles" }
+      Role.all.each do |role|
         label do
-          role.checkbox
-          plain " #{role.value}"
+          Field(:role_ids).checkbox(value: role.id)
+          whitespace
+          plain role.name
         end
       end
     end

lib/superform/rails/components/checkbox.rb

@@ -3,17 +3,39 @@ module Rails
     module Components
       class Checkbox < Field
         def view_template(&)
-          # Rails has a hidden and checkbox input to deal with sending back a value
-          # to the server regardless of if the input is checked or not.
-          input(name: dom.name, type: :hidden, value: "0")
-          # The hard coded keys need to be in here so the user can't overrite them.
-          input(type: :checkbox, value: "1", **attributes)
+          if boolean?
+            # Rails convention: hidden input ensures a value is sent even when unchecked
+            input(name: dom.name, type: :hidden, value: "0")
+            input(type: :checkbox, value: "1", **attributes)
+          elsif collection?
+            input(type: :checkbox, value: dom.value, **attributes)
+          else
+            input(type: :checkbox, **attributes)
+          end
         end
 
         def field_attributes
-          { id: dom.id, name: dom.name, checked: field.value }
+          if boolean?
+            { id: dom.id, name: dom.name, checked: field.value }
+          elsif collection?
+            { id: dom.id, name: dom.name, checked: true }
+          else
+            { id: dom.id, name: dom.array_name, checked: Array(field.value).include?(@attributes[:value]) }
+          end
+        end
+
+        private
+
+        # Inside a FieldCollection — the field is a child of another Field
+        def collection?
+          field.parent.is_a?(Superform::Field)
+        end
+
+        # Scalar field with no explicit value — classic on/off toggle
+        def boolean?
+          !collection? && !field.value.is_a?(Array)
         end
       end
     end
   end
-end
+end

spec/superform/rails/components/checkbox_spec.rb

@@ -0,0 +1,88 @@
+RSpec.describe Superform::Rails::Components::Checkbox, type: :view do
+  describe 'boolean mode' do
+    let(:object) { double('object', featured: featured_value) }
+    let(:featured_value) { false }
+    let(:field) do
+      Superform::Rails::Field.new(:featured, parent: nil, object: object)
+    end
+    let(:component) { described_class.new(field, attributes: {}) }
+
+    subject { render(component) }
+
+    it 'renders hidden input and checkbox with boolean values' do
+      expect(subject).to eq(
+        '<input name="featured" type="hidden" value="0">' \
+        '<input type="checkbox" value="1" id="featured" name="featured">'
+      )
+    end
+
+    context 'when checked' do
+      let(:featured_value) { true }
+
+      it 'renders with checked attribute' do
+        expect(subject).to match(/<input[^>]*type="checkbox"[^>]*checked/)
+      end
+    end
+
+    context 'when unchecked' do
+      let(:featured_value) { false }
+
+      it 'renders without checked attribute' do
+        expect(subject).not_to include('checked')
+      end
+    end
+  end
+
+  describe 'collection mode' do
+    let(:object) { double('object', role_ids: [1, 3]) }
+    let(:field) do
+      Superform::Rails::Field.new(:role_ids, parent: nil, object: object)
+    end
+
+    it 'renders checked checkboxes for each value in the collection' do
+      html = ""
+      field.collection.each do |role|
+        html += render(role.checkbox)
+      end
+
+      expect(html).to include('value="1"')
+      expect(html).to include('value="3"')
+      expect(html).to include('name="role_ids[]"')
+      expect(html).not_to include('type="hidden"')
+      expect(html.scan(/checked/).count).to eq(2)
+    end
+  end
+
+  describe 'all-options mode' do
+    let(:object) { double('object', role_ids: [1, 3]) }
+    let(:field) do
+      Superform::Rails::Field.new(:role_ids, parent: nil, object: object)
+    end
+
+    it 'checks selected values and leaves others unchecked' do
+      all_roles = [[1, "Admin"], [2, "Editor"], [3, "Viewer"]]
+      html = ""
+      all_roles.each do |id, _name|
+        html += render(described_class.new(field, attributes: { value: id }))
+      end
+
+      expect(html).to include('name="role_ids[]"')
+      expect(html).not_to include('type="hidden"')
+      # Only 1 and 3 are checked
+      expect(html.scan(/checked/).count).to eq(2)
+      expect(html).to match(/<input[^>]*checked[^>]*value="1"/)
+      expect(html).to match(/<input[^>]*checked[^>]*value="3"/)
+      expect(html).not_to match(/<input[^>]*checked[^>]*value="2"/)
+    end
+
+    it 'works through the field helper' do
+      html = render(field.checkbox(value: 1))
+      expect(html).to include('name="role_ids[]"')
+      expect(html).to include('checked')
+
+      html = render(field.checkbox(value: 2))
+      expect(html).to include('name="role_ids[]"')
+      expect(html).not_to include('checked')
+    end
+  end
+end