poetry-ui 0.0.2

data/app/components/poetry/ui/dropdown_menu/style.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Ui
+    module DropdownMenu
+      # Re-expressed through the cn-* theme layer: panel/item chrome,
+      # focus treatments, and the animate chains ride themes/default.css;
+      # popper vars, overflow, and the poetry indicator-visibility switch
+      # stay inline. Icon glyph classes stay inline per upstream (TSX
+      # inlines them on the lucide elements).
+      class Style < Poetry::Core::Style
+        element :content, "cn-dropdown-menu-content cn-menu-translucent z-50 max-h-(--available-height) " \
+                          "origin-(--transform-origin) overflow-x-hidden overflow-y-auto " \
+                          "data-closed:overflow-hidden outline-none w-(--anchor-width)"
+
+        # group/dropdown-menu-item: bare marker, no CSS - the vega
+        # shortcut re-color (group-focus/dropdown-menu-item) keys on it.
+        element :item, "cn-dropdown-menu-item group/dropdown-menu-item relative flex cursor-default " \
+                       "items-center outline-hidden select-none [&_svg]:pointer-events-none [&_svg]:shrink-0 " \
+                       "data-disabled:opacity-50 data-disabled:pointer-events-none"
+
+        element :checkbox_item, "cn-dropdown-menu-checkbox-item relative flex cursor-default items-center " \
+                                "outline-hidden select-none [&_svg]:pointer-events-none [&_svg]:shrink-0 " \
+                                "data-disabled:opacity-50 data-disabled:pointer-events-none"
+
+        element :radio_item, "cn-dropdown-menu-radio-item relative flex cursor-default items-center outline-hidden " \
+                             "select-none [&_svg]:pointer-events-none [&_svg]:shrink-0 data-disabled:opacity-50 " \
+                             "data-disabled:pointer-events-none"
+
+        element :label, "cn-dropdown-menu-label"
+
+        element :separator, "cn-dropdown-menu-separator"
+
+        element :shortcut, "cn-dropdown-menu-shortcut"
+
+        element :sub_trigger, "cn-dropdown-menu-sub-trigger flex cursor-default items-center outline-hidden " \
+                              "select-none [&_svg]:pointer-events-none [&_svg]:shrink-0 data-popup-open:bg-accent " \
+                              "data-popup-open:text-accent-foreground"
+
+        element :sub_content, "cn-dropdown-menu-sub-content z-50 origin-(--transform-origin) overflow-hidden w-auto"
+
+        # The indicator wrapper span, named dropdown-menu-item-indicator
+        # (the self-identification rule).
+        element :item_indicator, "cn-dropdown-menu-item-indicator pointer-events-none absolute " \
+                                 "flex items-center justify-center"
+
+        # The indicator stays in the DOM (never unmounted while
+        # unchecked); the parent item's data-checked/data-unchecked pair
+        # drives visibility, so the controller's aria-checked/data-checked
+        # flip is the whole toggle.
+        element :item_indicator_state, "[[data-unchecked]>&]:hidden"
+
+        # The source's inline lucide icon classes, named per part.
+        element :indicator_check, "size-4"
+        element :indicator_circle, "size-2 fill-current"
+        element :sub_indicator, "ml-auto size-4"
+      end
+    end
+  end
+end

data/app/components/poetry/ui/empty/component.html.erb

@@ -0,0 +1,10 @@
+<%= content_tag(:div, **root_attributes.to_attributes) do %>
+  <% if header? %>
+    <div data-slot="empty-header" class="<%= css(:header) %>">
+      <% if media? %><div data-slot="empty-icon" data-variant="<%= media_variant %>" class="<%= media_classes %>"><%= media %></div><% end %>
+      <% if title? %><%= content_tag(title_tag, title, "data-slot" => "empty-title", class: css(:title)) %><% end %>
+      <% if description? %><div data-slot="empty-description" class="<%= css(:description) %>"><%= description %></div><% end %>
+    </div>
+  <% end %>
+  <% if content.present? %><div data-slot="empty-content" class="<%= css(:content) %>"><%= content %></div><% end %>
+<% end %>

