velvetkit 0.1.0.beta → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9f176f98bff0013d64b619054845556e1323b6c285e374297238d9e13896c444
-  data.tar.gz: 37703180175c2b19f0630f92801e5831843531a97b1e1dfe3cd9f47f5995e6ad
+  metadata.gz: 783fb129530172b7add0378661a6542b52014dfb663b558b625aa5fef0489bdd
+  data.tar.gz: 9cb5e73f8e4ae8a94b3be1cb7ddbed5e8dbfd9ff36d9fbdddbfed317ba576769
 SHA512:
-  metadata.gz: e4432fd886028e08a31f840bebc3e9128fa84f19da9ab4d8bb1f40e78f623580279228c248bd21f98e6d9e1fe56adaa951cdadc508958386b0db4cdd652d53c6
-  data.tar.gz: b2be00dac1a8d5e8682b0ae02dae3670511644c92703397ad153a8934b5843087c9dfb0c88c4ca58ed81b36dbb5b441ed6021d69db2a3a45060712bac14884e9
+  metadata.gz: 3b399bf5d193fa63a3b92f7e686622761c56b453e14137bb6b8783ee95d703103ab6ca455dcade1f5695e868c44a8f6faa54eb652e0c4a141d0a6b4895553ed8
+  data.tar.gz: 4a7b4fb856f8645f7ed4ece0f8eeb5de9228d71ced91ae9ecd908814b51a59c8f1b9744bc40f99ca3af2443fb894014bdc548e7cc23074ec59b3ecb652fee1b5

data/README.md

