phlex-forms 0.5.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b43b29cfcccda75c6a0af1c888d3edd50b824f3c393c9938890355143d787231
-  data.tar.gz: 8b231701048287d17a7e44b004f6389f5d760e2b5e36750c90f2416dcbfdca89
+  metadata.gz: 1cbde20cd42869a04e1114e08575a532ea441763b6317893fef4aa9e28bd3902
+  data.tar.gz: ef6910db2fdcc82f01b5b61b50b6433c4e41bee9e72ab0acaae7cc3a12ed7446
 SHA512:
-  metadata.gz: 04f12370599fbae631ac6e88345a7e412eb8f0a143eaa20e76978d8e584aeab6d9657b182e8ac7a424b9624b9df7c362a4008a922c586d4669652fa3da67fa60
-  data.tar.gz: 802635cc20851fbade99760b38c05d6e3e8fb1a67433fedbcb59ff5318e2ef21fb66d202c7e6f0534c530005dfb468c9e4dc67a01fce5b69b3e5a6c8929db18d
+  metadata.gz: 0d4b972c08db3453e7ea345bfa8bacacc18416106a12af4dbdac730a6ebd4a634d26dd3d11cff431c383c41e59c1b352c76e008442095a59bd6e144b1d7cd6d3
+  data.tar.gz: bff7f0a358de04a2d41fa4f387025428033591e4d3f94fa4834a6aaa25427a8f0c509b9352d1d04d9752f42b2e887f2f05d9d1b8737041cec57ab100c2a391f5

data/CHANGELOG.md

@@ -7,7 +7,22 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
-## [0.5.0]
+## [0.6.0] - 2026-11-13
+
+### Added
+
+- **An advisory `recommended:` length on the length rule** (#51):
+  `validate: { length: { maximum: 50, recommended: 32 } }`, or the same
+  options on a model's `validates … length:`, emits
+  `data-validations--length-recommended-value`. The counter reads
+  `n / recommended` up to it, then `n / maximum` with `text-warning`, and
+  `text-error` past the maximum as before. It never adds an error and never
+  becomes `maxlength`; the server ignores it. A counter now renders for
+  `recommended:` alone, and an inline rule may give `recommended:` without a
+  bound. A value that is not a positive Integer below the maximum, or one
+  next to an exact `is:`, is ignored.
+
+## [0.5.0] - 2026-10-15
 
 ### Upgrading to 0.5
 
@@ -72,7 +87,24 @@ read one immutable value, and so can Ractors when every setting can be shared
   plain Ruby host got `NoMethodError` on its first form (and, with finalizing,
   from `configure`). phlex-forms requires json before phlex-reactive.
 
-## [0.4.1] and earlier
+## [0.4.1] - 2026-10-14
+
+### Fixed
+
+- **Client-side validators honour the validator's `message:`** (issue #41).
+  `validates :code, format: { with: /\A[a-z]*\z/, message: "lowercase only" }`
+  used to show the generic "is invalid" in the browser and the specific text
+  only after a round trip. The introspector now emits
+  `data-validations--<validator>-message-value`: a String as is (`%{count}`
+  stays for the browser to fill), a Symbol resolved on the server through
+  ActiveModel's lookup chain in the current locale, a Proc skipped (it needs a
+  record). Length's `too_long:` / `too_short:` / `wrong_length:` win over
+  `message:`, as on the server. Every shipped controller prefers the value and
+  falls back to its bundled message; the submit coordinator collects it too. A
+  `validate: { presence: { message: "…" } }` / `confirmation: { message: "…" }`
+  rules hash now keeps its options (it used to collapse them to `true`).
+
+## [0.4.0] - 2026-09-30
 
 ### Upgrading to 0.4
 
@@ -116,20 +148,10 @@ plus daisyUI's modifier groups). `PhlexForms::ClassMerge` is gone.
   longer raises `FeatureUnavailable`. The Plain theme is unchanged and still
   emits zero daisy classes.
 