data/app/components/poetry/ui/empty/component.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Ui
+    # The Empty family - the empty-state block for collections with nothing in them.
+    module Empty
+      # The Empty state - what a collection shows when there is nothing in
+      # it: an optional media glyph, a title, a description, and the actions
+      # that fix the emptiness (the content block). Slots compose the header;
+      # the content block becomes empty-content.
+      #
+      # @example Empty collection with a next action
+      #   render Poetry::Ui::Empty::Component.new do |empty|
+      #     empty.with_title { "No projects yet" }
+      #     empty.with_description { "Create your first project to get started." }
+      #     poetry_button { "New project" }
+      #   end
+      class Component < Poetry::Core::Component
+        # Projected into the registry, llms.txt, and the agent surface.
+        AGENT_RULES = [
+          "An empty collection gets an Empty state with a next action - never a bare 'No results' div.",
+          "Compose with the slots (media/title/description); the actions are the content block.",
+          "The title renders as a real heading (h3 default) - set title_tag: to fit the page outline.",
+          "media_variant: :icon gives the rounded muted icon tile; wrap a poetry_icon in with_media."
+        ].freeze
+
+        renders_one :media, doc: "Optional leading visual above the title - an icon or illustration."
+        renders_one :title, doc: "The headline, rendered as a real heading (see title_tag)."
+        renders_one :description, doc: "Muted copy under the title."
+
+        option :title_tag, :symbol, default: :h3,
+                                    doc: "The title's heading level - a real heading element, so set it to fit the " \
+                                         "page outline."
+        option :media_variant, :symbol, default: :default,
+                                        doc: "The media slot's treatment; :icon gives the rounded muted icon tile."
+
+        validates :title_tag, inclusion: { in: %i[h1 h2 h3 h4 h5 h6] }
+        validates :media_variant, inclusion: { in: %i[default icon] }
+
+        part "empty", "The empty-state root - the centered header and content stack"
+        part "empty-header", "Wrapper around media/title/description - renders when at " \
+                             "least one of those slots is set"
+        part "empty-icon", "The media slot's box - media_variant: :icon gives the rounded " \
+                           "muted icon tile",
+             states: {
+               "data-variant" => { condition: "always - the resolved media_variant",
+                                   values: %w[default icon] }
+             }
+        part "empty-title", "The title as a real heading (title_tag, h3 by default)"
+        part "empty-description", "Muted copy under the title"
+        part "empty-content", "The actions that fix the emptiness - the content block " \
+                              "renders here"
+
+        # Whether the header wrapper renders (any of media/title/description set).
+        # @api private
+        def header?
+          media? || title? || description?
+        end
+
+        # The media box's classes for the resolved media_variant.
+        # @api private
+        def media_classes
+          variant = media_variant == :icon ? :media_icon : :media_default
+          "#{css(:media)} #{css(variant)}"
+        end
+
+        # The empty-state root's attributes.
+        # @api private
+        def root_attributes
+          html_attributes.merge_if_not_set(
+            { "data-slot" => "empty" }.merge(component_data_attributes)
+          )
+        end
+
+        private :header?, :media_classes, :root_attributes
+      end
+    end
+  end
+end

data/app/components/poetry/ui/empty/preview.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Ui
+    module Empty
+      # The Empty preview: the basic no-data state and the icon-tile
+      # variant with actions.
+      class Preview < Poetry::Core::Preview::Base
+        def default
+          render_component do |empty|
+            empty.with_title { "No projects yet" }
+            empty.with_description { "Get started by creating your first project." }
+          end
+        end
+
+        def with_icon_and_actions
+          render_component(media_variant: :icon) do |empty|
+            empty.with_media { embed(Poetry::Ui::Icon::Component.new(name: :folder)) }
+            empty.with_title { "No projects yet" }
+            empty.with_description { "Get started by creating your first project." }
+            embed(Poetry::Ui::Button::Component.new(size: :sm).with_content("Create project"))
+          end
+        end
+      end
+    end
+  end
+end

