phlex-forms 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 0c3cb45e86fb22d3240e3d9b0441476376004c2996c2b08e682c00e86ad51fd7
+  data.tar.gz: d5abd208265060aade20c4b70a834c3404124dec41534892e243babae60f19b0
+SHA512:
+  metadata.gz: 42908177da2fdddef940576259b03ede3a07b7e561704d4eaa4d30dd5b3768d163b02cb03a0ec2c98fb9912923043f55fe41aaae64fc34709318329703c2961e
+  data.tar.gz: db8f2f000cfe38ceb447f016b39aac2f3fc9a48c8749aab309f48e56019060b8516707fd43dfd726338a683ffc441e65c2b926e09bf9c797acca1feb959f843f

data/CHANGELOG.md

@@ -0,0 +1,23 @@
+# Changelog
+
+All notable changes to this project are documented here.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+
+- 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
+  `required` flag from the model.
+- Escape-hatch component API preserved: `f.Input`, `f.Select`, `f.Textarea`,
+  `f.Checkbox`, `f.Toggle`, `f.FileInput`, `f.Hidden`, `f.Label`, `f.Control`,
+  `f.submit`.
+- Configurable icon renderer (`PhlexForms.configure`) with a zero-dependency
+  inline-SVG default and optional `glyps` auto-detection.
+- Polymorphic array model support in `Form(model: [parent, child])`.
+- Bundled Stimulus controllers (choices, searchable-select, time zone) and
+  default `en`/`sv`/`de` locales, wired through an optional Rails engine.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Mikael Henriksson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,170 @@
+# phlex-forms
+
+A model-bound, DaisyUI-styled form builder for [Phlex](https://www.phlex.fun).
+
+`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
+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
+  f.submit :primary
+end
+```
+
+## Installation
+
+```ruby
+# Gemfile
+gem "phlex-forms"
+```
+
+phlex-forms exposes its components under the `Forms::` namespace as a
+[Phlex::Kit](https://www.phlex.fun/kits.html). Include it wherever you render
+components (typically your `ApplicationComponent` / base view):
+
+```ruby
+class ApplicationComponent < Phlex::HTML
+  include Forms
+end
+```
+
+Now `Form(...)`, `Submit(...)`, and every other `Forms::*` component are available
+as bare kit helpers.
+
+## 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):
+
+| 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. |
+| `required:` | Force the required flag. Otherwise inferred from the model's presence validators. |
+| `choices:` | Choices for `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`, …).
+
+### Escape hatches
+
+When you need full control (custom Stimulus wiring, bespoke layout), the
+lower-level component methods are always available with stable signatures:
+
+```ruby
+f.Control(:email, label: "Email") do
+  f.Input(:email, :primary, data: { controller: "autocomplete" })
+end
+
+f.Input(:name, :primary, :lg)     # bare input, variants stacked
+f.Select(:role, choices: roles)   # native <select>
+f.Textarea(:bio, :ghost)
+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)
+
+`WrappedInput` renders the `<label class="input">{icon}{input}` pattern:
+
+```ruby
+f.field(:search).wrapped_input(:primary) do
+  LucideIcon("search", class: "opacity-50")   # leading content
+end
+```
+
+## Nested attributes & collections
+
+```ruby
+f.fields_for(:line_items) do |item|          # single assoc or has_many
+  item.field :description
+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…")
+```
+
+## Client-side validation
+
+phlex-forms ships a Stimulus validation framework that mirrors your ActiveModel
+validators — no ugly, browser-inconsistent native validation bubbles.
+
+```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 :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:
+
+```js
+// app/javascript/controllers/index.js
+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`.
+
+## 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):
+
+```ruby
+PhlexForms.configure do |c|
+  c.icon_renderer = PhlexForms::Configuration.glyphs_renderer
+end
+```
+
+## RuboCop cops
+
+Two cops nudge call sites toward the phlex-forms API. Enable them in your
+`.rubocop.yml`:
+
+```yaml
+require:
+  - phlex_forms/rubocop
+inherit_gem:
+  phlex-forms: config/rubocop.yml
+```
+
+- `PhlexForms/RawForm` — use `Form()` over `form_with` / raw `form()` (autocorrects).
+- `PhlexForms/LegacyFormMethod` — use `form.field(...)` / the PascalCase methods
+  over Rails-style `text_field` / `select` / etc.
+
+## JavaScript peer dependencies
+
+- `@hotwired/stimulus` — required.
+- `choices.js` — only if you use searchable/multi selects (`searchable: true`).
+
+## Companion
+
+Form-level error summaries (`FormErrors`) live in your app's UI kit, not here —
+pair them with `Form()` as you like.
+
+## License
+
+MIT © Mikael Henriksson

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

@@ -0,0 +1,23 @@
+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
+// value is in the accepted list.
+export default class extends FieldValidatorController {
+  static values = {
+    accept: { type: String, default: '["1","true"]' },
+  }
+
+  check(value) {
+    if (this.element.type === "checkbox") {
+      return this.element.checked ? null : t("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")
+    } catch (_e) {
+      return null
+    }
+  }
+}

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

@@ -0,0 +1,166 @@
+import { Controller } from "@hotwired/stimulus"
+
+// Shared base for every field-level validator. Subclasses implement
+// `check(value)` and return either `null` (valid) or a translation
+// key / message string (invalid). The base class wires up the DOM
+// hooks (blur, validate event), error rendering, and the message
+// the form coordinator collects on submit.
+//
+// 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.
+export class FieldValidatorController extends Controller {
+  // `error` is opt-in: callers that pre-render a `<p data-forms--validations--error-target="error">`
+  // get a stable slot the controller toggles. Inputs without an
+  // explicit target still work — the controller lazily creates one
+  // adjacent to the input below.
+  static targets = ["error"]
+  static values = {
+    allowBlank: { type: Boolean, default: false },
+    allowNil: { type: Boolean, default: false },
+  }
+
+  // Element must be the input itself — these controllers are attached
+  // directly to <input>, <textarea>, <select> via the form builder.
+  connect() {
+    this.element.addEventListener("blur", this.onBlur)
+    this.element.addEventListener("invalidate:forms--validations", this.onValidate)
+  }
+
+  disconnect() {
+    this.element.removeEventListener("blur", this.onBlur)
+    this.element.removeEventListener("invalidate:forms--validations", this.onValidate)
+  }
+
+  onBlur = () => {
+    this.runCheck({ silent: false })
+  }
+
+  onValidate = (event) => {
+    const result = this.runCheck({ silent: false })
+    if (result) {
+      event.detail.errors.push({ element: this.element, message: result })
+    }
+  }
+
+  runCheck({ silent }) {
+    const value = this.fieldValue()
+    if (this.shouldSkip(value)) {
+      this.clearError()
+      return null
+    }
+
+    const error = this.check(value)
+    if (error) {
+      if (!silent) this.renderError(error)
+      return error
+    }
+    this.clearError()
+    return null
+  }
+
+  // Subclasses override.
+  check(_value) {
+    return null
+  }
+
+  shouldSkip(value) {
+    if (this.allowNilValue && (value === null || value === undefined)) return true
+    if (this.allowBlankValue && this.isBlank(value)) return true
+    return false
+  }
+
+  isBlank(value) {
+    if (value === null || value === undefined) return true
+    if (typeof value === "string") return value.trim().length === 0
+    return false
+  }
+
+  fieldValue() {
+    if (this.element.type === "checkbox") return this.element.checked
+    return this.element.value
+  }
+
+  // Stores this validator's error state on the input element and
+  // re-renders the consolidated message. Multiple validators share
+  // a single container per field but track their errors separately
+  // so one validator's "valid" doesn't blow away another's "invalid".
+  renderError(message) {
+    this.setValidatorError(message)
+    this.renderConsolidated()
+  }
+
+  clearError() {
+    this.setValidatorError(null)
+    this.renderConsolidated()
+  }
+
+  setValidatorError(message) {
+    if (!this.element.__formsValidationErrors) {
+      this.element.__formsValidationErrors = {}
+    }
+    this.element.__formsValidationErrors[this.identifier] = message
+  }
+
+  renderConsolidated() {
+    const errors = this.element.__formsValidationErrors || {}
+    // Stable order so the displayed message doesn't flicker.
+    const ordered = Object.keys(errors)
+      .sort()
+      .map((k) => errors[k])
+      .filter(Boolean)
+    const message = ordered[0] || null
+
+    const container = this.errorContainer({ create: !!message })
+    if (container) {
+      container.textContent = message || ""
+      container.hidden = !message
+    }
+    const errorClass = this.errorClassForElement()
+    if (message) {
+      this.element.setAttribute("aria-invalid", "true")
+      this.element.classList.add(errorClass)
+    } else {
+      this.element.removeAttribute("aria-invalid")
+      this.element.classList.remove(errorClass)
+    }
+  }
+
+  // DaisyUI uses tag-specific error classes (`input-error` vs
+  // `textarea-error` vs `select-error`). Adding all three to every
+  // element is inert today but invites CSS bleed once the variants
+  // diverge — pick the one that matches.
+  errorClassForElement() {
+    switch (this.element.tagName) {
+      case "TEXTAREA":
+        return "textarea-error"
+      case "SELECT":
+        return "select-error"
+      default:
+        return "input-error"
+    }
+  }
+
+  errorContainer({ create = true } = {}) {
+    // If the caller pre-rendered a Stimulus error target on the same
+    // controller, use that — preferred path for server-rendered forms.
+    if (this.hasErrorTarget) return this.errorTarget
+
+    // Fallback: lazily create (and cache by element id/name) a slot
+    // adjacent to the input. Keeps the framework usable on plain
+    // forms that haven't opted into the static-target convention.
+    const id = this.element.id || this.element.name
+    const selector = `[data-forms--validations--error="${id}"]`
+    const existing = this.element.closest("form")?.querySelector(selector)
+    if (existing) return existing
+    if (!create) return null
+
+    const container = document.createElement("p")
+    container.className = "text-error text-sm mt-1"
+    // `dataset` rejects keys with `--`, so we set the attribute
+    // directly. The CSS selector still matches.
+    container.setAttribute("data-forms--validations--error", id)
+    this.element.insertAdjacentElement("afterend", container)
+    return container
+  }
+}

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

@@ -0,0 +1,27 @@
+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
+// and asserts equality.
+export default class extends FieldValidatorController {
+  static values = {
+    match: String,
+  }
+
+  check(value) {
+    if (!this.hasMatchValue) return null
+    const form = this.element.closest("form")
+    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")
+  }
+
+  partnerByAttribute(form) {
+    // Rails scopes form fields as `model[name_confirmation]`, so
+    // `form.elements[matchValue]` lookup fails for scoped names.
+    // Fall back to a `[name$="[<matchValue>]"]` selector.
+    return form.querySelector(`[name$="[${this.matchValue}]"]`)
+  }
+}

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

@@ -0,0 +1,19 @@
+import { FieldValidatorController } from "phlex_forms/controllers/validations/base_controller"
+import { t } from "phlex_forms/i18n"
+
+// Mirrors ActiveModel::Validations::ExclusionValidator.
+export default class extends FieldValidatorController {
+  static values = {
+    in: String,
+  }
+
+  check(value) {
+    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
+    } catch (_e) {
+      return null
+    }
+  }
+}

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

