phlex-forms 0.4.1 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c9b781532660ae609037596969274d95acbb9eac449c60475c51a91329a9fcb5
-  data.tar.gz: e242d6ecb20a6eb2238b5a2dfb1bb86bd68ad5f2b7a783bdb9b23e2d6cc1c42c
+  metadata.gz: 1cbde20cd42869a04e1114e08575a532ea441763b6317893fef4aa9e28bd3902
+  data.tar.gz: ef6910db2fdcc82f01b5b61b50b6433c4e41bee9e72ab0acaae7cc3a12ed7446
 SHA512:
-  metadata.gz: c9bbc43663fb51f9e8f414702a4aaf7349870ca23f854ce3b9b38220dc32abe42f77820ab840a78708c473d5e30bbb9f918f6ae39025d94b5e94103e9b2ae3de
-  data.tar.gz: 9435b6699cab6da09d974077c8b2ff4f6f83d4f28b0cc44d2fd56419fea1b5bca2cb7347ef86b16a6ede417fddda62ce2d4c03c1e02d9e2ae58b315272701969
+  metadata.gz: 0d4b972c08db3453e7ea345bfa8bacacc18416106a12af4dbdac730a6ebd4a634d26dd3d11cff431c383c41e59c1b352c76e008442095a59bd6e144b1d7cd6d3
+  data.tar.gz: bff7f0a358de04a2d41fa4f387025428033591e4d3f94fa4834a6aaa25427a8f0c509b9352d1d04d9752f42b2e887f2f05d9d1b8737041cec57ab100c2a391f5

data/CHANGELOG.md

