phlex-forms 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 26a87406065dfe0b6d5b023949661d89548c3ad6379af9d0e4d74c4162f49070
-  data.tar.gz: b36430b1faf88ad5095a358709bce31a72869c40619dc527bc3e04be10450c0f
+  metadata.gz: b43b29cfcccda75c6a0af1c888d3edd50b824f3c393c9938890355143d787231
+  data.tar.gz: 8b231701048287d17a7e44b004f6389f5d760e2b5e36750c90f2416dcbfdca89
 SHA512:
-  metadata.gz: f9e5a95dfea504c6b487c23a0b5683a4a68391b4e07ff33192b548a40a5b7eff3a0562e0af1097a20bbeca3762017254fe626fb1fe7079408996815f8b1d7a71
-  data.tar.gz: 1ae2b903bfe9057f1705b3d3a6e788c16acf1c4d837c0bdbd723434aca71c45432d194ebf638ce17c14d597826751a6c4bb124e92f02e7b3d01fdf29ac6bbf34
+  metadata.gz: 04f12370599fbae631ac6e88345a7e412eb8f0a143eaa20e76978d8e584aeab6d9657b182e8ac7a424b9624b9df7c362a4008a922c586d4669652fa3da67fa60
+  data.tar.gz: 802635cc20851fbade99760b38c05d6e3e8fb1a67433fedbcb59ff5318e2ef21fb66d202c7e6f0534c530005dfb468c9e4dc67a01fce5b69b3e5a6c8929db18d

data/CHANGELOG.md

@@ -7,6 +7,73 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.5.0]
+
+### 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] and earlier
+
 ### Upgrading to 0.4
 
 phlex-forms now depends on **daisyui `~> 2.0`** and merges every default +
@@ -51,6 +118,18 @@ plus daisyUI's modifier groups). `PhlexForms::ClassMerge` is gone.
 
 ### 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

data/README.md

@@ -345,7 +345,19 @@ the form-level `validations--form` coordinator), which `lazyLoadControllersFrom`
 resolves to `phlex_forms/controllers/validations/*_controller` — the path the gem
 ships them at.
 
-Messages ship for `en` / `fr` / `af`; override via `window.PhlexForms.messages`.
+A validator's own `message:` reaches the browser too, so the client shows what
+the server would: a String as is (`%{value}` is filled in, and `%{count}` for
+rules that have one: length and the numericality bounds), a Symbol resolved on
+the server through your app's i18n, a Proc skipped (it needs a record).
+Length's `too_long:` / `too_short:` / `wrong_length:` win over `message:`.
+
+```ruby
+validates :code, format: { with: /\A[a-z]*\z/, message: "may only contain lowercase letters" }
+f.field :note, validate: { length: { maximum: 30, too_long: "keep it under %{count}" } }
+```
+
+Without a `message:`, the bundled messages apply: they ship for `en` / `fr` /
+`af`; override them page-wide via `window.PhlexForms.messages`.
 
 ## Nested attributes, collections & escape valves
 
@@ -425,6 +437,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/acceptance_controller.js

@@ -1,5 +1,4 @@
 import { FieldValidatorController } from "phlex_forms/controllers/validations/base_controller"
-import { t } from "phlex_forms/i18n"
 
 // Mirrors ActiveModel::Validations::AcceptanceValidator. For
 // checkboxes, asserts `.checked`. For other inputs, asserts the
