phlex-forms 0.2.2 → 0.2.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c814b751d3d8dd050595b4d29aa7a261dd0b5dbb15787912a58e676fe09d76a9
-  data.tar.gz: 1c9bb1ff0df9584b34a7e9e67a4698a04569d985b0406f9e9d79e60d2abe160f
+  metadata.gz: 74bd32547d30535c35060ea6c93f9cfd199614a9ced2cf1a95a7c32fe62eb3e6
+  data.tar.gz: cf0087d9bee7cb13366ef489fb8764c82867b406881934eb92cdb7dbc271d0f8
 SHA512:
-  metadata.gz: 6d86f0ca8fa5497a118b5e137e9bd23b67a68b4db6076cad19a38d6dc4bad4e3d42a5b3958077666e5f1370658b6069dc9787d816c3904c4717c5f5725d7cac0
-  data.tar.gz: fbe09ab98824da11331b9a6d4abaf502356bb617157b12a68a82096eab790b2d5e794bd2457e8ccd94651e418b69dbab76317e3bfb6542f7dfe7d60d37479d25
+  metadata.gz: 33980ae64283b549a82ab25bd445df927616ac7bc5d0929c41aba13c10439d795c631268e6154bd64a5c0b9783baee4573e7e4efdeef7ecd3e8ac4633791b1bd
+  data.tar.gz: d4d4efd19dd0dbde90311922d91040052925a87948cdcd95d42b50049028186a6cd1b7b80a8b7027154cadd67e8801ad242777817a1ab214d13088e40a5558b3

data/CHANGELOG.md

@@ -9,6 +9,44 @@ 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.
+
+### 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

@@ -90,7 +90,7 @@ control wrapping the label, the input, and an error (or hint).
 | --- | --- |
 | `label:` | Label text. Defaults to the model's humanized attribute name. `label: false` omits it. |
 | `hint:` | Help text shown when there is no error. |
