poetry-ui 0.0.2

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

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Ui
+    # A styled native <select>.
+    module NativeSelect
+      # A styled REAL <select> - platform picker, form submission, and
+      # mobile UX for free - with a decorative chevron replacing the
+      # native arrow. The fast path is options: pairs; compose
+      # <option>/<optgroup> in the content block for anything richer
+      # (poetry_native_select_option / _optgroup stamp the classes).
+      #
+      # @example The options: fast path
+      #   render Poetry::Ui::NativeSelect::Component.new(
+      #     name: "sort", label: "Sort by",
+      #     options: [["Newest first", "newest"], ["Oldest first", "oldest"]],
+      #     selected: "newest"
+      #   )
+      class Component < Poetry::Core::Component
+        # The closed vocabulary for the size axis.
+        SIZES = %i[default sm].freeze
+
+        # Projected into the registry, llms.txt, and the agent surface.
+        AGENT_RULES = [
+          "This is a REAL <select> - use it for plain picking; the JS Select is for styled options.",
+          "Pair it with a Label (for_id: its id) or a Field - a bare select has no accessible name.",
+          "The fast path is options: [[label, value], ...] + selected:; a content block overrides it."
+        ].freeze
+
+        option :name, :string, doc: "The submitted field name, forwarded to the native select."
+        option :id, :string, doc: "The select's dom id - the seam a Label's for_id: points at."
+        option :label, :string,
+               doc: "The accessible name for label-less placements (a visible Label paired via id:/for_id: is still " \
+                    "the default pattern)."
+        option :size, :symbol, default: :default, doc: "The control size axis; :sm suits dense toolbars and table rows."
+        option :disabled, :boolean, default: false, doc: "Disables the native select; the wrapper dims the whole pair."
+        option :invalid, :boolean, default: false, doc: "Marks the select invalid (aria-invalid on the element itself)."
+        option :described_by, :string,
+               doc: "Space-separated hint/error ids wired to the SELECT itself - a raw aria-describedby in " \
+                    "html_attributes would land on the wrapper div, unassociated for assistive technology."
+
+        validates :size, inclusion: { in: SIZES }
+
+        part "native-select-wrapper", "Relative shell around the select and the chevron - " \
+                                      "dims the pair when the select is disabled",
+             states: {
+               "data-size" => { condition: "always - the resolved size",
+                                values: SIZES.map(&:to_s) }
+             }
+        part "native-select", "The real <select> - appearance-none (the chevron replaces the " \
+                              "native arrow); platform picker and form submission stay native",
+             states: {
+               "data-size" => { condition: "always - the resolved size (mirrors the wrapper)",
+                                values: SIZES.map(&:to_s) }
+             }
+        part "native-select-icon", "The decorative chevron wrapper - absolutely pinned, " \
+                                   "aria-hidden"
+        part "native-select-option", "An <option> from the options: fast path (or " \
+                                     "poetry_native_select_option) - Canvas system colors " \
+                                     "keep the native dropdown legible"
+
+        # @api private
+        def call
+          content_tag(:div, wrapper_attributes.to_attributes) do
+            safe_join([select_element, chevron])
+          end
+        end
+
+        # @api private
+        def wrapper_attributes
+          html_attributes.merge_if_not_set(
+            {
+              "data-slot" => "native-select-wrapper", "data-size" => size
+            }.merge(component_data_attributes)
+          )
+        end
+
+        # @api private
+        def select_attributes
+          attrs = { "data-slot" => "native-select", "data-size" => size, "class" => css(:select) }
+          attrs["name"] = name if name.present?
+          attrs["id"] = id if id.present?
+          attrs["aria-label"] = label if label.present?
+          attrs["aria-describedby"] = described_by if described_by.present?
+          attrs["disabled"] = true if disabled
+          attrs["aria-invalid"] = true if invalid
+          attrs
+        end
+
+        private
+
+        # options: pairs are structural data, not a typed option.
+        def initialize(options: nil, selected: nil, **)
+          super(**)
+          @options = options
+          @selected = selected
+        end
+
+        def select_element
+          content_tag(:select, select_content, select_attributes)
+        end
+
+        def select_content
+          return content if content.present?
+
+          safe_join(Array(@options).map do |entry|
+            label, value = entry.is_a?(Array) ? entry : [entry, entry]
+            tag.option(label, value: value, selected: value.to_s == @selected.to_s || nil,
+                              "data-slot": "native-select-option", class: css(:option))
+          end)
+        end
+
+        # The chevron svg is the icon part itself (the source's shape) - the
+        # theme rule sizes and pins it; no wrapper span.
+        def chevron
+          render(Poetry::Ui::Icon::Component.new(name: :"chevron-down", class: css(:icon),
+                                                 data: { slot: "native-select-icon" }))
+        end
+
+        private :wrapper_attributes, :select_attributes
+      end
+    end
+  end
+end

