poetry-ui 0.0.2

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

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Ui
+    # The Item family - the generic list row.
+    module Item
+      # The Item - the generic list row (Empty's sibling): media, a
+      # title/description content column, and trailing actions, with
+      # variant (default/outline/muted) and density (default/sm/xs).
+      # Rows stack inside poetry_item_group (role=list) separated by
+      # poetry_item_separator. Renders as a div by default; pass tag: :a
+      # (+ href via passthrough) for a fully-clickable row.
+      #
+      # @example
+      #   render Poetry::Ui::Item::Component.new(variant: :outline) do |item|
+      #     item.with_title { "Backups" }
+      #     item.with_description { "Nightly, retained 30 days" }
+      #   end
+      class Component < Poetry::Core::Component
+        # The closed vocabulary for the variant axis.
+        VARIANTS = %i[default outline muted].freeze
+        # The closed vocabulary for the size (density) axis.
+        SIZES = %i[default sm xs].freeze
+        # The closed vocabulary for the media_variant axis.
+        MEDIA_VARIANTS = %i[default icon image].freeze
+
+        # Projected into the registry, llms.txt, and the agent surface.
+        AGENT_RULES = [
+          "Rows live inside poetry_item_group (role=list) and each row passes role: \"listitem\" - " \
+          "a role=list parent with roleless children fails aria-required-children.",
+          "Separate grouped rows with poetry_item_separator.",
+          "Compose with the slots (media/title/description/actions); loose content lands in the " \
+          "content column after the description.",
+          "media_variant: :icon for a glyph, :image for a thumbnail (sized/rounded automatically).",
+          "A clickable row is tag: :a with href: - never wrap an Item in a bare <a>."
+        ].freeze
+
+        renders_one :media, doc: "The leading media cell - a glyph or thumbnail (see media_variant)."
+        renders_one :title, doc: "The title row."
+        renders_one :description, doc: "The muted description line (clamps to two lines)."
+        renders_one :actions, doc: "The trailing actions cell - buttons, a menu, a switch."
+        renders_one :header, doc: "Full-width row above the media/content columns."
+        renders_one :footer, doc: "Full-width row below the media/content columns."
+
+        style :variant, default: :default, required: true, variants: VARIANTS,
+                        doc: "The row's visual treatment - :outline boxes it, :muted recedes."
+        style :size, default: :default, required: true, variants: SIZES, doc: "The row's density."
+
+        option :tag, :symbol, default: :div,
+                              doc: "The root element - tag: :a (href via passthrough) makes the whole row clickable."
+        option :media_variant, :symbol, default: :default,
+                                        doc: "The media treatment - :icon for a glyph, :image for a thumbnail."
+
+        validates :media_variant, inclusion: { in: MEDIA_VARIANTS }
+
+        part "item", "The row root (a div by default; tag: :a for a clickable row) - variant and " \
+                     "density land here as data attributes",
+             states: {
+               "data-variant" => { condition: "the row's visual variant", values: VARIANTS.map(&:to_s) },
+               "data-size" => { condition: "the row's density", values: SIZES.map(&:to_s) }
+             }
+        part "item-media", "The leading media cell - sized and rounded by its variant",
+             states: {
+               "data-variant" => { condition: "the media treatment", values: MEDIA_VARIANTS.map(&:to_s) }
+             }
+        part "item-content", "The center column collecting title, description, and loose content"
+        part "item-title", "The title row"
+        part "item-description", "The muted description line"
+        part "item-header", "Full-width row above the media/content columns"
+        part "item-actions", "The trailing actions cell"
+        part "item-footer", "Full-width row below the media/content columns"
+
+        # Whether the center column renders (title, description, or loose content).
+        # @api private
+        def content_column?
+          title? || description? || content.present?
+        end
+
+        # The media cell's classes for the resolved media_variant.
+        # @api private
+        def media_classes
+          "#{css(:media)} #{css(:"media_#{media_variant}")}".strip
+        end
+
+        # The row root's attributes.
+        # @api private
+        def root_attributes
+          html_attributes.merge_if_not_set(
+            {
+              "data-slot" => "item", "data-variant" => variant, "data-size" => size
+            }.merge(component_data_attributes)
+          )
+        end
+
+        private :content_column?, :media_classes, :root_attributes
+      end
+    end
+  end
+end

data/app/components/poetry/ui/item/group_preview.html.erb

