phlex-forms 0.2.3 → 0.2.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 536c63a40e17d971808a285a30d6bd8a96a0f0049ecdd1fc2472e39d2359337b
-  data.tar.gz: 81460e049eccf72d1181420e705834b111bcd64aa5e4865f04fa811350c423f1
+  metadata.gz: '0038bad89aee72fb6b4e162bfc83dc9afbaadbc2280f3ea23be2985e81774d41'
+  data.tar.gz: 9b35b71658c4ffbb14667a79e6e85e4a0437d6953b64921272ae629a443a0ac2
 SHA512:
-  metadata.gz: 1479141adae7a0f38ed945d1cd572b6a1ad6c0504964d6690e0f4db1ed1a901f8f9ba99c6e2af497020bce01adbca8fbe1ab36c46f59815296c6b46bc894f482
-  data.tar.gz: a72f1a2367fc0e0ddcc155241805e5c70943c7d11ebe5a08ad88f2e33f2094e7a03b14ecbd61fc4f205072f0473f3e6ba9cf5413ed3ce3a8313a920db5309d1e
+  metadata.gz: b8ada79a4a87a79096b16f82d000ea0e5620096ebe4b8fff9560ae5e556ff982ff6e13ccb52c77e0d7ea72e0d094055595870468de9c40d9f498350bab399eb4
+  data.tar.gz: bce76ac9a71f33cab8c15f6f4b529b636da88d802c4b86ba07ee90948daaa1a2e1c0637f898a11be75e37ab4b8dd7abb8f42ce654a9481907b5cbcc5a299263a

data/CHANGELOG.md

