poetry-ui 0.0.2

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

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Ui
+    module Avatar
+      # The Avatar preview: the initials fallback (the deterministic base
+      # state), the image layer actually covering it (a data-URI svg, so the
+      # browser rig loads it without a network), sizes, a badge, and the
+      # stacked group via the sidecar template.
+      class Preview < Poetry::Core::Preview::Base
+        # A gradient + head-and-shoulders silhouette - unlike the 1x1 solid
+        # pixel it replaced, this is visibly an image, so the screenshot can
+        # tell "image loaded" apart from a tinted fallback.
+        IMAGE = "data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCA2NC" \
+                "A2NCI+PGRlZnM+PGxpbmVhckdyYWRpZW50IGlkPSJnIiB4MT0iMCIgeTE9IjAiIHgyPSIxIiB5Mj0iMSI+PHN0b3Agb2Zmc2V0PS" \
+                "IwIiBzdG9wLWNvbG9yPSIjNjM2NmYxIi8+PHN0b3Agb2Zmc2V0PSIuNTUiIHN0b3AtY29sb3I9IiM4YjVjZjYiLz48c3RvcCBvZm" \
+                "ZzZXQ9IjEiIHN0b3AtY29sb3I9IiNlYzQ4OTkiLz48L2xpbmVhckdyYWRpZW50PjwvZGVmcz48cmVjdCB3aWR0aD0iNjQiIGhlaW" \
+                "dodD0iNjQiIGZpbGw9InVybCgjZykiLz48Y2lyY2xlIGN4PSIzMiIgY3k9IjI1IiByPSIxMCIgZmlsbD0iI2ZmZiIgb3BhY2l0eT" \
+                "0iLjkiLz48cGF0aCBkPSJNMTIgNjRjMi0xMyAxMC0xOSAyMC0xOXMxOCA2IDIwIDE5eiIgZmlsbD0iI2ZmZiIgb3BhY2l0eT0iLj" \
+                "kiLz48L3N2Zz4="
+
+        def default
+          render_component(label: "Matt Solt") { "MS" }
+        end
+
+        def with_image
+          render_component(src: IMAGE, label: "Grace Hopper") { "GH" }
+        end
+
+        def small_with_badge
+          render_component(size: :sm, label: "Ada Lovelace (online)") do |avatar|
+            avatar.with_badge { "" }
+            "AL"
+          end
+        end
+
+        def large
+          render_component(size: :lg, label: "Annie Easley") { "AE" }
+        end
+
+        def group
+          # An explicit per-example template: a CLASS-level preview.html.erb
+          # would shadow the shared default for EVERY example (the contrib
+          # sidecar contract), silently replacing the other previews.
+          render_with_template(template: "poetry/ui/avatar/group_preview")
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Ui
+    module Avatar
+      # Re-expressed through the cn-* theme layer.
+      # :image keeps the "absolute inset-0" rule inline (the
+      # server-native layered fallback keeps BOTH fallback and image in the
+      # DOM, so the image must cover the initials); the after:* ring
+      # machinery stays inline as a structural rule.
+      class Style < Poetry::Core::Style
+        base "cn-avatar group/avatar relative flex shrink-0 select-none " \
+             "after:absolute after:inset-0 after:border after:border-border " \
+             "after:mix-blend-darken dark:after:mix-blend-lighten"
+
+        element :image, "cn-avatar-image absolute inset-0 aspect-square size-full object-cover"
+        element :fallback, "cn-avatar-fallback flex size-full items-center justify-center " \
+                           "text-sm group-data-[size=sm]/avatar:text-xs"
+        element :badge, "cn-avatar-badge absolute right-0 bottom-0 z-10 inline-flex items-center " \
+                        "justify-center rounded-full bg-blend-color ring-2 select-none " \
+                        "group-data-[size=default]/avatar:[&>svg]:size-2 " \
+                        "group-data-[size=default]/avatar:size-2.5 group-data-[size=lg]/avatar:[&>svg]:size-2 " \
+                        "group-data-[size=lg]/avatar:size-3 group-data-[size=sm]/avatar:[&>svg]:hidden " \
+                        "group-data-[size=sm]/avatar:size-2"
+
+        # The stack (poetry_avatar_group) + its overflow count.
+        element :group, "group/avatar-group flex -space-x-2 " \
+                        "*:data-[slot=avatar]:ring-2 *:data-[slot=avatar]:ring-background"
+        element :group_count, "cn-avatar-group-count relative flex shrink-0 items-center " \
+                              "justify-center ring-2 ring-background"
+      end
+    end
+  end
+end

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

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Ui
+    # Non-interactive status pills.
+    module Badge
+      # A small status pill. Variants carry semantic intent: the solid
+      # set (default/secondary/destructive/outline/ghost/link) for labels
+      # and emphasis, plus the soft status trio (success/warning/info) -
+      # the muted color-coded pills record-status columns need.
+      #
+      # Badges are non-interactive; the one interactive form is href:,
+      # which renders the pill as a real link.
+      #
+      # @example A soft status pill
+      #   render Poetry::Ui::Badge::Component.new(variant: :success) { "Fulfilled" }
+      class Component < Poetry::Core::Component
+        # A status label with no text is an invisible sliver.
+        requires_content "the visible status text"
+
+        # The closed vocabulary for the variant axis.
+        VARIANTS = %i[default secondary destructive outline ghost link success warning info].freeze
+
+        # Projected into the registry, llms.txt, and the agent surface.
+        AGENT_RULES = [
+          "Badges are non-interactive status labels - never attach click handlers; use Button for " \
+          "actions. The one interactive form is href:, which renders the badge AS a real link " \
+          "(a navigational chip - the themes' [a&]:hover treatments activate).",
+          "The visible text is the content block: render ... { \"beta\" } - there is no label: option.",
+          "Pick the variant by intent (destructive = error states; success/warning/info = record " \
+          "status, e.g. Fulfilled/Processing/Syncing), never by color preference.",
+          "Status badges on one surface read as a SET: keep one treatment family per table/list - " \
+          "the soft trio (+ outline for neutral) together, or the solid pair together; never a " \
+          "solid destructive pill inside a soft status column (design lint flags the mix)."
+        ].freeze
+
+        style :variant, default: :default, required: true, variants: VARIANTS,
+                        doc: "The intent axis; success/warning/info are the soft record-status treatments."
+
+        option :href, :string,
+               doc: "Renders the pill as a real <a> - a navigational chip; the theme's link hover treatments " \
+                    "activate on exactly this element."
+
+        part "badge", "The status pill itself (a <span>; a real <a> when href: is given) - " \
+                      "the whole component is this one element",
+             states: {
+               "data-variant" => { condition: "always - the resolved variant",
+                                   values: VARIANTS.map(&:to_s) }
+             }
+
+        # Enforces the visible-text content block.
+        # @api private
+        def before_render
+          ensure_content!
+        end
+
+        # @api private
+        def call
+          content_tag(href.present? ? :a : :span, content, **root_attributes.to_attributes)
+        end
+
+        # @api private
+        def root_attributes
+          attrs = { "data-slot" => "badge", "data-variant" => variant }
+          attrs["href"] = href if href.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/badge/preview.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Ui
+    module Badge
+      class Preview < Poetry::Core::Preview::Base
+        def default
+          render_component(variant: :default) { "New" }
+        end
+
+        def secondary
+          render_component(variant: :secondary) { "Draft" }
+        end
+
+        def destructive
+          render_component(variant: :destructive) { "Failed" }
+        end
+
+        def outline
+          render_component(variant: :outline) { "Beta" }
+        end
+
+        def ghost
+          render_component(variant: :ghost) { "Muted on hover" }
+        end
+
+        # The link VARIANT (distinct from the badge-as-anchor example below).
+        def link_variant
+          render_component(variant: :link) { "Reference" }
+        end
+
+        # Badge-as-link (upstream badge#link parity): a real <a>, so the
+        # axe walk covers the anchor treatment and its contrast.
+        def link
+          render_component(href: "#changelog") { "v2.0 release notes" }
+        end
+
+        # The status vocabulary: soft tints on the status
+        # tokens - the axe walk holds every theme's treatment to AA here.
+        def success
+          render_component(variant: :success) { "Fulfilled" }
+        end
+
+        def warning
+          render_component(variant: :warning) { "Processing" }
+        end
+
+        def info
+          render_component(variant: :info) { "Syncing" }
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Ui
+    module Badge
+      # Re-expressed through the cn-* theme layer. The focus/invalid
+      # ring chain deviates from upstream's inline split DELIBERATELY: the
+      # destructive variant re-colors focus-visible:ring-* in the theme and
+      # can only beat the base treatment from the same layer (the
+      # split-side conflict rule).
+      class Style < Poetry::Core::Style
+        base "cn-badge inline-flex w-fit shrink-0 items-center justify-center overflow-hidden " \
+             "whitespace-nowrap [&>svg]:pointer-events-none aria-invalid:border-destructive " \
+             "aria-invalid:ring-destructive/20 dark:aria-invalid:ring-destructive/40 " \
+             "focus-visible:border-ring focus-visible:ring-[3px] focus-visible:ring-ring/50 " \
+             "group/badge"
+
+        # success/warning/info: the poetry-original soft status vocabulary
+        # (upstream Badge has no status variants); every theme carries the
+        # soft treatment on the new status tokens.
+        variant :variant, {
+          ghost: "cn-badge-variant-ghost",
+          link: "cn-badge-variant-link",
+          default: "cn-badge-variant-default",
+          secondary: "cn-badge-variant-secondary",
+          destructive: "cn-badge-variant-destructive",
+          outline: "cn-badge-variant-outline",
+          success: "cn-badge-variant-success",
+          warning: "cn-badge-variant-warning",
+          info: "cn-badge-variant-info"
+        }
+      end
+    end
+  end
+end

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

