poetry-ui 0.0.2

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

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Ui
+    module Resizable
+      # The Resizable preview: the two-pane split (with the grip) and a
+      # nested two-axis layout.
+      class Preview < Poetry::Core::Preview::Base
+        def default
+          render_component(grip: true, class: "h-48 max-w-md rounded-lg border") do |group|
+            group.with_panel(default_size: 25, min_size: 15) do
+              tag.div("Sidebar", class: "flex h-full items-center justify-center p-6 text-sm")
+            end
+            group.with_panel do
+              tag.div("Content", class: "flex h-full items-center justify-center p-6 text-sm")
+            end
+          end
+        end
+
+        def nested
+          render_component(class: "h-48 max-w-md rounded-lg border") do |group|
+            group.with_panel(default_size: 40) do
+              tag.div("Left", class: "flex h-full items-center justify-center p-6 text-sm")
+            end
+            group.with_panel do
+              embed(nested_group)
+            end
+          end
+        end
+
+        private
+
+        def nested_group
+          Poetry::Ui::Resizable::Component.new(direction: :vertical).tap do |group|
+            group.with_panel { tag.div("Top", class: "flex h-full items-center justify-center p-6 text-sm") }
+            group.with_panel { tag.div("Bottom", class: "flex h-full items-center justify-center p-6 text-sm") }
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Ui
+    module Resizable
+      # Style dictionary for the Resizable family. The GROUP's layout keys
+      # off data-orientation - aria-orientation is not permitted on a
+      # plain group container (an axe aria-allowed-attr violation). The
+      # handle keeps aria-[orientation] selectors (valid on
+      # role=separator).
+      class Style < Poetry::Core::Style
+        base "flex h-full w-full data-[orientation=vertical]:flex-col"
+
+        element :panel, "overflow-hidden"
+
+        element :handle, "relative flex w-px touch-none items-center justify-center bg-border " \
+                         "cursor-col-resize aria-[orientation=horizontal]:cursor-row-resize " \
+                         "ring-offset-background after:absolute after:inset-y-0 after:left-1/2 " \
+                         "after:w-1 after:-translate-x-1/2 focus-visible:ring-1 focus-visible:ring-ring " \
+                         "focus-visible:outline-hidden aria-[orientation=horizontal]:h-px " \
+                         "aria-[orientation=horizontal]:w-full aria-[orientation=horizontal]:after:left-0 " \
+                         "aria-[orientation=horizontal]:after:h-1 aria-[orientation=horizontal]:after:w-full " \
+                         "aria-[orientation=horizontal]:after:translate-x-0 " \
+                         "aria-[orientation=horizontal]:after:-translate-y-1/2 " \
+                         "[&[aria-orientation=horizontal]>div]:rotate-90"
+        element :grip, "cn-resizable-handle-icon z-10 flex shrink-0"
+      end
+    end
+  end
+end

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

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Ui
+    # A bounded scroll region with themed scrollbars.
+    module ScrollArea
+      # A bounded, keyboard-reachable scroll region with themed
+      # scrollbars. Reach for it when content should scroll inside a fixed
+      # height or width. Deliberately NATIVE: scrollbar-width and
+      # scrollbar-color are Baseline CSS, so the platform's own scrollbars
+      # are styled and zero JS ships - scrolling, momentum, and keyboard
+      # support come from the browser.
+      #
+      # The viewport is focusable (tabindex=0) - a scrollable region a
+      # keyboard can't reach fails WCAG (the axe scrollable-region-focusable
+      # rule); label: names it (role=region + aria-label) and is required.
+      #
+      # @example A bounded list that scrolls
+      #   render Poetry::Ui::ScrollArea::Component.new(label: "Tags", class: "h-72 w-48") do
+      #     safe_join(tags.map { |tag| tag.name })
+      #   end
+      class Component < Poetry::Core::Component
+        requires_content "what scrolls"
+
+        # Projected into the registry, llms.txt, and the agent surface.
+        AGENT_RULES = [
+          "Size the scroll area with classes (h-72 w-48, max-h-96) - content decides the overflow.",
+          "label: is REQUIRED - the viewport is focusable, and a focusable region needs a name " \
+          "(role=region + aria-label).",
+          "This is a NATIVE scroll surface - never bolt scroll JS onto it; " \
+          "use MessageScroller for chat transcripts."
+        ].freeze
+
+        option :label, :string, required: true,
+                                doc: "The region's accessible name (role=region + aria-label) - required, because a " \
+                                     "focusable region must be named."
+
+        part "scroll-area", "The bounding wrapper - size it with classes; content decides the overflow"
+        part "scroll-area-viewport", "The focusable native scroll region (role=region + tabindex=0) " \
+                                     "with themed platform scrollbars - zero JS"
+
+        # @api private
+        def before_render
+          raise ArgumentError, "ScrollArea requires label: (the region's accessible name)" if label.blank?
+
+          ensure_content!
+        end
+
+        # @api private
+        def call
+          content_tag(:div, root_attributes.to_attributes) do
+            content_tag(:div, content, viewport_attributes)
+          end
+        end
+
+        # @api private
+        def root_attributes
+          html_attributes.merge_if_not_set(
+            { "data-slot" => "scroll-area" }.merge(component_data_attributes)
+          )
+        end
+
+        # @api private
+        def viewport_attributes
+          {
+            "data-slot" => "scroll-area-viewport", "tabindex" => "0",
+            "role" => "region", "aria-label" => label,
+            "class" => css(:viewport)
+          }
+        end
+
+        private :root_attributes, :viewport_attributes
+      end
+    end
+  end
+end

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

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Ui
+    module ScrollArea
+      # The ScrollArea preview: a vertical tag list and a horizontal strip -
+      # both overflow so the themed native scrollbars actually show.
+      class Preview < Poetry::Core::Preview::Base
+        def default
+          render_component(label: "Tags", class: "h-72 w-48 rounded-md border") do
+            tag.div(class: "p-4") do
+              safe_join([
+                          tag.h4("Tags", class: "mb-4 text-sm leading-none font-medium"),
+                          *(1..30).map do |n|
+                            tag.div("v1.2.0-beta.#{n}", class: "border-b py-2 text-sm last:border-0")
+                          end
+                        ])
+            end
+          end
+        end
+
+        def horizontal
+          render_component(label: "Artwork strip", class: "w-96 rounded-md border") do
+            tag.div(class: "flex w-max gap-4 p-4") do
+              safe_join((1..8).map do |n|
+                tag.div("Artwork #{n}",
+                        class: "flex h-32 w-40 shrink-0 items-center justify-center rounded-md bg-muted text-sm")
+              end)
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Ui
+    module ScrollArea
+      # Style dictionary for the ScrollArea family: overflow-auto +
+      # scrollbar-width/scrollbar-color (Baseline CSS) style the native
+      # scrollbars, so no scrollbar/thumb part dictionaries exist.
+      class Style < Poetry::Core::Style
+        base "relative"
+
+        element :viewport, "size-full rounded-[inherit] transition-[color,box-shadow] outline-none " \
+                           "focus-visible:ring-[3px] focus-visible:ring-ring/50 focus-visible:outline-1 " \
+                           "overflow-auto [scrollbar-width:thin] " \
+                           "[scrollbar-color:var(--color-border)_transparent]"
+      end
+    end
+  end
+end

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

