velvetkit 0.1.0.beta → 0.1.0

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

@@ -42,7 +42,7 @@ class UI::Input < UI::Base
 
   def initialize(type: :text, size: :default, variant: :default,
                  label: nil, label_size: :default, label_weight: :medium,
-                 required: false, error: false, disabled: false,
+                 hint: nil, required: false, error: nil, disabled: false,
                  form: nil, field: nil,
                  class: nil, **html_attrs)
     @form           = form
@@ -58,13 +58,20 @@ class UI::Input < UI::Base
     @disabled       = disabled
     @user_class     = binding.local_variable_get(:class)
     @html_attrs     = html_attrs
-    @input_id       = @html_attrs[:id] || (render_label? ? "ui-input-#{SecureRandom.hex(4)}" : nil)
+    @wrapper        = UI::FormField.new(label: label, hint: hint, error: error,
+                                        required: required, disabled: disabled,
+                                        label_size: label_size, label_weight: label_weight,
+                                        form: form, field: field)
+    @input_id       = @html_attrs[:id] || (@wrapper.wrap? ? "ui-input-#{SecureRandom.hex(4)}" : nil)
     @html_attrs[:id] = @input_id if @input_id
+    @wrapper.for    = @input_id
   end
 
+  attr_reader :wrapper
+
   def classes
     cn(
-      variant_classes(size: @size, variant: @variant),
+      variant_classes(size: @size, variant: wrapper.error? ? :error : @variant),
       @user_class
     )
   end
@@ -76,7 +83,8 @@ class UI::Input < UI::Base
     opts[:class]          = classes
     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
   end
 
@@ -92,36 +100,4 @@ class UI::Input < UI::Base
   def form_builder_method
     BUILDER_METHODS.fetch(@type.to_sym, :text_field)
   end
-
-  # Labels follow Rails' own convention: bound to a form object, the attribute
-  # name supplies the text (via human_attribute_name, so i18n and
-  # `activerecord.attributes.*` overrides apply) with no per-call-site string.
-  # Pass `label:` to override the text, or `label: false` to opt out entirely.
-  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: @input_id,
-      size: @label_size,
-      weight: @label_weight,
-      required: @required,
-      disabled: @disabled
-    )
-  end
 end

data/registry/app/components/ui/input_group/addon.rb

@@ -33,7 +33,10 @@ class UI::InputGroup::Addon < UI::Base
       class: cn(
         "text-sm flex gap-2 items-center h-6 gap-1 px-2",
         "rounded-[calc(var(--radius)-5px)]",
-        "[&>svg:not([class*='size-'])]:size-3.5 has-[>svg]:px-2"
+        "[&>svg:not([class*='size-'])]:size-3.5 has-[>svg]:px-2",
+        # Inside a field a click shouldn't ring the button (it reads as a
+        # second ring on the field); keyboard focus still does.
+        "focus:ring-0 focus:ring-offset-0 focus-visible:ring-2 focus-visible:ring-offset-1"
       ),
       **opts
     )

data/registry/app/components/ui/input_group/field.rb

@@ -3,7 +3,7 @@
 # UI::InputGroup::Field — a UI::Input variant stripped of its own
 # border/shadow/ring so the parent wrapper owns those styles.
 #
-# The wrapper owns the focus treatment via :focus-within; the field strips
+# The wrapper owns the focus treatment (lit while this field has focus); the field strips
 # its own outline + ring so there is no double indicator on focus.
 class UI::InputGroup::Field < UI::Input
   STRIPPED_CLASSES =
@@ -16,6 +16,9 @@ class UI::InputGroup::Field < UI::Input
 
   def initialize(**args)
     super(**args)
+    # Inside the group's border there is no room for a label or messages: the
+    # component composing the group shows those. Keep only the invalid state.
+    @wrapper = UI::FormField.new(label: false, error: @wrapper.error?)
     @html_attrs[:data] ||= {}
     @html_attrs[:data][:slot] = "input-group-control"
   end

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

@@ -13,8 +13,11 @@
 #     <%= g.with_field(type: :email, placeholder: "you@example.com") %>
 #   <% end %>
 class UI::InputGroup < UI::Base
