phlex-forms 0.1.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0c3cb45e86fb22d3240e3d9b0441476376004c2996c2b08e682c00e86ad51fd7
-  data.tar.gz: d5abd208265060aade20c4b70a834c3404124dec41534892e243babae60f19b0
+  metadata.gz: 07e978bd7062d93d342a6048d51a54559abecf20098ae39eda81c10497856578
+  data.tar.gz: 30c5714c27d7a892da6eb591a4c3e98cae860d0d971d47932e7eed2f127fe1da
 SHA512:
-  metadata.gz: 42908177da2fdddef940576259b03ede3a07b7e561704d4eaa4d30dd5b3768d163b02cb03a0ec2c98fb9912923043f55fe41aaae64fc34709318329703c2961e
-  data.tar.gz: db8f2f000cfe38ceb447f016b39aac2f3fc9a48c8749aab309f48e56019060b8516707fd43dfd726338a683ffc441e65c2b926e09bf9c797acca1feb959f843f
+  metadata.gz: 5ab143d433e88c413810036f0b53cc3f70c3eb74c75b0d5fb4f319b94c44ba9b62b003156274a95d67aa048623edeeafab45fc6e0bcc17875817c980f956126d
+  data.tar.gz: 502f58b8543f1b31ba0700a24da4588875945b38f54bf26ac411fa13b88c304f9d2250d822357e327a689ec58863b2d3651d16bb09ed20f7c486c24193259888

data/CHANGELOG.md