data/app/components/poetry/ui/native_select/labelled_preview.html.erb

@@ -0,0 +1,7 @@
+<%# The labelled pair - a bare select has no accessible name. %>
+<div class="flex flex-col gap-2 p-4">
+  <%= poetry_label(for_id: "native-select-sort") { "Sort by" } %>
+  <%= poetry_native_select(name: "sort", id: "native-select-sort",
+                           options: [["Newest first", "newest"], ["Oldest first", "oldest"], ["Title", "title"]],
+                           selected: "newest") %>
+</div>

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

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Ui
+    module NativeSelect
+      # The NativeSelect preview: the labelled pair (its whole a11y
+      # contract), plus small/disabled states.
+      class Preview < Poetry::Core::Preview::Base
+        def default
+          render_with_template(template: "poetry/ui/native_select/labelled_preview")
+        end
+
+        def small_disabled
+          render_component(size: :sm, disabled: true, name: "plan", id: "native-select-plan",
+                           label: "Plan", options: %w[Starter Team], selected: "Team")
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Ui
+    module NativeSelect
+      # Re-expressed through the cn-* theme layer. appearance-none
+      # stays inline as a mechanism guard (a swapped theme must never
+      # resurrect the double native arrow); the wrapper and the
+      # option/optgroup Canvas system-color guards are structural, no cn
+      # names. The chevron wrapper keeps position mechanics inline.
+      class Style < Poetry::Core::Style
+        base "relative w-fit has-[select:disabled]:opacity-50 group/native-select"
+
+        element :select, "cn-native-select w-full appearance-none outline-none " \
+                         "disabled:pointer-events-none disabled:cursor-not-allowed"
+        element :icon, "cn-native-select-icon pointer-events-none absolute select-none"
+        element :option, "bg-[Canvas] text-[CanvasText]"
+        element :optgroup, "bg-[Canvas] text-[CanvasText]"
+      end
+    end
+  end
+end

data/app/components/poetry/ui/navigation_menu/bar_preview.html.erb

@@ -0,0 +1,14 @@
+<%# The site-nav bar: a trigger item with a link panel + plain links. %>
+<div class="flex min-h-64 justify-center p-4">
+  <%= poetry_navigation_menu(label: "Main") do |nav| %>
+    <% nav.with_item("Products", value: "products") do %>
+      <div class="grid w-64 gap-1">
+        <%= poetry_navigation_menu_link(href: "#", active: true) { "Analytics" } %>
+        <%= poetry_navigation_menu_link(href: "#") { "Automation" } %>
+        <%= poetry_navigation_menu_link(href: "#") { "Reports" } %>
+      </div>
+    <% end %>
+    <% nav.with_link("Pricing", href: "#") %>
+    <% nav.with_link("Docs", href: "#") %>
+  <% end %>
+</div>

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

@@ -0,0 +1,25 @@
+<%= content_tag(:nav, **root_attributes.to_attributes) do %>
+  <div data-slot="navigation-menu-list" class="<%= css(:list) %>">
+    <% entries.each do |entry| %>
+      <%= content_tag(:div, item_attributes(entry)) do %>
+        <% if entry.panel %>
+          <%= content_tag(:button, trigger_attributes(entry)) do %>
+            <%= entry.title %>
+            <%= render Poetry::Ui::Icon::Component.new(name: :"chevron-down",
+                                                       class: css(:chevron), "aria-hidden": "true") %>
+          <% end %>
+          <%= content_tag(:div, capture(&entry.panel), panel_attributes(entry)) %>
+        <% else %>
+          <a href="<%= entry.href %>" data-slot="navigation-menu-link" class="<%= css(:trigger) %>"><%= entry.title %></a>
+        <% end %>
+      <% end %>
+    <% end %>
+  </div>
+  <% if viewport %>
+    <%= content_tag(:div, positioner_attributes) do %>
+      <div data-slot="navigation-menu-popup" data-closed class="<%= css(:popup) %>">
+        <div data-slot="navigation-menu-viewport" class="<%= css(:viewport_shell) %>"></div>
+      </div>
+    <% end %>
+  <% end %>
+<% end %>

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