-  # Wrapper owns the focus ring via :focus-within so it lights up on any
-  # descendant focus (mouse click or keyboard). focus-visible is too narrow.
+  # Wrapper owns the control's focus ring, lit when the control itself has
+  # focus (mouse or keyboard). Not :focus-within: an addon button has its own
+  # ring, and the two would stack.
+  # An invalid, enabled control turns the border red: [aria-invalid]:enabled,
+  # because a :has() nested inside has-[] is invalid CSS and drops the rule.
   WRAPPER_BASE =
     "group/input-group relative flex w-full items-center rounded-md border " \
     "border-input bg-background " \
@@ -28,12 +31,12 @@ class UI::InputGroup < UI::Base
     "has-[>[data-align=block-end]]:h-auto " \
     "has-[>[data-align=block-end]]:flex-col " \
     "has-[>[data-align=block-end]]:[&>input]:pt-3 " \
-    "focus-within:ring-2 " \
-    "focus-within:ring-primary " \
-    "focus-within:ring-offset-1 " \
+    "has-[[data-slot]:focus]:ring-2 " \
+    "has-[[data-slot]:focus]:ring-primary " \
+    "has-[[data-slot]:focus]:ring-offset-1 " \
     "ring-offset-background " \
-    "has-[[data-slot][aria-invalid=true]:not(:has(input:disabled))]:border-destructive " \
-    "has-[[data-slot][aria-invalid=true]:not(:has(input:disabled))]:ring-destructive " \
+    "has-[[data-slot][aria-invalid=true]:enabled]:border-destructive " \
+    "has-[[data-slot][aria-invalid=true]:enabled]:ring-destructive " \
     "has-[input:disabled]:border-input " \
     "has-[input:disabled]:bg-muted " \
     "has-[input:disabled]:opacity-50"
@@ -47,9 +50,8 @@ class UI::InputGroup < UI::Base
     @html_attrs = html_attrs
   end
 
+  # The invalid state comes from the field's aria-invalid, via WRAPPER_BASE.
   def wrapper_classes
-    # Propagate error styling to the wrapper when the field is in error state.
-    error = field&.instance_variable_get(:@error)
-    cn(WRAPPER_BASE, { "border-destructive" => error }, @user_class)
+    cn(WRAPPER_BASE, @user_class)
   end
 end

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

@@ -2,15 +2,8 @@
     is drawn back with a positioned icon over the control. %>
 <% control = capture do %>
   <div class="relative w-full">
-    <% if form_field? %><%= @form.select(@field, normalized_options, { include_blank: prompt.presence, selected: @selected }, form_select_options) %><% else %><%= tag.select(**select_options) do %><% if prompt.present? %><option value=""><%= prompt %></option><% end %><% normalized_options.each do |label, value| %><option value="<%= value %>" <%= "selected" if selected?(value) %>><%= label %></option><% end %><% end %><% end %>
+    <% if form_field? %><%= @form.select(@field, normalized_options, builder_select_options, form_select_options) %><% else %><%= tag.select(**select_options) do %><% if prompt.present? %><option value=""><%= prompt %></option><% end %><% normalized_options.each do |label, value| %><option value="<%= value %>" <%= "selected" if selected?(value) %>><%= label %></option><% end %><% end %><% end %>
     <span class="pointer-events-none absolute inset-y-0 right-0 flex items-center pr-3 text-muted-foreground"><%= render(UI::Icon.new(name: "chevron-down", size: :sm, aria: { hidden: true })) %></span>
   </div>
 <% end %>
-<% if render_label? %>
-  <div class="flex flex-col gap-2 w-full">
-    <%= render(label_component) { label_text } %>
-    <%= control %>
-  </div>
-<% else %>
-  <%= control %>
-<% end %>
+<%= render(wrapper) { control } %>

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

@@ -30,8 +30,8 @@ class UI::NativeSelect < UI::Base
   )
 
   def initialize(name: nil, options: [], selected: nil, prompt: nil,
-                 label: nil, size: :default,
-                 required: false, error: false, disabled: false,
+                 label: nil, hint: nil, size: :default,
+                 required: false, error: nil, disabled: false,
                  form: nil, field: nil,
                  class: nil, **html_attrs)
     @name       = name