-| `as:` | Override the control: `:select`, `:textarea`, `:toggle`, `:checkbox`, `:file`, `:radio`, `:hidden`, `:rich_textarea`, or any text-like type. |
+| `as:` | Override the control: `:select`, `:textarea`, `:toggle`, `:checkbox`, `:file`, `:radio`, `:hidden`, `:rich_textarea`, `:tags` (see [Tag fields](#tag-fields)), or any text-like type. |
 | `required:` | Force the required flag. Otherwise inferred from the model's presence validators. |
 | `choices:` | Choices for a select (implies `as: :select`). |
 | positional modifiers | daisyui variants — `:primary`, `:lg`, `:ghost`, … — stacked onto the input. |
@@ -154,6 +154,67 @@ end
 
 Both work on inline forms (`f.row { … }`) and inside `fields_for` builders.
 
+### Tag fields
+
+`as: :tags` renders a polished tag/chip input — label + error/hint chrome and
+daisyUI styling on top of
+[phlex-reactive](https://github.com/mhenrixon/phlex-reactive)'s client-only tag
+primitives (form state, no server round trips). **Requires phlex-reactive** (the `:tags` role is
+registered only when it's loaded).
+
+```ruby
+f.field :tags, as: :tags, suggestions: %w[Ruby Rails Hotwire Postgres]
+
+# Hash form: the value is a "haystack" of synonyms the type-ahead filter matches
+f.field :tags, as: :tags, suggestions: { "Postgres" => "postgres database db sql" }
+```
+
+The widget submits **one comma-joined param** (`user[tags] = "Ruby,Rails"`) — the
+primitive's wire contract. The visible type-ahead input carries **no `name`**, so
+it never posts a stray param; only a hidden field does.
+
+Have the model split the comma-joined string back into an array:
+
+```ruby
+class Post < ApplicationRecord
+  attribute :tags, default: []            # a text[] / JSONB column, say
+
+  # accept the widget's "Ruby,Rails" and a normal Array alike
+  def tags=(value)
+    super(value.is_a?(String) ? value.split(",").map(&:strip).reject(&:empty?) : value)
+  end
+end
+```
+
+Notes:
+
+- **Custom styling** — the leaf reads daisyUI classes from overridable seams
+  (`root_classes`, `chip_classes`, `menu_classes`, …). The plain theme's twin
+  (`Forms::Plain::TagField`) keeps the full client wire contract but ships zero
+  styling classes; the invalid state rides `aria-invalid` on the query input.
+- **Inside a `live` form**, declare `live_tags` so the outer form validates the
+  tags too. A standalone tag widget is a *nested* reactive root, so the live
+  root would skip its hidden field — `live_tags` lifts the widget's wire
+  attributes onto the `<form>` root and renders the widget rootless, so the form
+  owns the hidden field and `:validate` sees the value:
+
+  ```ruby
+  class PostForm < Forms::Base
+    live model: Post
+    live_tags :tags, suggestions: %w[Ruby Rails Hotwire]  # lift onto the form root
+
+    def fields
+      field :title
+      field :tags, as: :tags        # renders rootless; the form validates it
+      submit :primary
+    end
+  end
+  ```
+
+  phlex-reactive's tag controller reads **one** tag field per root, so a live
+  form lifts **at most one** — a second `live_tags` raises. A second tag input
+  must stay a standalone (non-live) `field :other, as: :tags`.
+
 ## Escape hatches & custom widgets
 
 The lower-level component methods are always available with stable signatures:
@@ -276,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
@@ -290,13 +356,29 @@ 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
+# ...or through field inference:
+f.field :tag_ids, as: :checkbox_group, collection: Tag.all, value: :id, label: :name
+
 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).
+
 `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,85 @@
+# 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)
+  #
+  # 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: "")
+
+      div(class: group_classes, role: "group", "aria-invalid": @error || nil) 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
@@ -91,6 +95,40 @@ module Forms
       end
     end
 
+    # A model-bound tag/chip input (phlex-reactive client-only primitives).
+    # suggestions: an Array of tags or a Hash of tag => haystack (synonyms the
+    # filter matches). Submits one comma-joined param under the field name.
+    def tag_field(*modifiers, suggestions: [], **)
+      theme[:tag_field].new(
+        *modifiers,
+        name: field_name, id: field_id, value: field_value,
+        suggestions:, error: invalid?, **
+      )
+    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
@@ -218,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/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/live/field.rb

@@ -17,6 +17,30 @@ module Forms
 
         merged.merge(data: merge_data(merged[:data], @live_trigger[:data]))
       end
+
+      # When THIS field is the form's declared `live_tags` field, render the
+      # ROOTLESS variant: no nested reactive root, so the outer <form> DOM-owns
+      # the hidden tags field and live :validate collects it. Its wire attrs were
+      # hoisted onto the form root by Forms::Live#form_attributes. Any other tag
+      # field falls through to the standard (self-rooted, non-live) widget.
+      def tag_field(*modifiers, suggestions: [], **)
+        declaration = @form.class.respond_to?(:live_tags_declaration) && @form.class.live_tags_declaration
+        return super unless declaration && declaration[:name] == @name
+
+        # Call-site suggestions win; otherwise fall back to the declaration's.
+        suggestions = declaration[:suggestions] if blank_suggestions?(suggestions)
+        theme[:rootless_tag_field].new(
+          *modifiers,
+          name: field_name, id: field_id, value: field_value,
+          suggestions:, error: invalid?, **
+        )
+      end
+
+      private
+
+      def blank_suggestions?(suggestions)
+        suggestions.respond_to?(:empty?) ? suggestions.empty? : suggestions.nil?
+      end
     end
   end
 end

data/lib/forms/live.rb

@@ -67,8 +67,38 @@ module Forms
       def live_permit(*attrs) = @live_permit = attrs.map(&:to_s)
       def live_deny(*attrs)   = @live_deny = attrs.map(&:to_s)
 
+      # Lift a tag field onto the form's reactive root so live :validate sees its
+      # comma-joined value. The widget renders ROOTLESS (no nested reactive root),
+      # so the outer <form> DOM-owns the hidden tags field; its wire attrs ride on
+      # the form root (see #form_attributes). The declared tag name is
+      # auto-permitted for :validate assignment.
+      #
+      #   class PostForm < Forms::Base
+      #     live model: Post
+      #     live_tags :tags, suggestions: %w[Ruby Rails]
+      #     def fields = field(:tags, as: :tags)
+      #   end
+      #
+      # phlex-reactive's tag controller reads ONE data-reactive-tags-field per
+      # root, so a live form lifts AT MOST ONE tag field — a second raises.
+      def live_tags(name, suggestions: [])
+        if @live_tags
+          raise ArgumentError,
+            "a live form can lift at most one tag field onto its reactive root " \
+            "(already declared live_tags #{@live_tags[:name].inspect}); render the " \
+            "second as a standalone `field #{name.inspect}, as: :tags` (it stays " \
+            "non-live)."
+        end
+
+        @live_tags = { name: name.to_sym, suggestions: }
+      end
+
+      def live_tags_declaration = @live_tags || inherited_live(:live_tags_declaration)
+
       def live_permitted_attributes(model)
         permitted = @live_permit || derived_live_attributes(model)
+        tag = live_tags_declaration
+        permitted |= [tag[:name].to_s] if tag
         permitted - (@live_deny || [])
       end
 
@@ -129,11 +159,19 @@ module Forms
     # per-element).
     def form_attributes
       attrs = super
-      mix(
+      attrs = mix(
         attrs,
         reactive_root(id: attrs[:id] || id),
         on(:validate, event: "input", debounce: self.class.live_debounce)
       )
+      # Hoist a declared tag field's wire attrs onto the form root so the rootless
+      # widget (rendered in the block) is driven by this root, which then DOM-owns
+      # its hidden field. Name/id derived through field_name/field_id — the same
+      # path the rootless render uses, so the [name=…]/#…_query selectors match.
+      tag = self.class.live_tags_declaration
+      return attrs unless tag
+
+      mix(attrs, Forms::TagField.root_tag_attributes(name: field_name(tag[:name]), id: field_id(tag[:name])))
     end
 
     # Untouched fields get no error set, so nothing flashes before the user

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/rootless_tag_field.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Forms
+  module Plain
+    # The rootless tag field under the plain theme: the wire contract of
+    # Forms::RootlessTagField with the bare-styling seams of Forms::Plain::TagField.
+    # Multiple-inheritance-free: subclass the rootless variant and re-apply the
+    # plain seam overrides.
+    class RootlessTagField < Forms::RootlessTagField
+      private
+
+      def root_classes = "tag-field"
+      def list_classes = nil
+      def menu_classes = nil
+      def option_classes = nil
+      def chip_classes = nil
+      def remove_classes = nil
+      def input_classes = @attributes[:class]
+    end
+  end
+end

data/lib/forms/plain/tag_field.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Forms
+  module Plain
+    # Bare tag/chip input. Inherits the ENTIRE reactive wire contract from
+    # Forms::TagField (the client behavior must still work under the plain theme)
+    # and overrides only the styling seams to ship zero daisyUI classes. The
+    # invalid state rides aria-invalid on the query input, never a color class.
+    #
+    # Like its parent, this file autoloads only when Phlex::Reactive is present
+    # (it inherits from a ClientBindings-including class).
+    class TagField < Forms::TagField
+      private
+
+      def root_classes = "tag-field"
+      def list_classes = nil
+      def menu_classes = nil
+      def option_classes = nil
+      def chip_classes = nil
+      def remove_classes = nil
+      def input_classes = @attributes[:class]
+    end
+  end
+end

data/lib/forms/rootless_tag_field.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Forms
+  # A tag field WITHOUT its own reactive root — for use inside a Forms::Live form,
+  # which is itself the reactive root and carries the tag wire attributes
+  # (data-reactive-tags-field / data-reactive-filter-input, hoisted by
+  # Forms::Live#form_attributes). Emitting no nested root means the hidden tags
+  # field's nearest reactive-root ancestor is the <form>, so the outer form OWNS
+  # it and live :validate collects it (phlex-reactive #ownsField, issue #15).
+  #
+  # Reuses Forms::TagField's #body verbatim (chip/template/suggestion markup), so
+  # the two never drift; it only drops the root <div> wrapper.
+  #
+  # Autoloaded only when Phlex::Reactive is present (it inherits from a
+  # ClientBindings-including class).
+  class RootlessTagField < Forms::TagField
+    def view_template
+      # No reactive_root wrapper: a bare container that groups the body. The tag
+      # attrs live on the ancestor <form>, not here.
+      div(class: root_classes) { body }
+    end
+  end
+end

data/lib/forms/tag_field.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+module Forms
+  # A model-bound tag/chip input, composed from phlex-reactive's CLIENT-ONLY tag
+  # primitives (form state, no token, zero round trips). phlex-forms owns the
+  # polished chrome — daisyUI styling, model binding, the hidden comma-joined
+  # field — while phlex-reactive owns the behavior contract.
+  #
+  #   f.field :tags, as: :tags, suggestions: %w[Ruby Rails Hotwire Postgres]
+  #   f.field :tags, as: :tags, suggestions: { "Postgres" => "postgres database db sql" }
+  #
+  # Submits ONE comma-joined param (`user[tags] = "Ruby,Rails"`), the primitive's
+  # wire contract — the model splits it (an `attribute :tags` + a `tags=` writer,
+  # or an ActiveModel array type).
+  #
+  # This file is autoloaded ONLY when Phlex::Reactive is present (the Forms::Live
+  # gate in lib/phlex_forms.rb) because it includes ClientBindings at class level.
+  # The reactive_tags_* client helpers require phlex-reactive >= 0.11.4.
+  #
+  # It uses the reactive_tags_add/option/remove helpers for the chip/query/option
+  # behavior, but emits the ROOT's `data-reactive-tags-field` raw rather than via
+  # reactive_tags(:tags): that helper compiles a SYMBOL through the class-level
+  # reactive_scope, but a form builder's wire name is per-instance ("user[tags]").
+  # The data attribute IS the public contract; any CSS selector works (issue #6
+  # Caveats 1 & 2). Likewise the query input targets by #id so it never submits.
+  class TagField < Phlex::HTML
+    include Phlex::Reactive::ClientBindings
+
+    def initialize(*modifiers, name:, id:, value: nil, suggestions: [], error: false,
+                   placeholder: "Add a tag…", **attributes)
+      @modifiers = modifiers
+      @name = name # "user[tags]" — instance-dynamic
+      @id = id
+      @value = value.is_a?(Array) ? value.compact.join(",") : value.to_s
+      @suggestions = normalize_suggestions(suggestions)
+      @error = error
+      @placeholder = placeholder
+      @attributes = attributes
+      super()
+    end
+
+    def view_template
+      # Standalone: THIS div is the reactive root. Inside a Forms::Live form the
+      # widget renders rootless (Forms::RootlessTagField) — the outer <form> is
+      # the root and carries these tag attrs — so the form owns the hidden field.
+      div(**mix(reactive_root(id: "#{@id}_widget"), root_tag_attributes, class: root_classes)) do
+        body
+      end
+    end
+
+    # The root's tag wire attrs. Raw, not reactive_tags(:tags)/reactive_filter(:q)
+    # (Caveats 1 & 2): target the hidden field by [name=…] and the query input by
+    # #id (an id selector means the query input never submits a stray param).
+    # Public so Forms::Live can hoist these onto the <form> root when the widget
+    # is lifted rootless.
+    def self.root_tag_attributes(name:, id:)
+      { data: {
+        reactive_tags_field: %([name="#{name}"]),
+        reactive_filter_input: "##{id}_query"
+      } }
+    end
+
+    private
+
+    def root_tag_attributes = self.class.root_tag_attributes(name: @name, id: @id)
+
+    # The widget body WITHOUT its root wrapper — shared with the rootless variant
+    # so chip/template/suggestion markup never drifts between the two.
+    def body
+      input(type: :hidden, name: @name, id: @id, value: @value)
+
+      div(class: list_classes, data: { reactive_tags_list: true }) do
+        current_tags.each { |tag| chip(tag) } # server-rendered first paint
+      end
+      template(data: { reactive_tags_template: true }) { chip }
+
+      # Enter adds free text; mix AFTER reactive_listnav so Enter prefers a
+      # highlighted option. NO name → never submits.
+      input(**mix(reactive_listnav, reactive_tags_add, query_attributes))
+
+      ul(class: menu_classes) do
+        @suggestions.each { |tag, haystack| suggestion(tag, haystack) }
+      end
+    end
+
+    def normalize_suggestions(suggestions)
+      return suggestions if suggestions.is_a?(Hash)
+
+      Array(suggestions).to_h { |tag| [tag, tag.to_s.downcase] }
+    end
+
+    def current_tags = @value.split(",").map(&:strip).reject(&:empty?)
+
+    def query_attributes
+      {
+        id: "#{@id}_query", type: "search", autocomplete: "off",
+        placeholder: @placeholder, class: input_classes,
+        "aria-invalid": @error || nil
+      }.compact
+    end
+
+    # A preloaded suggestion that adds its tag on click (reactive_tags_option
+    # forces type="button" + role="option" + the tagsPick action + the tag
+    # param). The filter haystack rides alongside via mix.
+    def suggestion(tag, haystack)
+      li do
+        button(**mix(reactive_tags_option(tag),
+          { class: option_classes, data: { reactive_filter_text: haystack } })) { tag }
+      end
+    end
+
+    # One method, both forms: with a tag = a server-rendered chip (its remove
+    # button carries the tag param); without = the <template> prototype (the
+    # client fills the text node + the remove button's tag param per clone).
+    def chip(tag = nil)
+      span(class: chip_classes, data: { reactive_tag: tag }) do
+        span(data: { reactive_tag_text: true }) { tag }
+        button(**mix(reactive_tags_remove(tag),
+          { class: remove_classes, aria: { label: "Remove" } })) { "×" }
+      end
+    end
+
+    # --- styling seams (the Plain twin overrides these to bare/empty) ---
+
+    def root_classes = "tag-field flex flex-col gap-2"
+    def list_classes = "flex flex-wrap gap-1"
+    def menu_classes = "menu bg-base-200 rounded-box"
+    def option_classes = nil
+    def chip_classes = "badge badge-primary gap-1"
+    def remove_classes = "cursor-pointer"
+    def input_classes = PhlexForms::ClassMerge.merge("input w-full", @attributes[:class])
+  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

@@ -165,15 +165,29 @@ 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, **)
+      # The tag widget's value lives in a hidden field; `required` on it can't be
+      # satisfied by the browser, so drop it (validate server-side instead).
+      when :tags          then render fo.tag_field(*modifiers, **)
       else
         type = kind == :datetime ? :"datetime-local" : kind
         render fo.input(*(modifiers - INPUT_TYPE_MODIFIERS), type:, required:, **)
       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

@@ -51,29 +51,46 @@ module PhlexForms
             "Gemfile, or use the plain theme."
         end
 
-        @daisy ||= new(
+        @daisy ||= new({
           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,
-          submit: Forms::Submit, row: Forms::Row, group: Forms::Group
-        )
+          submit: Forms::Submit, row: Forms::Row, group: Forms::Group,
+          # tag_field is phlex-reactive-gated (ClientBindings); only registered
+          # when the soft dep is present, else :tag_field raises a clear KeyError.
+          **reactive_roles(Forms::TagField, Forms::RootlessTagField)
+        })
       end
 
       # choices_select degrades to the native plain select (no choices.js) and
       # rich_textarea to a plain textarea; toggle renders as a checkbox.
       def plain
-        @plain ||= new(
+        @plain ||= new({
           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,
-          submit: Forms::Plain::Submit, row: Forms::Plain::Row, group: Forms::Plain::Group
-        )
+          submit: Forms::Plain::Submit, row: Forms::Plain::Row, group: Forms::Plain::Group,
+          **reactive_roles(Forms::Plain::TagField, Forms::Plain::RootlessTagField)
+        })
+      end
+
+      private
+
+      # phlex-reactive-gated roles: mapped only when the soft dep is present. When
+      # absent, the leaf classes aren't autoloaded, so these roles are simply not
+      # registered (fetching one raises the theme's own KeyError with the list).
+      def reactive_roles(tag_field_class, rootless_tag_field_class)
+        return {} unless defined?(Phlex::Reactive)
+
+        { tag_field: tag_field_class, rootless_tag_field: rootless_tag_field_class }
       end
     end
   end

data/lib/phlex_forms/version.rb

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

data/lib/phlex_forms.rb

@@ -91,10 +91,15 @@ loader.ignore("#{__dir__}/phlex_forms/rubocop.rb") # cop entry point (RuboCop::
 loader.ignore("#{__dir__}/phlex_forms/engine.rb")
 
 # The live-validation layer includes Phlex::Reactive::Component at class level,
-# so it can only load when the phlex-reactive soft dependency is present.
+# and the tag_field leaf includes Phlex::Reactive::ClientBindings — both can only
+# load when the phlex-reactive soft dependency is present.
 unless defined?(Phlex::Reactive)
   loader.ignore("#{__dir__}/forms/live.rb")
   loader.ignore("#{__dir__}/forms/live")
+  loader.ignore("#{__dir__}/forms/tag_field.rb")
+  loader.ignore("#{__dir__}/forms/plain/tag_field.rb")
+  loader.ignore("#{__dir__}/forms/rootless_tag_field.rb")
+  loader.ignore("#{__dir__}/forms/plain/rootless_tag_field.rb")
 end
 
 loader.setup

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: phlex-forms
 version: !ruby/object:Gem::Version
-  version: 0.2.2
+  version: 0.2.4
 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
@@ -141,17 +143,21 @@ files:
 - lib/forms/plain/input.rb
 - lib/forms/plain/label.rb
 - lib/forms/plain/radio.rb
+- lib/forms/plain/rootless_tag_field.rb
 - lib/forms/plain/row.rb
 - lib/forms/plain/select.rb
 - lib/forms/plain/submit.rb
+- lib/forms/plain/tag_field.rb
 - lib/forms/plain/textarea.rb
 - lib/forms/plain/wrapped_input.rb
 - lib/forms/radio.rb
 - lib/forms/range.rb
 - lib/forms/rich_textarea.rb
+- lib/forms/rootless_tag_field.rb
 - lib/forms/row.rb
 - lib/forms/select.rb
 - lib/forms/submit.rb
+- lib/forms/tag_field.rb
 - lib/forms/textarea.rb
 - lib/forms/time_zone_select.rb
 - lib/forms/toggle.rb