@@ -0,0 +1,15 @@
+<%# InputGroup anatomy: leading search glyph, the type=search control,
+    trailing clear affordance (hidden while empty). %>
+<%= 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 Poetry::Ui::Icon::Component.new(name: :search) %>
+    <% end %>
+    <%= tag.input(**input_attributes.to_attributes) %>
+    <%= content_tag(:div, **Poetry::Core::HTML::Attributes.new(addon_attributes(:end)).to_attributes) do %>
+      <%= render clear_button do %>
+        <%= render Poetry::Ui::Icon::Component.new(name: :x) %>
+      <% end %>
+    <% end %>
+  <% end %>
+<% end %>

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

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Ui
+    # A search input with a leading glyph and a clear affordance.
+    module SearchField
+      # A type=search input on the bordered group chrome - leading search
+      # glyph, trailing clear affordance. Escape CLEARS a non-empty field
+      # and is consumed (the NEXT press reaches the dismissal layer), an
+      # empty field lets it propagate; the clear button never steals focus
+      # (mobile keyboards stay up) and is not a tab stop - keyboard users
+      # already have Escape. Enter is never intercepted: native form
+      # submission is the Rails path. The native WebKit cancel affordance
+      # is suppressed so the clear button is the only one.
+      #
+      # @example
+      #   render Poetry::Ui::SearchField::Component.new(name: "q", label: "Search", placeholder: "Search...")
+      class Component < Poetry::Core::Component
+        include Poetry::Ui::InputGroupField
+
+        # Projected into the registry, llms.txt, and the agent surface.
+        AGENT_RULES = [
+          "Search inputs are a SearchField (poetry_search_field) - never a bare Input with a " \
+          "hand-rolled clear button; Escape-clears and focus retention ride the controller.",
+          "Enter submits the surrounding form natively - wrap it in a form/turbo-frame for " \
+          "live search; listen for poetry:search-field:clear to reset results.",
+          "Pair with a Label/Field for the accessible name, or pass label: standalone."
+        ].freeze
+
+        use_stimulus do
+          on :root do
+            controller(:search_field) { register }
+          end
+          on :input do
+            controller :search_field do
+              target :input
+              action :changed, on: :input
+              action :keydown, on: :keydown
+            end
+          end
+          # The clear affordance holds focus through pointerdown (never a
+          # tab stop) and clears on click.
+          on :clear do
+            controller :search_field do
+              target :clear
+              action :holdFocus, on: :pointerdown
+              action :clear, on: :click
+            end
+          end
+        end
+
+        option :name, :string, required: true, doc: "The form field name on the search input."
+        option :value, :string, doc: "The pre-filled query; presence unhides the clear affordance."
+        option :placeholder, :string, doc: "Hint text shown while the field is empty."
+        option :id, :string, doc: "The input's DOM id - what a Field label's for: must reference."
+        option :label, :string,
+               doc: "The accessible name (aria-label) for standalone use - or pair with a Label/Field instead."
+        option :described_by, :string, doc: "aria-describedby on the input - Field hint/error wiring."
+        option :disabled, :boolean, default: false, doc: "Disables the input and hides the clear affordance."
+        option :readonly, :boolean, default: false,
+                                    doc: "The query can be read but not edited; the clear affordance hides."
+        option :required, :boolean, default: false, doc: "Marks the input required for native constraint validation."
+        option :invalid, :boolean, default: false,
+                                   doc: "aria-invalid on the input - set by Field/FormBuilder from model errors."
+
+        part "search-field", "Root - the controller and the emptiness state ride here",
+             states: {
+               "data-empty" => "the input holds no text (server-set, controller-kept; hides " \
+                               "the clear affordance)"
+             }
+        part "input-group-addon", "The leading search-glyph cell - InputGroup's addon " \
+                                  "vocabulary (the NumberField precedent)",
+             states: {
+               "data-align" => { condition: "always - inline-start holds the glyph, " \
+                                            "inline-end the clear button",
+                                 values: %w[inline-start inline-end] }
+             }
+        part "search-field-group", "The bordered field surface - InputGroup's chrome, focus " \
+                                   "ring keyed on the control inside"
+        part "input-group-control", "The native <input type=search> - InputGroup's control " \
+                                    "slot (the themes' focus-ring hook); WebKit's own cancel " \
+                                    "affordance suppressed"
+        # The clear affordance renders as a composed ghost Button carrying
+        # data-slot=search-field-clear on Button's root - part ownership
+        # attributes it to Button, so it is documented here in prose only:
+        # tabindex -1 (Escape is the keyboard path), hidden while empty,
+        # never steals focus.
+
+        # @api private
+        def root_attributes
+          attrs = {
+            "data-slot" => "search-field",
+            "class" => css
+          }.merge(component_data_attributes)
+          attrs["data-empty"] = "" if value.blank?
+          html_attributes.merge_if_not_set(attrs.merge(stimulus_attributes_for(:root)))
+        end
+
+        # @api private
+        def input_attributes
+          attrs = Poetry::Core::HTML::Attributes.new(
+            "type" => "search",
+            "name" => name,
+            "id" => control_id,
+            "data-slot" => "input-group-control",
+            "class" => "#{Input::Style.css(class: InputGroup::Style.css(:control_input))} #{css(:input)}",
+            "autocomplete" => "off",
+            "autocorrect" => "off",
+            "spellcheck" => "false"
+          )
+          attrs["value"] = value if value.present?
+          attrs["placeholder"] = placeholder if placeholder.present?
+          attrs["aria-label"] = label if label.present?
+          attrs["aria-invalid"] = "true" if invalid && !disabled
+          attrs["aria-describedby"] = described_by if described_by.present?
+          attrs["disabled"] = "" if disabled
+          attrs["readonly"] = "" if readonly
+          attrs["required"] = "" if required
+          attrs.merge!(stimulus_attributes_for(:input))
+          attrs
+        end
+
+        # The clear affordance: a ghost icon Button that is NEVER a tab
+        # stop and never steals focus.
+        # @api private
+        def clear_button
+          group_tool_button(slot: "search-field-clear",
+                            label: t("poetry.search_field.clear"),
+                            extra: { "hidden" => value.blank? || readonly || disabled ? "" : nil },
+                            wiring: stimulus_attributes_for(:clear))
+        end
+
+        private :root_attributes, :input_attributes, :clear_button
+      end
+    end
+  end
+end

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

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Ui
+    module SearchField
+      class Preview < Poetry::Core::Preview::Base
+        def default
+          render_component(name: "q", label: "Search", placeholder: "Search…")
+        end
+
+        # Non-empty: the clear affordance shows; Escape clears once, the
+        # next Escape reaches the dismissal layer.
+        def with_value
+          render_component(name: "q", label: "Search", value: "design tokens")
+        end
+
+        def disabled
+          render_component(name: "q", label: "Search", value: "locked", disabled: true)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Ui
+    module SearchField
+      # Utility-only: InputGroup + Input wear the chrome (the NumberField
+      # composition - zero new theme CSS). The input element only
+      # suppresses WebKit's native search affordances so poetry's clear
+      # button is the single clear path.
+      class Style < Poetry::Core::Style
+        base "flex w-full flex-col"
+
+        element :input, "[&::-webkit-search-cancel-button]:hidden " \
+                        "[&::-webkit-search-decoration]:hidden"
+      end
+    end
+  end
+end

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

@@ -0,0 +1,15 @@
+<%# The option union renders FIRST (into a capture) so the shared
+    OptionSet is populated before the native <select> and the trigger's
+    value display derive from it - one server-side truth, three surfaces. %>
+<% listbox_body = capture do %>
+  <% items.each do |item| %><%= item %><% end %>
+<% end %>
+<%= content_tag(:div, **root_attributes.to_attributes) do %>
+  <%= native_select %>
+  <%= trigger_button %>
+  <%= content_tag(:div, **Poetry::Core::HTML::Attributes.new(content_attributes).to_attributes) do %>
+    <%= scroll_button(:up) %>
+    <%= content_tag(:div, listbox_body, viewport_attributes) %>
+    <%= scroll_button(:down) %>
+  <% end %>
+<% end %>