@@ -47,52 +47,32 @@ class UI::NativeSelect < UI::Base
     @field      = field
     @user_class = binding.local_variable_get(:class)
     @html_attrs = html_attrs
-    @select_id  = @html_attrs[:id] || (render_label? ? "ui-native-select-#{SecureRandom.hex(4)}" : nil)
+    @wrapper    = UI::FormField.new(label: label, hint: hint, error: error,
+                                    required: required, disabled: disabled,
+                                    form: form, field: field)
+    @select_id  = @html_attrs[:id] || (@wrapper.wrap? ? "ui-native-select-#{SecureRandom.hex(4)}" : nil)
     @html_attrs[:id] = @select_id if @select_id
+    @wrapper.for = @select_id
   end
 
-  attr_reader :options, :prompt
+  attr_reader :options, :prompt, :wrapper
 
   def classes
     cn(variant_classes(size: @size),
-       { "border-destructive focus:ring-destructive" => @error },
+       { "border-destructive focus:ring-destructive" => wrapper.error? },
        @user_class)
   end
 
   def form_field? = @form.present? && @field.present?
 
-  # Same convention as UI::Input: bound to a form object the attribute name
-  # supplies the label; `label:` overrides, `label: false` opts out.
-  def render_label?
-    return false if @label == false
-
-    @label.present? || form_field?
-  end
-
-  def label_text
-    return nil unless render_label?
-    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: @select_id, required: @required, disabled: @disabled)
-  end
-
   def select_options
     opts = @html_attrs.dup
     opts[:class] = classes
     opts[:name] = @name if @name
     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
   end
 
@@ -100,6 +80,12 @@ class UI::NativeSelect < UI::Base
   # to avoid overriding the scoped name with a bare one.
   def form_select_options = select_options.except(:name)
 
+  # Without an explicit `selected:` the builder selects the model's value;
+  # passing `selected: nil` would select nothing, losing it on a re-render.
+  def builder_select_options
+    { include_blank: prompt.presence, selected: @selected }.compact
+  end
+
   # Accepts [["Label", value], ...] or a plain list of scalars.
   def normalized_options
     options.map { |option| option.is_a?(Array) ? option : [ option, option ] }

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

@@ -10,11 +10,4 @@
     <% addon.with_icon_button(**toggle_button_options) do %><span class="inline-flex" data-ui--password-visibility-target="iconShow"><%= render(UI::Icon.new(name: "eye", size: :sm)) %></span><span class="inline-flex" style="display: none" data-ui--password-visibility-target="iconHide"><%= render(UI::Icon.new(name: "eye-off", size: :sm)) %></span><% end %>
   <% end %>
 <% end %><% end %>
-<% if render_label? %>
-  <div class="flex flex-col gap-2 w-full">
-    <%= render(label_component) { label_text } %>
-    <%= group %>
-  </div>
-<% else %>
-  <%= group %>
-<% end %>
+<%= render(wrapper) { group } %>

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

@@ -16,8 +16,8 @@ require "securerandom"
 #   <%= render(UI::PasswordInput.new(form: f, field: :password, required: true)) %>
 #   <%= render(UI::PasswordInput.new(name: "user[password]")) %>
 class UI::PasswordInput < UI::Base
-  def initialize(form: nil, field: nil, label: nil, required: false,
-                 disabled: false, error: false, class: nil, **html_attrs)
+  def initialize(form: nil, field: nil, label: nil, hint: nil, required: false,
+                 disabled: false, error: nil, class: nil, **html_attrs)
     @form       = form
     @field      = field
     @label      = label
@@ -29,8 +29,13 @@ class UI::PasswordInput < UI::Base
     @error      = error
     @user_class = binding.local_variable_get(:class)
     @html_attrs = html_attrs
+    @wrapper    = UI::FormField.new(label: label, hint: hint, error: error,
+                                    required: required, disabled: disabled,
+                                    form: form, field: field, for: @input_id)
   end
 
+  attr_reader :wrapper
+
   def group_component
     UI::InputGroup.new(
       class: @user_class,
@@ -38,34 +43,10 @@ class UI::PasswordInput < UI::Base
     )
   end
 
