phlex-forms 0.2.4 → 0.2.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 74bd32547d30535c35060ea6c93f9cfd199614a9ced2cf1a95a7c32fe62eb3e6
-  data.tar.gz: cf0087d9bee7cb13366ef489fb8764c82867b406881934eb92cdb7dbc271d0f8
+  metadata.gz: fd321ccbe2bec3d9b8966d0eda0e1036e4143af38b4aa55dec702ce8c6d23137
+  data.tar.gz: 2abe25e3c63dd5d689a6c6d762df3ed6204c0dca0ef6b7d569f6e8c3da4ee1d7
 SHA512:
-  metadata.gz: 33980ae64283b549a82ab25bd445df927616ac7bc5d0929c41aba13c10439d795c631268e6154bd64a5c0b9783baee4573e7e4efdeef7ecd3e8ac4633791b1bd
-  data.tar.gz: d4d4efd19dd0dbde90311922d91040052925a87948cdcd95d42b50049028186a6cd1b7b80a8b7027154cadd67e8801ad242777817a1ab214d13088e40a5558b3
+  metadata.gz: fb8b8768817fef4b18e0dacadbfb966cf7356339badfce5e96ea04ccc7e0d5bcc60686e65288413376bbe7873e17993746b35dceefb917a58132505ef88f9094
+  data.tar.gz: e7f775c0c15db6e595f9ac5c93449fb49b12d032f1a615f231b5e23f1aa2ac188fb2eb21a6afccf073758227a3e100a69def8f24185baadd63ddc19e923a48e0

data/CHANGELOG.md

@@ -16,6 +16,20 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   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.
+- **`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

@@ -366,9 +366,15 @@ 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
+  size: :sm,                                  # daisyUI checkbox size
+  aria: { label: "Tags" })                    # names the group for screen readers
+# ...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",
+  item_label: ->(t) { t.name.presence || t.slug }, variant: :pill
 
 f.collection_select(:country_id, Country.all, :id, :name, prompt: "Select…")
 ```
@@ -379,6 +385,27 @@ 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
+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/lib/forms/checkbox_group.rb

@@ -8,13 +8,28 @@ 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)
   #
+  # 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
@@ -44,7 +59,11 @@ module Forms
       # convention as collection_check_boxes).
       input(type: "hidden", name: @name, value: "")
 
-      div(class: group_classes, role: "group", "aria-invalid": @error || nil) do
+      # 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

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/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_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/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/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
     # ------------------------------------------------------------------

data/lib/phlex_forms/version.rb

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

metadata

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