@@ -0,0 +1,254 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Ui
+    # A site-navigation bar with disclosure panels.
+    module NavigationMenu
+      # A site-navigation bar - a <nav> landmark, never a menu role:
+      # top-level links plus triggers whose panels of links open on
+      # hover or click beneath their items. It is a DISCLOSURE bar,
+      # so Tab moves through it normally and nothing traps focus.
+      #
+      # By default each panel opens under its own item. viewport: true
+      # switches to one shared card that morphs its size and position
+      # between triggers - the fit for rich title-and-description panel
+      # grids.
+      #
+      # @example Disclosure bar with a panel and a link
+      #   <%= poetry_navigation_menu(label: "Main") do |nav| %>
+      #     <% nav.with_item("Products", value: "products") do %>
+      #       <%= poetry_navigation_menu_link(href: products_path) { "All products" } %>
+      #     <% end %>
+      #     <% nav.with_link("Docs", href: docs_path) %>
+      #   <% end %>
+      class Component < Poetry::Core::Component
+        # Projected into the registry, llms.txt, and the agent surface.
+        AGENT_RULES = [
+          "label: is REQUIRED (the nav landmark's accessible name).",
+          "with_item(title, value:) declares a trigger + panel; with_link(title, href:) is a " \
+          "top-level destination - use links for pages, panels for groups of links.",
+          "Panel content is poetry_navigation_menu_link entries (active: marks the current page) - " \
+          "never buttons; navigation navigates.",
+          "This is a DISCLOSURE bar: Tab moves through it normally and nothing traps - do not " \
+          "wire menu/menuitem roles.",
+          "Rich panels (title + description grids) want viewport: true - the shared morphing " \
+          "card contains and sizes them; the default per-item mode suits simple link lists " \
+          "(the top-nav block shows the viewport pattern)."
+        ].freeze
+
+        # One declared bar entry - a link (href:) or a trigger + panel pair.
+        # @api private
+        Entry = Data.define(:title, :value, :href, :panel)
+
+        renders_many :items,
+                     doc: "The bar entries. with_item(title, value:) { panel } declares a trigger + panel; " \
+                          "with_item(title, href:) a top-level link (with_link is the shorthand).",
+                     renders: lambda { |title, value: nil, href: nil, &panel|
+                       if href.nil? && panel.nil?
+                         raise ArgumentError,
+                               "NavigationMenu item #{title.inspect} needs href: (a link) or a panel block"
+                       end
+
+                       entries << Entry.new(title: title, value: value&.to_s || title.to_s.parameterize, href: href,
+                                            panel: panel)
+                       nil
+                     }
+
+        use_stimulus do
+          on :root do
+            controller :navigation_menu do
+              register
+              action :keydown, on: :keydown
+              action :focus_left, on: :focusout
+            end
+            # The whole positioning engine is viewport-gated.
+            controller :popper, if: :viewport do
+              register
+              value :side, "bottom"
+              value :align, "start"
+              value :side_offset, 6
+              value :strategy, "absolute"
+            end
+          end
+          # Hover intent per panel-bearing item (the call site gates
+          # per-entry - plain links carry no wiring).
+          on :item do
+            controller :navigation_menu do
+              action :schedule_open, on: :pointerenter
+              action :schedule_close, on: :pointerleave
+            end
+          end
+          on :trigger do
+            controller(:navigation_menu) { action :toggle, on: :click }
+          end
+          # BOTH controllers on ONE element, declared together - the wiring
+          # merges through the Builder, never as two separate Attributes
+          # joined with plain Hash#merge (that drops one controller's
+          # tokens).
+          on :positioner do
+            controller(:popper) { target :content }
+            controller :navigation_menu do
+              action :cancel_close, on: :pointerenter
+              action :schedule_close, on: :pointerleave
+            end
+          end
+        end
+
+        option :label, :string, required: true,
+                                doc: "The nav landmark's accessible name - a page may hold more than one nav."
+        option :viewport, :boolean, default: false,
+                                    doc: "Opts into the shared morphing viewport: panels adopt into one positioned " \
+                                         "card that morphs size and position between triggers. Off, each panel opens " \
+                                         "under its own item (also the no-JS shape)."
+
+        part "navigation-menu", "The <nav> landmark around the whole disclosure bar",
+             states: {
+               "data-viewport" => "the mode marker (\"true\" = shared morphing viewport, \"false\" = " \
+                                  "per-item panels) - the dictionary's group-data chrome keys on it"
+             }
+        part "navigation-menu-list", "The bar row holding every item"
+        part "navigation-menu-item", "One bar entry - wraps a trigger + panel pair or a top-level link",
+             states: {
+               "data-value" => "the entry's value - the controller's open/close key"
+             }
+        part "navigation-menu-trigger", "The disclosure button opening its panel",
+             states: {
+               "data-popup-open" => "its panel is open (written with aria-expanded - the chevron " \
+                                    "rotation hook)",
+               "data-open" => "its panel is open (the controller writes both vocabularies)",
+               "data-closed" => "its panel is closed (written after the first close)"
+             }
+        part "navigation-menu-content", "One item's panel - presence-animated; in viewport mode it is " \
+                                        "adopted into the shared viewport on first activation",
+             states: {
+               "data-open" => "panel is open (presence flips the pair at runtime)",
+               "data-closed" => "panel is closed or animating out (the server-rendered state)",
+               "data-activation-direction" => "which way the activation traveled between triggers " \
+                                              "(left/right, viewport mode) - keys the slide styles",
+               "data-viewport-panel" => "stamped once the panel is adopted into the shared viewport"
+             }
+        part "navigation-menu-positioner", "The viewport-mode shell popper positions against the " \
+                                           "active trigger",
+             states: {
+               "data-instant" => "suppresses the morph transitions for one painted frame (cold opens)"
+             },
+             vars: {
+               "--positioner-width" => "the pinned morph width (reset to auto once the transition settles)",
+               "--positioner-height" => "the pinned morph height (reset to auto once the transition settles)"
+             }
+        part "navigation-menu-popup", "The morphing card inside the positioner - open state and the " \
+                                      "size transition ride here",
+             states: {
+               "data-open" => "a panel is showing (the controller flips the pair)",
+               "data-closed" => "the popup is closed (the server-rendered state)",
+               "data-instant" => "suppresses the morph transitions for one painted frame (cold opens)",
+               "data-starting-style" => "the enter transition's first frame (the presence module's " \
+                                        "two-frame trick)",
+               "data-ending-style" => "held through the exit transition before the popup hides"
+             },
+             vars: {
+               "--popup-width" => "the pinned morph width (reset to auto once the transition settles)",
+               "--popup-height" => "the pinned morph height (reset to auto once the transition settles)"
+             }
+        part "navigation-menu-viewport", "The adoption container inside the popup - adopted panels " \
+                                         "stack absolutely in it"
+        part "navigation-menu-link", "A REAL destination link - top-level (with_link) or a panel entry " \
+                                     "(poetry_navigation_menu_link)",
+             states: {
+               "data-active" => "the current page (active: true)"
+             }
+
+        # Enforces the required label and at least one entry.
+        # @api private
+        def before_render
+          raise ArgumentError, "NavigationMenu requires label: (the nav landmark's name)" if label.blank?
+          raise ArgumentError, "NavigationMenu requires at least one with_item or with_link" unless items?
+        end
+
+        # Declares a top-level destination link - shorthand for
+        # with_item(title, href:).
+        # @param title [String] the visible link text
+        # @param href [String] the destination URL
+        def with_link(title, href:)
+          with_item(title, href: href)
+        end
+
+        # The declared entries, in bar order.
+        # @api private
+        def entries
+          @entries ||= []
+        end
+
+        # @api private
+        def root_attributes
+          html_attributes.merge_if_not_set(
+            {
+              "aria-label" => label, "data-slot" => "navigation-menu",
+              # The mode marker the dictionary's group-data-[viewport=false]
+              # chrome keys on.
+              "data-viewport" => viewport.to_s
+            }.merge(stimulus_attributes_for(:root)).merge(component_data_attributes)
+          )
+        end
+
+        # @api private
+        def item_attributes(entry)
+          attrs = {
+            "data-slot" => "navigation-menu-item", "data-value" => entry.value,
+            "class" => css(:item)
+          }
+          attrs.merge!(stimulus_attributes_for(:item)) if entry.panel
+          attrs
+        end
+
+        # @api private
+        def trigger_attributes(entry)
+          {
+            "type" => "button", "data-slot" => "navigation-menu-trigger",
+            "aria-expanded" => "false", "aria-controls" => panel_id(entry),
+            "class" => "#{css(:trigger)} group"
+          }.merge(stimulus_attributes_for(:trigger))
+        end
+
+        # @api private
+        def panel_attributes(entry)
+          {
+            "id" => panel_id(entry), "data-slot" => "navigation-menu-content",
+            "data-closed" => "", "hidden" => true,
+            # Viewport mode: panels stack absolutely inside the shared viewport
+            # (adopted on first activation); per-item mode positions under the
+            # relative item.
+            "class" => "#{css(:content)} #{viewport ? css(:viewport_panel) : css(:content_position)}"
+          }
+        end
+
+        # The shared shell (viewport mode): the positioner is re-anchored
+        # against the ACTIVE trigger on each activation with the full
+        # positioning engine; the popup carries the morphing size vars;
+        # panels adopt into the viewport.
+        # @api private
+        def positioner_attributes
+          attrs = {
+            "data-slot" => "navigation-menu-positioner", "hidden" => true,
+            "class" => css(:positioner)
+          }
+          attrs.merge(stimulus_attributes_for(:positioner))
+        end
+
+        # @api private
+        def panel_id(entry)
+          "#{instance_id}-panel-#{entry.value}"
+        end
+
+        private
+
+        def instance_id
+          @instance_id ||= poetry_instance_id("poetry-nav")
+        end
+
+        private :entries, :root_attributes, :item_attributes, :trigger_attributes, :panel_attributes
+        private :positioner_attributes, :panel_id
+      end
+    end
+  end
+end

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

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Ui
+    module NavigationMenu
+      # The NavigationMenu preview: a bar with a panel item and plain links
+      # (the panel opens on hover/click - the dommy tier drives it; the
+      # sidecar template composes the panel's link grid).
+      class Preview < Poetry::Core::Preview::Base
+        def default
+          render_with_template(template: "poetry/ui/navigation_menu/bar_preview")
+        end
+
+        def viewport
+          render_with_template(template: "poetry/ui/navigation_menu/viewport_preview")
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Ui
+    module NavigationMenu
+      # Re-expressed through the cn-* theme layer. The morph
+      # machinery stays ENTIRELY inline (positioner insets + size-var
+      # transitions, panel adoption pins, activation-direction slides,
+      # data-instant suppressors) - a swapped theme restyles the popup
+      # surface, never the morph. The viewport=false chrome chain and the
+      # trigger/link treatments ride the theme.
+      class Style < Poetry::Core::Style
+        base "cn-navigation-menu group/navigation-menu relative flex max-w-max flex-1 items-center justify-center"
+
+        element :list, "cn-navigation-menu-list group flex flex-1 list-none items-center justify-center"
+        element :item, "relative"
+
+        element :trigger, "cn-navigation-menu-trigger group/navigation-menu-trigger inline-flex h-9 " \
+                          "w-max items-center justify-center outline-none " \
+                          "disabled:pointer-events-none disabled:opacity-50"
+        element :chevron, "cn-navigation-menu-trigger-icon relative top-px transition duration-300 " \
+                          "group-data-popup-open/navigation-menu-trigger:rotate-180 " \
+                          "group-data-open/navigation-menu-trigger:rotate-180"
+
+        # The activation-direction slides stay inline (authored as VALID
+        # Tailwind variants - upstream's own strings are malformed and
+        # compile to nothing): content slides
+        # in FROM the travel direction and out the other way.
+        # h-full is the VIEWPORT-mode contract (the panel fills the
+        # morphing popup box); inline panels size to their content - an
+        # unscoped h-full clamps them to the 36px list item and the
+        # popover chrome paints short of the rows.
+        element :content,
+                "cn-navigation-menu-content w-auto " \
+                "group-data-[viewport=true]/navigation-menu:h-full " \
+                "transition-[opacity,transform,translate] duration-[0.35s] " \
+                "ease-[cubic-bezier(0.22,1,0.36,1)] " \
+                "group-data-[viewport=false]/navigation-menu:duration-300 " \
+                "data-ending-style:opacity-0 data-starting-style:opacity-0 " \
+                "data-[activation-direction=right]:data-starting-style:translate-x-1/2 " \
+                "data-[activation-direction=left]:data-starting-style:-translate-x-1/2 " \
+                "data-[activation-direction=right]:data-ending-style:-translate-x-1/2 " \
+                "data-[activation-direction=left]:data-ending-style:translate-x-1/2 " \
+                "**:data-[slot=navigation-menu-link]:focus:ring-0 " \
+                "**:data-[slot=navigation-menu-link]:focus:outline-none"
+        element :content_position, "absolute top-full left-0 isolate z-50 mt-1.5 w-max min-w-48"
+
+        # The morphing shared viewport: the popper writes the positioner's
+        # insets (CSS transitions them - the position morph); the popup pins
+        # --popup-width/height old -> new so size transitions; panels stack
+        # absolutely inside the viewport and size intrinsically. data-instant
+        # (cold opens) suppresses both transitions for a frame.
+        element :positioner, "absolute isolate z-50 w-(--positioner-width) h-(--positioner-height) " \
+                             "transition-[top,left,right,bottom] duration-[0.35s] " \
+                             "ease-[cubic-bezier(0.22,1,0.36,1)] data-instant:transition-none"
+        element :popup, "cn-navigation-menu-popup relative h-(--popup-height) w-(--popup-width) " \
+                        "overflow-hidden transition-[width,height] duration-[0.35s] " \
+                        "ease-[cubic-bezier(0.22,1,0.36,1)] data-instant:transition-none"
+        # The ACTIVE panel sits in flow - after the settle reset returns the
+        # size vars to auto, IT is what sizes the popup (all-absolute panels
+        # would collapse the auto popup to 0x0). Only an EXITING panel lifts
+        # out of flow (data-ending-style rides the whole exit), overlaying
+        # the incoming one while both are visible - the crossfade, done
+        # declaratively.
+        element :viewport_shell, "relative overflow-hidden"
+        element :viewport_panel, "w-max min-w-48 data-ending-style:absolute " \
+                                 "data-ending-style:top-0 data-ending-style:left-0"
+
+        element :link, "cn-navigation-menu-link flex items-center outline-none"
+      end
+    end
+  end
+end