@@ -0,0 +1,43 @@
+import { Controller } from "@hotwired/stimulus"
+
+// Form-level coordinator for the validation framework. Sits on the
+// <form> element and intercepts `submit` to broadcast a synchronous
+// validation event to every field. Each field controller listens
+// for `invalidate:forms--validations`, runs its check, and (on
+// failure) appends its error to the event's `detail.errors` array.
+// If anything ended up in that array, we cancel the submit and
+// focus the first invalid field.
+//
+// The mechanism is deliberately decoupled — the form controller
+// doesn't know which validators are attached to which fields. It
+// just fires the event and looks at what came back. Adding a new
+// validator type means adding a new field controller, nothing here.
+export default class extends Controller {
+  onSubmit = (event) => {
+    const errors = []
+    // Skip disabled controls — the browser won't submit them, so
+    // validating them can incorrectly block a submit that the server
+    // would happily accept.
+    const fields = this.element.querySelectorAll("input:not(:disabled), textarea:not(:disabled), select:not(:disabled)")
+
+    fields.forEach((field) => {
+      const validators = (field.dataset.controller || "")
+        .split(/\s+/)
+        .filter((c) => c.startsWith("forms--validations--") && c !== "forms--validations--form")
+      if (validators.length === 0) return
+
+      field.dispatchEvent(
+        new CustomEvent("invalidate:forms--validations", {
+          detail: { errors },
+        }),
+      )
+    })
+
+    if (errors.length === 0) return
+
+    event.preventDefault()
+    event.stopPropagation()
+    errors[0].element.focus({ preventScroll: false })
+    errors[0].element.scrollIntoView({ behavior: "smooth", block: "center" })
+  }
+}

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