@@ -0,0 +1,15 @@
+<%# A grouped list: rows in poetry_item_group (role=list) - each row wears
+    role=listitem (upstream omits it and fails aria-required-children). %>
+<div class="p-4">
+  <%= poetry_item_group do %>
+    <%= poetry_item(variant: :muted, size: :sm, role: "listitem") do |item| %>
+      <% item.with_title { "Invoices synced" } %>
+      <% item.with_description { "All invoices are up to date." } %>
+    <% end %>
+    <%= poetry_item_separator %>
+    <%= poetry_item(size: :sm, role: "listitem") do |item| %>
+      <% item.with_title { "Payment pending" } %>
+      <% item.with_description { "One transfer awaits confirmation." } %>
+    <% end %>
+  <% end %>
+</div>

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

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Ui
+    module Item
+      # The Item preview: a basic row, an outline row with an icon and
+      # actions, and the grouped list via the sidecar template.
+      class Preview < Poetry::Core::Preview::Base
+        def default
+          render_component do |item|
+            item.with_title { "Basic Item" }
+            item.with_description { "A simple item with title and description." }
+          end
+        end
+
+        # The full-width header/footer rows around the columns.
+        def with_header_and_footer
+          render_component do |item|
+            item.with_header { "Pinned" }
+            item.with_title { "Framed Item" }
+            item.with_description { "Header above, footer below." }
+            item.with_footer { "Updated 2 hours ago" }
+          end
+        end
+
+        def outline_with_icon_and_actions
+          render_component(variant: :outline, media_variant: :icon) do |item|
+            item.with_media { embed(Poetry::Ui::Icon::Component.new(name: :"badge-check")) }
+            item.with_title { "Your profile has been verified." }
+            item.with_actions do
+              embed(Poetry::Ui::Button::Component.new(size: :sm, variant: :outline).with_content("View"))
+            end
+          end
+        end
+
+        # The tightest row (sm lives in the group template below).
+        def size_xs
+          render_component(size: :xs) do |item|
+            item.with_title { "Cache cleared" }
+            item.with_description { "2 minutes ago" }
+          end
+        end
+
+        def group
+          # An explicit per-example template (a class-level preview.html.erb
+          # would shadow every other example - see Avatar's group note).
+          render_with_template(template: "poetry/ui/item/group_preview")
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Ui
+    module Item
+      # Re-expressed through the cn-* theme layer. The media variants
+      # use upstream's cn-item-media-variant-* names. Upstream's unused
+      # group/item-group marker stays dropped (the compiled-CSS gate).
+      class Style < Poetry::Core::Style
+        base "cn-item group/item flex w-full flex-wrap items-center transition-colors " \
+             "duration-100 outline-none focus-visible:border-ring focus-visible:ring-[3px] " \
+             "focus-visible:ring-ring/50 [a]:transition-colors"
+
+        variant :variant, {
+          default: "cn-item-variant-default",
+          outline: "cn-item-variant-outline",
+          muted: "cn-item-variant-muted"
+        }
+
+        variant :size, {
+          default: "cn-item-size-default",
+          sm: "cn-item-size-sm",
+          xs: "cn-item-size-xs"
+        }
+
+        element :media, "cn-item-media flex shrink-0 items-center justify-center " \
+                        "[&_svg]:pointer-events-none"
+        element :media_default, "cn-item-media-variant-default"
+        element :media_icon, "cn-item-media-variant-icon"
+        element :media_image, "cn-item-media-variant-image"
+        element :content, "cn-item-content flex flex-1 flex-col [&+[data-slot=item-content]]:flex-none"
+        element :title, "cn-item-title line-clamp-1 flex w-fit items-center"
+        element :description, "cn-item-description line-clamp-2 font-normal [&>a]:underline " \
+                              "[&>a]:underline-offset-4 [&>a:hover]:text-primary"
+        element :actions, "cn-item-actions flex items-center"
+        element :header, "cn-item-header flex basis-full items-center justify-between"
+        element :footer, "cn-item-footer flex basis-full items-center justify-between"
+
+        # The list wrapper + row separator (poetry_item_group / _separator).
+        element :group, "cn-item-group flex w-full flex-col"
+        element :separator, "cn-item-separator"
+      end
+    end
+  end
+end

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

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Ui
+    # The Kbd family - the keyboard-key chip.
+    module Kbd
+      # The Kbd - a real <kbd> element for a keyboard key or shortcut. The
+      # content is the key text (⌘, Ctrl, K); compose several for a chord.
+      #
+      # @example
+      #   render Poetry::Ui::Kbd::Component.new { "Esc" }
+      class Component < Poetry::Core::Component
+        requires_content "the key text"
+
+        # Projected into the registry, llms.txt, and the agent surface.
+        AGENT_RULES = [
+          "Kbd renders a real <kbd> - the key text is the content block (⌘, Esc, Ctrl).",
+          "For a chord (⌘+K) render one Kbd per key inside an inline-flex row."
+        ].freeze
+
+        part "kbd", "The <kbd> element itself - the key text renders here"
+
+        # Enforces the required key text before render.
+        # @api private
+        def before_render
+          ensure_content!
+        end
+
+        # Renders the <kbd> element.
+        # @api private
+        def call
+          content_tag(:kbd, content, **root_attributes.to_attributes)
+        end
+
+        # The <kbd> element's attributes.
+        # @api private
+        def root_attributes
+          html_attributes.merge_if_not_set(
+            { "data-slot" => "kbd" }.merge(component_data_attributes)
+          )
+        end
+
+        private :root_attributes
+      end
+    end
+  end
+end