@@ -0,0 +1,32 @@
+<%= content_tag(:nav, **root_attributes.to_attributes) do %>
+  <ol data-slot="breadcrumb-list" class="<%= css(:list) %>">
+    <% entries.each_with_index do |entry, index| %>
+      <li data-slot="breadcrumb-item" class="<%= css(:item) %>">
+        <% if entry.ellipsis %>
+          <span data-slot="breadcrumb-ellipsis" role="presentation" aria-hidden="true" class="<%= css(:ellipsis) %>">
+            <%= render Poetry::Ui::Icon::Component.new(name: :ellipsis) %>
+          </span>
+          <span class="sr-only">More</span>
+        <% else %>
+          <% if entry.block %>
+            <%= capture(&entry.block) %>
+          <% elsif entry.href.present? %>
+            <a data-slot="breadcrumb-link" href="<%= entry.href %>" class="<%= css(:link) %>"><%= entry.label %></a>
+          <% else %>
+            <span data-slot="breadcrumb-page" role="link" aria-disabled="true" aria-current="page"
+                  class="<%= css(:page) %>"><%= entry.label %></span>
+          <% end %>
+        <% end %>
+      </li>
+      <% unless index == entries.size - 1 %>
+        <li data-slot="breadcrumb-separator" role="presentation" aria-hidden="true" class="<%= css(:separator) %>">
+          <% if separator_block %>
+            <%= capture(&separator_block) %>
+          <% else %>
+            <%= render Poetry::Ui::Icon::Component.new(name: :"chevron-right", class: "cn-rtl-flip") %>
+          <% end %>
+        </li>
+      <% end %>
+    <% end %>
+  </ol>
+<% end %>

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

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Ui
+    # Ancestor-trail navigation.
+    module Breadcrumb
+      # A navigation trail of ancestor links. Declare the trail (with_item
+      # per crumb, with_ellipsis for a collapsed middle) and the component
+      # owns the <nav>/<ol> chrome, the separators, and the current-page
+      # semantics. An item with href: is a link; an item without href:
+      # is the current page (aria-current="page").
+      #
+      # @example
+      #   <%= poetry_breadcrumb do |crumb| %>
+      #     <% crumb.with_item("Home", href: "/") %>
+      #     <% crumb.with_ellipsis %>
+      #     <% crumb.with_item("Breadcrumb") %>
+      #   <% end %>
+      class Component < Poetry::Core::Component
+        # The caller's separator block, captured by with_separator.
+        # @api private
+        attr_reader :separator_block
+
+        # Projected into the registry, llms.txt, and the agent surface.
+        AGENT_RULES = [
+          "Declare the trail with with_item(label, href:) - never hand-build the nav/ol/li chain.",
+          "The current page is the item WITHOUT href: (it renders aria-current=page, not a link).",
+          "Collapse a long middle with with_ellipsis - it announces 'More' to screen readers.",
+          "A BLOCK item (with_item { ... }) renders your content inside the <li> - the seat for a " \
+          "dropdown crumb or a custom-rendered link; you own its semantics (aria-current only " \
+          "applies to label items).",
+          "with_separator(icon: :dot) - or a block - replaces the chevron in EVERY gap; the default " \
+          "chevron RTL-flips, a custom glyph is used as given."
+        ].freeze
+
+        # Slots the component cannot render without; static checks read this without rendering.
+        REQUIRED_SLOTS = { item: "at least one item" }.freeze
+
+        renders_many :items,
+                     doc: "The crumbs, in declaration order. A label with href: renders a link; without one, the " \
+                          "current page. A block makes the <li>'s content caller-owned (a dropdown crumb, a " \
+                          "custom-rendered link).",
+                     renders: lambda { |label = nil, href: nil, ellipsis: false, &block|
+                       entries << Entry.new(label: label, href: href, ellipsis: ellipsis, block: block)
+                       nil
+                     }
+
+        renders_one :separator,
+                    doc: "Replaces the separator glyph in EVERY gap: an icon name, or a block for arbitrary " \
+                         "content. Absent, the default chevron renders (with its RTL flip - a custom glyph is used " \
+                         "as given).",
+                    renders: lambda { |icon: nil, &block|
+                      @separator_block = icon ? proc { render Icon::Component.new(name: icon) } : block
+                      nil
+                    }
+
+        part "breadcrumb", "The <nav> landmark (aria-label=breadcrumb) around the trail"
+        part "breadcrumb-list", "The <ol> laying crumbs and separators out as one wrapping row"
+        part "breadcrumb-item", "One <li> of the trail - wraps a link, the current page, the ellipsis, " \
+                                "or a block item's own content (a dropdown crumb, a custom link)"
+        part "breadcrumb-link", "A crumb with href: - a real <a> to an ancestor page"
+        part "breadcrumb-page", "The current page (the item without href:) - aria-current=page, not a link"
+        part "breadcrumb-separator", "The chevron <li> between crumbs - presentational, aria-hidden"
+        part "breadcrumb-ellipsis", "The collapsed-middle glyph (with_ellipsis) - aria-hidden; a sibling " \
+                                    "sr-only 'More' announces it"
+
+        # Enforces the required item slot.
+        # @api private
+        def before_render
+          # items? is the SLOT predicate: it forces the render block (which
+          # populates entries) - reading @entries directly here would run
+          # before the block ever executed.
+          raise ArgumentError, "Breadcrumb requires at least one with_item" unless items?
+        end
+
+        # Adds a collapsed-middle marker to the trail; screen readers hear "More".
+        def with_ellipsis
+          with_item(ellipsis: true)
+        end
+
+        # The declared crumbs in order.
+        # @api private
+        def entries
+          @entries ||= []
+        end
+
+        # @api private
+        def root_attributes
+          html_attributes.merge_if_not_set(
+            { "aria-label" => "breadcrumb", "data-slot" => "breadcrumb" }.merge(component_data_attributes)
+          )
+        end
+
+        # One declared crumb.
+        # @api private
+        Entry = Data.define(:label, :href, :ellipsis, :block)
+
+        private :entries, :root_attributes
+      end
+    end
+  end
+end