data/app/components/poetry/ui/empty/style.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Ui
+    module Empty
+      # Re-expressed through the cn-* theme layer. The title wears
+      # cn-font-heading (upstream parity): a no-op until a theme
+      # defines --font-heading - the sanctioned heading-font hook.
+      class Style < Poetry::Core::Style
+        base "cn-empty flex w-full min-w-0 flex-1 flex-col items-center justify-center " \
+             "text-center text-balance"
+
+        element :header, "cn-empty-header flex max-w-sm flex-col items-center"
+        # The media wrapper splits shared chrome from its two variants
+        # (default: transparent; icon: the rounded muted tile).
+        element :media, "cn-empty-media flex shrink-0 items-center justify-center " \
+                        "[&_svg]:pointer-events-none [&_svg]:shrink-0"
+        element :media_default, "cn-empty-media-default"
+        element :media_icon, "cn-empty-media-icon"
+        element :title, "cn-empty-title cn-font-heading"
+        element :description, "cn-empty-description text-muted-foreground [&>a]:underline " \
+                              "[&>a]:underline-offset-4 [&>a:hover]:text-primary"
+        element :content, "cn-empty-content flex w-full max-w-sm min-w-0 flex-col items-center text-balance"
+      end
+    end
+  end
+end

data/app/components/poetry/ui/family_identity.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Ui
+    # Gives an including component its family identity, derived from the
+    # namespace (Poetry::Ui::HoverCard::Component -> "HoverCard" /
+    # "hover-card"): the data-slot prefix, error nouns, and the sibling
+    # Style dictionary all resolve through it, so shared modules never
+    # hard-code a family name. Also supplies the root-shell attributes
+    # and the instance-id seed; a family with a different root or id
+    # shape simply overrides.
+    module FamilyIdentity
+      # The family root's data-slot, Stimulus, and self-identification
+      # attributes, merged under any caller-passed HTML attributes.
+      # @api private
+      def root_attributes
+        html_attributes.merge_if_not_set(
+          { "data-slot" => family_slot_prefix }
+            .merge(stimulus_attributes_for(:root))
+            .merge(component_data_attributes)
+        )
+      end
+
+      private
+
+      def family_namespace
+        self.class.module_parent
+      end
+
+      def family_name
+        @family_name ||= family_namespace.name.demodulize
+      end
+
+      def family_slot_prefix
+        @family_slot_prefix ||= family_name.underscore.dasherize
+      end
+
+      def family_style
+        family_namespace::Style
+      end
+
+      # Server-stable unique id seed (two of a family on one page must
+      # not share ids); portal-safe by convention - controllers resolve
+      # content via the id pair, never a Stimulus target.
+      def instance_id
+        @instance_id ||= poetry_instance_id("poetry-#{family_slot_prefix}")
+      end
+
+      private :root_attributes
+    end
+  end
+end

data/app/components/poetry/ui/field/component.html.erb

@@ -0,0 +1,19 @@
+<%= content_tag(:div, **root_attributes.to_attributes) do %>
+  <% if label_text.present? %>
+    <% if group %>
+      <%= render Poetry::Ui::Label::Component.new(for_id: nil, id: label_id, class: css(:label),
+                                                 data: { slot: "field-label" }).with_content(label_text) %>
+    <% else %>
+      <%= render Poetry::Ui::Label::Component.new(for_id: id, class: css(:label),
+                                                 data: { slot: "field-label" }).with_content(label_text) %>
+    <% end %>
+  <% end %>
+  <% hint_body = hint_block ? capture(&hint_block) : hint %>
+  <% hint_tag = capture do %>
+    <% if hint_present? %><p id="<%= hint_id %>" data-slot="field-description" class="<%= css(:hint) %>"><%= hint_body %></p><% end %>
+  <% end %>
+  <%= hint_tag if hint_position == :above %>
+  <%= content %>
+  <%= hint_tag if hint_position == :below %>
+  <% if error.present? %><p id="<%= error_id %>" data-slot="field-error" class="<%= css(:error) %>"><%= error %></p><% end %>
+<% end %>

data/app/components/poetry/ui/field/component.rb

