phlex-forms 0.4.1 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c9b781532660ae609037596969274d95acbb9eac449c60475c51a91329a9fcb5
-  data.tar.gz: e242d6ecb20a6eb2238b5a2dfb1bb86bd68ad5f2b7a783bdb9b23e2d6cc1c42c
+  metadata.gz: b43b29cfcccda75c6a0af1c888d3edd50b824f3c393c9938890355143d787231
+  data.tar.gz: 8b231701048287d17a7e44b004f6389f5d760e2b5e36750c90f2416dcbfdca89
 SHA512:
-  metadata.gz: c9bbc43663fb51f9e8f414702a4aaf7349870ca23f854ce3b9b38220dc32abe42f77820ab840a78708c473d5e30bbb9f918f6ae39025d94b5e94103e9b2ae3de
-  data.tar.gz: 9435b6699cab6da09d974077c8b2ff4f6f83d4f28b0cc44d2fd56419fea1b5bca2cb7347ef86b16a6ede417fddda62ce2d4c03c1e02d9e2ae58b315272701969
+  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 +

data/README.md

@@ -437,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/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/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.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.1
+  version: 0.5.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