-  # Same convention as UI::Input: bound to a form object the attribute name
-  # supplies the label text; `label:` overrides it, `label: false` opts out.
-  def render_label?
-    return false if @label == false
-
-    @label.present? || form_field?
-  end
-
   def form_field?
     @form.present? && @field.present?
   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: @input_id, required: @required, disabled: @disabled)
-  end
-
   def field_options
     {
       type: :password,
@@ -75,7 +56,8 @@ class UI::PasswordInput < UI::Base
       label: false,
       required: @required,
       disabled: @disabled,
-      error: @error,
+      error: wrapper.error?,
+      "aria-describedby": wrapper.describedby,
       data: { "ui--password-visibility-target" => "input" },
       **@html_attrs
     }

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

@@ -48,6 +48,10 @@
     <% end %>
   <% end %>
 
+  <% if wrapper.hint.present? || wrapper.error_message.present? %>
+    <div class="mt-2 flex flex-col gap-2"><%= render(UI::FormField::Messages.new(wrapper)) %></div>
+  <% end %>
+
   <% if form_field? %>
     <%= @form.select(@field, native_choices, { selected: current_values }, native_options) %>
   <% else %>

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

@@ -42,8 +42,8 @@ class UI::Select < UI::Base
   )
 
   def initialize(name: nil, options: [], selected: nil, prompt: nil,
-                 label: nil, size: :default, searchable: false, multiple: false,
-                 required: false, error: false, disabled: false,
+                 label: nil, hint: nil, size: :default, searchable: false, multiple: false,
+                 required: false, error: nil, disabled: false,
                  form: nil, field: nil,
                  class: nil, **html_attrs)
     @name       = name
@@ -62,9 +62,15 @@ class UI::Select < UI::Base
     @user_class = binding.local_variable_get(:class)
     @html_attrs = html_attrs
     @uid        = SecureRandom.hex(4)
+    @wrapper    = UI::FormField.new(label: label, hint: hint, error: error,
+                                    required: required, disabled: disabled,
+                                    form: form, field: field, for: trigger_id)
   end
 
-  attr_reader :prompt, :size
+  attr_reader :prompt, :size, :wrapper
+
+  # Lays out its own label, so it takes FormField's parts rather than its wrapper.
+  delegate :render_label?, :label_text, :label_component, to: :wrapper
 
   def searchable? = @searchable
   def multiple? = @multiple
@@ -76,7 +82,7 @@ class UI::Select < UI::Base
 
   def trigger_classes
     cn(variant_classes(size: @size),
-       { "border-destructive focus:ring-destructive" => @error },
+       { "border-destructive focus:ring-destructive" => wrapper.error? },
        @user_class)
   end
 
@@ -87,7 +93,8 @@ class UI::Select < UI::Base
       class: trigger_classes,
       role: "combobox",
       disabled: @disabled,
-      aria: { haspopup: "listbox", expanded: "false", controls: listbox_id, invalid: (@error ? "true" : nil) },
+      aria: { haspopup: "listbox", expanded: "false", controls: listbox_id,
+              invalid: ("true" if wrapper.error?), describedby: wrapper.describedby },
       data: { "ui--select-target": "trigger",
               action: "click->ui--select#toggle keydown->ui--select#keydown" }
     }
@@ -95,30 +102,6 @@ class UI::Select < UI::Base
 
   def form_field? = @form.present? && @field.present?
 
-  # Same convention as UI::Input: bound to a form object the attribute name
-  # supplies the label; `label:` overrides, `label: false` opts out.
-  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: trigger_id, required: @required, disabled: @disabled)
-  end
-
   # Accepts [["Label", value], ...] or a plain list of scalars. A prompt
   # becomes a first, empty option, as `include_blank` makes it natively;
   # a multiple select has no "nothing" option, since nothing is unticking.

data/registry/app/components/ui/table_of_contents/item.html.erb

@@ -0,0 +1,8 @@
+<li>
+  <%= tag.a(@text, **link_options) %>
+  <% if items? %>
+    <ul class="ms-4 mt-1 space-y-1">
+      <% items.each do |item| %><%= item %><% end %>
+    </ul>
+  <% end %>
+</li>