@@ -7,6 +7,105 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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
+
+The configuration is frozen once the app has booted, so threads and fibers
+read one immutable value, and so can Ractors when every setting can be shared
+(#42, conformance-kit; see the unshareable-value note below).
+
+- **It finalizes on its own.** Under Rails the engine calls
+  `PhlexForms.finalize!` in `after_initialize`, after every initializer has
+  run, with no app code. Without Rails, `PhlexForms.configure` finalizes when
+  its block returns; a host that never calls `configure` (or loads Rails
+  without booting an app) calls `PhlexForms.finalize!` at boot.
+- **A direct write after boot raises `FrozenError`.** `PhlexForms.config.infer_from_model = false`
+  in a Rails initializer still works. After boot (a test's `before` block, or
+  after `configure` outside Rails), write through `PhlexForms.configure`
+  instead: it edits a copy and swaps it in.
+- **Finalizing never raises over a value it cannot share.** The value is kept
+  as given and works on the main Ractor only: an icon renderer lambda at the
+  top level of an initializer (its `self` is `main`, and it may close over a
+  logger) is one. Define it in a class or module body (or with
+  `Ractor.shareable_lambda` on Ruby 4.0) to keep the whole configuration
+  shareable. A renderer that is not a Proc (an object with `#call`, a
+  `Method`) is never copied or frozen, so one that keeps a cache still works.
+- **`form_options` and the `live` macros keep frozen copies** of what they are
+  given, so the values nested in `form_defaults` and the live settings are
+  frozen. Your own arrays and hashes are copied, never frozen.
+
+### Added
+
+- **`PhlexForms.finalize!`**: freezes the configuration and stores
+  Ractor-shareable copies of its settings. Idempotent; returns the
+  configuration. `PhlexForms::Theme::DAISY` / `PLAIN` are the built-in themes,
+  built once when the theme loads (`Theme.daisy` / `Theme.plain` return them),
+  and every `Theme` is frozen.
+- **Ractor support for the non-rendering paths.** On Ruby 4.0, field
+  inference, option resolution, theme resolution, the icon renderer and the
+  `form_options` / `live` settings work inside a non-main Ractor. Rendering
+  there waits on Phlex
+  ([yippee-fun/phlex#1055](https://github.com/yippee-fun/phlex/pull/1055)).
+- **conformance-kit 0.4 gates in CI**: the thread-safety RuboCop cops, thread
+  and fiber contention specs, a Ractor canary and a strict
+  `conformance-audit` of `PhlexForms` and `Forms` with nothing allowlisted.
+
+### Changed
+
+- **The configuration is frozen after boot** (see Upgrading to 0.5).
+  `Configuration` sets every default in `initialize`; no reader memoizes. The
+  default icon renderer and `Configuration.glyphs_renderer` are shareable.
+- `rich_textarea` renders `<lexxy-editor>` through Phlex's `tag` instead of
+  `register_element`; the markup is the same.
+
+### Fixed
+
+- **The themes build without phlex-reactive.** `Theme.daisy` named
+  `Forms::TagField` before checking for the soft dependency, so a host without
+  phlex-reactive got `NameError: uninitialized constant Forms::TagField` on its
+  first form.
+- **`Theme.daisy` / `Theme.plain` are built once.** Two threads resolving a
+  theme for the first time could each build their own.
+- **phlex-forms loads without Rails with phlex-reactive bundled.** phlex-reactive's
+  `Sortable` calls `Hash#to_json` while it loads without requiring json, so a
+  plain Ruby host got `NoMethodError` on its first form (and, with finalizing,
+  from `configure`). phlex-forms requires json before phlex-reactive.
+
+## [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
 
 phlex-forms now depends on **daisyui `~> 2.0`** and merges every default +
@@ -49,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
@@ -79,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
@@ -110,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**:
@@ -124,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
@@ -149,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`
@@ -217,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
@@ -437,6 +462,33 @@ PhlexForms.configure do |c|
 end
 ```
 
+## Configuration is finalized at boot
+
+`PhlexForms.configure` writes the configuration; finalizing freezes it and
+stores Ractor-shareable copies of its settings, so threads and fibers read one
+immutable value, and so can Ractors when every setting can be shared (see
+below). It happens on its own:
+
+- **Under Rails** the engine finalizes in `after_initialize`, once every
+  initializer has run, so initializers can still write (through `configure`
+  or directly).
+- **Without Rails** (no `Rails::Engine` when phlex-forms loads), `configure`
+  finalizes when its block returns. A host that never calls `configure`, or
+  loads Rails without booting an app, calls `PhlexForms.finalize!` at boot.
+
+After that, write through `configure` again (it edits a copy and swaps it in);
+a direct `PhlexForms.config.theme = :plain` raises `FrozenError`. Your own
+arrays and hashes are copied, never frozen.
+
+Finalizing never raises over a value it cannot share: that value is kept as
+given and works on the main Ractor only. An icon renderer lambda at the top
+level of an initializer (its `self` is `main`, and it may close over a logger)
+is one; define it in a class or module body (or with `Ractor.shareable_lambda`
+on Ruby 4.0) to keep the whole configuration shareable. A renderer that is not
+a Proc (an object with `#call`, a `Method`) is never copied or frozen, so one
+that keeps a cache still works. `PhlexForms.reset_configuration!` restores the
+open defaults (for test suites).
+
 ## RuboCop cops
 
 Two cops nudge call sites toward the phlex-forms API. Enable them in your

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/base.rb

@@ -26,9 +26,14 @@ module Forms
       # (instance args beat class defaults; subclass defaults beat parents'):
       #
       #   form_options :spaced, url: "/signup", validate: true
+      #
+      # A class macro: it runs while the form class body loads (at boot, on the
+      # main Ractor) and stores Ractor-shareable copies of its arguments
+      # (PhlexForms::Shareable.copy), so the readers work in any Ractor.
+      # rubocop:disable ThreadSafety/ClassInstanceVariable
       def form_options(*modifiers, **defaults)
-        @form_modifiers = modifiers
-        @form_defaults = defaults
+        @form_modifiers = PhlexForms::Shareable.copy(modifiers)
+        @form_defaults = PhlexForms::Shareable.copy(defaults)
       end
 
       def form_modifiers
@@ -40,6 +45,7 @@ module Forms
         inherited = superclass.respond_to?(:form_defaults) ? superclass.form_defaults : {}
         inherited.merge(@form_defaults || {})
       end
+      # rubocop:enable ThreadSafety/ClassInstanceVariable
 
       # Server-truth live validation via phlex-reactive (a soft dependency):
       #

data/lib/forms/live.rb

@@ -42,10 +42,15 @@ module Forms
     end
 
     class_methods do
+      # live (setup_live), live_permit, live_deny and live_tags are class macros:
+      # they run while the form class body loads (at boot, on the main Ractor)
+      # and store Ractor-shareable values (PhlexForms::Shareable.copy), so the
+      # readers work in any Ractor.
+      # rubocop:disable ThreadSafety/ClassInstanceVariable
       def setup_live(model_class:, scope:, debounce:)
         @live_model_class = model_class
-        @live_scope = scope.to_s
-        @live_debounce = debounce
+        @live_scope = PhlexForms::Shareable.copy(scope.to_s)
+        @live_debounce = PhlexForms::Shareable.copy(debounce)
         reactive_state :model_gid, :touched
         action :validate, params: { scope.to_sym => :form_attributes, _touch: :string }
         # phlex-reactive >= 0.11 defaults verify_authorized ON: an action that
@@ -64,8 +69,8 @@ module Forms
       # Narrow (live_permit) or trim (live_deny) the attributes the :validate
       # action may assign. Default: the model's column/attribute names plus
       # every validated attribute (and its _confirmation twin).
-      def live_permit(*attrs) = @live_permit = attrs.map(&:to_s)
-      def live_deny(*attrs)   = @live_deny = attrs.map(&:to_s)
+      def live_permit(*attrs) = @live_permit = PhlexForms::Shareable.copy(attrs.map(&:to_s))
+      def live_deny(*attrs)   = @live_deny = PhlexForms::Shareable.copy(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),
@@ -90,7 +95,7 @@ module Forms
             "non-live)."
         end
 
-        @live_tags = { name: name.to_sym, suggestions: }
+        @live_tags = PhlexForms::Shareable.copy({ name: name.to_sym, suggestions: })
       end
 
       def live_tags_declaration = @live_tags || inherited_live(:live_tags_declaration)
@@ -101,6 +106,7 @@ module Forms
         permitted |= [tag[:name].to_s] if tag
         permitted - (@live_deny || [])
       end
+      # rubocop:enable ThreadSafety/ClassInstanceVariable
 
       private
 
@@ -219,5 +225,11 @@ module Forms
         @model.public_send(setter, value) if @model.respond_to?(setter)
       end
     end
+
+    # ActiveSupport::Concern's own list of the concerns this one includes
+    # (Phlex::Reactive::Component): filled while this module body loads and
+    # only read after, when a form class includes Forms::Live. Frozen, so the
+    # module holds no mutable state.
+    @_dependencies.freeze
   end
 end

data/lib/forms/rich_textarea.rb

@@ -6,8 +6,6 @@ module Forms
   # Renders an editor bound to the field; when the value is an ActionText::RichText
   # its HTML body is used as the initial content.
   class RichTextarea < Phlex::HTML
-    register_element :lexxy_editor
-
     def initialize(*modifiers, name:, id: nil, value: nil, **options)
       @modifiers = modifiers
       @name = name
@@ -20,9 +18,12 @@ module Forms
 
     # Lexxy configures the editor through CHILD elements — `<lexxy-prompt>` for
     # @mentions, `<lexxy-code-language-picker>` for code blocks — so the block
-    # has to reach the element, not be dropped.
+    # has to reach the element, not be dropped. Rendered through `tag`, not a
+    # `register_element` method, so the class keeps no element registry of its
+    # own.
     def view_template(&)
-      lexxy_editor(
+      tag(
+        :lexxy_editor,
         name: @name,
         id: @id,
         value: formatted_value,

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/configuration.rb

@@ -22,7 +22,23 @@ module PhlexForms
   # glyphs is intentionally NOT the default: rails_icons reads SVGs from the host
   # app's asset paths, which a minimal host (or the gem's own test suite) has not
   # set up — so defaulting to glyphs would raise Icons::IconNotFound.
+  #
+  # Finalized at boot: `configure` finalizes when the Rails engine is absent, the
+  # engine's after_initialize does under Rails (or call `PhlexForms.finalize!`).
+  # Finalizing freezes the configuration and stores Ractor-shareable copies of
+  # its settings, so any Ractor can read it. A renderer that cannot be shared (a
+  # lambda written at the top level of an initializer has `main` as its self) is
+  # kept as given and still works on the main Ractor; build it in a class or
+  # module body, or with `Ractor.shareable_lambda` on Ruby 4.0, to keep the
+  # whole configuration shareable. A renderer that is not a Proc (an object with
+  # #call, a Method) is never copied or frozen: it is shared only if it already
+  # is. After finalizing, write through `configure`, which edits a copy and
+  # swaps it in.
   class Configuration
+    # The bundled inline SVGs. Built in the class body (self is the class and the
+    # lambda captures nothing), so it can be made shareable once, here.
+    DEFAULT_ICON_RENDERER = Shareable.copy(->(name, **opts) { InlineIcons.render(name, **opts) })
+
     # A ready-made renderer that delegates to glyphs' LucideIcon. Raises a clear
     # error if glyphs is not loaded.
     def self.glyphs_renderer
@@ -31,7 +47,7 @@ module PhlexForms
           "PhlexForms glyphs_renderer requires the `glyphs` gem to be loaded"
       end
 
-      ->(name, **opts) { Glyphs::LucideIcon.new(name, **opts) }
+      Shareable.copy(->(name, **opts) { Glyphs::LucideIcon.new(name, **opts) })
     end
 
     attr_writer :icon_renderer
@@ -43,29 +59,48 @@ module PhlexForms
 
     # Global daisyui variants prepended to every `field`'s inner input, e.g.
     # `c.field_variants = [:primary]`. Form-level `field_variants:` and
-    # call-site modifiers stack after (later wins).
-    attr_writer :field_variants
-
-    def field_variants
-      @field_variants ||= []
+    # call-site modifiers stack after (later wins). nil means none, stored as an
+    # empty list so `c.field_variants << :sm` keeps working.
+    def field_variants=(variants)
+      @field_variants = variants || []
     end
 
     # The default theme: :daisy, :plain, or a PhlexForms::Theme instance.
     # Defaults to daisy.
     attr_writer :theme
 
+    # Every default is set here, never memoized by a reader, so concurrent
+    # readers never race to build one. The theme stays nil until set or
+    # finalized (the reader falls back to Theme.daisy), so building a
+    # configuration loads no component.
+    def initialize
+      @theme = nil
+      @infer_from_model = true
+      @field_variants = []
+      @icon_renderer = DEFAULT_ICON_RENDERER
+    end
+
+    # `configure` on a finalized configuration edits a copy: give the copy its
+    # own variants list, so `c.field_variants << :sm` works on it.
+    def initialize_copy(source)
+      super
+      @field_variants = @field_variants.dup
+    end
+
+    def field_variants
+      @field_variants || []
+    end
+
     def theme
-      @theme ||= Theme.daisy
+      @theme || Theme.daisy
     end
 
     def infer_from_model
-      return @infer_from_model if defined?(@infer_from_model) && !@infer_from_model.nil?
-
-      true
+      @infer_from_model.nil? || @infer_from_model
     end
 
     def icon_renderer
-      @icon_renderer ||= ->(name, **opts) { InlineIcons.render(name, **opts) }
+      @icon_renderer || DEFAULT_ICON_RENDERER
     end
 
     # Returns a renderable for the named icon. Components pass the result to Phlex
@@ -73,5 +108,18 @@ module PhlexForms
     def render_icon(name, **)
       icon_renderer.call(name.to_s, **)
     end
+
+    # Stores Ractor-shareable copies of every setting and freezes the
+    # configuration. Resolves the default theme, which builds both built-in
+    # themes at boot rather than on the first render. Idempotent; returns self.
+    def finalize!
+      return self if frozen?
+
+      @theme = Shareable.copy(theme)
+      @infer_from_model = Shareable.copy(@infer_from_model)
+      @field_variants = Shareable.copy(@field_variants)
+      @icon_renderer = Shareable.callable(@icon_renderer)
+      freeze
+    end
   end
 end

data/lib/phlex_forms/engine.rb

@@ -32,6 +32,10 @@ module PhlexForms
       app.config.i18n.load_path.unshift(*locales)
     end
 
+    # PhlexForms.configure leaves the configuration open under Rails; freeze it
+    # (with Ractor-shareable settings) once every initializer has run.
+    config.after_initialize { PhlexForms.finalize! }
+
     # The raw-hash param type Forms::Live's :validate action schema declares.
     # Registered from an initializer because phlex-reactive freezes its
     # param-type registry after boot.

data/lib/phlex_forms/shareable.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module PhlexForms
+  # Ractor-shareable copies of boot-time settings (the configuration, the
+  # form_options / live class macros), so any Ractor can read them after boot.
+  module Shareable
+    module_function
+
+    # A deep-frozen, Ractor-shareable copy of value; value itself is left as the
+    # caller has it. A Proc cannot be copied, so it is shared in place, which
+    # works only when its self and everything it captures are already shareable
+    # (it never freezes them). A value that cannot be shared (a Proc whose self
+    # is not shareable, an IO, ...) comes back unchanged: it still works on the
+    # main Ractor. Engines without Ractor get the value back as is.
+    def copy(value)
+      return value unless defined?(::Ractor)
+      return value if ::Ractor.shareable?(value)
+      return ::Ractor.make_shareable(value) if value.is_a?(::Proc)
+
+      ::Ractor.make_shareable(value, copy: true)
+    rescue ::Ractor::Error, ::TypeError
+      value
+    end
+
+    # A callable (the icon renderer) shared only where that leaves it working: a
+    # Proc as in copy, any other object kept as given. A frozen copy of an
+    # object would break one that keeps state of its own (a cache, a buffer)
+    # on its first call, and a Method cannot be copied.
+    def callable(value)
+      value.is_a?(::Proc) ? copy(value) : value
+    end
+  end
+end

data/lib/phlex_forms/theme.rb

@@ -19,8 +19,10 @@ module PhlexForms
   #
   #   PhlexForms::Theme.resolve(:plain).with(input: MyInput)
   class Theme
+    # Frozen, so a theme of component classes is Ractor-shareable.
     def initialize(components)
       @components = components.freeze
+      freeze
     end
 
     def [](role)
@@ -45,48 +47,53 @@ module PhlexForms
         end
       end
 
-      def daisy
-        @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,
-          checkbox_group: Forms::CheckboxGroup,
-          file: Forms::FileInput, wrapped_input: Forms::WrappedInput, hidden: Forms::Hidden,
-          control: Forms::FormControl, label: Forms::Label,
-          field_error: Forms::FieldError, field_hint: Forms::FieldHint,
-          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
+      def daisy = DAISY
 
-      # 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({
-          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,
-          checkbox_group: Forms::Plain::CheckboxGroup,
-          file: Forms::Plain::FileInput, wrapped_input: Forms::Plain::WrappedInput, hidden: Forms::Hidden,
-          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,
-          **reactive_roles(Forms::Plain::TagField, Forms::Plain::RootlessTagField)
-        })
-      end
+      def plain = PLAIN
 
       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)
+      # Takes the namespace, not the classes: naming Forms::TagField without
+      # phlex-reactive would raise NameError before the guard ran.
+      def reactive_roles(namespace)
         return {} unless defined?(Phlex::Reactive)
 
-        { tag_field: tag_field_class, rootless_tag_field: rootless_tag_field_class }
+        { tag_field: namespace::TagField, rootless_tag_field: namespace::RootlessTagField }
       end
     end
+
+    # Both built-ins are built once, when this file loads (never memoized by a
+    # reader, so no two threads race to build one; PhlexForms.finalize! loads
+    # it at boot), and the phlex-reactive probe is evaluated once, here.
+    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,
+      checkbox_group: Forms::CheckboxGroup,
+      file: Forms::FileInput, wrapped_input: Forms::WrappedInput, hidden: Forms::Hidden,
+      control: Forms::FormControl, label: Forms::Label,
+      field_error: Forms::FieldError, field_hint: Forms::FieldHint,
+      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)
+    })
+
+    # choices_select degrades to the native plain select (no choices.js) and
+    # rich_textarea to a plain textarea; toggle renders as a checkbox.
+    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,
+      checkbox_group: Forms::Plain::CheckboxGroup,
+      file: Forms::Plain::FileInput, wrapped_input: Forms::Plain::WrappedInput, hidden: Forms::Hidden,
+      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,
+      **reactive_roles(Forms::Plain)
+    })
   end
 end