data/app/components/poetry/ui/kbd/group_preview.html.erb

@@ -0,0 +1,4 @@
+<%= poetry_kbd_group do %>
+  <%= poetry_kbd { "⌘" } %>
+  <%= poetry_kbd { "K" } %>
+<% end %>

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

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Ui
+    module Kbd
+      # The Kbd preview: single keys.
+      class Preview < Poetry::Core::Preview::Base
+        def default
+          render_component { "Esc" }
+        end
+
+        def command
+          render_component { "⌘" }
+        end
+
+        # A chord run in the themed group wrapper.
+        def group
+          render_with_template(template: "poetry/ui/kbd/group_preview")
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Ui
+    module Kbd
+      # Re-expressed through the cn-* theme layer: the keyboard-key
+      # chip's look (incl. the tooltip inversion) rides themes/default.css.
+      class Style < Poetry::Core::Style
+        base "cn-kbd pointer-events-none inline-flex items-center justify-center select-none"
+      end
+    end
+  end
+end

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

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Ui
+    # A caption for a form control.
+    module Label
+      # A <label> for a form control, wired to it via for_id:. The
+      # caption is the content block.
+      #
+      # Omit for_id: when the label names a GROUP of controls rather
+      # than one element: a for= pointing at a non-control is inert, so
+      # in group mode the group names itself via aria-labelledby at this
+      # label's id instead.
+      #
+      # @example A label wired to its control
+      #   render Poetry::Ui::Label::Component.new(for_id: "email").with_content("Email")
+      class Component < Poetry::Core::Component
+        # Projected into the registry, llms.txt, and the agent surface.
+        AGENT_RULES = [
+          "Every control gets a Label wired via for_id - placeholder text is never the label."
+        ].freeze
+
+        option :for_id, :string,
+               doc: "The id of the control this label names; omit it for a group label (the group then points at " \
+                    "this label via aria-labelledby)."
+
+        part "label", "The <label> element itself - for= rides it (dropped in group mode, " \
+                      "where the group names itself via aria-labelledby at this label's id)"
+
+        # @api private
+        def call
+          content_tag(:label, content, **root_attributes.to_attributes)
+        end
+
+        # @api private
+        def root_attributes
+          attrs = { "data-slot" => "label" }
+          attrs["for"] = for_id if for_id.present?
+          html_attributes.merge_if_not_set(attrs.merge(component_data_attributes))
+        end
+
+        private :root_attributes
+      end
+    end
+  end
+end

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