data/registry/app/components/ui/table_of_contents/item.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+class UI::TableOfContents::Item < UI::Base
+  variants(
+    base: "block rounded-md px-3 text-muted-foreground hover:text-foreground " \
+          "data-[state=ancestor]:text-foreground " \
+          "data-[state=active]:bg-muted data-[state=active]:font-medium data-[state=active]:text-foreground " \
+          "#{FOCUS_RING}",
+    variants: {
+      level: {
+        top:    "py-1.5",
+        nested: "py-1"
+      }
+    },
+    defaults: { level: :top }
+  )
+
+  renders_many :items, ->(href:, text:, **opts) {
+    UI::TableOfContents::Item.new(href: href, text: text, depth: @depth + 1, **opts)
+  }
+
+  def initialize(href:, text:, depth: 0, class: nil, **html_attrs)
+    @href       = href
+    @text       = text
+    @depth      = depth
+    @user_class = binding.local_variable_get(:class)
+    @html_attrs = html_attrs
+  end
+
+  def link_options
+    opts = @html_attrs.except(:data)
+    opts[:href]  = @href
+    opts[:class] = cn(variant_classes(level: @depth.zero? ? :top : :nested), @user_class)
+    opts[:data]  = {
+      state: "inactive",
+      "ui--table-of-contents-target": "link",
+      action: "click->ui--table-of-contents#select"
+    }.merge(@html_attrs[:data] || {})
+    opts
+  end
+end

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

@@ -0,0 +1,13 @@
+<%= tag.nav(**html_options) do %>
+  <% if @title %>
+    <%= tag.p(@title, id: title_id, class: "mb-3 font-medium text-foreground") %>
+  <% end %>
+  <div class="relative border-s border-border ps-3" data-ui--table-of-contents-target="rail">
+    <%# Slides to the current link; positioned by the controller. %>
+    <span aria-hidden="true" data-state="hidden" data-ui--table-of-contents-target="indicator"
+          class="absolute -start-px top-0 h-0 w-0.5 rounded-full bg-primary opacity-0 data-[state=visible]:opacity-100 transition-[transform,height,opacity] duration-200 ease-out motion-reduce:transition-none"></span>
+    <ul class="space-y-1">
+      <% items.each do |item| %><%= item %><% end %>
+    </ul>
+  </div>
+<% end %>

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

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+# "On this page" navigation with scrollspy. As the reader scrolls, the link to
+# the section they are reading is marked current (aria-current="location") and
+# an indicator slides beside it. A link jumps to its section like any anchor.
+#
+# Each item links to an element id on the page, and items nest:
+#
+#   <%= render(UI::TableOfContents.new(title: "On this page")) do |toc| %>
+#     <% toc.with_item(href: "#install", text: "Install") do |item| %>
+#       <% item.with_item(href: "#requirements", text: "Requirements") %>
+#     <% end %>
+#     <% toc.with_item(href: "#usage", text: "Usage") %>
+#   <% end %>
+#
+# A section counts as reached once its top passes `offset:` pixels below the
+# top of the scroll area; raise it to clear a sticky header. When the content
+# scrolls inside an element rather than the window, pass that element's CSS
+# selector as `container:`.
+class UI::TableOfContents < UI::Base
+  renders_many :items, ->(href:, text:, **opts) {
+    UI::TableOfContents::Item.new(href: href, text: text, depth: 0, **opts)
+  }
+
+  def initialize(title: nil, label: nil, offset: 80, container: nil, class: nil, **html_attrs)
+    @title      = title
+    @label      = label
+    @offset     = offset
+    @container  = container
+    @user_class = binding.local_variable_get(:class)
+    @html_attrs = html_attrs
+    @id         = @html_attrs[:id] || "ui-toc-#{SecureRandom.hex(4)}"
+    @html_attrs[:id] = @id
+  end
+
+  def title_id = "#{@id}-title"
+
+  def html_options
+    data = {
+      controller: "ui--table-of-contents",
+      # Until the controller has marked the current link, nothing animates:
+      # otherwise every page load fades the highlight in.
+      settling: "",
+      "ui--table-of-contents-offset-value": @offset,
+      "ui--table-of-contents-container-value": @container
+    }.compact
+
+    opts = @html_attrs.except(:data)
+    opts[:class] = cn("text-sm data-[settling]:[&_*]:transition-none", @user_class)
+    opts[:data]  = data.merge(@html_attrs[:data] || {})
+    if @title
+      opts[:"aria-labelledby"] = title_id
+    else
+      opts[:"aria-label"] = @label || I18n.t("ui.table_of_contents.label", default: "On this page")
+    end
+    opts
+  end
+end

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