@@ -0,0 +1,23 @@
+import { FieldValidatorController } from "phlex_forms/controllers/validations/base_controller"
+import { t } from "phlex_forms/i18n"
+
+// Mirrors ActiveModel::Validations::FormatValidator.
+export default class extends FieldValidatorController {
+  static values = {
+    pattern: String,
+    flags: { type: String, default: "" },
+  }
+
+  check(value) {
+    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")
+    } 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
+      // pattern we can't evaluate.
+      return null
+    }
+  }
+}

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

@@ -0,0 +1,19 @@
+import { FieldValidatorController } from "phlex_forms/controllers/validations/base_controller"
+import { t } from "phlex_forms/i18n"
+
+// Mirrors ActiveModel::Validations::InclusionValidator.
+export default class extends FieldValidatorController {
+  static values = {
+    in: String,
+  }
+
+  check(value) {
+    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")
+    } catch (_e) {
+      return null
+    }
+  }
+}

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

@@ -0,0 +1,95 @@
+import { FieldValidatorController } from "phlex_forms/controllers/validations/base_controller"
+import { t } from "phlex_forms/i18n"
+
+// Mirrors ActiveModel::Validations::LengthValidator. Reads:
+//   - maximum / minimum / is
+//   - allow-blank / allow-nil
+//
+// Counter is rendered next to the input when `maximum` is set, so
+// the user gets a live "12 / 60" indicator without having to wait
+// for blur.
+export default class extends FieldValidatorController {
+  // Stimulus walks the prototype chain to accumulate `static values`
+  // and `static targets`, so we only declare the validator-specific
+  // ones here. `counter` is opt-in: callers that pre-render
+  // `<span data-forms--validations--length-target="counter">` get a
+  // stable slot the controller updates. Inputs without an explicit
+  // target still get a lazily-injected one (see counterElement).
+  static targets = ["counter"]
+  static values = {
+    maximum: Number,
+    minimum: Number,
+    is: Number,
+  }
+
+  connect() {
+    super.connect()
+    if (this.hasMaximumValue) {
+      this.renderCounter()
+      this.element.addEventListener("input", this.updateCounter)
+    }
+  }
+
+  disconnect() {
+    super.disconnect()
+    if (this.hasMaximumValue) {
+      this.element.removeEventListener("input", this.updateCounter)
+    }
+  }
+
+  check(value) {
+    const length = this.codepointLength(value)
+
+    if (this.hasIsValue && length !== this.isValue) {
+      return t("js.forms.validations.length.wrong_length", { count: this.isValue })
+    }
+    if (this.hasMaximumValue && length > this.maximumValue) {
+      return t("js.forms.validations.length.too_long", { count: this.maximumValue })
+    }
+    if (this.hasMinimumValue && length < this.minimumValue) {
+      return t("js.forms.validations.length.too_short", { count: this.minimumValue })
+    }
+    return null
+  }
+
+  updateCounter = () => {
+    const counter = this.counterElement()
+    if (!counter) return
+    const length = this.codepointLength(this.element.value)
+    counter.textContent = `${length} / ${this.maximumValue}`
+    counter.classList.toggle("text-error", length > this.maximumValue)
+  }
+
+  // Ruby's String#length counts Unicode codepoints; JS's String#length
+  // counts UTF-16 code units, so an emoji like 👍 reads as 2 in JS but
+  // 1 in Ruby. Matching Rails here avoids the client falsely rejecting
+  // a string the server would accept.
+  codepointLength(value) {
+    return Array.from(String(value ?? "")).length
+  }
+
+  renderCounter() {
+    const counter = this.counterElement({ create: true })
+    this.updateCounter()
+    return counter
+  }
+
+  counterElement({ create = false } = {}) {
+    // Caller pre-rendered a Stimulus target — preferred path.
+    if (this.hasCounterTarget) return this.counterTarget
+
+    // Fallback: cache-by-id lookup or lazy injection for plain forms.
+    const id = this.element.id || this.element.name
+    const selector = `[data-forms--validations--counter="${id}"]`
+    const existing = this.element.closest("form")?.querySelector(selector)
+    if (existing) return existing
+    if (!create) return null
+
+    const counter = document.createElement("span")
+    counter.className = "text-xs text-base-content/60 ml-auto"
+    // `dataset` rejects keys containing `--`; use the raw attribute API.
+    counter.setAttribute("data-forms--validations--counter", id)
+    this.element.insertAdjacentElement("afterend", counter)
+    return counter
+  }
+}