Skip to content

Phlex Form System — Companion Project Kickoff Prompt

We are building a standalone Rails project to explore and document a comprehensive Phlex form system. This is a companion to a Phlex v2 on Rails tutorial series, published as a blog post (or series of posts).

Setup

  • Rails 8, importmaps, Tailwind CSS v4, SQLite, Phlex 2.x, Literal, Stimulus
  • No Devise — authentication is out of scope
  • Lookbook for component previews

The goal

Design a set of Phlex form components by building real example forms first and extracting components from the repetition — not by imposing an abstraction upfront. The reference point is simple_form — a field is a unit comprising label + input + hint + error — but implemented in pure Phlex.

Forms to build as the showcase (driving the design)

  • Simple single-column form (e.g. board creation)
  • Two-column form with grouped fields
  • Compact inline form (e.g. quick card creation)
  • Multi-section form with error summary at top

Components to design and build

  • TextInput — with integrated label: prop, error: boolean for styling, optional hint
  • Textarea — same pattern
  • Select — single select, multi-select, grouped select variants
  • Checkbox — single and group
  • Radio — single and group
  • DatePicker — wrapping a vanilla JS date picker via Stimulus
  • DateTimePicker — same
  • DateRangePicker — wrapping a vanilla date range picker via Stimulus
  • ErrorSummary — top-of-form error list component

Error handling strategies to demonstrate

  1. Summary at top of form only
  2. Inline per field only
  3. Both combined

Each strategy should work cleanly with the component set without fighting an abstraction.

Stimulus controllers needed

  • DatePickerController
  • DateRangePickerController
  • Possibly others as the project reveals them

Key design constraints

  • Components are Rails-agnostic where possible (no route helpers inside components)
  • Label is intrinsic to the field — not a separate component
  • No FormGroup abstraction — that belongs in a generic gem layer if anywhere
  • Components accept plain values as props — callers handle Rails-specific concerns
  • All components have Lookbook previews

Blog post structure (draft)

  1. The problem with forms in Phlex
  2. Starting with primitives
  3. The showcase — four real form layouts
  4. What the repetition reveals
  5. Extracting components — the simple_form parallel
  6. Error handling strategies
  7. The final component set and how to use it in your app

Relationship to main tutorial

The finished components from this project are imported into Module 6 of the main tutorial (Phlex v2 on Rails), replacing a minimal set built inline. A callout in Module 6 links to this project for readers who want the full story.