data/app/components/poetry/ui/breadcrumb/dropdown_crumb_preview.html.erb

@@ -0,0 +1,21 @@
+<%# A middle crumb IS a dropdown (upstream breadcrumb#dropdown): the block
+    item hands the <li> to caller content; the ghost trigger is restyled to
+    read as breadcrumb text. %>
+<%= poetry_breadcrumb do |crumb| %>
+  <% crumb.with_item("Home", href: "#") %>
+  <% crumb.with_item do %>
+    <%= poetry_dropdown_menu(align: :start) do |menu| %>
+      <% menu.with_trigger(variant: :ghost, size: :sm,
+                           class: "h-auto gap-1 p-0 font-normal text-muted-foreground hover:bg-transparent hover:text-foreground") do %>
+        Components
+        <%= poetry_icon(name: :"chevron-down", class: "size-3.5") %>
+      <% end %>
+      <% menu.with_group do |group| %>
+        <% group.with_item { "Documentation" } %>
+        <% group.with_item { "Themes" } %>
+        <% group.with_item { "GitHub" } %>
+      <% end %>
+    <% end %>
+  <% end %>
+  <% crumb.with_item("Breadcrumb") %>
+<% end %>

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

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Ui
+    module Breadcrumb
+      # The Breadcrumb preview: a plain trail and a collapsed-middle trail.
+      class Preview < Poetry::Core::Preview::Base
+        def default
+          render_component do |crumb|
+            crumb.with_item("Home", href: "#")
+            crumb.with_item("Components", href: "#")
+            crumb.with_item("Breadcrumb")
+          end
+        end
+
+        def collapsed
+          render_component do |crumb|
+            crumb.with_item("Home", href: "#")
+            crumb.with_ellipsis
+            crumb.with_item("Components", href: "#")
+            crumb.with_item("Breadcrumb")
+          end
+        end
+
+        # with_separator swaps the chevron in every gap (upstream
+        # breadcrumb#separator - the dot form).
+        def dot_separator
+          render_component do |crumb|
+            crumb.with_separator(icon: :dot)
+            crumb.with_item("Home", href: "#")
+            crumb.with_item("Components", href: "#")
+            crumb.with_item("Breadcrumb")
+          end
+        end
+
+        # A block item seats a dropdown as a middle crumb (upstream
+        # breadcrumb#dropdown) - the axe walk holds the composed menu
+        # inside the nav landmark to the same bar as everything else.
+        def dropdown_crumb
+          render_with_template(template: "poetry/ui/breadcrumb/dropdown_crumb_preview")
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Ui
+    module Breadcrumb
+      # Re-expressed through the cn-* theme layer. The separator
+      # chevron wears cn-rtl-flip (template-side): upstream ships that
+      # NAME with no rule anywhere - dead in source - so poetry authors the
+      # intended RTL mirror in the theme (rtl:-scale-x-100, LTR-neutral).
+      # No cn-breadcrumb root name: the root's poetry surface is empty and
+      # empty theme rules don't survive compilation (data-slot remains the
+      # restyle hook).
+      class Style < Poetry::Core::Style
+        base ""
+
+        element :list, "cn-breadcrumb-list flex flex-wrap items-center wrap-break-word"
+        element :item, "cn-breadcrumb-item inline-flex items-center"
+        element :link, "cn-breadcrumb-link"
+        element :page, "cn-breadcrumb-page"
+        element :separator, "cn-breadcrumb-separator"
+        element :ellipsis, "cn-breadcrumb-ellipsis flex items-center justify-center"
+      end
+    end
+  end
+end

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