@@ -0,0 +1,5 @@
+<%# The Label preview pair: a label wired to a real control via for_id. %>
+<div class="p-4">
+  <%= render component.with_content("Full name") %>
+  <%= render Poetry::Ui::Input::Component.new(name: "full_name", id: "label-full-name") %>
+</div>

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

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Ui
+    module Label
+      # The Label preview - always tied to a control via for_id (the
+      # component's whole contract), so the sidecar preview.html.erb renders
+      # the label/input pair.
+      class Preview < Poetry::Core::Preview::Base
+        def default
+          render_with(component: Component.new(for_id: "label-full-name"))
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Ui
+    module Label
+      # Re-expressed through the cn-* theme layer.
+      class Style < Poetry::Core::Style
+        base "cn-label flex items-center select-none peer-disabled:cursor-not-allowed " \
+             "group-data-[disabled=true]:pointer-events-none"
+      end
+    end
+  end
+end

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

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Ui
+    # A navigation link.
+    module Link
+      # A themed navigation link - a real <a>. Links navigate; buttons
+      # act - reach for Button when the click performs an action.
+      # current: true marks the active nav item via aria-current, and
+      # external: true opens a new tab with the safe rel pairing.
+      #
+      # @example
+      #   render Poetry::Ui::Link::Component.new(href: "/docs") { "Documentation" }
+      class Component < Poetry::Core::Component
+        # Projected into the registry, llms.txt, and the agent surface.
+        AGENT_RULES = [
+          "Use poetry_link for navigation - poetry_button for actions (never an <a> styled by hand).",
+          "Mark the active nav item with current: true (aria-current), never with a bespoke class.",
+          "external: true handles target/rel safely - never hand-write target=_blank."
+        ].freeze
+
+        style :underline, default: :hover, variants: %i[hover always none],
+                          doc: "When the underline appears; :none suits links styled by their container."
+
+        option :href, :string, required: true, doc: "The destination URL."
+        option :external, :boolean, default: false,
+                                    doc: "Opens in a new tab with rel=\"noopener noreferrer\" - never hand-write " \
+                                         "target=_blank."
+        option :current, :boolean, default: false, doc: "Marks this link as the current page via aria-current=page."
+
+        part "link", "The rendered <a> - the whole component; current: marks it aria-current=page"
+
+        # An empty link would be a focusable, invisible <a> - the visible
+        # text is required.
+        requires_content "the visible link text"
+
+        # @api private
+        def before_render
+          ensure_content!
+        end
+
+        # @api private
+        def call
+          content_tag(:a, content, **root_attributes.to_attributes)
+        end
+
+        # @api private
+        def root_attributes
+          attrs = { "href" => href, "data-slot" => "link" }.merge(component_data_attributes)
+          attrs["aria-current"] = "page" if current
+          if external
+            attrs["target"] = "_blank"
+            attrs["rel"] = "noopener noreferrer"
+          end
+          html_attributes.merge_if_not_set(attrs)
+        end
+
+        private :root_attributes
+      end
+    end
+  end
+end

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

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Ui
+    module Link
+      # The Link preview: the default hover underline, the aria-current
+      # nav item, an external link, and both underline extremes.
+      class Preview < Poetry::Core::Preview::Base
+        def default
+          render_component(href: "#") { "Documentation" }
+        end
+
+        def current_nav_item
+          render_component(href: "#", current: true) { "Dashboard" }
+        end
+
+        def external
+          render_component(href: "https://example.com", external: true) { "API reference" }
+        end
+
+        def always_underlined
+          render_component(href: "#", underline: :always) { "Terms of service" }
+        end
+
+        def never_underlined
+          render_component(href: "#", underline: :none) { "Settings" }
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Ui
+    module Link
+      # Re-expressed through the cn-* theme layer. No upstream
+      # counterpart - the split follows the category rule:
+      # layout/behavior inline, color/decoration/focus ring themed.
+      class Style < Poetry::Core::Style
+        base "cn-link inline-flex items-center outline-none transition-colors"
+
+        variant :underline, {
+          hover: "cn-link-underline-hover",
+          always: "cn-link-underline-always",
+          none: "cn-link-underline-none"
+        }
+      end
+    end
+  end
+end

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