@@ -0,0 +1,183 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Ui
+    # The Field family - the label/control/hint/error wrapper for one form control.
+    module Field
+      # The Field wrapper - label, control, hint, and error as one unit
+      # with the aria wiring done for you: the control (the content
+      # block) receives its id from the field, and control_attributes
+      # carries aria-invalid + aria-describedby pointing at the hint and
+      # error ids. The FormBuilder composes this from model truth; Field
+      # itself is model-agnostic.
+      #
+      # @example
+      #   render Poetry::Ui::Field::Component.new(
+      #     id: "email", label_text: "Email", hint: "We never share it."
+      #   ) do |field|
+      #     tag.input(type: "email", name: "email", **field.control_attributes)
+      #   end
+      class Component < Poetry::Core::Component
+        # The closed vocabulary for the orientation axis.
+        ORIENTATIONS = %i[vertical horizontal setting responsive].freeze
+
+        # The closed vocabulary for the hint_position axis.
+        HINT_POSITIONS = %i[below above].freeze
+
+        # Projected into the registry, llms.txt, and the agent surface.
+        AGENT_RULES = [
+          "Wire the control with field.control_attributes - never hand-write aria-describedby.",
+          "Error text arrives via error: (from model errors upstream) - never a bare red <p>.",
+          "hint: (escaped string) for pure data; with_hint { } for authored markup (links) - " \
+          "call it BEFORE the control so the hint id lands in aria-describedby.",
+          "orientation: :horizontal is the boolean-control layout (checkbox/switch left, " \
+          "label + hint stacked right) - text inputs and groups stay vertical.",
+          "orientation: :responsive stacks by default and flips label-left / control-right " \
+          "once its poetry_field_group container passes the md mark - the settings-page " \
+          "recipe (it needs that FieldGroup ancestor to measure against)."
+        ].freeze
+
+        style :orientation, default: :vertical, required: true, variants: ORIENTATIONS,
+                            doc: "The layout axis. :horizontal is the boolean-control pattern: the control lands in " \
+                                 "the first grid column, label + hint/error stack in the second, and the control " \
+                                 "row-centers against the label line."
+
+        option :id, :string, required: true, doc: "The control's DOM id - the hint/error/label ids derive from it."
+        option :label_text, :string, doc: "The visible label text, associated with the control via for=."
+        option :hint, :string,
+               doc: "Plain-text guidance under the control (escaped wholesale); use with_hint for authored markup."
+        option :hint_position, :symbol, default: :below,
+                                        doc: "Where the hint renders relative to the control - :above puts guidance " \
+                                             "before a tall control. aria-describedby is identical either way; this " \
+                                             "is visual order only."
+        option :error, :string,
+               doc: "The error line (typically from model errors) - presence flips the invalid skin and leads the " \
+                    "control's aria-describedby."
+        option :invalid, :boolean, default: false,
+                                   doc: "Flips the invalid skin (data-invalid + aria-invalid) WITHOUT an error line. " \
+                                        "error: implies it; use invalid: alone when the hint copy IS the " \
+                                        "requirement."
+        option :required, :boolean, default: false,
+                                    doc: "Marks the control required via aria-required only - never the native " \
+                                         "required attribute."
+        option :group, :boolean, default: false,
+                                 doc: "group: the control is a role-bearing <div> (RadioGroup, Slider) - label[for] " \
+                                      "would be inert (Chrome flags it), so the label drops for=, carries label_id, " \
+                                      "and control_attributes names the group via aria-labelledby (the visible " \
+                                      "label, i18n-proof)."
+
+        part "field", "The quartet's grid root - label, control, hint, and error stack inside",
+             states: {
+               "data-invalid" => { condition: "always - true when error: is present " \
+                                              "or invalid: is set, else false",
+                                   values: %w[true false] },
+               "data-orientation" => { condition: "always - the resolved orientation " \
+                                                  "(horizontal is the boolean-control layout)",
+                                       values: ORIENTATIONS.map(&:to_s) }
+             }
+        part "field-label", "The Label (composed) wearing the source's field-label slot - names the control"
+        part "field-description", "The hint <p> (the source's description) - its id lands in the control's " \
+                                  "aria-describedby"
+        part "field-error", "The error <p> - present only when error: is set; its id leads " \
+                            "the control's aria-describedby"
+        part "checkbox-input", "A nested Checkbox's hidden native input - the toggle renders " \
+                               "as a wrapper-free fragment, so its sibling form store sits " \
+                               "directly in the field's DOM (the horizontal boolean-control " \
+                               "layout)"
+        part "switch-input", "A nested Switch's hidden native input - the same wrapper-free " \
+                             "fragment escape as checkbox-input (the setting-row layout)"
+
+        # Validates hint_position and forces the content capture.
+        # @api private
+        def before_render
+          # Force the content block first: with_hint registers during the
+          # capture, and the template's hint tag must see it.
+          content
+
+          return if HINT_POSITIONS.include?(hint_position)
+
+          raise ArgumentError, "Field hint_position: #{hint_position.inspect} must be one of " \
+                               "#{HINT_POSITIONS.inspect}"
+        end
+
+        # The hint element's id (referenced from aria-describedby).
+        # @api private
+        def hint_id = "#{id}-hint"
+        # The error element's id (leads aria-describedby).
+        # @api private
+        def error_id = "#{id}-error"
+        # The label element's id (referenced from aria-labelledby when group:).
+        # @api private
+        def label_id = "#{id}-label"
+
+        # Block-form hint for authored markup - a link or emphasis inside
+        # the guidance. Call it BEFORE the control renders, so the hint id
+        # lands in the control's aria-describedby; conflicts with hint: -
+        # use one or the other. The captured buffer renders as-is and is
+        # never re-blessed: ERB-authored markup stays markup, every
+        # interpolated value escapes normally, and a plain-String return
+        # is escaped by capture. Untrusted data belongs in hint: (escaped
+        # wholesale) or inside <%= %> in the block - never pre-marked
+        # html_safe.
+        #
+        # @example A hint containing a link
+        #   <% field.with_hint do %>
+        #     Forgot it? <%= link_to "Reset your password", reset_path %>
+        #   <% end %>
+        def with_hint(&block)
+          raise ArgumentError, "Field with_hint conflicts with hint: - use one or the other" if hint.present?
+          if @control_attributes_issued
+            raise ArgumentError, "Field with_hint must be called before the control renders - " \
+                                 "control_attributes already handed out aria-describedby " \
+                                 "without the hint id"
+          end
+
+          @hint_block = block
+          self
+        end
+
+        # The captured hint block, consumed by the template.
+        # @api private
+        attr_reader :hint_block
+
+        # Whether any hint (string or block form) is present.
+        # @api private
+        def hint_present? = hint.present? || !@hint_block.nil?
+
+        # Whether the field wears the invalid skin (error: or invalid:).
+        # @api private
+        def invalid? = invalid || error.present?
+
+        # Everything the control inside the field must carry - the id,
+        # aria-describedby (error id first, then hint id), aria-invalid,
+        # aria-required, and aria-labelledby when group:. Merge it into
+        # the control's attributes (the FormBuilder does this for you).
+        def control_attributes
+          @control_attributes_issued = true
+          attrs = { "id" => id }
+          attrs["aria-labelledby"] = label_id if group && label_text.present?
+          describedby = []
+          describedby << error_id if error.present?
+          describedby << hint_id if hint_present?
+          attrs["aria-describedby"] = describedby.join(" ") if describedby.any?
+          attrs["aria-invalid"] = true if invalid?
+          # The aria-required-only rule: never the native required
+          # attribute - no native bubbles, no double announcement.
+          attrs["aria-required"] = true if required
+          attrs
+        end
+
+        # The quartet root's attributes.
+        # @api private
+        def root_attributes
+          html_attributes.merge_if_not_set(
+            { "data-slot" => "field", "data-invalid" => invalid?,
+              "data-orientation" => orientation }.merge(component_data_attributes)
+          )
+        end
+
+        private :hint_present?, :root_attributes
+      end
+    end
+  end
+end