+## [0.3.1] - 2026-09-09
+
 ### Fixed
 
-- **Client-side validators honour the validator's `message:`** (issue #41).
-  `validates :code, format: { with: /\A[a-z]*\z/, message: "lowercase only" }`
-  used to show the generic "is invalid" in the browser and the specific text
-  only after a round trip. The introspector now emits
-  `data-validations--<validator>-message-value`: a String as is (`%{count}`
-  stays for the browser to fill), a Symbol resolved on the server through
-  ActiveModel's lookup chain in the current locale, a Proc skipped (it needs a
-  record). Length's `too_long:` / `too_short:` / `wrong_length:` win over
-  `message:`, as on the server. Every shipped controller prefers the value and
-  falls back to its bundled message; the submit coordinator collects it too. A
-  `validate: { presence: { message: "…" } }` / `confirmation: { message: "…" }`
-  rules hash now keeps its options (it used to collapse them to `true`).
 - **`rich_textarea` forwards its block into `<lexxy-editor>`**: Lexxy configures
   an editor through CHILD elements — `<lexxy-prompt>` for @mentions,
   `<lexxy-code-language-picker>` for code blocks — but the component rendered
@@ -146,29 +168,59 @@ plus daisyUI's modifier groups). `PhlexForms::ClassMerge` is gone.
   pin uploads to whichever host rendered the page first), fully guarded — no
   Rails dependency is introduced, and a caller-supplied value always wins.
 
+## [0.3.0] - 2026-08-12
+
+### Fixed
+
 - **`FileInput` multiple uploads submit an array** (Rails `file_field` parity):
   with `multiple:` set, the input name now gets `[]` appended (unless already
   present), for the standalone component, the `Plain` variant, and the form
   builder path. Without it the browser collapsed a multi-file selection into
   ONE scalar param, which a host app's `params.expect(attr: [])` silently
   discarded — uploads no-opped with a success response.