@@ -0,0 +1,4 @@
+<%= content_tag(tag, **root_attributes.to_attributes) do %>
+  <% if icon? %><span data-slot="marker-icon" aria-hidden="true" class="<%= css(:icon) %>"><%= icon %></span><% end %>
+  <span data-slot="marker-content" class="<%= css(:content) %>"><%= content %></span>
+<% end %>

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

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Ui
+    # A transcript divider or inline status line for chat UIs.
+    module Marker
+      # A transcript divider or inline status line for chat UIs: date
+      # breaks, "3 new messages", an in-flight status. The label is real
+      # announced content - the decorative divider lines render around
+      # it, and the marker never takes a separator role. announce:
+      # :status turns it into a live status region for the single
+      # in-flight marker a transcript shows while streaming.
+      #
+      # @example
+      #   render Poetry::Ui::Marker::Component.new(variant: :separator) { "Yesterday" }
+      class Component < Poetry::Core::Component
+        # The closed vocabulary for the variant axis.
+        VARIANTS = %i[default separator border].freeze
+        # The closed vocabulary for the announce axis.
+        ANNOUNCE = %i[none status].freeze
+
+        # Projected into the registry, llms.txt, and the agent surface.
+        AGENT_RULES = [
+          "The marker text is real announced content - never mark it aria-hidden or role=separator.",
+          "announce: :status is for the ONE in-flight marker (streaming status); static dividers never announce.",
+          "Icons ride the icon slot (decorative always): with_icon(name:) for a lucide glyph, " \
+          "with_icon { } for other media (a Spinner mid-run).",
+          "Use variant: :separator for date/section breaks; :border under pinned headers."
+        ].freeze
+
+        renders_one :icon,
+                    doc: "Optional leading visual: name: renders an icon glyph; a block carries other media (a " \
+                         "Spinner mid-run). Either way it sits in an aria-hidden cell and stays decorative - the " \
+                         "marker root does the announcing.",
+                    renders: lambda { |name: nil, **options, &block|
+                      next Poetry::Ui::Icon::Component.new(name: name, **options) if name
+
+                      content_tag(:span, &block)
+                    }
+
+        style :variant, default: :default, required: true, variants: VARIANTS,
+                        doc: "The divider treatment - :separator for date/section breaks, :border for a full-width " \
+                             "rule under pinned headers."
+
+        option :tag, :symbol, default: :div, doc: "The root element's tag."
+        option :announce, :symbol, default: :none,
+                                   doc: "Makes the marker a live status region (role=status) for the one in-flight " \
+                                        "marker; static dividers never announce."
+
+        validates :announce, inclusion: { in: ANNOUNCE }
+
+        part "marker", "The divider/status root - the label is real announced content " \
+                       "(role=status when announce: :status; never role=separator)",
+             states: {
+               "data-variant" => { condition: "always - the resolved variant",
+                                   values: VARIANTS.map(&:to_s) }
+             }
+        # "The label IS the information" - an empty marker renders a bare
+        # divider span pretending to inform.
+        requires_content "the marker label"
+
+        part "marker-icon", "Decorative icon wrapper (aria-hidden always)"
+        part "marker-content", "The label span - the marker text itself"
+
+        # @api private
+        def before_render
+          ensure_content!
+        end
+
+        # @api private
+        def root_attributes
+          attrs = { "data-slot" => "marker", "data-variant" => variant }.merge(component_data_attributes)
+          attrs["role"] = "status" if announce == :status
+          html_attributes.merge_if_not_set(attrs)
+        end
+
+        private :root_attributes
+      end
+    end
+  end
+end

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

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Ui
+    module Marker
+      # The Marker preview matrix.
+      class Preview < Poetry::Core::Preview::Base
+        def default
+          render_component { "Assistant is thinking" }
+        end
+
+        def separator
+          render_component(variant: :separator) { "Yesterday" }
+        end
+
+        def border
+          render_component(variant: :border) { "Earlier in this thread" }
+        end
+
+        def with_icon
+          render_component do |marker|
+            marker.with_icon(name: :sparkles)
+            "Generating a summary"
+          end
+        end
+
+        def announcing_status
+          render_component(announce: :status) { "Searching the web…" }
+        end
+
+        # The block icon path: other media in the decorative cell - the
+        # Spinner's own status role is hidden by the aria-hidden wrapper,
+        # the marker root announces.
+        def status_with_spinner
+          render_component(announce: :status) do |marker|
+            marker.with_icon { render(Spinner::Component.new) }
+            "Compacting conversation"
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Ui
+    module Marker
+      # Re-expressed through the cn-* theme layer. The separator
+      # lines stay ::before/::after pseudo-elements (AT never sees them) -
+      # now in the variant theme rule.
+      class Style < Poetry::Core::Style
+        base "cn-marker group/marker relative flex w-full items-center"
+
+        variant :variant, {
+          default: "",
+          separator: "cn-marker-variant-separator",
+          border: "cn-marker-variant-border"
+        }
+
+        element :icon, "cn-marker-icon shrink-0"
+
+        element :content, "cn-marker-content min-w-0 wrap-break-word"
+      end
+    end
+  end
+end

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

@@ -0,0 +1,3 @@
+<%= content_tag(:div, **root_attributes.to_attributes) do %>
+  <% menus.each do |menu| %><%= menu %><% end %>
+<% end %>