data/app/components/poetry/ui/field/preview.html.erb

@@ -0,0 +1,30 @@
+<%# Shared template for every Field preview example: render the field with
+    a real Input wired through control_attributes - the canonical host
+    composition (see eval/arms/form_field/poetry.html.erb). group: wraps
+    the field in the FieldGroup @container scope responsive fields key on. %>
+<% field_markup = capture do %>
+  <%= render component do |field| %>
+    <% if local_assigns[:hint_link] %>
+      <% field.with_hint do %>Short and lowercase - see the <a class="underline underline-offset-4" href="/docs/naming">naming guide</a>.<% end %>
+    <% end %>
+    <% if local_assigns[:checkbox_options] %>
+      <%= render Poetry::Ui::Checkbox::Component.new(**checkbox_options,
+                                                     **field.control_attributes.transform_keys(&:to_sym)) %>
+    <% elsif local_assigns[:switch_options] %>
+      <%= render Poetry::Ui::Switch::Component.new(**switch_options,
+                                                   **field.control_attributes.transform_keys(&:to_sym)) %>
+    <% else %>
+      <%= render Poetry::Ui::Input::Component.new(**input_options,
+                                                  **field.control_attributes.transform_keys(&:to_sym)) %>
+    <% end %>
+  <% end %>
+<% end %>
+<div class="p-4">
+  <% if local_assigns[:group] %>
+    <%= render Poetry::Ui::FieldGroup::Component.new do %>
+      <%= field_markup %>
+    <% end %>
+  <% else %>
+    <%= field_markup %>
+  <% end %>
+</div>