@@ -1,15 +1,67 @@
-# VelvetKit
-
-Accessible UI components for Rails, built on [ViewComponent](https://viewcomponent.org),
-Tailwind CSS 4 and Stimulus. Website: **https://velvetkit.com**
+<div align="center">
+  <!-- One image on its own dark tile, so it reads in light and dark themes alike. -->
+  <a href="https://velvetkit.com"><img alt="VelvetKit by KitForge" src=".github/assets/readme-logo.svg" width="600"></a>
+
+  <p><strong>Rails UI components you own.</strong><br>
+  Accessible ViewComponents styled with Tailwind CSS 4 and wired up with Stimulus,<br>
+  copied into your app one at a time, under your namespace.</p>
+
+  <p>
+    <a href="https://rubygems.org/gems/velvetkit"><img alt="Gem version" src="https://img.shields.io/gem/v/velvetkit?include_prereleases&color=4D1A7F"></a>
+    <a href="https://github.com/kitforge-tech/velvetkit/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/kitforge-tech/velvetkit/actions/workflows/ci.yml/badge.svg"></a>
+    <img alt="Rails 7.1+" src="https://img.shields.io/badge/Rails-7.1%2B-CC0000?logo=rubyonrails&logoColor=white">
+    <img alt="Tailwind CSS 4" src="https://img.shields.io/badge/Tailwind_CSS-4-38BDF8?logo=tailwindcss&logoColor=white">
+    <a href="LICENSE.txt"><img alt="MIT licence" src="https://img.shields.io/badge/licence-MIT-blue"></a>
+  </p>
+
+  <p>
+    <a href="https://velvetkit.com"><strong>Website</strong></a> ·
+    <a href="https://velvetkit.com/docs">Docs</a> ·
+    <a href="https://velvetkit.com/docs/components">Components</a> ·
+    <a href="https://velvetkit.com/docs/ai">Build with AI</a> ·
+    <a href="CHANGELOG.md">Changelog</a>
+  </p>
+</div>
+
+<br>
+
+<a href="https://velvetkit.com">
+  <img alt="The velvetkit.com home page: a sign-in form, a team list, notification switches and a plan picker, all built from VelvetKit components" src="https://github.com/user-attachments/assets/ffafd932-34d5-4dfe-b314-ca3692fc54bf">
+</a>
+
+## Why VelvetKit
 
 VelvetKit doesn't load a component library at runtime. A generator copies the
 components you ask for, plus the ones they depend on, into your app. After
-that they're your code, under whatever module name you choose, and you can
-change them however you like.
+that they're your code, and you can change them however you like.
+
+- **Only what you use.** `velvetkit:add dialog` brings Dialog and the Button,
+  Icon and Spinner it renders, and nothing else.
+- **Your namespace.** Components land under `UI::`, `Kit::` or any module you
+  choose, with their Stimulus identifiers, translations and DOM ids renamed to match.
+- **Accessible by default.** Keyboard support, focus management and ARIA
+  wiring are built in, and every component ships with its Minitest tests.
+- **Previews included.** Each component comes with Lookbook previews, copied
+  alongside it.
+- **Themeable.** Everything styles itself from CSS variables, with dark mode
+  and no flash on load.
+- **Ready for AI agents.** Your coding agent gets a reference of the
+  components you've installed, so it uses them instead of inventing new ones.
+
+## Quick start
+
+```ruby
+# Gemfile
+gem "velvetkit", group: :development
+```
+
+```bash
+bundle install
+bin/rails generate velvetkit:install     # components under UI::
+bin/rails generate velvetkit:add dialog  # Dialog, and what it uses
+```
 
 ```bash
-bin/rails generate velvetkit:add dialog
 #  create  app/components/ui/base.rb
 #  create  app/components/ui/icon.rb
 #  create  app/components/ui/spinner.rb
@@ -18,22 +70,69 @@ bin/rails generate velvetkit:add dialog
 #  create  app/javascript/controllers/ui/dialog_controller.ts
 ```
 
-## Requirements
+```erb
+<%= render(UI::Button.new(variant: :outline)) { "Save draft" } %>
+```
+
+### Requirements
 
 - Rails 7.1+, Ruby 3.2+
 - Tailwind CSS 4
 - A JavaScript bundler that compiles TypeScript (Bun or esbuild through
   `jsbundling-rails`). The Stimulus controllers are `.ts` files.
 
-## Install
-
-```ruby
-# Gemfile
-gem "velvetkit", group: :development
-```
+## Components
+
+38 components, each with live examples on [velvetkit.com](https://velvetkit.com/docs/components):
+
+[Accordion](https://velvetkit.com/docs/components/accordion) ·
+[Alert](https://velvetkit.com/docs/components/alert) ·
+[Avatar](https://velvetkit.com/docs/components/avatar) ·
+[AvatarGroup](https://velvetkit.com/docs/components/avatar_group) ·
+[Badge](https://velvetkit.com/docs/components/badge) ·
+[Banner](https://velvetkit.com/docs/components/banner) ·
+[Breadcrumb](https://velvetkit.com/docs/components/breadcrumb) ·
+[Button](https://velvetkit.com/docs/components/button) ·
+[ButtonTo](https://velvetkit.com/docs/components/button_to) ·
+[Card](https://velvetkit.com/docs/components/card) ·
+[Checkbox](https://velvetkit.com/docs/components/checkbox) ·
+[Collapsible](https://velvetkit.com/docs/components/collapsible) ·
+[DataGrid](https://velvetkit.com/docs/components/data_grid) ·
+[DatePicker](https://velvetkit.com/docs/components/date_picker) ·
+[Dialog](https://velvetkit.com/docs/components/dialog) ·
+[Divider](https://velvetkit.com/docs/components/divider) ·
+[FormField](https://velvetkit.com/docs/components/form_field) ·
+[Icon](https://velvetkit.com/docs/components/icon) ·
+[Image](https://velvetkit.com/docs/components/image) ·
+[Input](https://velvetkit.com/docs/components/input) ·
+[InputGroup](https://velvetkit.com/docs/components/input_group) ·
+[Label](https://velvetkit.com/docs/components/label) ·
+[Link](https://velvetkit.com/docs/components/link) ·
+[Menu](https://velvetkit.com/docs/components/menu) ·
+[NativeSelect](https://velvetkit.com/docs/components/native_select) ·
+[Pagination](https://velvetkit.com/docs/components/pagination) ·
+[PasswordInput](https://velvetkit.com/docs/components/password_input) ·
+[Popover](https://velvetkit.com/docs/components/popover) ·
+[RadioGroup](https://velvetkit.com/docs/components/radio_group) ·
+[Select](https://velvetkit.com/docs/components/select) ·
+[Sheet](https://velvetkit.com/docs/components/sheet) ·
+[Sidebar](https://velvetkit.com/docs/components/sidebar) ·
+[Spinner](https://velvetkit.com/docs/components/spinner) ·
+[Switch](https://velvetkit.com/docs/components/switch) ·
+[Table](https://velvetkit.com/docs/components/table) ·
+[TableOfContents](https://velvetkit.com/docs/components/table_of_contents) ·
+[Tabs](https://velvetkit.com/docs/components/tabs) ·
+[Text](https://velvetkit.com/docs/components/text) ·
+[Textarea](https://velvetkit.com/docs/components/textarea) ·
+[ThemeToggle](https://velvetkit.com/docs/components/theme_toggle) ·
+[Tooltip](https://velvetkit.com/docs/components/tooltip) ·
+[Typography](https://velvetkit.com/docs/components/typography)
+
+## Usage
+
+### Install
 
 ```bash
-bundle install
 bin/rails generate velvetkit:install                 # components under UI::
 bin/rails generate velvetkit:install --namespace=Kit # or under Kit::
 ```
@@ -50,11 +149,12 @@ bin/rails generate velvetkit:install --namespace=Kit # or under Kit::
 - installs `@hotwired/stimulus`, `lucide` and `tw-animate-css` with your
   package manager, which it picks from your lockfile
 
-## Add components
+### Add components
 
 ```bash
 bin/rails generate velvetkit:add                  # list what's available
 bin/rails generate velvetkit:add date_picker menu # add these and what they use
+bin/rails generate velvetkit:add --all            # everything
 ```
 
 `add` does the following for each component:
@@ -73,7 +173,7 @@ Options: `--namespace=Kit`, `--skip-tests`, `--skip-previews`,
 `--skip-packages` (list the packages instead of installing them), and the usual
 `--force`/`--skip` for files that already exist.
 
-## AI agents
+### AI agents
 
 `install` also writes three files so coding agents use your components
 instead of inventing new ones:
@@ -90,7 +190,7 @@ Run `bin/rails generate velvetkit:ai` to regenerate them, or install with
 [llms.txt](https://velvetkit.com/llms.txt), and every component page has a
 Markdown version.
 
-## Namespacing
+### Namespacing
 
 Every component is written once, against `UI`. The generators rewrite each file
 as they copy it, so with `--namespace=Kit`:
@@ -105,7 +205,7 @@ as they copy it, so with `--namespace=Kit`:
 
 The namespace must be a single constant name, like `UI`, `Kit` or `VelvetKit`.
 
-## Theming
+### Theming
 
 Components style themselves from the CSS variables in `velvetkit.css`
 (`--primary`, `--radius`, `--sidebar`, …), with a `.dark` set alongside. To
@@ -118,13 +218,18 @@ partial in your layout's `<head>`:
 <%= render "layouts/theme_script" %>
 ```
 
-## Developing VelvetKit
+## Contributing
+
+Bug reports and pull requests are welcome on
+[GitHub](https://github.com/kitforge-tech/velvetkit/issues).
 
 ```bash
 bundle install
+bundle exec rake test             # all three suites below
 bundle exec rake test:gem         # namespace rewriting, registry, generators
 bundle exec rake test:components  # every component, from the registry, as UI::
 bundle exec rake test:namespaced  # every component copied out as Kit::, then tested
+bundle exec rubocop
 ```
 
 `registry/` holds the components, laid out like a Rails app.
@@ -132,66 +237,29 @@ bundle exec rake test:namespaced  # every component copied out as Kit::, then te
 (descriptions, package and gem versions). Dependencies, Stimulus controllers
 and npm imports are read from the source, so they can't drift.
 
-## The docs site (velvetkit.com)
-
-`site/` is a Rails app that serves https://velvetkit.com. It installs the kit
-from `registry/` the way any app would, with `bin/sync-kit` (it runs
-`velvetkit:install` and `velvetkit:add --all`). The copied files are
-gitignored, so the registry is the only source.
-
-The pages build themselves from the registry:
-
-- each component page renders that component's Lookbook preview templates
-  live, next to their source
-- the "Comes with" list comes from the same dependency scan `add` uses
-- the arguments and slots are read from the component's Ruby
-
-To document a component, write or improve its preview. The site picks it up.
+To document a component, write or improve its Lookbook preview: the docs
+site renders previews live. `site/` is the Rails app behind velvetkit.com;
+see [site/README.md](site/README.md) to run and deploy it.
 
-```bash
-cd site
-bun install && bundle install
-bin/dev            # sync the kit, then run Rails, JS and CSS watchers
-bin/rails test     # every page renders, every live example, SEO and AI endpoints
-bin/ux-check       # real clicks, keys and clipboard in headless Chrome (site on :3000)
-```
-
-### Deploying
-
-The image is built from the `Dockerfile` at the repository root. It needs
-the gem and the registry as well as `site/`.
+### Releasing
 
-**Dokploy:** create an Application from this repository with build type
-**Dockerfile**. The defaults fit: Dockerfile path `Dockerfile`, context `.`.
-Then:
+1. Bump `VERSION` in `lib/velvetkit/version.rb` and add a `CHANGELOG.md`
+   entry, in a pull request.
+2. Once it's merged, tag the merge commit and push the tag:
 
-- Environment:
-  - `SECRET_KEY_BASE`, required: generate one with `openssl rand -hex 64`.
-  - `SITE_URL`, if the site isn't served at https://velvetkit.com.
-- Domains: `velvetkit.com` on container port **80**, with HTTPS on. Traefik
-  terminates TLS and the app trusts it (`assume_ssl`).
-- Health check: the image declares one against `GET /up`.
+   ```bash
+   git tag v0.1.1.beta && git push origin v0.1.1.beta
+   ```
 
-**Kamal:** fill in the TODOs in `site/config/deploy.yml`, then run
-`bin/kamal deploy` from `site/`. It uses the same Dockerfile.
-
-**Anywhere else:**
-
-```bash
-docker build -t velvetkit-site .
-docker run -p 8080:80 -e SECRET_KEY_BASE=$(openssl rand -hex 64) -e FORCE_SSL=false velvetkit-site
-```
+The [release workflow](.github/workflows/release.yml) checks the tag matches
+the version, runs the tests and publishes the gem to RubyGems.
 
-### SEO and AI
+## Licence
 
-Every page has its own title, description, canonical URL and Open Graph
-and Twitter cards, using `public/og.png`. The home page carries JSON-LD for
-`SoftwareApplication` and `WebSite`; docs pages carry `TechArticle` and
-`BreadcrumbList`. `/sitemap.xml` and `/robots.txt` are built from the
-routes, and robots explicitly welcomes AI crawlers and points them at
-`/llms.txt`. Component pages link their Markdown version with
-`rel="alternate"`.
+VelvetKit is released under the [MIT licence](LICENSE.txt).
 
-## License
+<br>
 
-MIT
+<div align="center">
+  <sub>Built by <a href="https://kitforge.tech">KitForge</a></sub>
+</div>

data/lib/velvetkit/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Velvetkit
-  VERSION = "0.1.0.beta"
+  VERSION = "0.1.0"
 end

data/registry/app/components/ui/checkbox.html.erb

@@ -1,3 +1,4 @@
+<%= render(wrapper) do %>
 <% if label.present? %>
   <%= tag.label for: @id, class: wrapper_classes do %>
     <%= tag.span class: "relative inline-flex" do %>
@@ -16,3 +17,4 @@
     <% end %>
   <% end %>
 <% end %>
+<% end %>

data/registry/app/components/ui/checkbox.rb

@@ -20,9 +20,9 @@ class UI::Checkbox < UI::Base
   )
 
   def initialize(name: nil, value: "1", unchecked_value: "0", checked: false,
-                 label: nil, size: :default,
+                 label: nil, hint: nil, size: :default,
                  form: nil, field: nil,
-                 required: false, error: false, disabled: false,
+                 required: false, error: nil, disabled: false,
                  class: nil, **html_attrs)
     @form            = form
     @field           = field
@@ -37,10 +37,15 @@ class UI::Checkbox < UI::Base
     @disabled   = disabled
     @user_class = binding.local_variable_get(:class)
     @html_attrs = html_attrs
-    @id = @html_attrs[:id] || ("ui-cb-#{SecureRandom.hex(4)}" if label?)
+    # The label sits beside the box, so FormField only adds the messages below.
+    @wrapper = UI::FormField.new(label: false, hint: hint, error: error, form: form, field: field)
+    @id = @html_attrs[:id] || ("ui-cb-#{SecureRandom.hex(4)}" if label? || @wrapper.wrap?)
     @html_attrs[:id] = @id if @id
+    @wrapper.for = @id
   end
 
+  attr_reader :wrapper
+
   def form_field?
     @form.present? && @field.present?
   end
@@ -87,7 +92,8 @@ class UI::Checkbox < UI::Base
     opts[:checked] = true if @checked
     opts[:disabled] = true if @disabled
     opts[:required] = true if @required
-    opts[:"aria-invalid"] = "true" if @error
+    opts[:"aria-invalid"] = "true" if wrapper.error?
+    opts[:"aria-describedby"] = wrapper.describedby if wrapper.describedby
     opts[:class]   = classes
     # Add accessible name when no visual label is present
     if !label? && opts[:"aria-label"].blank?
@@ -107,7 +113,7 @@ class UI::Checkbox < UI::Base
   def classes
     cn(
       variant_classes(size: @size),
-      { "border-destructive aria-invalid:focus:ring-destructive" => @error },
+      { "border-destructive aria-invalid:focus:ring-destructive" => wrapper.error? },
       @user_class
     )
   end

data/registry/app/components/ui/collapsible.html.erb

@@ -0,0 +1,7 @@
+<%= tag.details(**details_options) do %>
+  <%= tag.summary(class: trigger_classes) do %>
+    <span class="min-w-0 flex-1 truncate"><%= trigger %></span>
+    <%= render(UI::Icon.new(name: "chevron-right", size: :sm, class: "shrink-0 transition-transform duration-200 group-open/collapsible:rotate-90 motion-reduce:transition-none", aria: { hidden: true })) %>
+  <% end %>
+  <%= tag.div(class: content_classes) { content } %>
+<% end %>

data/registry/app/components/ui/collapsible.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+# A section that opens and closes under its trigger: a tree of links in a
+# sidebar, "Show more" details, an advanced-settings block.
+#
+# Built on <details> and <summary>, so it works before any JavaScript loads,
+# Enter and Space toggle it, screen readers announce it as expanded or
+# collapsed, and find-in-page opens it to show a match. Browsers that can
+# animate to auto height slide it open; the rest open it at once.
+#
+#   <%= render(UI::Collapsible.new(open: current_page_is_a_form?)) do |c| %>
+#     <% c.with_trigger { "Forms" } %>
+#     <%= link_to "Input", input_path %>
+#   <% end %>
+#
+# Collapsibles nest, so a trigger inside the content makes a deeper branch.
+class UI::Collapsible < UI::Base
+  variants(
+    base: "flex w-full cursor-pointer list-none items-center gap-2 rounded-md " \
+          "[&::-webkit-details-marker]:hidden " \
+          "#{UI::Base::FOCUS_RING}",
+    variants: {
+      size: {
+        sm:      "px-2 py-1 text-xs",
+        default: "px-3 py-1.5 text-sm",
+        lg:      "px-3 py-2 text-base"
+      }
+    },
+    defaults: { size: :default }
+  )
+
+  renders_one :trigger
+
+  def initialize(open: false, size: :default, trigger_class: nil, content_class: nil,
+                 class: nil, **html_attrs)
+    @open          = open
+    @size          = size
+    @trigger_class = trigger_class
+    @content_class = content_class
+    @user_class    = binding.local_variable_get(:class)
+    @html_attrs    = html_attrs
+  end
+
+  def details_options
+    opts = @html_attrs.dup
+    opts[:open]  = true if @open
+    # interpolate-size lets the content's height transition to and from auto.
+    opts[:class] = cn(
+      "group/collapsible [interpolate-size:allow-keywords] " \
+      "[&::details-content]:[block-size:0] [&::details-content]:overflow-hidden " \
+      "[&::details-content]:transition-[block-size,content-visibility] " \
+      "[&::details-content]:duration-200 [&::details-content]:[transition-behavior:allow-discrete] " \
+      "open:[&::details-content]:[block-size:auto] " \
+      "motion-reduce:[&::details-content]:transition-none",
+      @user_class
+    )
+    opts
+  end
+
+  def trigger_classes
+    cn(variant_classes(size: @size), @trigger_class)
+  end
+
+  def content_classes
+    cn("pt-1", @content_class)
+  end
+end

data/registry/app/components/ui/date_picker.html.erb

@@ -17,7 +17,7 @@
            placeholder="<%= placeholder %>" class="<%= input_classes %>"
            value="<%= typed_value %>"
            <%= "required" if @required %> <%= "disabled" if @disabled %>
-           <%= "aria-describedby=\"#{input_id}-hint\"".html_safe if render_hint? %>
+           <%= tag.attributes("aria-describedby": describedby, "aria-invalid": ("true" if wrapper.error?)) %>
            data-ui--date-picker-target="input"
            data-action="input->ui--date-picker#typed">
 
@@ -41,6 +41,9 @@
       <%= t("ui.date_picker.hint", pattern: placeholder) %>
     </p>
   <% end %>
+  <% if wrapper.error_message %>
+    <%= tag.p(wrapper.error_message, id: wrapper.error_id, class: "mt-1 text-xs text-destructive") %>
+  <% end %>
 
   <div id="<%= panel_id %>" role="dialog" hidden
        class="absolute z-30 mt-1 rounded-md border bg-popover p-3 text-popover-foreground shadow-md"

data/registry/app/components/ui/date_picker.rb

@@ -26,7 +26,7 @@
 #   <%= render(UI::DatePicker.new(name: "event[date]", value: @date, label: "Date")) %>
 class UI::DatePicker < UI::Base
   def initialize(name: nil, value: nil, form: nil, field: nil, label: nil,
-                 required: false, error: false, disabled: false, hint: true,
+                 required: false, error: nil, disabled: false, hint: true,
                  min: nil, max: nil, class: nil, **html_attrs)
     @name = name
     @value = value
@@ -44,8 +44,12 @@ class UI::DatePicker < UI::Base
     @max = max
     @user_class = binding.local_variable_get(:class)
     @html_attrs = html_attrs
+    # Only for the error: the label and the format hint are laid out here.
+    @wrapper = UI::FormField.new(label: false, error: error, form: form, field: field, for: input_id)
   end
 
+  attr_reader :wrapper
+
   def field_name = @name || (@form && @field && "#{@form.object_name}[#{@field}]")
 
   # The value the form submits, always ISO, whatever was typed.
@@ -65,6 +69,10 @@ class UI::DatePicker < UI::Base
   def render_hint? = @hint != false
 
   def input_id = @input_id ||= "ui-date-#{SecureRandom.hex(4)}"
+
+  def describedby
+    [ ("#{input_id}-hint" if render_hint?), (wrapper.error_id if wrapper.error_message) ].compact.join(" ").presence
+  end
   def panel_id = "#{input_id}-panel"
 
   def classes = cn("relative", @user_class)
@@ -78,7 +86,7 @@ class UI::DatePicker < UI::Base
       # aria-invalid rather than a Ruby flag, so a date the user mistypes is
       # marked without a round trip.
       "aria-invalid:border-destructive aria-invalid:ring-destructive",
-      @error && "border-destructive"
+      wrapper.error? && "border-destructive"
     )
   end
 

data/registry/app/components/ui/form_field/messages.html.erb

@@ -0,0 +1,6 @@
+<% if @field.hint.present? %>
+  <%= tag.p(@field.hint, id: @field.hint_id, class: "text-xs text-muted-foreground") %>
+<% end %>
+<% if @field.error_message.present? %>
+  <%= tag.p(@field.error_message, id: @field.error_id, class: "text-xs text-destructive") %>
+<% end %>

data/registry/app/components/ui/form_field/messages.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+# The hint and error under a control, with the ids its aria-describedby names.
+# For controls that lay out their own label, as UI::Select does.
+class UI::FormField::Messages < UI::Base
+  def initialize(field)
+    @field = field
+  end
+
+  def render? = @field.hint.present? || @field.error_message.present?
+end

data/registry/app/components/ui/form_field.html.erb

@@ -0,0 +1,9 @@
+<% if wrap? %>
+  <%= tag.div(class: classes, **@html_attrs) do %>
+    <% if render_label? %><%= render(label_component) { label_text } %><% end %>
+    <%= content %>
+    <%= render(UI::FormField::Messages.new(self)) %>
+  <% end %>
+<% else %>
+  <%= content %>
+<% end %>

data/registry/app/components/ui/form_field.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+# A label, a control, a hint and an error message, wired together: the label
+# points at the control, and the control is described by the hint and error.
+#
+# Input, Textarea, NativeSelect and Select render through it, so they take
+# `hint:` and `error:` directly. Wrap any other control yourself and spread
+# `field.control_attributes` onto it:
+#
+#   <%= render(UI::FormField.new(label: "Colour", hint: "Used for your avatar")) do |field| %>
+#     <%= tag.input(type: "color", name: "colour", **field.control_attributes) %>
+#   <% end %>
+#
+# `error:` takes a message, or `true` to mark the control invalid without one.
+# Bound to a form (`form:` + `field:`), the model's errors on that attribute
+# are the message (for `team_id`, the `team` association's too, where
+# belongs_to puts "must exist"), and the attribute's human name is the label
+# (`label:` overrides it, `label: false` opts out). Nothing to show means no
+# wrapper: just the control.
+class UI::FormField < UI::Base
+  def initialize(label: nil, hint: nil, error: nil, required: false, disabled: false,
+                 label_size: :default, label_weight: :medium,
+                 form: nil, field: nil, for: nil,
+                 class: nil, **html_attrs)
+    @label        = label
+    @hint         = hint
+    @error        = error
+    @required     = required
+    @disabled     = disabled
+    @label_size   = label_size
+    @label_weight = label_weight
+    @form         = form
+    @field        = field
+    @for          = binding.local_variable_get(:for)
+    @user_class   = binding.local_variable_get(:class)
+    @html_attrs   = html_attrs
+  end
+
+  attr_reader :hint
+  attr_writer :for
+
+  def form_field? = @form.present? && @field.present?
+
+  def wrap? = render_label? || hint.present? || error_message.present?
+
+  # The id the label points at and the messages hang off. Controls set their
+  # own (`for:`); otherwise one is made the first time it's asked for.
+  def control_id
+    @for ||= "ui-field-#{SecureRandom.hex(4)}"
+  end
+
+  def hint_id = "#{control_id}-hint"
+  def error_id = "#{control_id}-error"
+
+  def error_message
+    return @error if @error.is_a?(String)
+    return if @error == false || !form_field?
+
+    errors = @form.object.respond_to?(:errors) ? @form.object.errors : nil
+    return unless errors
+
+    attributes = [ @field.to_sym, @field.to_s.delete_suffix("_id").to_sym ].uniq
+    attributes.flat_map { |attribute| errors.full_messages_for(attribute) }.uniq.to_sentence.presence
+  end
+
+  def error? = @error == true || error_message.present?
+
+  def describedby
+    [ (hint_id if hint.present?), (error_id if error_message.present?) ].compact.join(" ").presence
+  end
+
+  # Spread onto a control you render yourself.
+  def control_attributes
+    { id: control_id, "aria-describedby": describedby, "aria-invalid": ("true" if error?) }.compact
+  end
+
+  def render_label?
+    return false if @label == false
+
+    @label.present? || form_field?
+  end
+
+  def label_text
+    return @label if @label.is_a?(String) && @label.present?
+    return nil unless form_field?
+
+    object = @form.object
+    if object.respond_to?(:class) && object.class.respond_to?(:human_attribute_name)
+      object.class.human_attribute_name(@field)
+    else
+      @field.to_s.humanize
+    end
+  end
+
+  def label_component
+    UI::Label.new(for: control_id, size: @label_size, weight: @label_weight,
+                  required: @required, disabled: @disabled)
+  end
+
+  def classes
+    cn("flex flex-col gap-2 w-full", @user_class)
+  end
+end

data/registry/app/components/ui/input.html.erb

@@ -1,9 +1,2 @@
 <%# frozen_string_literal: true %>
-<% if render_label? %>
-  <div class="flex flex-col gap-2 w-full">
-    <%= render(label_component) { label_text } %>
-    <% if form_field? %><%= @form.public_send(form_builder_method, @field, **form_field_options) %><% else %><%= tag.input(**html_options) %><% end %>
-  </div>
-<% else %>
-  <% if form_field? %><%= @form.public_send(form_builder_method, @field, **form_field_options) %><% else %><%= tag.input(**html_options) %><% end %>
-<% end %>
+<%= render(wrapper) do %><% if form_field? %><%= @form.public_send(form_builder_method, @field, **form_field_options) %><% else %><%= tag.input(**html_options) %><% end %><% end %>