+- **Hidden fields render as bare inputs** (#22): `f.Hidden`, `f.hidden_field`,
+  `f.field(..., as: :hidden)` and `f.Input(..., type: :hidden)` went through
+  the `:input` theme role, so under the daisy theme a hidden field carried
+  `class="input w-full"`, and daisyUI's `display: inline-flex` beat Safari's
+  non-`!important` `display: none`: an empty box and a phantom tab stop. They
+  now render the new `Forms::Hidden` leaf through a new `:hidden` theme role,
+  with no styling classes and no `error:`.
+
+## [0.2.9] - 2026-07-16
+
+### Fixed
+
+- **A caller width class stacked with the `w-full` default instead of replacing
+  it**: `DelegatedField#width_class` joined `"w-full"` and the caller's
+  `class:` verbatim, so `Forms::Select(class: "w-36")` emitted
+  `class="... w-full w-36"` and stylesheet source order — not author intent —
+  picked the winner (in practice `w-full`, which blew filter selects up to full
+  width; zazu#2934). `ClassMerge` gained a width family (anchored `w-*`, so
+  `min-w-*`/`max-w-*` still compose) and `width_class` merges through it —
+  last width wins, matching the daisyui size/color family semantics.
+
+## [0.2.8] - 2026-07-11
+
+### Added
+
+- **`hidden_field`** (#21): a snake_case alias of `f.Hidden` for Rails
+  `FormBuilder` migrations, on inline forms and `fields_for` builders. An
+  explicit `value:` still wins over the model's value.
+
+## [0.2.7] - 2026-07-11
+
+### Changed
+
+- **`tag_field` uses phlex-reactive 0.12.2's escape-hatch sugar**
+  (`reactive_tags` / `reactive_filter`) (#20): the wire name is validated at
+  render, and the client-side type-ahead filter runs again (under
+  phlex-reactive 0.12.x only one of its two selectors was emitted, so it never
+  ran).
+
+## [0.2.6] - 2026-07-11
 
 ### 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.
-- **`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
@@ -177,6 +229,30 @@ plus daisyUI's modifier groups). `PhlexForms::ClassMerge` is gone.
   item text; on the bare verb `label:` stays the item accessor and `item_label:`
   is an alias. Absent it, behavior is unchanged.
 
+## [0.2.5] - 2026-07-11
+
+### Added
+
+- **`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.
+
+## [0.2.4] - 2026-07-11
+
+### 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**:
@@ -191,15 +267,6 @@ plus daisyUI's modifier groups). `PhlexForms::ClassMerge` is gone.
 
 ### Fixed
 
-- **A caller width class stacked with the `w-full` default instead of replacing
-  it**: `DelegatedField#width_class` joined `"w-full"` and the caller's
-  `class:` verbatim, so `Forms::Select(class: "w-36")` emitted
-  `class="... w-full w-36"` and stylesheet source order — not author intent —
-  picked the winner (in practice `w-full`, which blew filter selects up to full
-  width; zazu#2934). `ClassMerge` gained a width family (anchored `w-*`, so
-  `min-w-*`/`max-w-*` still compose) and `width_class` merges through it —
-  last width wins, matching the daisyui size/color family semantics.
-
 - **`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
@@ -216,6 +283,37 @@ plus daisyUI's modifier groups). `PhlexForms::ClassMerge` is gone.
   instead of a single `scope[assoc][field]`. It is now treated as a single
   nested scope; only genuine collections (Enumerable, not Hash) iterate.
 
+## [0.2.3] - 2026-07-08
+
+### Added
+
+- **`tag_field`** (#7): `f.field :tags, as: :tags, suggestions: [...]`, a
+  model-bound tag/chip control composed from phlex-reactive's client-only tag
+  primitives. It submits one comma-joined param; `live_tags` validates it
+  inside a `live` form.
+
+## [0.2.2] - 2026-07-08
+
+### Fixed
+
+- **`Forms::TimeZoneSelect` raised at render time** (#5): `NoMethodError` for
+  `time_zone_options_for_select` (called on the `DaisyUI::Select` receiver)
+  and `Phlex::ArgumentError: Expected a String` (an HTML-safe buffer passed to
+  `safe`). It was broken in 0.2.0 and 0.2.1.
+
+## [0.2.1] - 2026-07-08
+
+### Added
+
+- **Rails form-builder compat aliases** (#4): `Forms::Form#object` (`model`),
+  `#object_name` (`scope`) and `#[]` (`field_object`), and
+  `Forms::FieldsForBuilder#object` / `#[]`, for call sites migrating off an
+  ActionView `FormBuilder`.
+
+## [0.2.0] - 2026-07-08
+
+### Added
+
 - **`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`
@@ -284,7 +382,9 @@ plus daisyUI's modifier groups). `PhlexForms::ClassMerge` is gone.
   Pass `as:` explicitly or set `PhlexForms.config.infer_from_model = false`
   to keep the old rendering.
 
-### Initial extraction
+## [0.1.0] - 2026-07-07
+
+### Added
 
 - Initial extraction of the `Forms::` Phlex form builder from the Cosmos apps.
 - Control-first builder API: `f.field :email, label:, hint:, as:, choices:`

data/README.md

@@ -359,6 +359,31 @@ f.field :note, validate: { length: { maximum: 30, too_long: "keep it under %{cou
 Without a `message:`, the bundled messages apply: they ship for `en` / `fr` /
 `af`; override them page-wide via `window.PhlexForms.messages`.
 
+The length counter can count against an advisory `recommended:` length below
+the hard `maximum:`. It never adds an error, never becomes `maxlength`, and the
+server ignores it (ActiveModel keeps the unknown option without reading it):
+
+```ruby
+f.field :title, as: :textarea, validate: { length: { maximum: 50, recommended: 32 } }
+validates :title, length: { maximum: 50, recommended: 32 }  # the same, from the model
+```
+
+| Length | Counter | Class |
+|---|---|---|
+| up to `recommended` | `n / recommended` | none |
+| past `recommended`, up to `maximum` | `n / maximum` | `text-warning` |
+| past `maximum` | `n / maximum` | `text-error` (and the `too_long` message) |
+
+Without a `maximum:`, the counter reads `n / recommended` and turns
+`text-warning` past it. An inline `validate: { length: { recommended: 32 } }`
+needs no bound; a model-level `validates … length:` still needs one, because
+ActiveModel requires it there. A `recommended:` that is not a positive Integer
+below the maximum, or one next to an exact `is:`, is ignored. The counter's
+`text-warning` / `text-error` classes are toggled from the gem's JavaScript, so
+your Tailwind build must include them. The counter comes from these client-side
+rules only: live validation's server round trip (`Forms::Live`) adds none, and
+a live field shows one only when it also carries client-side length rules.
+
 ## Nested attributes, collections & escape valves
 
 ```ruby

data/app/javascript/phlex_forms/controllers/validations/length_controller.js

@@ -3,12 +3,14 @@ import { interpolate } from "phlex_forms/i18n"
 
 // Mirrors ActiveModel::Validations::LengthValidator. Reads:
 //   - maximum / minimum / is
+//   - recommended (advisory: the counter's target, never an error)
 //   - too-long / too-short / wrong-length messages (win over `message`)
 //   - allow-blank / allow-nil
 //
-// Counter is rendered next to the input when `maximum` is set, so
-// the user gets a live "12 / 60" indicator without having to wait
-// for blur.
+// Counter is rendered next to the input when `maximum` or `recommended`
+// is set, so the user gets a live "12 / 60" indicator without having to
+// wait for blur. Past `recommended` it counts against `maximum` and turns
+// `text-warning`; past `maximum` it turns `text-error`.
 export default class extends FieldValidatorController {
   // Stimulus walks the prototype chain to accumulate `static values`
   // and `static targets`, so we only declare the validator-specific
@@ -21,6 +23,7 @@ export default class extends FieldValidatorController {
     maximum: Number,
     minimum: Number,
     is: Number,
+    recommended: Number,
     tooLongMessage: String,
     tooShortMessage: String,
     wrongLengthMessage: String,
@@ -28,7 +31,7 @@ export default class extends FieldValidatorController {
 
   connect() {
     super.connect()
-    if (this.hasMaximumValue) {
+    if (this.counts) {
       this.renderCounter()
       this.element.addEventListener("input", this.updateCounter)
     }
@@ -36,11 +39,15 @@ export default class extends FieldValidatorController {
 
   disconnect() {
     super.disconnect()
-    if (this.hasMaximumValue) {
+    if (this.counts) {
       this.element.removeEventListener("input", this.updateCounter)
     }
   }
 
+  get counts() {
+    return this.hasMaximumValue || this.recommendedLength(null) !== null
+  }
+
   check(value) {
     const length = this.codepointLength(value)
 
@@ -67,8 +74,35 @@ export default class extends FieldValidatorController {
     const counter = this.counterElement()
     if (!counter) return
     const length = this.codepointLength(this.element.value)
-    counter.textContent = `${length} / ${this.maximumValue}`
-    counter.classList.toggle("text-error", length > this.maximumValue)
+    const { limit, state, advisory } = this.counterState(length)
+    counter.textContent = `${length} / ${limit}`
+    // Without a recommended length the counter is exactly 0.5.0's: a caller's
+    // own `text-warning` on a pre-rendered counter target is left alone.
+    if (advisory) counter.classList.toggle("text-warning", state === "warning")
+    counter.classList.toggle("text-error", state === "error")
+  }
+
+  // The counter's denominator and state. `recommended` applies only below
+  // `maximum` (the server drops it otherwise; this guards a hand-written
+  // attribute): up to it the counter reads "n / recommended", past it
+  // "n / maximum" in a warning colour, past `maximum` an error.
+  counterState(length) {
+    const maximum = this.hasMaximumValue ? this.maximumValue : null
+    const recommended = this.recommendedLength(maximum)
+
+    const advisory = recommended !== null
+
+    if (maximum !== null && length > maximum) return { limit: maximum, state: "error", advisory }
+    if (!advisory) return { limit: maximum, state: null, advisory }
+    if (length <= recommended) return { limit: recommended, state: null, advisory }
+    return { limit: maximum ?? recommended, state: "warning", advisory }
+  }
+
+  recommendedLength(maximum) {
+    if (!this.hasRecommendedValue) return null
+    const recommended = this.recommendedValue
+    if (!(recommended > 0) || (maximum !== null && recommended >= maximum)) return null
+    return recommended
   }
 
   // Ruby's String#length counts Unicode codepoints; JS's String#length

data/lib/forms/validations/introspector.rb

@@ -166,17 +166,32 @@ module Forms
           attrs[key] = opts[key].to_s if opts.key?(key)
         end
 
-        if opts.key?(:in) || opts.key?(:within)
-          range = opts[:in] || opts[:within]
+        range = opts[:in] || opts[:within]
+        if range
           attrs[:minimum] = range.min.to_s
           attrs[:maximum] = range.max.to_s
         end
 
+        attrs[:recommended] = opts[:recommended].to_s if recommended?(opts, range ? range.max : opts[:maximum])
         attrs[:allow_blank] = "true" if opts[:allow_blank]
         attrs[:allow_nil] = "true" if opts[:allow_nil]
         attrs
       end
 
+      # `recommended:` is advisory (the counter's target, never an error), so
+      # it is kept only when it can sit below the hard limit: a positive
+      # Integer under a numeric maximum, or any positive Integer when there is
+      # no maximum. An exact `is:` length leaves nothing to recommend. Anything
+      # else is dropped without raising.
+      def recommended?(opts, maximum)
+        recommended = opts[:recommended]
+        return false unless recommended.is_a?(Integer) && recommended.positive?
+        return false if opts.key?(:is)
+        return true if maximum.nil?
+
+        maximum.is_a?(Numeric) && recommended < maximum
+      end
+
       def format_attrs(validator)
         opts = validator.options
         regex = opts[:with]

data/lib/forms/validations/manual_rules.rb

@@ -21,6 +21,20 @@ module Forms
     #     acceptance: true,
     #   )
     class ManualRules
+      # ActiveModel's LengthValidator demands a bound, so `length: { recommended: 32 }`
+      # alone (an advisory counter with no limit) can't go through `validates`.
+      # This no-op validator carries the options instead; the Introspector matches
+      # it by its short name, LengthValidator, and it never adds an error.
+      module Advisory
+        class LengthValidator < ActiveModel::EachValidator
+          def validate_each(_record, _attribute, _value); end
+        end
+      end
+
+      # The only keys a bound-less advisory rule may carry. Anything else (a
+      # misspelled `maxium:`) goes to ActiveModel, which raises for the missing bound.
+      ADVISORY_LENGTH_KEYS = %i[recommended allow_blank allow_nil].freeze
+
       def initialize(rules)
         @rules = rules
       end
@@ -51,7 +65,11 @@ module Forms
             when :presence
               validates :value, presence: opts.is_a?(Hash) ? opts : true if opts
             when :length
-              validates :value, length: opts
+              if opts.is_a?(Hash) && opts.key?(:recommended) && (opts.keys - ADVISORY_LENGTH_KEYS).empty?
+                validates_with Advisory::LengthValidator, opts.merge(attributes: [:value])
+              else
+                validates :value, length: opts
+              end
             when :format
               validates :value, format: opts
             when :numericality

data/lib/phlex_forms/version.rb

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

metadata

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