data/app/components/poetry/ui/field/preview.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Ui
+    module Field
+      # The Field preview matrix - the label/control/hint/error quartet with
+      # the control wired through control_attributes (the aria plumbing the
+      # component exists to own). Rendering rides the sidecar preview.html.erb:
+      # nesting a control inside the field needs a real view context, and
+      # Preview#render inside a content block is the render_args DSL, not
+      # ActionView's render.
+      class Preview < Poetry::Core::Preview::Base
+        def default
+          render_with(component: Component.new(id: "field-email", label_text: "Email"),
+                      input_options: { type: "email", name: "email" })
+        end
+
+        def with_hint
+          render_with(component: Component.new(id: "field-handle", label_text: "Handle",
+                                               hint: "Public, letters and dashes only."),
+                      input_options: { name: "handle" })
+        end
+
+        def with_error
+          render_with(component: Component.new(id: "field-work-email", label_text: "Work email",
+                                               hint: "We never share it.", error: "can't be blank",
+                                               required: true),
+                      input_options: { type: "email", name: "work_email" })
+        end
+
+        # The block-form hint: ERB-authored markup (the link) rides the
+        # same cn-field-description skin and aria-describedby wiring as
+        # the hint: option.
+        def with_hint_link
+          render_with(component: Component.new(id: "field-workspace", label_text: "Workspace"),
+                      input_options: { name: "workspace" }, hint_link: true)
+        end
+
+        # The SETTING ROW: label + hint stacked left, control right and
+        # centered on the label line (upstream's content-first horizontal
+        # Field - the switch-description pattern).
+        def setting_with_switch
+          render_with(component: Component.new(id: "field-share", label_text: "Share across devices",
+                                               hint: "Focus is shared across devices, and turns " \
+                                                     "off when you leave the app.",
+                                               orientation: :setting),
+                      switch_options: { name: "share" })
+        end
+
+        # The container-driven layout: stacked by default, label-left /
+        # control-right once the FieldGroup container passes the md mark
+        # (the sidecar wraps this one in the FieldGroup @container scope).
+        def responsive
+          render_with(component: Component.new(id: "field-display-name", label_text: "Display name",
+                                               hint: "Shown on your public profile.",
+                                               orientation: :responsive),
+                      input_options: { name: "display_name" }, group: true)
+        end
+
+        # The boolean-control layout: control left, label + hint stacked
+        # right, box centered on the label line (the checkbox/switch field
+        # pattern upstream demos with orientation=horizontal).
+        def horizontal_with_checkbox
+          render_with(component: Component.new(id: "field-newsletter", label_text: "Email newsletter",
+                                               hint: "Sent weekly. Unsubscribe anytime.",
+                                               orientation: :horizontal),
+                      checkbox_options: { name: "newsletter", checked: true })
+        end
+      end
+    end
+  end
+end