@@ -9,6 +9,76 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### 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`
+  defaults are inherited and merged down the subclass chain; a render-time
+  block appends after the declared fields.
+- **`live` server-truth validation** (`Forms::Base` only, phlex-reactive soft
+  dependency): `live model: User` runs the real ActiveModel validators
+  server-side on blur/debounced input — uniqueness, `:if`/`:unless`,
+  confirmation, `:on` context — and morphs errors back in with focus
+  preserved. Touched-field tracking rides the signed reactive state; nothing
+  is persisted. Inline `Form(live: true)` raises with guidance.
+- **Model-driven type inference** in `field`: boolean column → toggle, AR enum
+  → humanized select, non-polymorphic `belongs_to` → association select (name
+  rewritten to the foreign key, errors still surface from the association
+  name), text column → textarea, date/datetime/time/numeric columns → matching
+  inputs (+`step`), `has_rich_text` → rich textarea, attachments → file
+  (`multiple` + `name[]` for `has_many_attached`), length/numericality
+  validators → `maxlength`/`min`/`max`. Explicit `as:`/`choices:`/positional
+  type modifiers always win; POROs and untyped models behave exactly as
+  before. Kill-switch: `PhlexForms.config.infer_from_model = false`.
+- `choices:` without `as: :select` now implies a select (previously silently
+  dropped).
+- **Themes**: component roles resolve through `PhlexForms::Theme`. The daisy
+  theme (default when the daisyui gem is loaded) is unchanged; the new Plain
+  theme renders bare semantic HTML — same binding contract, variants accepted
+  and ignored, `aria-invalid` + `role="alert"` + `data-field-error/hint`
+  hooks, zero styling classes — so the same form class renders in non-daisyui
+  projects. Select per form (`theme:`), per class (`form_options theme:`), or
+  globally; override single roles with `Theme#with`.
+- **Form-level variant defaults**: `field_variants: [:primary, :sm]` on a
+  form / `form_options` / `PhlexForms.config.field_variants` prepends daisyui
+  variants to every `field`'s inner input (call-site modifiers stack last).
+- Layout helpers: `f.row(columns:)` (responsive grid) and `f.group(legend:)`
+  (fieldset), available on inline forms and `fields_for` builders.
+- Adoption enablers: `Form(scope: false)` emits bare field names (reactive row
+  editors, `<template>` rows); `fields_for(..., nested_attributes: false)`
+  skips the `_attributes` suffix (JSONB columns); public `Form#field_value`
+  joins `field_name`/`field_id` for external widgets.
+
+### Changed
+
+- **Minimum Ruby is now 3.4** (was 3.2). The optional `live` validation runs on
+  phlex-reactive, which has required Ruby >= 3.4 since its 0.9 line; aligning the
+  floor keeps the whole gem installable wherever the live integration is.
+- **`daisyui` is now a soft dependency** (removed from the gemspec). With it
+  loaded nothing changes; without it the Plain theme is the default and the
+  gem renders unstyled semantic HTML.
+- **Live validation is compatible with phlex-reactive >= 0.11's default-ON
+  `verify_authorized` (#168).** The `:validate` action declares
+  `skip_verify_authorized` — it's a no-persist, read-only validation pass, so it
+  needs no authorization call and won't raise `AuthorizationNotVerified`. No host
+  action required.
+- Model-driven inference changes rendered output for ActiveRecord-backed
+  forms that previously fell through to a text input. Before/after:
+
+  | field on an AR model | before | after |
+  | --- | --- | --- |
+  | boolean column | `<input type="text">` | toggle (checkbox + hidden pair) |
+  | text column | `<input type="text">` | `<textarea>` |
+  | AR enum | text input | `<select>` with humanized options |
+  | `belongs_to` (`:country`/`:country_id`) | text input | `<select>` over the association, `name="…[country_id]"` |
+  | date/datetime/time column | text input (unless name-mapped) | matching input type |
+  | integer/decimal/float column | text input | `<input type="number" step=…>` |
+  | attachment / rich text | text input | file input / rich textarea |
+
+  Pass `as:` explicitly or set `PhlexForms.config.infer_from_model = false`
+  to keep the old rendering.
+
+### Initial extraction
+
 - Initial extraction of the `Forms::` Phlex form builder from the Cosmos apps.
 - Control-first builder API: `f.field :email, label:, hint:, as:, choices:`
   renders label + input + error/hint in one call, inferring input type and the

data/README.md

@@ -1,20 +1,38 @@
 # phlex-forms
 
-A model-bound, DaisyUI-styled form builder for [Phlex](https://www.phlex.fun).
+A model-bound form builder for [Phlex](https://www.phlex.fun) — forms as
+first-class Phlex classes, types inferred from your model, DaisyUI styling by
+default (and a plain-HTML theme when you want none), and optional
+**server-truth live validation** over
+[phlex-reactive](https://github.com/mhenrixon/phlex-reactive).
 
-`Form(model:) { |f| f.field :email }` renders a label, an input, and an
-error/hint in **one call** — inferring the input type from the attribute name and
-the `required` flag from the model's validations. It's built on the
-[`daisyui`](https://github.com/mhenrixon/daisyui) gem, so every field is a thin
-binding layer over a real DaisyUI component: positional variants stack, blocks
-pass through, and the markup stays DaisyUI v5-correct.
+```ruby
+class UserForm < Forms::Base
+  live model: User                 # real validators, live, focus preserved
+
+  def fields                       # self IS the form — no f. prefix
+    field :email                   # name → type=email, required inferred
+    field :role                    # AR enum → select, humanized
+    field :country                 # belongs_to → select over the association
+    field :notify                  # boolean column → toggle
+    field :bio                     # text column → textarea
+    row do
+      field :first_name
+      field :last_name
+    end
+    submit :primary
+  end
+end
+
+render UserForm.new(model: @user)
+```
+
+For one-offs, the inline builder does the same with a yielded form:
 
 ```ruby
-Form(:spaced, model: @user) do |f|
-  f.field :email, hint: t("users.email_hint")      # type=email, required inferred
-  f.field :role,  as: :select, choices: roles
-  f.field :bio,   as: :textarea, rows: 6
-  f.field :notify, as: :toggle
+Form(model: @user) do |f|
+  f.field :email, hint: t("users.email_hint")
+  f.field :bio
   f.submit :primary
 end
 ```
@@ -24,6 +42,8 @@ end
 ```ruby
 # Gemfile
 gem "phlex-forms"
+gem "daisyui"        # optional — the daisy theme; omit for plain semantic HTML
+gem "phlex-reactive" # optional — the `live` server-truth validation
 ```
 
 phlex-forms exposes its components under the `Forms::` namespace as a
@@ -36,36 +56,109 @@ class ApplicationComponent < Phlex::HTML
 end
 ```
 
-Now `Form(...)`, `Submit(...)`, and every other `Forms::*` component are available
-as bare kit helpers.
+## Form classes (`Forms::Base`)
+
+Subclass `Forms::Base`, declare the fields in `#fields`, render. The whole
+builder surface (`field`, `row`, `group`, `Input`, `submit`, `fields_for`, …)
+is available as bare calls — the form is an object you can reuse, subclass,
+and test in isolation.
+
+```ruby
+class ApplicationForm < Forms::Base
+  form_options :spaced, field_variants: [:primary]   # inherited defaults
+end
+
+class UserForm < ApplicationForm
+  form_options url: "/signup"                        # merged over the parent's
+
+  def fields
+    field :email
+    submit :primary
+  end
+end
+
+render UserForm.new(model: @user)                    # instance args win
+render UserForm.new(model: @user) { |f| f.Hidden(:token) }  # appends after fields
+```
 
 ## The `field` API
 
-`f.field(name, *modifiers, **options)` is the primary verb. It renders a
-`form-control` wrapping a label, the input, and an error (or hint):
+`f.field(name, *modifiers, **options)` is the primary verb: one call renders a
+control wrapping the label, the input, and an error (or hint).
 
 | Option | Effect |
 | --- | --- |
 | `label:` | Label text. Defaults to the model's humanized attribute name. `label: false` omits it. |
 | `hint:` | Help text shown when there is no error. |
-| `as:` | Override the control: `:select`, `:textarea`, `:toggle`, `:checkbox`, `:file`, `:radio`, `:hidden`, or any text-like type. |
+| `as:` | Override the control: `:select`, `:textarea`, `:toggle`, `:checkbox`, `:file`, `:radio`, `:hidden`, `:rich_textarea`, or any text-like type. |
 | `required:` | Force the required flag. Otherwise inferred from the model's presence validators. |
-| `choices:` | Choices for `as: :select`. |
+| `choices:` | Choices for a select (implies `as: :select`). |
 | positional modifiers | daisyui variants — `:primary`, `:lg`, `:ghost`, … — stacked onto the input. |
 
-Type is inferred from the attribute name (`email` → `type=email`, `password` →
-`type=password`, `phone` → `type=tel`, …).
+### Model-driven inference
+
+`field :x` interrogates the bound model, so `as:` is an override, not a
+requirement. Precedence (first hit wins):
+
+1. Explicit `as:`
+2. A positional type modifier (`field :price, :number`)
+3. `choices:` → select
+4. Model structure — `has_rich_text` → rich textarea; ActiveStorage attachment
+   → file input (`multiple` for `has_many_attached`); ActiveRecord enum →
+   select over humanized keys; non-polymorphic `belongs_to` (as `:country` or
+   `:country_id`) → select over the association (`name="user[country_id]"`,
+   label and required flag from the association, errors surface from
+   `:country`)
+5. Non-string column type — boolean → toggle, text → textarea,
+   date/datetime/time → matching inputs, integer/decimal/float → number with
+   a sensible `step`
+6. The attribute-name map (`email` → `type=email`, `password` →
+   `type=password`, `phone` → `type=tel`, …)
+7. `type=text`
+
+Length and numericality validators also emit `maxlength`/`min`/`max`
+(conditional validators are skipped; caller options always win). Everything is
+duck-typed behind `respond_to?` guards — plain objects, Structs, and form
+objects fall through to the name map, exactly as before. Opt out entirely
+with:
+
+```ruby
+PhlexForms.configure { |c| c.infer_from_model = false }
+```
+
+Association selects load `klass.all` per render — pass `choices:` to scope,
+order, or cache.
 
-### Escape hatches
+### Variants
 
-When you need full control (custom Stimulus wiring, bespoke layout), the
-lower-level component methods are always available with stable signatures:
+daisyui variants stack positionally, per field or as defaults:
 
 ```ruby
-f.Control(:email, label: "Email") do
-  f.Input(:email, :primary, data: { controller: "autocomplete" })
+f.field :email, :primary, :sm                        # this field
+Form(model: @user, field_variants: [:primary])       # every field in this form
+form_options field_variants: [:primary]              # every field in this class
+PhlexForms.configure { |c| c.field_variants = [:sm] }  # everywhere
+```
+
+Defaults stack first, call-site modifiers last — the most local wins.
+
+### Layout
+
+```ruby
+row { field :first_name; field :last_name }   # responsive grid, columns: 2|3|4
+group(legend: "Address") do                   # <fieldset> + legend
+  field :street
+  field :city
 end
+```
+
+Both work on inline forms (`f.row { … }`) and inside `fields_for` builders.
+
+## Escape hatches & custom widgets
 
+The lower-level component methods are always available with stable signatures:
+
+```ruby
 f.Input(:name, :primary, :lg)     # bare input, variants stacked
 f.Select(:role, choices: roles)   # native <select>
 f.Textarea(:bio, :ghost)
@@ -73,51 +166,109 @@ f.Checkbox(:terms) ; f.Toggle(:notify) ; f.FileInput(:avatar)
 f.Label(:email) ; f.Hidden(:token) ; f.submit("Save", :primary)
 ```
 
-### Icons inside a field (DaisyUI v5)
+For a bespoke widget (date picker, tag field, remote select), wrap it in
+`f.Control` and bind through the public helpers — this is the supported path,
+not a fork reason:
+
+```ruby
+f.Control(:starts_at, label: "Starts") do
+  render MyDatePicker.new(
+    name: f.field_name(:starts_at),
+    id: f.field_id(:starts_at),
+    value: f.field_value(:starts_at)
+  )
+end
+```
 
-`WrappedInput` renders the `<label class="input">{icon}{input}` pattern:
+Icons inside a field (daisyui v5 `<label class="input">` pattern):
 
 ```ruby
 f.field(:search).wrapped_input(:primary) do
-  LucideIcon("search", class: "opacity-50")   # leading content
+  LucideIcon("search", class: "opacity-50")
 end
 ```
 
-## Nested attributes & collections
+## Themes — using phlex-forms without daisyui
+
+Every component resolves through a theme (a role → component-class map). With
+the daisyui gem loaded, the daisy theme is the default. Without it — or on
+demand — the **Plain theme** renders bare semantic HTML: the same binding
+(names, ids, values, required, errors), variants accepted and ignored, no
+styling classes, and stable hooks (`aria-invalid`, `role="alert"`,
+`data-field-error`, `data-field-hint`, `data-form-row`) for your own CSS.
 
 ```ruby
-f.fields_for(:line_items) do |item|          # single assoc or has_many
-  item.field :description
-end
+render UserForm.new(model: @user, theme: :plain)     # per render
+form_options theme: :plain                           # per class
+PhlexForms.configure { |c| c.theme = :plain }        # global
 
-f.collection_check_boxes(:role_ids, Role.all, :id, :name) do |b|
-  render b.check_box
-  render b.label
+# override single roles:
+PhlexForms.configure do |c|
+  c.theme = PhlexForms::Theme.resolve(:plain).with(input: MyInput)
 end
+```
 
-f.collection_select(:country_id, Country.all, :id, :name, prompt: "Select…")
+The same `UserForm` class renders under either theme — write the form once,
+style it per project. (Plain degradations: `searchable:` selects fall back to
+the native select; `rich_textarea` falls back to a plain textarea.)
+
+## Live validation (server-truth, via phlex-reactive)
+
+The `live` macro turns the whole form into one reactive component. Blurring a
+field (or typing, debounced) POSTs **all** form fields to a single signed
+`:validate` action; the server assigns a whitelisted slice to the model, runs
+the **real** ActiveModel validators, and morphs the errors back in — the
+focused input and caret survive.
+
+```ruby
+class UserForm < Forms::Base
+  live model: User, debounce: 300
+
+  def fields
+    field :email                  # uniqueness validates against the real DB
+    field :password
+    field :password_confirmation  # cross-field confirmation just works
+    submit :primary
+  end
+end
 ```
 
-## Client-side validation
+What you get over any client-side mirror:
 
-phlex-forms ships a Stimulus validation framework that mirrors your ActiveModel
-validators — no ugly, browser-inconsistent native validation bubbles.
+- **One source of truth** — uniqueness, `:if`/`:unless`, `:on` contexts,
+  cross-field and custom validators all run, because it *is* your model.
+- **i18n is plain Rails i18n** — no duplicated message catalogs.
+- **No premature errors** — a field's error first appears on blur (`touched`
+  tracking rides the signed token; zero client-side bookkeeping), while fixing
+  a field live-updates errors of fields you already touched.
+- **Progressive enhancement** — nothing is ever persisted by `:validate`;
+  native submit and your controller stay authoritative. A failed-submit 422
+  re-render shows all errors as usual.
+
+Constraints: `live` needs a `Forms::Base` subclass (the endpoint rebuilds the
+form from its class — an inline block cannot be serialized; `Form(live: true)`
+raises and says so). Collection controls (`collection_check_boxes`,
+multi-selects) are excluded from live assignment in v1. Use
+`live_permit`/`live_deny` to adjust the assignable attributes; setters run on
+an in-memory model only.
+
+### Client-side fallback (`validate: true`)
+
+Without phlex-reactive, the bundled Stimulus framework mirrors your validators
+client-side:
 
 ```ruby
 Form(model: @partner, validate: true) do |f|
   f.field :title                              # every validator on :title
-  f.field :slug, validate: false             # opt this field out
+  f.field :slug, validate: false              # opt this field out
   f.field :note, validate: { length: { maximum: 30 } }  # explicit rules
 end
 ```
 
-When `validate: true`, the form gets `novalidate` and a submit coordinator; each
-field emits `data-forms--validations--*` bindings introspected from the model.
 Supported: presence, length (with a live counter), format, numericality,
-inclusion, exclusion, confirmation, acceptance. Validators with `:if` / `:unless`
-/ `:on` are skipped (they need server context); the server stays authoritative.
-
-Register the controllers in your Stimulus setup:
+inclusion, exclusion, confirmation, acceptance. Validators with
+`:if`/`:unless`/`:on` are skipped; uniqueness can't be checked client-side —
+the server stays authoritative. Register the controllers:
 
 ```js
 // app/javascript/controllers/index.js
@@ -125,13 +276,36 @@ import { lazyLoadControllersFrom } from "@hotwired/stimulus-loading"
 lazyLoadControllersFrom("phlex_forms/controllers", application)
 ```
 
-Validation messages ship for `en` / `fr` / `af`; override any string via
-`window.PhlexForms.messages`.
+Messages ship for `en` / `fr` / `af`; override via `window.PhlexForms.messages`.
+
+## Nested attributes, collections & escape valves
+
+```ruby
+f.fields_for(:line_items) do |item|          # single assoc or has_many
+  item.field :description
+end
+
+f.fields_for(:settings, nested_attributes: false) do |s|
+  s.field :locale                            # user[settings][locale] — JSONB/hash columns
+end
+
+f.collection_check_boxes(:role_ids, Role.all, :id, :name) do |b|
+  render b.check_box
+  render b.label
+end
+
+f.collection_select(:country_id, Country.all, :id, :name, prompt: "Select…")
+```
+
+`Form(model: @item, scope: false)` emits **bare** field names
+(`name="quantity"`) — the shape phlex-reactive row editors and
+`<template>`-cloned rows need. External widgets bind through the public
+`f.field_name` / `f.field_id` / `f.field_value` helpers.
 
 ## Icons
 
 Icons default to a bundled inline SVG so the gem is self-contained. To use
-[`glyphs`](https://rubygems.org/gems/glyphs) (rails-icons under the hood):
+[`glyphs`](https://rubygems.org/gems/glyphs):
 
 ```ruby
 PhlexForms.configure do |c|
@@ -155,10 +329,13 @@ inherit_gem:
 - `PhlexForms/LegacyFormMethod` — use `form.field(...)` / the PascalCase methods
   over Rails-style `text_field` / `select` / etc.
 
-## JavaScript peer dependencies
+## Dependencies
 
-- `@hotwired/stimulus` — required.
-- `choices.js` — only if you use searchable/multi selects (`searchable: true`).
+- Hard: `phlex` (~> 2.0), `activesupport`, `zeitwerk`, `glyphs`.
+- Soft: `daisyui` (the daisy theme — without it the Plain theme is the
+  default), `phlex-reactive` (the `live` macro).
+- JS peers: `@hotwired/stimulus` (client validation fallback), `choices.js`
+  (only for `searchable: true` selects).
 
 ## Companion
 

data/lib/forms/base.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+module Forms
+  # Declarative form classes: subclass, declare the fields in #fields, render.
+  # Inside #fields, `self` IS the form — the whole builder surface (field, row,
+  # group, Input, submit, fields_for, ...) is available as bare calls.
+  #
+  #   class UserForm < Forms::Base
+  #     form_options :spaced
+  #
+  #     def fields
+  #       field :email
+  #       row { field :first_name; field :last_name }
+  #       submit :primary
+  #     end
+  #   end
+  #
+  #   render UserForm.new(model: @user)
+  #
+  # A render-time block appends after the declared fields:
+  #
+  #   render UserForm.new(model: @user) { |f| f.Hidden(:token) }
+  class Base < Form
+    class << self
+      # Class-level defaults, inherited and merged down the subclass chain
+      # (instance args beat class defaults; subclass defaults beat parents'):
+      #
+      #   form_options :spaced, url: "/signup", validate: true
+      def form_options(*modifiers, **defaults)
+        @form_modifiers = modifiers
+        @form_defaults = defaults
+      end
+
+      def form_modifiers
+        inherited = superclass.respond_to?(:form_modifiers) ? superclass.form_modifiers : []
+        (inherited + (@form_modifiers || [])).uniq
+      end
+
+      def form_defaults
+        inherited = superclass.respond_to?(:form_defaults) ? superclass.form_defaults : {}
+        inherited.merge(@form_defaults || {})
+      end
+
+      # Server-truth live validation via phlex-reactive (a soft dependency):
+      #
+      #   class UserForm < Forms::Base
+      #     live model: User
+      #     def fields = field(:email)
+      #   end
+      #
+      # Blur/debounced input POST every field to a :validate action that runs
+      # the REAL model validators and morphs the errors back in, focus intact.
+      # Only Forms::Base subclasses can be live — the endpoint rebuilds the
+      # form from its class; an inline block cannot be serialized.
+      def live(model:, scope: nil, debounce: 300)
+        unless reactive_available?
+          raise PhlexForms::FeatureUnavailable,
+            "#{name || 'this form'} declares `live` but the phlex-reactive gem is not " \
+            "installed. Add `gem \"phlex-reactive\"` to your Gemfile, or use " \
+            "`validate: true` for the client-side Stimulus mirror instead."
+        end
+
+        include Forms::Live
+
+        setup_live(model_class: model, scope: scope || derive_live_scope(model), debounce:)
+      end
+
+      # Extracted so specs can exercise the FeatureUnavailable guard.
+      def reactive_available?
+        defined?(Phlex::Reactive::Component) ? true : false
+      end
+
+      private
+
+      def derive_live_scope(model)
+        model.respond_to?(:model_name) ? model.model_name.param_key : model.name.underscore.tr("/", "_")
+      end
+    end
+
+    def initialize(*modifiers, **options)
+      super(*(self.class.form_modifiers + modifiers).uniq, **self.class.form_defaults.merge(options))
+    end
+
+    # Renders Form's chrome (action/method/CSRF/enctype), then the declared
+    # fields. `yield`/`block_given?` inside the inner block bind to
+    # view_template's own block — the optional render-time block.
+    def view_template
+      super do
+        fields
+        yield self if block_given?
+      end
+    end
+
+    # The hook name `fields` is verified free against Phlex::HTML (phlex 2.4.x)
+    # and this gem (Form defines fields_for/field_object, never fields).
+    def fields
+      raise NotImplementedError, "#{self.class} must define #fields"
+    end
+  end
+end