data/lib/phlex_forms/version.rb

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

data/lib/phlex_forms.rb

@@ -10,6 +10,11 @@ require "zeitwerk"
 require "daisy_ui"
 
 begin
+  # phlex-reactive's Sortable calls Hash#to_json while it loads without
+  # requiring json (a Rails host has it loaded already). Finalizing builds the
+  # themes, which load the tag-field leaves and with them Sortable, so without
+  # Rails `configure` would raise NoMethodError.
+  require "json"
   require "phlex/reactive"
 rescue LoadError
   # phlex-reactive is a soft dependency: without it the `live` server-truth
@@ -32,17 +37,38 @@ module PhlexForms
   # used but its backing dependency is not available.
   class FeatureUnavailable < Error; end
 
+  # @configuration is built when this file loads (see the bottom) and replaced
+  # only by configure and reset_configuration!, on the main Ractor at boot or
+  # between tests (a non-main Ractor cannot write a module ivar). Once finalized
+  # it is frozen and Ractor-shareable, so any Ractor may read it.
+  # rubocop:disable-next ThreadSafety/ClassInstanceVariable
   class << self
-    def configuration
-      @configuration ||= Configuration.new
-    end
+    attr_reader :configuration
     alias config configuration
 
+    # Yields the configuration, then finalizes it unless the Rails engine is
+    # loaded (its after_initialize finalizes once every initializer has run). A
+    # finalized configuration is never edited in place: the block gets a copy,
+    # which is finalized and swapped in whole. Returns the block's value.
     def configure
