phlex-forms 0.2.5 → 0.2.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '0038bad89aee72fb6b4e162bfc83dc9afbaadbc2280f3ea23be2985e81774d41'
-  data.tar.gz: 9b35b71658c4ffbb14667a79e6e85e4a0437d6953b64921272ae629a443a0ac2
+  metadata.gz: d963c5c0eb08c6027d236da0489af8e2b7fd5ef258092c91cc280c8fe4711c5e
+  data.tar.gz: d1a686ce5b6b249c3860584c8b7a9447e4198efe7d0b6c9aed86441a3d7ee915
 SHA512:
-  metadata.gz: b8ada79a4a87a79096b16f82d000ea0e5620096ebe4b8fff9560ae5e556ff982ff6e13ccb52c77e0d7ea72e0d094055595870468de9c40d9f498350bab399eb4
-  data.tar.gz: bce76ac9a71f33cab8c15f6f4b529b636da88d802c4b86ba07ee90948daaa1a2e1c0637f898a11be75e37ab4b8dd7abb8f42ce654a9481907b5cbcc5a299263a
+  metadata.gz: 4563f81fac25d23e76303ee2c96f2734add870c5b5707b8d45683a62479fccc30d0cd36464492627bb7bbabba209f41df8d657514d37a7fd748715d1af3150ab
+  data.tar.gz: 39961525f504962d9345cb6e9ab6215c624717d710db5e801b6fad872a8b60dc792233f66f653711c17aa694aa961263d720a8c75084e54d6832c55315c57f65

data/CHANGELOG.md

@@ -23,6 +23,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   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.
+- **`checkbox_group` `item_label:`** — the per-item text accessor, so a
+  `f.field(:tags, as: :checkbox_group, label: "Tags", item_label: ->(t){…})`
+  renders a visible group heading (`label:`, via the Control) AND custom item
+  labels at once — previously `label:` on the `f.field` path was eaten by the
+  heading and items fell back to `to_s`. `item_label:` wins over `label:` for the
+  item text; on the bare verb `label:` stays the item accessor and `item_label:`
+  is an alias. Absent it, behavior is unchanged.
 
 ### Changed
 

data/README.md

@@ -368,9 +368,13 @@ f.checkbox_group(:tag_ids, Tag.all, value: :id,
   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):
+# ...or through field inference. Here `label:`/`hint:` are the field's VISIBLE
+# heading + description (rendered by the Control, which also names the group);
+# `item_label:` gives the per-item text, so you get a heading AND custom item
+# labels at once:
 f.field :tag_ids, as: :checkbox_group, collection: Tag.all, value: :id,