@@ -0,0 +1,2 @@
+<%# frozen_string_literal: true %>
+<%= render(wrapper) do %><% if form_field? %><%= @form.text_area(@field, **form_field_options) %><% else %><%= tag.textarea(value, **html_options) %><% end %><% end %>

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

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+# A multi-line text field, with the same label, hint, required, error and
+# form-builder options as UI::Input.
+#
+# `autogrow: true` grows the box with its text (CSS field-sizing, no
+# JavaScript); browsers without it keep `rows:` lines and scroll. Cap the
+# height with a class such as `max-h-60`.
+class UI::Textarea < UI::Base
+  variants(
+    base: "flex w-full rounded-md border border-input bg-background " \
+          "text-foreground " \
+          "placeholder:text-muted-foreground " \
+          "#{UI::Base::FOCUS_RING} " \
+          "disabled:cursor-not-allowed disabled:opacity-50",
+    variants: {
+      size: {
+        sm:      "px-2.5 py-1.5 text-xs",
+        default: "px-3 py-2 text-sm",
+        lg:      "px-4 py-2.5 text-base"
+      },
+      resize: {
+        vertical: "resize-y",
+        none:     "resize-none",
+        both:     "resize"
+      },
+      autogrow: {
+        true  => "field-sizing-content min-h-16 resize-none",
+        false => ""
+      },
+      error: {
+        true  => "border-destructive focus:ring-destructive",
+        false => ""
+      }
+    },
+    defaults: { size: :default, resize: :vertical, autogrow: false, error: false }
+  )
+
+  # `form:` + `field:` render through the form builder's text_area, so the
+  # field gets a scoped name like `post[body]` and its value from the model.
+  # Without them a plain <textarea> is rendered; pass `name:` and `value:`.
+  def initialize(size: :default, rows: 3, resize: :vertical, autogrow: false,
+                 label: nil, label_size: :default, label_weight: :medium,
+                 hint: nil, required: false, error: nil, disabled: false,
+                 value: nil, form: nil, field: nil,
+                 class: nil, **html_attrs)
+    @form         = form
+    @field        = field
+    @size         = size
+    @rows         = rows
+    @resize       = resize
+    @autogrow     = autogrow
+    @label        = label
+    @label_size   = label_size
+    @label_weight = label_weight
+    @required     = required
+    @error        = error
+    @disabled     = disabled
+    @value        = value
+    @user_class   = binding.local_variable_get(:class)
+    @html_attrs   = html_attrs
+    @wrapper      = UI::FormField.new(label: label, hint: hint, error: error,
+                                      required: required, disabled: disabled,
+                                      label_size: label_size, label_weight: label_weight,
+                                      form: form, field: field)
+    @textarea_id  = @html_attrs[:id] || (@wrapper.wrap? ? "ui-textarea-#{SecureRandom.hex(4)}" : nil)
+    @html_attrs[:id] = @textarea_id if @textarea_id
+    @wrapper.for  = @textarea_id
+  end
+
+  attr_reader :value, :wrapper
+
+  def classes
+    cn(
+      variant_classes(size: @size, resize: @resize, autogrow: @autogrow, error: wrapper.error?),
+      @user_class
+    )
+  end
+
+  def html_options
+    opts = @html_attrs.dup
+    opts[:rows]           = @rows
+    opts[:class]          = classes
+    opts[:disabled]       = true if @disabled
+    opts[:required]       = true if @required
+    opts[:"aria-invalid"] = "true" if wrapper.error?
+    opts[:"aria-describedby"] = wrapper.describedby if wrapper.describedby
+    opts
+  end
+
+  def form_field?
+    @form.present? && @field.present?
+  end
+
+  # The builder derives the name and value itself.
+  def form_field_options
+    html_options.except(:name)
+  end
+end