-      yield(configuration)
+      if @configuration.frozen?
+        draft = @configuration.dup
+        result = yield(draft)
+        @configuration = draft.finalize!
+      else
+        result = yield(@configuration)
+        finalize! unless defined?(PhlexForms::Engine)
+      end
+      result
+    end
+
+    # Freezes the configuration with Ractor-shareable settings (see
+    # Configuration#finalize!). Idempotent; returns the configuration.
+    def finalize!
+      @configuration.finalize!
     end
 
-    # Reset configuration to defaults. Intended for test isolation.
+    # Reset configuration to defaults, open again. Intended for test isolation.
     def reset_configuration!
       @configuration = Configuration.new
     end
@@ -97,6 +123,10 @@ end
 
 loader.setup
 
+# The default configuration, built at load (never lazily, so no two readers
+# race to create it).
+PhlexForms.reset_configuration!
+
 # Optional Rails integration (Stimulus controllers via importmap/assets, and
 # the gem's default locale files). Loaded only under Rails; the gem stays pure
 # Phlex otherwise.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: phlex-forms
 version: !ruby/object:Gem::Version
-  version: 0.4.1
+  version: 0.6.0
 platform: ruby
 authors:
 - Mikael Henriksson
@@ -189,6 +189,7 @@ files:
 - lib/phlex_forms/inference.rb
 - lib/phlex_forms/inline_icons.rb
 - lib/phlex_forms/rubocop.rb
+- lib/phlex_forms/shareable.rb
 - lib/phlex_forms/theme.rb
 - lib/phlex_forms/version.rb
 - lib/rubocop/phlex_forms/cop/legacy_form_method.rb