phlex-forms 0.2.2 → 0.2.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c814b751d3d8dd050595b4d29aa7a261dd0b5dbb15787912a58e676fe09d76a9
-  data.tar.gz: 1c9bb1ff0df9584b34a7e9e67a4698a04569d985b0406f9e9d79e60d2abe160f
+  metadata.gz: 536c63a40e17d971808a285a30d6bd8a96a0f0049ecdd1fc2472e39d2359337b
+  data.tar.gz: 81460e049eccf72d1181420e705834b111bcd64aa5e4865f04fa811350c423f1
 SHA512:
-  metadata.gz: 6d86f0ca8fa5497a118b5e137e9bd23b67a68b4db6076cad19a38d6dc4bad4e3d42a5b3958077666e5f1370658b6069dc9787d816c3904c4717c5f5725d7cac0
-  data.tar.gz: fbe09ab98824da11331b9a6d4abaf502356bb617157b12a68a82096eab790b2d5e794bd2457e8ccd94651e418b69dbab76317e3bfb6542f7dfe7d60d37479d25
+  metadata.gz: 1479141adae7a0f38ed945d1cd572b6a1ad6c0504964d6690e0f4db1ed1a901f8f9ba99c6e2af497020bce01adbca8fbe1ab36c46f59815296c6b46bc894f482
+  data.tar.gz: a72f1a2367fc0e0ddcc155241805e5c70943c7d11ebe5a08ad88f2e33f2094e7a03b14ecbd61fc4f205072f0473f3e6ba9cf5413ed3ce3a8313a920db5309d1e

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:

data/lib/forms/field.rb

@@ -91,6 +91,17 @@ 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
+
     def label(text = nil, *modifiers, **, &block)
       theme[:label].new(*modifiers, text: text || (block ? nil : field_label), for: field_id, **, &block)
     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/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/phlex_forms/builder.rb

@@ -168,6 +168,9 @@ module PhlexForms
       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:, **)

data/lib/phlex_forms/theme.rb

@@ -51,29 +51,44 @@ 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,
           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,
           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.3"
 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.3
 platform: ruby
 authors:
 - Mikael Henriksson
@@ -141,17 +141,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