@@ -9,6 +9,51 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+- **`checkbox_group` — batched checkbox group for array-valued fields** (the
+  tag/facet-picker shape): `f.checkbox_group(:tag_ids, Tag.all, value: :id,
+  label: :name, variant: :pill, size: :sm)`, or via field inference
+  (`f.field :tag_ids, as: :checkbox_group, collection: Tag.all, value: :id`).
+  Shares one array-valued field name with a leading empty-array hidden field,
+  derives the checked set from the model's current value, and renders under both
+  themes. `variant:` (`:stack`/`:inline`/`:pill`) is layout-only, no JS.
+- **`checkbox_group` accessible name** (issue #17): the `div[role="group"]` can
+  now carry an accessible name/description. HTML/ARIA attributes pass straight
+  through to the group, so the bare verb is named with plain `aria:`
+  (`aria: { label: "Tags" }` or `aria: { labelledby: "id" }`); through `f.field`
+  the Control's own visible `label:` / `hint:` get stable ids and the field wires
+  `aria-labelledby` / `aria-describedby` at them (no duplicate markup). Absent a
+  name, output is unchanged.
+
+### Changed
+
+- **Client-side validation Stimulus identifiers dropped the `forms--` prefix**:
+  the bundled controllers now emit `validations--presence`, `validations--length`,
+  … (and the `validations--form` coordinator) so
+  `lazyLoadControllersFrom("phlex_forms/controllers")` resolves them to their
+  shipped path `phlex_forms/controllers/validations/*_controller` — previously
+  `forms--validations--*` derived `.../forms/validations/*`, which 404'd and the
+  controllers never connected (issue #12). The `data-validations--*` binding
+  attributes and the `invalidate:validations` event changed to match. Hosts that
+  registered `forms--validations--*` explicitly must update the identifier.
+
+### Fixed
+
+- **`f.Radio` / `Field#radio` rendered the model's current value on every radio
+  instead of each radio's own value**: `field_attributes` carried `value:
+  field_value` and was splatted after the explicit positional value, clobbering
+  it — a new record lost the value entirely, an edit form gave every radio the
+  same value. `radio` now drops `field_attributes`' `value` (issue #13).
+- **`Form(validate: true)` never fired client-side validation on submit**: the
+  coordinator controller was attached but no `data-action` wired its `onSubmit`
+  handler, so submitting an invalid form was not blocked. `apply_validation_coordinator`
+  now emits `submit->validations--form#onSubmit` (joined with any
+  caller-supplied `data-action`).
+- **`fields_for` iterated a Hash-backed association (JSONB), emitting bogus
+  indices**: a Hash responds to `#each_with_index`, so a JSONB column rendered
+  with `nested_attributes: false` produced `scope[assoc][0][field]`, `[1]`, …
+  instead of a single `scope[assoc][field]`. It is now treated as a single
+  nested scope; only genuine collections (Enumerable, not Hash) iterate.
+
 - **`Forms::Base` declarative form classes**: subclass, declare fields in
   `#fields` where `self` IS the form (bare `field :email`, no `f.` prefix),
   render with `render UserForm.new(model: @user)`. Class-level `form_options`

data/README.md

@@ -337,6 +337,11 @@ import { lazyLoadControllersFrom } from "@hotwired/stimulus-loading"
 lazyLoadControllersFrom("phlex_forms/controllers", application)
 ```
 
+The emitted identifiers are `validations--presence`, `validations--length`, … (and
+the form-level `validations--form` coordinator), which `lazyLoadControllersFrom`
+resolves to `phlex_forms/controllers/validations/*_controller` — the path the gem
+ships them at.
+
 Messages ship for `en` / `fr` / `af`; override via `window.PhlexForms.messages`.
 
 ## Nested attributes, collections & escape valves
@@ -351,13 +356,45 @@ f.fields_for(:settings, nested_attributes: false) do |s|
 end
 
 f.collection_check_boxes(:role_ids, Role.all, :id, :name) do |b|
-  render b.check_box
+  render b.check_box                          # per-item control, full custom layout
   render b.label
 end
 
+# The batched "tag/facet picker" shape: one array-valued field name, checked
+# state derived from the model (record.tag_ids), sensible defaults, no block.
+f.checkbox_group(:tag_ids, Tag.all, value: :id, label: :name)
+f.checkbox_group(:tag_ids, Tag.all, value: :id,
+  label: ->(t) { t.name.presence || t.slug }, # Symbol method or Proc
+  variant: :pill,                             # :stack (default) | :inline | :pill
+  size: :sm,                                  # daisyUI checkbox size
+  aria: { label: "Tags" })                    # names the group for screen readers
+# ...or through field inference (the field's label/hint name the group):
+f.field :tag_ids, as: :checkbox_group, collection: Tag.all, value: :id,
+  label: "Tags", hint: "Pick any"
+
 f.collection_select(:country_id, Country.all, :id, :name, prompt: "Select…")
 ```
 
+`checkbox_group` submits an array param (`user[tag_ids][]`) with a leading
+empty-array hidden field, so deselecting everything still submits. The checked
+set comes from the model's current value matched by each item's resolved
+`value:` — re-rendering an edit form pre-checks the right boxes. The `:pill`
+variant styles the active chip with Tailwind's `has-[:checked]:` (no JS).
+
+A `role="group"` needs an **accessible name** for assistive tech. The verb has
+no bespoke naming option — HTML/ARIA attributes pass straight through to the
+group, so name it with plain `aria:` (`aria: { label: "Tags" }` for a literal
+name, or `aria: { labelledby: "some_id" }` to point at an existing element).
+Through `f.field`, the Control's own visible `label:` / `hint:` name the group
+automatically (the field wires `aria-labelledby` / `aria-describedby` at them).
+Without a name the group renders as before — naming is the caller's call, the
+same posture as Rails' derived form markup.
+
+Field ids derive from scope + name (+ value for group items), exactly like
+Rails' `form_with`; the gem does not guarantee page-wide id uniqueness across
+multiple forms for the same model — scope one form (`Form(model:, scope: …)`) to
+disambiguate, as you would in Rails.
+
 `Form(model: @item, scope: false)` emits **bare** field names
 (`name="quantity"`) — the shape phlex-reactive row editors and
 `<template>`-cloned rows need. External widgets bind through the public

data/app/javascript/phlex_forms/controllers/validations/base_controller.js

@@ -10,7 +10,7 @@ import { Controller } from "@hotwired/stimulus"
 // reads from data attributes; the base class only knows about the
 // `allowBlank` / `allowNil` short-circuits.
 export class FieldValidatorController extends Controller {
-  // `error` is opt-in: callers that pre-render a `<p data-forms--validations--error-target="error">`
+  // `error` is opt-in: callers that pre-render a `<p data-validations--<validator>-target="error">`
   // get a stable slot the controller toggles. Inputs without an
   // explicit target still work — the controller lazily creates one
   // adjacent to the input below.
@@ -24,12 +24,12 @@ export class FieldValidatorController extends Controller {
   // directly to <input>, <textarea>, <select> via the form builder.
   connect() {
     this.element.addEventListener("blur", this.onBlur)
-    this.element.addEventListener("invalidate:forms--validations", this.onValidate)
+    this.element.addEventListener("invalidate:validations", this.onValidate)
   }
 
   disconnect() {
     this.element.removeEventListener("blur", this.onBlur)
-    this.element.removeEventListener("invalidate:forms--validations", this.onValidate)
+    this.element.removeEventListener("invalidate:validations", this.onValidate)
   }
 
   onBlur = () => {
@@ -150,7 +150,7 @@ export class FieldValidatorController extends Controller {
     // adjacent to the input. Keeps the framework usable on plain
     // forms that haven't opted into the static-target convention.
     const id = this.element.id || this.element.name
-    const selector = `[data-forms--validations--error="${id}"]`
+    const selector = `[data-validations--error="${id}"]`
     const existing = this.element.closest("form")?.querySelector(selector)
     if (existing) return existing
     if (!create) return null
@@ -159,7 +159,7 @@ export class FieldValidatorController extends Controller {
     container.className = "text-error text-sm mt-1"
     // `dataset` rejects keys with `--`, so we set the attribute
     // directly. The CSS selector still matches.
-    container.setAttribute("data-forms--validations--error", id)
+    container.setAttribute("data-validations--error", id)
     this.element.insertAdjacentElement("afterend", container)
     return container
   }

data/app/javascript/phlex_forms/controllers/validations/form_controller.js

@@ -3,7 +3,7 @@ import { Controller } from "@hotwired/stimulus"
 // Form-level coordinator for the validation framework. Sits on the
 // <form> element and intercepts `submit` to broadcast a synchronous
 // validation event to every field. Each field controller listens
-// for `invalidate:forms--validations`, runs its check, and (on
+// for `invalidate:validations`, runs its check, and (on
 // failure) appends its error to the event's `detail.errors` array.
 // If anything ended up in that array, we cancel the submit and
 // focus the first invalid field.
@@ -23,11 +23,11 @@ export default class extends Controller {
     fields.forEach((field) => {
       const validators = (field.dataset.controller || "")
         .split(/\s+/)
-        .filter((c) => c.startsWith("forms--validations--") && c !== "forms--validations--form")
+        .filter((c) => c.startsWith("validations--") && c !== "validations--form")
       if (validators.length === 0) return
 
       field.dispatchEvent(
-        new CustomEvent("invalidate:forms--validations", {
+        new CustomEvent("invalidate:validations", {
           detail: { errors },
         }),
       )

data/app/javascript/phlex_forms/controllers/validations/length_controller.js

@@ -12,7 +12,7 @@ export default class extends FieldValidatorController {
   // Stimulus walks the prototype chain to accumulate `static values`
   // and `static targets`, so we only declare the validator-specific
   // ones here. `counter` is opt-in: callers that pre-render
-  // `<span data-forms--validations--length-target="counter">` get a
+  // `<span data-validations--length-target="counter">` get a
   // stable slot the controller updates. Inputs without an explicit
   // target still get a lazily-injected one (see counterElement).
   static targets = ["counter"]
@@ -80,7 +80,7 @@ export default class extends FieldValidatorController {
 
     // Fallback: cache-by-id lookup or lazy injection for plain forms.
     const id = this.element.id || this.element.name
-    const selector = `[data-forms--validations--counter="${id}"]`
+    const selector = `[data-validations--counter="${id}"]`
     const existing = this.element.closest("form")?.querySelector(selector)
     if (existing) return existing
     if (!create) return null
@@ -88,7 +88,7 @@ export default class extends FieldValidatorController {
     const counter = document.createElement("span")
     counter.className = "text-xs text-base-content/60 ml-auto"
     // `dataset` rejects keys containing `--`; use the raw attribute API.
-    counter.setAttribute("data-forms--validations--counter", id)
+    counter.setAttribute("data-validations--counter", id)
     this.element.insertAdjacentElement("afterend", counter)
     return counter
   }

data/lib/forms/checkbox_group.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+module Forms
+  # A batched checkbox group for an array-valued field (the tag/facet-picker
+  # shape). Renders a set of checkboxes sharing ONE array-valued field name
+  # (`user[tag_ids][]`), with a leading empty-array hidden field so an empty
+  # selection still submits, and derives each box's checked state from the
+  # resolved value: of its item against the model's current set.
+  #
+  #   f.checkbox_group(:tag_ids, Tag.all, value: :id,
+  #     label: ->(t) { t.name.presence || t.slug }, variant: :pill, size: :sm)
+  #
+  # value:   method or proc -> the submitted value of each item (default :id)
+  # label:   method or proc -> the visible text of each item (default :to_s)
+  # variant: :stack (default) | :inline | :pill — layout only, zero JS
+  # size:    daisyUI checkbox size modifier (:xs :sm :md :lg :xl)
+  #
+  # Accessible name (issue #17): `role="group"` needs one so a screen reader
+  # announces the group when focus enters a checkbox. The leaf does NOT invent
+  # its own naming API — extra attributes pass straight through to the group
+  # `div`, so the caller names it with plain HTML/ARIA:
+  #
+  #   f.checkbox_group(:tag_ids, Tag.all, value: :id, aria: { label: "Tags" })
+  #   f.checkbox_group(:tag_ids, Tag.all, value: :id, aria: { labelledby: "hdr" })
+  #
+  # Through `f.field`, the builder points the group at the Control's own visible
+  # <label>/hint via `aria: { labelledby:, describedby: }` (so the accessible
+  # name matches what sighted users see) — same passthrough, no special API.
+  #
+  # The checked set is passed in pre-resolved by the builder (Field#checkbox_group
+  # matches the model's current value by each item's resolved value:), so the
+  # component itself stays presentation-only. Each checkbox's markup is delegated
+  # to DaisyUI::Checkbox so its size class is a literal, scanner-visible token.
+  class CheckboxGroup < Phlex::HTML
+    # variant -> the container class. The pill variant uses Tailwind's
+    # `has-[:checked]:` to style the active label with no JS.
+    VARIANT_CLASSES = {
+      stack: "flex flex-col gap-2",
+      inline: "flex flex-wrap gap-4",
+      pill: "flex flex-wrap gap-2"
+    }.freeze
+
+    def initialize(name:, id:, options:, variant: :stack, size: nil, error: false, **attributes)
+      @name = name          # already the array name: "user[tag_ids][]"
+      @id = id
+      @options = options    # [{ value:, label:, checked:, id: }, ...]
+      @variant = variant
+      @size = size
+      @error = error
+      @attributes = attributes
+      super()
+    end
+
+    def view_template
+      # Empty-array hidden field so an empty selection still submits (the same
+      # convention as collection_check_boxes).
+      input(type: "hidden", name: @name, value: "")
+
+      # class is the per-checkbox styling seam (see render_checkbox), not a group
+      # attribute — everything else the caller passed lands on the group so aria:,
+      # data:, id: etc. pass straight through.
+      div(class: group_classes, role: "group", "aria-invalid": @error || nil,
+        **@attributes.except(:class)) do
+        @options.each { |option| item(option) }
+      end
+    end
+
+    private
+
+    def item(option)
+      label(class: item_classes) do
+        render_checkbox(option)
+        span(class: item_label_classes) { option[:label].to_s }
+      end
+    end
+
+    # Delegate the checkbox markup to the daisyui gem so the size modifier
+    # resolves to a literal class (checkbox-sm, ...) the CSS scanner can see.
+    def render_checkbox(option)
+      render DaisyUI::Checkbox.new(
+        *checkbox_modifiers,
+        name: @name, id: option[:id], value: option[:value],
+        checked: option[:checked] || nil, class: @attributes[:class]
+      )
+    end
+
+    def checkbox_modifiers = @size ? [@size] : []
+
+    # --- styling seams (the Plain twin overrides these to bare/empty) ---
+
+    def group_classes = VARIANT_CLASSES.fetch(@variant, VARIANT_CLASSES[:stack])
+
+    def item_classes
+      return "label cursor-pointer gap-2 justify-start" unless @variant == :pill
+
+      "badge badge-lg cursor-pointer gap-2 has-[:checked]:badge-primary"
+    end
+
+    def item_label_classes = nil
+  end
+end

data/lib/forms/field.rb

@@ -67,11 +67,15 @@ module Forms
     end
 
     def radio(value, *modifiers, **options)
+      # field_attributes carries value: field_value (the model's CURRENT value).
+      # Drop it here so it can't clobber this radio's own positional value —
+      # otherwise every radio in the group renders the model's value (issue #13).
+      attrs = field_attributes.except(:value).merge(options)
       theme[:radio].new(
         *modifiers,
         value:,
         checked: field_value == value,
-        **field_attributes.merge(options).merge(id: "#{field_id}_#{value}")
+        **attrs.merge(id: "#{field_id}_#{value}")
       )
     end
     alias radio_button radio
@@ -102,6 +106,29 @@ module Forms
       )
     end
 
+    # A model-bound checkbox group over a collection. Shares one array-valued
+    # field name (`scope[name][]`) and derives the checked set from the model's
+    # current value, matched by each item's resolved value: (issue #9).
+    #
+    #   field.checkbox_group(Tag.all, value: :id, label: ->(t) { t.name })
+    #
+    # value:/label: are a method name (Symbol) or a proc taking the item.
+    def checkbox_group(collection, value: :id, label: :to_s, **)
+      # The model's current value is already the raw values (e.g. record.tag_ids
+      # => [1, 3]), so compare against them directly — don't re-resolve value:.
+      selected = Array(field_value)
+      opts = Array(collection).map do |item|
+        item_value = resolve_item(item, value)
+        {
+          value: item_value,
+          label: resolve_item(item, label),
+          checked: selected.include?(item_value),
+          id: "#{field_id}_#{item_value}"
+        }
+      end
+      theme[:checkbox_group].new(name: "#{field_name}[]", id: field_id, options: opts, error: invalid?, **)
+    end
+
     def label(text = nil, *modifiers, **, &block)
       theme[:label].new(*modifiers, text: text || (block ? nil : field_label), for: field_id, **, &block)
     end
@@ -229,6 +256,11 @@ module Forms
       validator.options.key?(:if) || validator.options.key?(:unless) || validator.options.key?(:on)
     end
 
+    # value:/label: for checkbox_group: a Proc taking the item, or a method name.
+    def resolve_item(item, accessor)
+      accessor.respond_to?(:call) ? accessor.call(item) : item.public_send(accessor)
+    end
+
     def field_attributes
       { name: field_name, id: field_id, value: field_value, error: invalid? }
     end

data/lib/forms/field_hint.rb

@@ -12,7 +12,7 @@ module Forms
     def view_template
       return unless @text
 
-      p(class: classes) { @text }
+      p(class: classes, **@options.except(:class)) { @text }
     end
 
     private

data/lib/forms/form.rb

@@ -104,7 +104,7 @@ module Forms
       attributes_key = nested_attributes ? "#{association_name}_attributes" : association_name.to_s
       base_scope = @scope ? "#{@scope}[#{attributes_key}]" : attributes_key
 
-      if associated.respond_to?(:each_with_index)
+      if collection?(associated)
         associated.each_with_index do |item, index|
           yield build_fields_for("#{base_scope}[#{index}]", item)
         end
@@ -133,6 +133,13 @@ module Forms
       end
     end
 
+    # A batched checkbox group for an array-valued field (issue #9). Delegates to
+    # Field#checkbox_group, which derives the checked set from the model.
+    #   f.checkbox_group(:tag_ids, Tag.all, value: :id, label: :name, variant: :pill)
+    def checkbox_group(name, collection, **)
+      render field_object(name).checkbox_group(collection, **)
+    end
+
     # Rails-style collection_select over an enumerable of records.
     def collection_select(name, collection, value_method, text_method, options = {}, html_options = {})
       choices = collection.map do |item|
@@ -156,6 +163,15 @@ module Forms
 
     private
 
+    # A genuine has_many collection (Array / ActiveRecord::Relation), NOT a
+    # Hash-backed nested scope. A Hash responds to #each_with_index but is a
+    # single nested record (a JSONB column), so iterating it would emit bogus
+    # positional indices — scope[assoc][0][field] — instead of scope[assoc][field]
+    # (issue #10). Enumerable-but-not-Hash covers Relations without requiring AR.
+    def collection?(associated)
+      associated.is_a?(Enumerable) && !associated.is_a?(Hash)
+    end
+
     def build_fields_for(scope, item)
       Forms::FieldsForBuilder.new(
         model: item,
@@ -194,8 +210,16 @@ module Forms
     # UI (novalidate) — the Stimulus layer owns error display.
     def apply_validation_coordinator(attrs)
       existing = attrs[:data][:controller].to_s
-      coordinator = "forms--validations--form"
+      # Derive the coordinator identifier from the introspector's prefix so the
+      # form-level and field-level controllers can never drift (issue #12).
+      coordinator = "#{Forms::Validations::Introspector::CONTROLLER_PREFIX}--form"
       attrs[:data][:controller] = [existing, coordinator].reject(&:empty?).join(" ")
+      # Wire the coordinator's submit handler. Without this data-action the
+      # controller connects but onSubmit never fires, so an invalid form is not
+      # blocked client-side (issue #11). Joined with any caller-supplied action.
+      existing_action = attrs[:data][:action].to_s
+      submit_action = "submit->#{coordinator}#onSubmit"
+      attrs[:data][:action] = [existing_action, submit_action].reject(&:empty?).join(" ")
       attrs[:novalidate] = true
     end
 

data/lib/forms/form_control.rb

@@ -6,27 +6,33 @@ module Forms
   # workhorse behind the Control-first `f.field` API and the explicit `f.Control`
   # escape hatch.
   class FormControl < Phlex::HTML
-    def initialize(*modifiers, label: nil, hint: nil, error: nil, for: nil, required: false, **options)
+    # label_id:/hint_id: give the label and hint stable ids so a group control
+    # (checkbox_group's div[role="group"], which a plain `for`/`id` can't name)
+    # can reference them via aria-labelledby / aria-describedby (issue #17).
+    def initialize(*modifiers, label: nil, hint: nil, error: nil, for: nil, required: false,
+                   label_id: nil, hint_id: nil, **options)
       @modifiers = modifiers
       @label = label
       @hint = hint
       @error = error
       @field_id = grab(for:)
       @required = required
+      @label_id = label_id
+      @hint_id = hint_id
       @options = options
       super()
     end
 
     def view_template(&)
       div(class: control_classes, **@options.except(:class)) do
-        render Forms::Label.new(text: @label, for: @field_id, required: @required) if @label
+        render Forms::Label.new(text: @label, for: @field_id, required: @required, id: @label_id) if @label
 
         yield if block_given?
 
         if @error
           render Forms::FieldError.new(message: @error)
         elsif @hint
-          render Forms::FieldHint.new(text: @hint)
+          render Forms::FieldHint.new(text: @hint, id: @hint_id)
         end
       end
     end

data/lib/forms/plain/checkbox_group.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Forms
+  module Plain
+    # Bare checkbox group. Inherits the whole binding contract from
+    # Forms::CheckboxGroup (the shared array name, the empty-array hidden field,
+    # the per-item checked state) and overrides only the rendering seams to ship
+    # zero daisyUI classes. The invalid state rides aria-invalid on the group,
+    # never a color class.
+    class CheckboxGroup < Forms::CheckboxGroup
+      private
+
+      # Bare <input type=checkbox>, no DaisyUI delegation, no styling classes.
+      def render_checkbox(option)
+        input(
+          type: "checkbox", name: @name, id: option[:id],
+          value: option[:value], class: @attributes[:class],
+          checked: option[:checked] || nil
+        )
+      end
+
+      def group_classes = @attributes[:class]
+      def item_classes = nil
+      def item_label_classes = nil
+    end
+  end
+end

data/lib/forms/plain/control.rb

@@ -7,14 +7,14 @@ module Forms
     class Control < Forms::FormControl
       def view_template
         div(**@options.except(:class), class: @options[:class]) do
-          render Label.new(text: @label, for: @field_id, required: @required) if @label
+          render Label.new(text: @label, for: @field_id, required: @required, id: @label_id) if @label
 
           yield if block_given?
 
           if @error
             render FieldError.new(message: @error)
           elsif @hint
-            render FieldHint.new(text: @hint)
+            render FieldHint.new(text: @hint, id: @hint_id)
           end
         end
       end

data/lib/forms/validations/introspector.rb

@@ -13,7 +13,11 @@ module Forms
     # validation remains authoritative — the client side just
     # shortens the loop for the common cases.
     class Introspector
-      CONTROLLER_PREFIX = "forms--validations"
+      # The Stimulus identifier prefix. Kept in sync with the file path the
+      # controllers ship at (phlex_forms/controllers/validations/*_controller),
+      # so lazyLoadControllersFrom("phlex_forms/controllers") resolves
+      # `validations--length` → .../validations/length_controller (issue #12).
+      CONTROLLER_PREFIX = "validations"
 
       # Validators we know how to mirror. Keys are the short class
       # name (without namespace), values are the controller suffix
@@ -59,9 +63,9 @@ module Forms
 
       # Returns a hash of the shape:
       #   {
-      #     controller: "forms--validations--presence forms--validations--length",
-      #     forms__validations__presence_required_value: "true",
-      #     forms__validations__length_maximum_value: "60",
+      #     controller: "validations--presence validations--length",
+      #     validations__presence_required_value: "true",
+      #     validations__length_maximum_value: "60",
       #   }
       #
       # Returns {} when no supported validators are present.
@@ -95,7 +99,7 @@ module Forms
 
       # Phlex turns underscores in `data:` hash keys into hyphens
       # in the rendered HTML. To produce a key like
-      # `data-forms--validations--length-maximum-value` from a
+      # `data-validations--length-maximum-value` from a
       # Ruby symbol we need every "-" represented as "__" in the
       # symbol. That's what this method builds.
       def data_key(suffix, key)

data/lib/phlex_forms/builder.rb

@@ -81,11 +81,39 @@ module PhlexForms
       options = fo.apply_validations(options)
       choices ||= materialize_choices(inferred.choices)
 
-      render fo.control(label: label_text, hint:, required: req) do
+      # A checkbox_group renders div[role="group"], which a plain <label for> can't
+      # name. Give the Control's label/hint stable ids (control_opts) and point the
+      # group at them with a passed-through aria: { labelledby:, describedby: }
+      # (group_opts), reusing the Control's own visible chrome (issue #17).
+      control_opts, group_opts = group_aria(fo, inferred.as, label_text, hint)
+      options = options.merge(group_opts)
+
+      render fo.control(label: label_text, hint:, required: req, **control_opts) do
         render_field_input(fo, inferred.name, inferred.as, modifiers, choices:, required: req, **options)
       end
     end
 
+    # For a checkbox_group field: the stable ids to stamp on the Control's
+    # label/hint (control_opts), and a group `aria:` hash pointing back at them
+    # (group_opts) — passed through to the group div, no special leaf API. Returns
+    # [{}, {}] for every other field type (a label associates via for/id, no aria
+    # needed) and when neither label nor hint is present.
+    def group_aria(fo, as, label_text, hint)
+      return [{}, {}] unless as == :checkbox_group
+
+      control_opts = {}
+      aria = {}
+      if label_text
+        control_opts[:label_id] = "#{fo.field_id}_label"
+        aria[:labelledby] = control_opts[:label_id]
+      end
+      if hint
+        control_opts[:hint_id] = "#{fo.field_id}_hint"
+        aria[:describedby] = control_opts[:hint_id]
+      end
+      [control_opts, aria.empty? ? {} : { aria: }]
+    end
+
     # ------------------------------------------------------------------
     # Layout helpers
     # ------------------------------------------------------------------
@@ -165,6 +193,9 @@ module PhlexForms
       when :textarea      then render fo.textarea(*modifiers, required:, **)
       when :toggle        then render fo.toggle(*modifiers, required:, **)
       when :checkbox      then render fo.checkbox(*modifiers, required:, **)
+      # required: doesn't apply to a group of checkboxes sharing one array name;
+      # validate the selection server-side instead.
+      when :checkbox_group then render_checkbox_group(fo, **)
       when :file          then render fo.file(*modifiers, required:, **)
       when :hidden        then render fo.hidden(**)
       when :rich_textarea then render fo.rich_textarea(*modifiers, **)
@@ -177,6 +208,14 @@ module PhlexForms
       end
     end
 
+    # `f.field :tag_ids, as: :checkbox_group, collection: Tag.all, value:, label:`.
+    # collection: names the enumerable; the rest (value:/label:/variant:/size:)
+    # passes through to Field#checkbox_group. (choices:/required: are consumed by
+    # render_field_input's own signature, so they never reach here.)
+    def render_checkbox_group(fo, collection: [], **)
+      render fo.checkbox_group(collection, **)
+    end
+
     def materialize_choices(choices)
       choices.respond_to?(:call) ? choices.call : choices
     end

data/lib/phlex_forms/theme.rb

@@ -55,6 +55,7 @@ module PhlexForms
           input: Forms::Input, select: Forms::Select, choices_select: Forms::ChoicesSelect,
           textarea: Forms::Textarea, rich_textarea: Forms::RichTextarea,
           checkbox: Forms::Checkbox, toggle: Forms::Toggle, radio: Forms::Radio,
+          checkbox_group: Forms::CheckboxGroup,
           file: Forms::FileInput, wrapped_input: Forms::WrappedInput,
           control: Forms::FormControl, label: Forms::Label,
           field_error: Forms::FieldError, field_hint: Forms::FieldHint,
@@ -72,6 +73,7 @@ module PhlexForms
           input: Forms::Plain::Input, select: Forms::Plain::Select, choices_select: Forms::Plain::Select,
           textarea: Forms::Plain::Textarea, rich_textarea: Forms::Plain::Textarea,
           checkbox: Forms::Plain::Checkbox, toggle: Forms::Plain::Checkbox, radio: Forms::Plain::Radio,
+          checkbox_group: Forms::Plain::CheckboxGroup,
           file: Forms::Plain::FileInput, wrapped_input: Forms::Plain::WrappedInput,
           control: Forms::Plain::Control, label: Forms::Plain::Label,
           field_error: Forms::Plain::FieldError, field_hint: Forms::Plain::FieldHint,

data/lib/phlex_forms/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module PhlexForms
-  VERSION = "0.2.3"
+  VERSION = "0.2.5"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: phlex-forms
 version: !ruby/object:Gem::Version
-  version: 0.2.3
+  version: 0.2.5
 platform: ruby
 authors:
 - Mikael Henriksson
@@ -114,6 +114,7 @@ files:
 - config/rubocop.yml
 - lib/forms/base.rb
 - lib/forms/checkbox.rb
+- lib/forms/checkbox_group.rb
 - lib/forms/choices_select.rb
 - lib/forms/collection_check_box.rb
 - lib/forms/collection_check_box_builder.rb
@@ -133,6 +134,7 @@ files:
 - lib/forms/live/field.rb
 - lib/forms/password_field.rb
 - lib/forms/plain/checkbox.rb
+- lib/forms/plain/checkbox_group.rb
 - lib/forms/plain/control.rb
 - lib/forms/plain/field_error.rb
 - lib/forms/plain/field_hint.rb