@@ -11,11 +10,11 @@ export default class extends FieldValidatorController {
 
   check(value) {
     if (this.element.type === "checkbox") {
-      return this.element.checked ? null : t("js.forms.validations.acceptance.accepted")
+      return this.element.checked ? null : this.messageOr("js.forms.validations.acceptance.accepted")
     }
     try {
       const list = JSON.parse(this.acceptValue)
-      return list.map(String).includes(String(value ?? "")) ? null : t("js.forms.validations.acceptance.accepted")
+      return list.map(String).includes(String(value ?? "")) ? null : this.messageOr("js.forms.validations.acceptance.accepted")
     } catch (_e) {
       return null
     }

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

@@ -1,4 +1,5 @@
 import { Controller } from "@hotwired/stimulus"
+import { interpolate, t } from "phlex_forms/i18n"
 
 // Shared base for every field-level validator. Subclasses implement
 // `check(value)` and return either `null` (valid) or a translation
@@ -8,7 +9,8 @@ import { Controller } from "@hotwired/stimulus"
 //
 // Each subclass declares its own `static values` for the rules it
 // reads from data attributes; the base class only knows about the
-// `allowBlank` / `allowNil` short-circuits.
+// `allowBlank` / `allowNil` short-circuits and the `message` value,
+// which carries the validator's own `message:` option (issue #41).
 export class FieldValidatorController extends Controller {
   // `error` is opt-in: callers that pre-render a `<p data-validations--<validator>-target="error">`
   // get a stable slot the controller toggles. Inputs without an
@@ -18,6 +20,7 @@ export class FieldValidatorController extends Controller {
   static values = {
     allowBlank: { type: Boolean, default: false },
     allowNil: { type: Boolean, default: false },
+    message: String,
   }
 
   // Element must be the input itself — these controllers are attached
@@ -64,6 +67,14 @@ export class FieldValidatorController extends Controller {
     return null
   }
 
+  // The validator's own `message:` when the server rendered one, else the
+  // bundled translation for `key`. Either way `%{count}` & co. are filled in;
+  // a custom message may also carry `%{value}`, as on the server.
+  messageOr(key, vars = {}) {
+    if (!(this.hasMessageValue && this.messageValue)) return t(key, vars)
+    return interpolate(this.messageValue, { value: this.fieldValue(), ...vars })
+  }
+
   shouldSkip(value) {
     if (this.allowNilValue && (value === null || value === undefined)) return true
     if (this.allowBlankValue && this.isBlank(value)) return true

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

@@ -1,5 +1,4 @@
 import { FieldValidatorController } from "phlex_forms/controllers/validations/base_controller"
-import { t } from "phlex_forms/i18n"
 
 // Mirrors ActiveModel::Validations::ConfirmationValidator. Looks
 // for the `<name>_confirmation` field by name within the same form
@@ -15,7 +14,7 @@ export default class extends FieldValidatorController {
     if (!form) return null
     const partner = form.elements[this.matchValue] || this.partnerByAttribute(form)
     if (!partner) return null
-    return String(partner.value) === String(value ?? "") ? null : t("js.forms.validations.confirmation.confirmation")
+    return String(partner.value) === String(value ?? "") ? null : this.messageOr("js.forms.validations.confirmation.confirmation")
   }
 
   partnerByAttribute(form) {

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

@@ -1,5 +1,4 @@
 import { FieldValidatorController } from "phlex_forms/controllers/validations/base_controller"
-import { t } from "phlex_forms/i18n"
 
 // Mirrors ActiveModel::Validations::ExclusionValidator.
 export default class extends FieldValidatorController {
@@ -11,7 +10,7 @@ export default class extends FieldValidatorController {
     if (!this.hasInValue) return null
     try {
       const list = JSON.parse(this.inValue)
-      return list.map(String).includes(String(value ?? "")) ? t("js.forms.validations.exclusion.exclusion") : null
+      return list.map(String).includes(String(value ?? "")) ? this.messageOr("js.forms.validations.exclusion.exclusion") : null
     } catch (_e) {
       return null
     }

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

@@ -1,5 +1,4 @@
 import { FieldValidatorController } from "phlex_forms/controllers/validations/base_controller"
-import { t } from "phlex_forms/i18n"
 
 // Mirrors ActiveModel::Validations::FormatValidator.
 export default class extends FieldValidatorController {
@@ -12,7 +11,7 @@ export default class extends FieldValidatorController {
     if (!this.hasPatternValue) return null
     try {
       const regex = new RegExp(this.patternValue, this.flagsValue)
-      return regex.test(String(value ?? "")) ? null : t("js.forms.validations.format.invalid")
+      return regex.test(String(value ?? "")) ? null : this.messageOr("js.forms.validations.format.invalid")
     } catch (_e) {
       // If Rails' regex doesn't translate cleanly to JS, fall back to
       // letting the server be the authority — don't block submit on a

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

@@ -1,5 +1,4 @@
 import { FieldValidatorController } from "phlex_forms/controllers/validations/base_controller"
-import { t } from "phlex_forms/i18n"
 
 // Mirrors ActiveModel::Validations::InclusionValidator.
 export default class extends FieldValidatorController {
@@ -11,7 +10,7 @@ export default class extends FieldValidatorController {
     if (!this.hasInValue) return null
     try {
       const list = JSON.parse(this.inValue)
-      return list.map(String).includes(String(value ?? "")) ? null : t("js.forms.validations.inclusion.inclusion")
+      return list.map(String).includes(String(value ?? "")) ? null : this.messageOr("js.forms.validations.inclusion.inclusion")
     } catch (_e) {
       return null
     }

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

@@ -1,8 +1,9 @@
 import { FieldValidatorController } from "phlex_forms/controllers/validations/base_controller"
-import { t } from "phlex_forms/i18n"
+import { interpolate } from "phlex_forms/i18n"
 
 // Mirrors ActiveModel::Validations::LengthValidator. Reads:
 //   - maximum / minimum / is
+//   - 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
@@ -20,6 +21,9 @@ export default class extends FieldValidatorController {
     maximum: Number,
     minimum: Number,
     is: Number,
+    tooLongMessage: String,
+    tooShortMessage: String,
+    wrongLengthMessage: String,
   }
 
   connect() {
@@ -41,17 +45,24 @@ export default class extends FieldValidatorController {
     const length = this.codepointLength(value)
 
     if (this.hasIsValue && length !== this.isValue) {
-      return t("js.forms.validations.length.wrong_length", { count: this.isValue })
+      return this.lengthMessage(this.wrongLengthMessageValue, "wrong_length", this.isValue)
     }
     if (this.hasMaximumValue && length > this.maximumValue) {
-      return t("js.forms.validations.length.too_long", { count: this.maximumValue })
+      return this.lengthMessage(this.tooLongMessageValue, "too_long", this.maximumValue)
     }
     if (this.hasMinimumValue && length < this.minimumValue) {
-      return t("js.forms.validations.length.too_short", { count: this.minimumValue })
+      return this.lengthMessage(this.tooShortMessageValue, "too_short", this.minimumValue)
     }
     return null
   }
 
+  // A per-case message (`too_long:` & co.) wins over `message:`, as on the
+  // server; the bundled translation is the final fallback.
+  lengthMessage(caseMessage, key, count) {
+    if (caseMessage) return interpolate(caseMessage, { value: this.fieldValue(), count })
+    return this.messageOr(`js.forms.validations.length.${key}`, { count })
+  }
+
   updateCounter = () => {
     const counter = this.counterElement()
     if (!counter) return

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

@@ -1,5 +1,4 @@
 import { FieldValidatorController } from "phlex_forms/controllers/validations/base_controller"
-import { t } from "phlex_forms/i18n"
 
 // Mirrors ActiveModel::Validations::NumericalityValidator.
 export default class extends FieldValidatorController {
@@ -20,40 +19,40 @@ export default class extends FieldValidatorController {
     if (raw === "") return null
 
     const number = Number(raw)
-    if (Number.isNaN(number)) return t("js.forms.validations.numericality.not_a_number")
+    if (Number.isNaN(number)) return this.messageOr("js.forms.validations.numericality.not_a_number")
 
     if (this.onlyIntegerValue && !Number.isInteger(number)) {
-      return t("js.forms.validations.numericality.not_an_integer")
+      return this.messageOr("js.forms.validations.numericality.not_an_integer")
     }
     if (this.hasGreaterThanValue && !(number > this.greaterThanValue)) {
-      return t("js.forms.validations.numericality.greater_than", { count: this.greaterThanValue })
+      return this.messageOr("js.forms.validations.numericality.greater_than", { count: this.greaterThanValue })
     }
     if (this.hasGreaterThanOrEqualToValue && !(number >= this.greaterThanOrEqualToValue)) {
-      return t("js.forms.validations.numericality.greater_than_or_equal_to", {
+      return this.messageOr("js.forms.validations.numericality.greater_than_or_equal_to", {
         count: this.greaterThanOrEqualToValue,
       })
     }
     if (this.hasLessThanValue && !(number < this.lessThanValue)) {
-      return t("js.forms.validations.numericality.less_than", { count: this.lessThanValue })
+      return this.messageOr("js.forms.validations.numericality.less_than", { count: this.lessThanValue })
     }
     if (this.hasLessThanOrEqualToValue && !(number <= this.lessThanOrEqualToValue)) {
-      return t("js.forms.validations.numericality.less_than_or_equal_to", {
+      return this.messageOr("js.forms.validations.numericality.less_than_or_equal_to", {
         count: this.lessThanOrEqualToValue,
       })
     }
     if (this.hasEqualToValue && number !== this.equalToValue) {
-      return t("js.forms.validations.numericality.equal_to", { count: this.equalToValue })
+      return this.messageOr("js.forms.validations.numericality.equal_to", { count: this.equalToValue })
     }
     if (this.hasOtherThanValue && number === this.otherThanValue) {
-      return t("js.forms.validations.numericality.other_than", { count: this.otherThanValue })
+      return this.messageOr("js.forms.validations.numericality.other_than", { count: this.otherThanValue })
     }
     // Rails' NumericalityValidator coerces with `.to_i` before
     // checking parity, so `2.5` is treated as `2` (even). JS `%` on
     // a float diverges from that — truncate first to keep client and
     // server in agreement.
     const truncated = Math.trunc(number)
-    if (this.oddValue && truncated % 2 === 0) return t("js.forms.validations.numericality.odd")
-    if (this.evenValue && truncated % 2 !== 0) return t("js.forms.validations.numericality.even")
+    if (this.oddValue && truncated % 2 === 0) return this.messageOr("js.forms.validations.numericality.odd")
+    if (this.evenValue && truncated % 2 !== 0) return this.messageOr("js.forms.validations.numericality.even")
     return null
   }
 }

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

@@ -1,5 +1,4 @@
 import { FieldValidatorController } from "phlex_forms/controllers/validations/base_controller"
-import { t } from "phlex_forms/i18n"
 
 // Mirrors ActiveModel::Validations::PresenceValidator.
 export default class extends FieldValidatorController {
@@ -9,6 +8,6 @@ export default class extends FieldValidatorController {
 
   check(value) {
     if (!this.requiredValue) return null
-    return this.isBlank(value) ? t("js.forms.validations.presence.blank") : null
+    return this.isBlank(value) ? this.messageOr("js.forms.validations.presence.blank") : null
   }
 }

data/app/javascript/phlex_forms/i18n.js

@@ -26,7 +26,7 @@ function lookup(scope, locale) {
   return scope.split(".").reduce((node, key) => (node == null ? undefined : node[key]), table)
 }
 
-function interpolate(string, vars) {
+export function interpolate(string, vars = {}) {
   return string.replace(/%\{(\w+)\}/g, (_, key) => (key in vars ? String(vars[key]) : `%{${key}}`))
 }
 

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

@@ -46,6 +46,11 @@ module Forms
         only_integer odd even
       ].freeze
 
+      # LengthValidator's per-case messages; each wins over `message:` on the
+      # server, so the length controller checks them first. Each maps to the
+      # bound it reports, so a Symbol resolves with that count.
+      LENGTH_MESSAGE_KEYS = { too_long: :maximum, too_short: :minimum, wrong_length: :is }.freeze
+
       # Convenience: returns a null introspector for nil models so
       # callers don't need to guard.
       def self.for(model_or_class)
@@ -83,7 +88,8 @@ module Forms
           next unless suffix
 
           controllers << "#{CONTROLLER_PREFIX}--#{suffix}"
-          value_attributes(suffix, validator, attribute).each do |key, value|
+          value_attributes(suffix, validator, attribute).merge(message_attrs(suffix, validator, attribute))
+            .each do |key, value|
             attrs[data_key(suffix, key)] = value
           end
         end
@@ -131,6 +137,23 @@ module Forms
         end
       end
 
+      # `message` (and length's `too_long_message` & co.) values, for the
+      # validator's own `message:` options. Omitted when there is none, or when
+      # it can't be resolved without a record, so the generic message stays.
+      def message_attrs(suffix, validator, attribute)
+        counts = suffix == "length" ? length_message_counts(validator) : {}
+        options = counts.keys + [:message]
+        options.each_with_object({}) do |option, attrs|
+          text = Message.resolve(validator.options[option], model_class:, attribute:, count: counts[option])
+          attrs[option == :message ? :message : :"#{option}_message"] = text if text
+        end
+      end
+
+      def length_message_counts(validator)
+        bounds = length_attrs(validator)
+        LENGTH_MESSAGE_KEYS.to_h { |option, bound| [option, bounds[bound]&.to_i] }
+      end
+
       def presence_attrs
         { required: "true" }
       end

data/lib/forms/validations/manual_rules.rb

@@ -13,7 +13,7 @@ module Forms
     #   ManualRules.new(
     #     length: { maximum: 60, minimum: 3 },
     #     presence: true,
-    #     format: { with: /\A[a-z]+\z/i },
+    #     format: { with: /\A[a-z]+\z/i, message: "letters only" },
     #     numericality: { greater_than_or_equal_to: 0 },
     #     inclusion: { in: %w[a b c] },
     #     exclusion: { in: %w[admin] },
@@ -49,7 +49,7 @@ module Forms
           captured_rules.each do |key, opts|
             case key
             when :presence
-              validates :value, presence: true if opts
+              validates :value, presence: opts.is_a?(Hash) ? opts : true if opts
             when :length
               validates :value, length: opts
             when :format
@@ -61,7 +61,7 @@ module Forms
             when :exclusion
               validates :value, exclusion: opts
             when :confirmation
-              validates :value, confirmation: true if opts
+              validates :value, confirmation: opts.is_a?(Hash) ? opts : true if opts
             when :acceptance
               validates :value, acceptance: opts.is_a?(Hash) ? opts : { accept: %w[1 true] }
             end

data/lib/forms/validations/message.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module Forms
+  module Validations
+    # Turns a validator's `message:` option into the text the browser should
+    # show, so the client mirror says what the server would (issue #41).
+    #
+    #   - a String is emitted as is; `%{count}`-style placeholders stay in place
+    #     for the Stimulus controller to fill, as it does for its own messages.
+    #     A blank String resolves to nil: the browser reads "" as valid.
+    #   - a Symbol is resolved on the server through ActiveModel's lookup chain
+    #     (`<scope>.errors.models.<model>.attributes.<attr>.<key>` ... then
+    #     `errors.messages.<key>`), in the current locale. With a known `count:`
+    #     (length's per-case messages) it is passed to I18n, so a pluralised
+    #     translation picks the right form; otherwise `%{count}` stays a
+    #     placeholder and the plural `:other` form is used.
+    #   - anything else (a Proc needs a record) resolves to nil, so the
+    #     controller keeps its generic message.
+    #
+    # Mirrors `ActiveModel::Error.generate_message` against the class alone: the
+    # introspector never instantiates the model.
+    class Message
+      # Interpolations the browser fills in, kept as literal placeholders.
+      PLACEHOLDERS = { count: "%{count}", value: "%{value}" }.freeze
+
+      def self.resolve(message, model_class:, attribute:, count: nil)
+        case message
+        when String then message unless message.empty?
+        when Symbol then new(model_class, attribute).translate(message, count:)
+        end
+      end
+
+      def initialize(model_class, attribute)
+        @model_class = model_class
+        @attribute = attribute.to_s
+      end
+
+      def translate(key, count: nil)
+        return unless defined?(I18n)
+
+        first, *rest = lookup_keys(key)
+        vars = interpolations
+        vars[:count] = count unless count.nil?
+        I18n.translate(first, **vars, default: rest, raise: true)
+      rescue StandardError
+        nil
+      end
+
+      private
+
+      attr_reader :model_class, :attribute
+
+      def lookup_keys(key)
+        model_keys(key) + [:"errors.attributes.#{attribute}.#{key}", :"errors.messages.#{key}"]
+      end
+
+      def model_keys(key)
+        return [] unless model_class.respond_to?(:i18n_scope) && model_class.respond_to?(:lookup_ancestors)
+
+        scope = model_class.i18n_scope
+        keys = model_class.lookup_ancestors.flat_map do |klass|
+          i18n_key = klass.model_name.i18n_key
+          [:"#{scope}.errors.models.#{i18n_key}.attributes.#{attribute}.#{key}",
+            :"#{scope}.errors.models.#{i18n_key}.#{key}"]
+        end
+        keys << :"#{scope}.errors.messages.#{key}"
+      end
+
+      def interpolations
+        names = {}
+        names[:model] = model_class.model_name.human if model_class.respond_to?(:model_name)
+        names[:attribute] = model_class.human_attribute_name(attribute) if model_class.respond_to?(:human_attribute_name)
+        PLACEHOLDERS.merge(names)
+      end
+    end
+  end
+end

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.0"
+  VERSION = "0.5.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.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Mikael Henriksson
@@ -178,6 +178,7 @@ files:
 - lib/forms/toggle.rb
 - lib/forms/validations/introspector.rb
 - lib/forms/validations/manual_rules.rb
+- lib/forms/validations/message.rb
 - lib/forms/wrapped_input.rb
 - lib/phlex-forms.rb
 - lib/phlex_forms.rb
@@ -188,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