phlex-forms 0.2.4 → 0.2.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 74bd32547d30535c35060ea6c93f9cfd199614a9ced2cf1a95a7c32fe62eb3e6
-  data.tar.gz: cf0087d9bee7cb13366ef489fb8764c82867b406881934eb92cdb7dbc271d0f8
+  metadata.gz: '0038bad89aee72fb6b4e162bfc83dc9afbaadbc2280f3ea23be2985e81774d41'
+  data.tar.gz: 9b35b71658c4ffbb14667a79e6e85e4a0437d6953b64921272ae629a443a0ac2
 SHA512:
-  metadata.gz: 33980ae64283b549a82ab25bd445df927616ac7bc5d0929c41aba13c10439d795c631268e6154bd64a5c0b9783baee4573e7e4efdeef7ecd3e8ac4633791b1bd
-  data.tar.gz: d4d4efd19dd0dbde90311922d91040052925a87948cdcd95d42b50049028186a6cd1b7b80a8b7027154cadd67e8801ad242777817a1ab214d13088e40a5558b3
+  metadata.gz: b8ada79a4a87a79096b16f82d000ea0e5620096ebe4b8fff9560ae5e556ff982ff6e13ccb52c77e0d7ea72e0d094055595870468de9c40d9f498350bab399eb4
+  data.tar.gz: bce76ac9a71f33cab8c15f6f4b529b636da88d802c4b86ba07ee90948daaa1a2e1c0637f898a11be75e37ab4b8dd7abb8f42ce654a9481907b5cbcc5a299263a

data/CHANGELOG.md

@@ -16,6 +16,13 @@ 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.
 
 ### Changed
 

data/README.md

@@ -366,9 +366,11 @@ 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 (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…")
 ```
@@ -379,6 +381,20 @@ 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/lib/forms/checkbox_group.rb

@@ -15,6 +15,18 @@ module Forms
   # 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 +56,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_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.5"
 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.5
 platform: ruby
 authors:
 - Mikael Henriksson