data/app/components/poetry/ui/navigation_menu/viewport_preview.html.erb

@@ -0,0 +1,23 @@
+<%# The morphing shared viewport: two panel items - switching between
+    them morphs the shared popup's size and position; panels slide by
+    activation direction. %>
+<div class="flex min-h-72 justify-center p-4">
+  <%= poetry_navigation_menu(label: "Main", viewport: true) do |nav| %>
+    <% nav.with_item("Products", value: "products") do %>
+      <div class="grid w-64 gap-1">
+        <%= poetry_navigation_menu_link(href: "#", active: true) { "Analytics" } %>
+        <%= poetry_navigation_menu_link(href: "#") { "Automation" } %>
+        <%= poetry_navigation_menu_link(href: "#") { "Reports" } %>
+      </div>
+    <% end %>
+    <% nav.with_item("Company", value: "company") do %>
+      <div class="grid w-96 grid-cols-2 gap-1">
+        <%= poetry_navigation_menu_link(href: "#") { "About" } %>
+        <%= poetry_navigation_menu_link(href: "#") { "Careers" } %>
+        <%= poetry_navigation_menu_link(href: "#") { "Press" } %>
+        <%= poetry_navigation_menu_link(href: "#") { "Contact" } %>
+      </div>
+    <% end %>
+    <% nav.with_link("Docs", href: "#") %>
+  <% end %>
+</div>

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

@@ -0,0 +1,19 @@
+<%# Two-input architecture (Base UI): the group holds the formatted
+    visible text input between two stepper addons; the hidden number
+    input beside it is the form/validation truth. %>
+<%= content_tag(:div, **root_attributes.to_attributes) do %>
+  <%= content_tag(:div, **Poetry::Core::HTML::Attributes.new(group_attributes).to_attributes) do %>
+    <%= content_tag(:div, **Poetry::Core::HTML::Attributes.new(addon_attributes(:start)).to_attributes) do %>
+      <%= render stepper(:decrement) do %>
+        <%= render Poetry::Ui::Icon::Component.new(name: stepper_icon(:decrement)) %>
+      <% end %>
+    <% end %>
+    <%= tag.input(**input_attributes.to_attributes) %>
+    <%= content_tag(:div, **Poetry::Core::HTML::Attributes.new(addon_attributes(:end)).to_attributes) do %>
+      <%= render stepper(:increment) do %>
+        <%= render Poetry::Ui::Icon::Component.new(name: stepper_icon(:increment)) %>
+      <% end %>
+    <% end %>
+  <% end %>
+  <%= tag.input(**hidden_attributes.to_attributes) %>
+<% end %>