-  label: "Tags", hint: "Pick any"
+  label: "Tags", hint: "Pick any",
+  item_label: ->(t) { t.name.presence || t.slug }, variant: :pill
 
 f.collection_select(:country_id, Country.all, :id, :name, prompt: "Select…")
 ```
@@ -381,6 +385,13 @@ 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).
 
+**Two labels, no collision.** Through `f.field`, `label:` is the field's visible
+group heading (the Control renders it); the per-item text comes from `item_label:`
+(a Symbol method or Proc). On the bare `f.checkbox_group` verb there is no Control
+heading, so `label:` *is* the per-item accessor (and `item_label:` is accepted as
+an alias). Either way `value:` is the submitted value; `item_label:` wins over
+`label:` for the item text when both are present.
+
 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

data/lib/forms/checkbox_group.rb

@@ -8,10 +8,13 @@ module Forms
   # 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)
+  #     item_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)
+  # The item value/text accessors (value:/label:/item_label:) live on the BUILDER
+  # (Forms::Field#checkbox_group), which pre-resolves each item to
+  # { value:, label:, checked:, id: } before this leaf renders. This leaf is
+  # presentation-only — it receives the resolved options: array, never the raw
+  # accessors.
   # variant: :stack (default) | :inline | :pill — layout only, zero JS
   # size:    daisyUI checkbox size modifier (:xs :sm :md :lg :xl)
   #

data/lib/forms/field.rb

@@ -112,8 +112,20 @@ module Forms
     #
     #   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, **)
+    # value: is a method name (Symbol) or a proc taking the item -> its submitted
+    # value. The per-item visible text comes from item_label: (Symbol/Proc/String)
+    # if given, else label:; when NEITHER is given each item is labelled by the
+    # first of name/title/label/to_s it responds to (the same LABEL_METHODS chain
+    # Inference uses for association choices) — so a plain
+    # `f.field(:tags, as: :checkbox_group, label: "Tags")` shows readable item
+    # text without an explicit accessor.
+    #
+    # item_label: exists so the `f.field` path can pass a visible group heading as
+    # `label:` (consumed by the Control) AND still customize the per-item text
+    # here — the two no longer collide. item_label: is consumed here; it never
+    # leaks to the group div.
+    def checkbox_group(collection, value: :id, label: nil, item_label: nil, **)
+      text = item_label || label
       # 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)
@@ -121,7 +133,7 @@ module Forms
         item_value = resolve_item(item, value)
         {
           value: item_value,
-          label: resolve_item(item, label),
+          label: text ? resolve_item(item, text) : infer_item_label(item),
           checked: selected.include?(item_value),
           id: "#{field_id}_#{item_value}"
         }
@@ -256,9 +268,25 @@ 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.
+    # value:/label:/item_label: for checkbox_group. A Proc is called with the
+    # item; a String is literal text (the same for every item — no method
+    # dispatch, so a stray string can't NoMethodError); anything else (a Symbol)
+    # is sent to the item as a method name.
     def resolve_item(item, accessor)
-      accessor.respond_to?(:call) ? accessor.call(item) : item.public_send(accessor)
+      case accessor
+      when Proc   then accessor.call(item)
+      when String then accessor
+      else item.public_send(accessor)
+      end
+    end
+
+    # Default per-item label when no label:/item_label: was given: the first of
+    # name/title/label/to_s the item responds to (mirrors PhlexForms::Inference's
+    # LABEL_METHODS for association choices, so option text is picked the same way
+    # across the gem).
+    def infer_item_label(item)
+      method = PhlexForms::Inference::LABEL_METHODS.find { |m| item.respond_to?(m) }
+      item.public_send(method || :to_s)
     end
 
     def field_attributes

data/lib/forms/live.rb

@@ -168,10 +168,16 @@ module Forms
       # 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.
+      # This form IS a reactive component, so it has reactive_tags/reactive_filter
+      # itself — the same 0.12.2 escape-hatch sugar Forms::TagField uses, emitting
+      # both filter selectors the client needs (issue #6 Caveats 1 & 2).
       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])))
+      query_id = Forms::TagField.query_id(field_id(tag[:name]))
+      mix(attrs,
+        reactive_tags(name: field_name(tag[:name])),
+        reactive_filter(input: "##{query_id}"))
     end
 
     # Untouched fields get no error set, so nothing flashes before the user

data/lib/forms/tag_field.rb

@@ -18,11 +18,13 @@ module Forms
   # 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.
+  # behavior, and the ROOT's wire attrs come from the 0.12.2 escape-hatch sugar:
+  # reactive_tags(name: @name) takes the per-instance wire name verbatim ("user[tags]")
+  # — the class-level reactive_scope compile can't express it — validated at render;
+  # reactive_filter(input: "#…_query") targets the query input by id so it never
+  # submits, and (unlike the old raw -input-only attr) also emits
+  # data-reactive-filter-option so the 0.12.x client type-ahead actually runs
+  # (issue #6 Caveats 1 & 2).
   class TagField < Phlex::HTML
     include Phlex::Reactive::ClientBindings
 
@@ -48,21 +50,26 @@ module Forms
       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
+    # The query input's id — the reactive_filter(input:) target and the id the
+    # search input itself carries. Public so Forms::Live can derive the same id
+    # when it hoists the tag wire attrs onto the <form> root (rootless widget).
+    def self.query_id(id) = "#{id}_query"
 
     private
 
-    def root_tag_attributes = self.class.root_tag_attributes(name: @name, id: @id)
+    # The root's tag wire attrs, via the 0.12.2 escape-hatch sugar (Caveats 1 & 2):
+    # reactive_tags(name:) takes the instance-dynamic wire name verbatim and
+    # validates it at render; reactive_filter(input:) targets the query input by
+    # #id (so it never submits a stray param) and emits both filter selectors the
+    # 0.12.x client needs to run the type-ahead. Both are private helpers from
+    # ClientBindings — Forms::Live has its own copies (it's a reactive component)
+    # and calls them directly when hoisting these onto the <form> root.
+    def root_tag_attributes
+      mix(
+        reactive_tags(name: @name),
+        reactive_filter(input: "##{self.class.query_id(@id)}")
+      )
+    end
 
     # The widget body WITHOUT its root wrapper — shared with the rootless variant
     # so chip/template/suggestion markup never drifts between the two.
@@ -93,7 +100,7 @@ module Forms
 
     def query_attributes
       {
-        id: "#{@id}_query", type: "search", autocomplete: "off",
+        id: self.class.query_id(@id), type: "search", autocomplete: "off",
         placeholder: @placeholder, class: input_classes,
         "aria-invalid": @error || nil
       }.compact

data/lib/phlex_forms/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: phlex-forms
 version: !ruby/object:Gem::Version
-  version: 0.2.5
+  version: 0.2.7
 platform: ruby
 authors:
 - Mikael Henriksson