[Documentation] Form: document Rails form_with integration and real-world examples

Merged
DJ
5mo ago
+179-1

Closes #134

How to reproduce the gap

Open https://rubyui.com/docs/form — the existing docs show visual examples (disabled, error states, checkbox, select, combobox) but give no guidance on:

  • How to set the form action / HTTP method
  • What name / id to give each input so Rails params parse correctly
  • How to wire a CSRF token
  • How to map model.errors to FormFieldError

What changed

Three new items added immediately before the component-setup tabs in both gem/lib/ruby_ui/form/form_docs.rb and docs/app/views/docs/form.rb:

  1. "Rails Integration" heading + prose — explains the recommended strategy: use form_with (or set action manually), set explicit name/id on every input, include the CSRF hidden field, and pass server-side errors via FormFieldError.
  2. "Minimal Rails form" code example — a single-field form with action: helpers.users_path, CSRF token, FormFieldError, and a submit button; demonstrates the basic wiring.
  3. "Devise-style login form" code example — a complete sign-in form using session[email] / session[password] / session[remember_me] params, autocomplete attributes, minlength validation, and error display — the real-world pattern most Rails devs need.

Testing instructions

  • Visit /docs/form on a local or preview build and confirm the three new items appear below the Combobox example
  • Verify the code blocks render correctly (no syntax highlighting errors)
  • Copy the "Minimal Rails form" snippet into a Phlex view in a Rails app and confirm it submits with the correct params
  • Copy the "Devise-style login form" snippet and confirm Devise recognises the session[email] / session[password] parameters

Summary by cubic

Adds a “Rails Integration” section to the Form docs with clear guidance on form_with, CSRF, input name/id, and mapping server errors to FormFieldError. Converts the Rails examples to code-only blocks so they don’t execute Rails helpers in the docs app.

  • New Features

    • Prose on using form_with for action + CSRF, setting explicit name/id, and showing server errors with FormFieldError + model.errors.
    • Minimal Rails form example with a single email field, hidden CSRF input, and a submit button.
    • Devise-style login example using session[email], session[password], session[remember_me], with autocomplete, minlength, and error display.
  • Bug Fixes

    • Render the two Rails examples as syntax-highlighted code via Heading + Codeblock (no instance_eval) to avoid crashes from missing helpers.* routes in the docs app; rebuilt mcp/data/registry.json.