@@ -0,0 +1,4 @@
+<%= content_tag(:div, **root_attributes.to_attributes) do %>
+  <%= content_tag(content_tag_name, content, **content_attributes) %>
+  <%= reactions %>
+<% end %>

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

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Ui
+    # Chat message bubbles.
+    module Bubble
+      # A chat message bubble - one per message, aligned to the sender's
+      # side. The content block is the message; tag: :button or :a (with
+      # href:) turns the bubble into a quick reply, and the reactions slot
+      # overlays a pill of reactions. Purely presentational - no
+      # JavaScript.
+      #
+      # @example An assistant reply
+      #   render Poetry::Ui::Bubble::Component.new(variant: :secondary) { "Here's the summary." }
+      class Component < Poetry::Core::Component
+        # The closed vocabulary for the variant axis.
+        VARIANTS = %i[default secondary muted tinted outline ghost destructive].freeze
+        # The closed vocabulary for the align axis.
+        ALIGNS = %i[start end].freeze
+        # The closed vocabulary for the tag: axis.
+        CONTENT_TAGS = %i[div button a].freeze
+
+        # Projected into the registry, llms.txt, and the agent surface.
+        AGENT_RULES = [
+          "One Bubble per message; stack a sender's run inside poetry_bubble_group.",
+          "Quick replies are tag: :button (with the caller's data-action) or tag: :a + " \
+          "href: - never a click handler on a div.",
+          "ghost is for tool output / system text flowing full-width - not a visual preference.",
+          "Reactions REQUIRE label: (the accessible name for the cluster).",
+          "Inside a Message, alignment follows the Message's align - do not set both."
+        ].freeze
+
+        renders_one :reactions,
+                    doc: "The reactions pill overlaid on an edge; label: names the cluster for assistive tech, " \
+                         "side:/align: place it (default bottom end).",
+                    renders: lambda { |label:, side: :bottom, align: :end, &block|
+                      content_tag(:div,
+                                  class: css(:reactions), "data-slot" => "bubble-reactions",
+                                  "data-side" => side, "data-align" => align,
+                                  role: "group", "aria-label" => label, &block)
+                    }
+
+        # The content block IS the message; an empty bubble is an empty pill.
+        requires_content "the message content"
+
+        style :variant, default: :default, required: true, variants: VARIANTS,
+                        doc: "The intent axis; :ghost is for tool output / system text flowing full-width."
+
+        option :align, :symbol, default: :start,
+                                doc: "Which side the bubble hugs; inside a Message, set the Message's align instead."
+        option :tag, :symbol, default: :div,
+                              doc: "The content element: :div (default), or :button/:a for a quick reply."
+        option :href, :string, doc: "Renders the content as a real anchor; implies tag: :a."
+
+        validates :align, inclusion: { in: ALIGNS }
+        validates :tag, inclusion: { in: CONTENT_TAGS }
+
+        part "bubble", "The message surface root - variant and alignment ride here",
+             states: {
+               "data-variant" => { condition: "always - the resolved variant",
+                                   values: VARIANTS.map(&:to_s) },
+               "data-align" => { condition: "always - the resolved align",
+                                 values: ALIGNS.map(&:to_s) }
+             }
+        part "bubble-content", "The body (<div>, or a <button>/<a> quick reply via tag:) - " \
+                               "the content block renders here"
+        part "bubble-reactions", "The reactions pill overlay (role=group, named by label:)",
+             states: {
+               "data-side" => "always - which edge the pill overlays (default bottom)",
+               "data-align" => "always - placement along that edge (default end)"
+             }
+
+        # Enforces the message content block.
+        # @api private
+        def before_render
+          ensure_content!
+        end
+
+        # @api private
+        def root_attributes
+          html_attributes.merge_if_not_set(
+            { "data-slot" => "bubble", "data-variant" => variant, "data-align" => align }
+              .merge(component_data_attributes)
+          )
+        end
+
+        # href: implies the anchor - an href on the default :div would
+        # otherwise be silently dropped, leaving a dead control.
+        # @api private
+        def content_tag_name
+          href.present? ? :a : tag
+        end
+
+        # @api private
+        def content_attributes
+          attrs = { class: css(:content), "data-slot" => "bubble-content" }
+          attrs[:href] = href if content_tag_name == :a
+          attrs[:type] = "button" if content_tag_name == :button
+          attrs
+        end
+
+        private :root_attributes, :content_tag_name, :content_attributes
+      end
+    end
+  end
+end

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

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Ui
+    module Bubble
+      # The Bubble preview matrix - one corpus for Lookbook, docs, and the
+      # agent visual loop.
+      class Preview < Poetry::Core::Preview::Base
+        # @!group Variants
+
+        def default
+          render_component { "Sounds good - see you at 10." }
+        end
+
+        def secondary
+          render_component(variant: :secondary) { "Here's the summary you asked for." }
+        end
+
+        def muted
+          render_component(variant: :muted) { "Typing indicator context." }
+        end
+
+        def tinted
+          render_component(variant: :tinted) { "A tinted assistant reply." }
+        end
+
+        def outline
+          render_component(variant: :outline) { "An outlined reply." }
+        end
+
+        def ghost
+          render_component(variant: :ghost) { "Tool output flows full-width without a surface." }
+        end
+
+        def destructive
+          render_component(variant: :destructive) { "That upload failed." }
+        end
+
+        # @!endgroup
+
+        def align_end
+          render_component(align: :end) { "Sent by me." }
+        end
+
+        def quick_reply_button
+          render_component(variant: :outline, tag: :button) { "Yes, book it" }
+        end
+
+        def quick_reply_link
+          render_component(variant: :outline, tag: :a, href: "/details") { "View details" }
+        end
+
+        def with_reactions
+          render_component do |bubble|
+            bubble.with_reactions(label: "Reactions: thumbs up") { "👍" }
+            "Great idea!"
+          end
+        end
+      end
+    end
+  end
+end