data/app/components/poetry/ui/field/style.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Ui
+    module Field
+      # Re-expressed through the cn-* theme layer. Poetry's Field is
+      # its own small shape (grid + hint + error); the cn names borrow
+      # upstream's vocabulary where semantics align (:hint wears
+      # cn-field-description - the style hook tracks upstream naming, the
+      # data-slot stays poetry's).
+      class Style < Poetry::Core::Style
+        base "cn-field grid group/field w-full"
+
+        # The grid re-flow is structural and rides the dictionary like
+        # upstream's cva (control auto-places into column 1, label pins to
+        # column 2 row 1, hint/error stack under it - DOM stays label-first
+        # for the for= association); the COLUMN GAP is design and lives
+        # theme-side under the cn name. Vertical is the base state and
+        # emits nothing (the marker/core-X empty-variant precedent).
+        variant :orientation, {
+          vertical: "",
+          horizontal: "cn-field-orientation-horizontal grid-cols-[auto_1fr] items-center " \
+                      "[&>[data-slot=field-label]]:col-start-2 [&>[data-slot=field-label]]:row-start-1 " \
+                      "[&>[data-slot=field-description]]:col-start-2 [&>[data-slot=field-error]]:col-start-2",
+          # The SETTING ROW (label + hint left, control right - upstream's
+          # content-first horizontal Field): the horizontal treatment
+          # mirrored, control auto-places beside the label line.
+          setting: "cn-field-orientation-horizontal grid-cols-[1fr_auto] items-center " \
+                   "[&>[data-slot=field-label]]:col-start-1 [&>[data-slot=field-label]]:row-start-1 " \
+                   "[&>[data-slot=field-description]]:col-start-1 [&>[data-slot=field-error]]:col-start-1",
+          # Horizontal mirrored and container-gated: stacked below the
+          # FieldGroup's md mark; above it the label + hint pair stacks
+          # tight in column 1 (the theme narrows the row gap to its
+          # cn-field-content value via the marker class) and the control
+          # spans both rows in column 2, centered against the whole pair
+          # - upstream's FieldContent geometry, expressed on poetry's
+          # flat quartet DOM. Outside a @container/field-group scope the
+          # query never fires and the field stays vertical (upstream
+          # parity: "container-aware parents").
+          # rubocop:disable Layout/LineLength -- each line is one indivisible
+          # utility token, and Tailwind scans this literal source (an
+          # interpolated shared prefix would silently drop the CSS).
+          responsive: "cn-field-orientation-responsive " \
+                      "@md/field-group:grid-cols-[1fr_auto] " \
+                      "@md/field-group:[&>[data-slot=field-label]]:col-start-1 " \
+                      "@md/field-group:[&>[data-slot=field-label]]:row-start-1 " \
+                      "@md/field-group:[&>[data-slot=field-label]]:self-center " \
+                      "@md/field-group:[&>[data-slot=field-description]]:col-start-1 " \
+                      "@md/field-group:[&>[data-slot=field-error]]:col-start-1 " \
+                      "@md/field-group:[&>:not([data-slot=field-label],[data-slot=field-description],[data-slot=field-error])]:col-start-2 " \
+                      "@md/field-group:[&>:not([data-slot=field-label],[data-slot=field-description],[data-slot=field-error])]:row-start-1 " \
+                      "@md/field-group:[&>:not([data-slot=field-label],[data-slot=field-description],[data-slot=field-error])]:row-span-2 " \
+                      "@md/field-group:[&>:not([data-slot=field-label],[data-slot=field-description],[data-slot=field-error])]:self-center"
+          # rubocop:enable Layout/LineLength
+        }
+
+        # The Label wears the source's field-label slot and its structural
+        # tokens on top of its own (a composed Label, the outer's part).
+        element :label, "cn-field-label group/field-label peer/field-label flex w-fit items-center " \
+                        "has-[>[data-slot=field]]:w-full has-[>[data-slot=field]]:flex-col"
+        element :hint, "cn-field-description [&>a:hover]:text-primary [&>a]:underline " \
+                       "[&>a]:underline-offset-4 font-normal group-has-data-horizontal/field:text-balance " \
+                       "last:mt-0 leading-normal nth-last-2:-mt-1"
+        element :error, "cn-field-error font-normal"
+      end
+    end
+  end
+end