poetry-ui 0.0.2

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

@@ -0,0 +1,139 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Ui
+    # File/image upload chips.
+    module Attachment
+      # A file or image chip showing an upload's name, metadata, and
+      # lifecycle state. The server owns the state: render state:
+      # (idle/uploading/processing/error/done) and update it by
+      # re-rendering or a Turbo Stream replace - the component ships no
+      # upload JavaScript of its own.
+      #
+      # In-flight and error states carry a translated screen-reader
+      # status announcement; the visual lifecycle is pure CSS.
+      #
+      # @example A finished upload
+      #   render Poetry::Ui::Attachment::Component.new do |attachment|
+      #     attachment.with_title { "quarterly-report.pdf" }
+      #     attachment.with_description { "1.2 MB" }
+      #   end
+      class Component < Poetry::Core::Component
+        # The closed vocabulary for the state axis (the server-owned upload lifecycle).
+        STATES = %i[idle uploading processing error done].freeze
+        # The closed vocabulary for the size axis.
+        SIZES = %i[default sm xs].freeze
+        # The closed vocabulary for the orientation axis.
+        ORIENTATIONS = %i[horizontal vertical].freeze
+        # The closed vocabulary for the with_media variant.
+        MEDIA_VARIANTS = %i[icon image].freeze
+        # States that render the screen-reader status announcement.
+        ANNOUNCED_STATES = %i[uploading processing error].freeze
+
+        # Projected into the registry, llms.txt, and the agent surface.
+        AGENT_RULES = [
+          "State is server-owned: render data-upload-state and flip it by Turbo Stream replace - " \
+          "never toggle it in JS.",
+          "with_media(variant: :image) wraps the caller's <img>; file names and URLs are " \
+          "user content - never render them html_safe.",
+          "Actions are with_action(...) poetry Buttons (ghost/icon-xs defaults) - each needs label: (icon-only).",
+          "with_trigger makes the whole chip the control (a stretched overlay UNDER the " \
+          "actions) - don't also wrap the chip in a link.",
+          "error state needs a with_description explaining the failure - the tint alone is not the message."
+        ].freeze
+
+        renders_one :media,
+                    doc: "Leading visual: :icon (default) boxes an icon tile, :image wraps the caller's <img>.",
+                    renders: lambda { |variant: :icon, &block|
+                      unless MEDIA_VARIANTS.include?(variant)
+                        raise ArgumentError,
+                              "media variant must be :icon or :image"
+                      end
+
+                      content_tag(:div, "data-slot" => "attachment-media", "data-variant" => variant,
+                                        class: css(:media, class: (if variant == :image
+                                                                     "cn-attachment-media-variant-image"
+                                                                   end)), &block)
+                    }
+        renders_one :title, doc: "The file name line. User content - never mark it html_safe."
+        renders_one :description, doc: "Muted metadata under the title (size, type); in the error state, the " \
+                                       "failure explanation."
+        renders_many :actions,
+                     doc: "Trailing icon actions - each renders a Button (ghost, icon-xs defaults) and requires " \
+                          "label:.",
+                     renders: lambda { |label:, **options, &block|
+                       # Caller data: augments the slot marker instead of replacing it
+                       # at the kwargs splat.
+                       data = { slot: "attachment-action" }.merge(options.delete(:data) || {})
+                       Button::Component.new(variant: options.delete(:variant) || :ghost,
+                                             size: options.delete(:size) || :"icon-xs",
+                                             label: label, data: data, **options, &block)
+                     }
+        renders_one :trigger,
+                    doc: "Makes the whole chip the control - a stretched button (or anchor via tag: :a, href:) " \
+                         "layered under the actions. Don't also wrap the chip in a link.",
+                    renders: lambda { |tag: :button, href: nil, **options, &block|
+                      attrs = Poetry::Core::HTML::Attributes.merged(
+                        { class: css(:trigger), "data-slot" => "attachment-trigger" }, options
+                      )
+                      attrs[:type] = "button" if tag == :button
+                      attrs[:href] = href if tag == :a
+                      content_tag(tag, attrs, &block)
+                    }
+
+        style :size, default: :default, required: true, variants: SIZES, doc: "The chip density axis."
+        style :orientation, default: :horizontal, required: true, variants: ORIENTATIONS,
+                            doc: "Row (:horizontal) or stacked thumbnail-card (:vertical) layout."
+
+        option :state, :symbol, default: :done,
+                                doc: "The upload lifecycle state; flip it by re-render or Turbo Stream replace, " \
+                                     "never in JS."
+
+        validates :state, inclusion: { in: STATES }
+
+        part "attachment", "The chip root - the server-owned upload lifecycle rides here " \
+                           "(flip data-upload-state by re-render / Turbo Stream replace)",
+             states: {
+               "data-upload-state" => { condition: "always - the resolved state",
+                                        values: STATES.map(&:to_s) },
+               "data-size" => { condition: "always - the resolved size",
+                                values: SIZES.map(&:to_s) },
+               "data-orientation" => { condition: "always - the resolved orientation",
+                                       values: ORIENTATIONS.map(&:to_s) }
+             }
+        part "attachment-media", "The media slot's box - the icon tile or the caller's <img>",
+             states: {
+               "data-variant" => { condition: "always - the media variant",
+                                   values: MEDIA_VARIANTS.map(&:to_s) }
+             }
+        part "attachment-content", "Text column wrapping title/description - renders when " \
+                                   "either slot is set"
+        part "attachment-title", "The file name line (title slot; user content, never html_safe)"
+        part "attachment-description", "Muted metadata / failure copy under the title"
+        part "attachment-actions", "Row of with_action poetry Buttons"
+        part "attachment-trigger", "The whole-chip control (with_trigger: a button or tag: :a " \
+                                   "anchor) - wraps the picker/download affordance"
+        part "attachment-status", "sr-only role=status announcement for the in-flight and " \
+                                  "error states (uploading/processing/error)"
+
+        # Whether the current state renders the screen-reader status announcement.
+        # @api private
+        def announced?
+          ANNOUNCED_STATES.include?(state)
+        end
+
+        # @api private
+        def root_attributes
+          html_attributes.merge_if_not_set(
+            {
+              "data-slot" => "attachment", "data-upload-state" => state,
+              "data-size" => size, "data-orientation" => orientation
+            }.merge(component_data_attributes)
+          )
+        end
+
+        private :announced?, :root_attributes
+      end
+    end
+  end
+end

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

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Ui
+    module Attachment
+      # The Attachment preview matrix - every lifecycle state + both
+      # orientations (the visual states are pure CSS on data-upload-state).
+      class Preview < Poetry::Core::Preview::Base
+        def default
+          render_component do |attachment|
+            attachment.with_media { icon(:file) }
+            attachment.with_title { "quarterly-report.pdf" }
+            attachment.with_description { "1.2 MB" }
+          end
+        end
+
+        # The whole-chip trigger control (download/open affordance).
+        def with_trigger
+          render_component do |attachment|
+            attachment.with_trigger(tag: :a, href: "/files/report.pdf") { "Download" }
+            attachment.with_media { icon(:file) }
+            attachment.with_title { "quarterly-report.pdf" }
+            attachment.with_description { "1.2 MB" }
+          end
+        end
+
+        def uploading
+          render_component(state: :uploading) do |attachment|
+            attachment.with_media { icon(:file) }
+            attachment.with_title { "photo.png" }
+            attachment.with_description { "uploading…" }
+          end
+        end
+
+        def error
+          render_component(state: :error) do |attachment|
+            attachment.with_media { icon(:"circle-alert") }
+            attachment.with_title { "notes.txt" }
+            attachment.with_description { "Too large (max 10 MB)" }
+          end
+        end
+
+        def idle_dropzone
+          render_component(state: :idle) do |attachment|
+            attachment.with_media { icon(:plus) }
+            attachment.with_title { "Add a file" }
+          end
+        end
+
+        # The compact rows cover the size axis: sm for dense lists,
+        # xs for inline chips.
+        def size_sm
+          render_component(size: :sm) do |attachment|
+            attachment.with_media { icon(:file) }
+            attachment.with_title { "invoice.pdf" }
+            attachment.with_description { "84 KB" }
+          end
+        end
+
+        def size_xs
+          render_component(size: :xs) do |attachment|
+            attachment.with_media { icon(:file) }
+            attachment.with_title { "readme.md" }
+          end
+        end
+
+        def vertical_with_actions
+          render_component(orientation: :vertical) do |attachment|
+            attachment.with_media(variant: :image) { icon(:image) }
+            attachment.with_title { "screenshot.png" }
+            attachment.with_action(label: "Remove") { icon(:x) }
+          end
+        end
+
+        private
+
+        def icon(name)
+          embed(Icon::Component.new(name: name))
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Ui
+    module Attachment
+      # Re-expressed through the cn-* theme layer. The upload
+      # lifecycle stays PURE CSS and INLINE per upstream's own split (idle
+      # dashes, error tints, the in-flight image dim) - it is coupled to
+      # the data-[upload-state] machine; sizes/orientation/surface ride the
+      # theme. w-fit moved theme-side WITH the vertical w-24 (split-side).
+      class Style < Poetry::Core::Style
+        base "cn-attachment group/attachment relative flex max-w-full min-w-0 shrink-0 flex-wrap border " \
+             "bg-card text-card-foreground transition-colors " \
+             "has-[>a,>button]:hover:bg-muted/50 data-[upload-state=error]:border-destructive/30 " \
+             "data-[upload-state=idle]:border-dashed"
+
+        variant :size, {
+          default: "cn-attachment-size-default",
+          sm: "cn-attachment-size-sm",
+          xs: "cn-attachment-size-xs"
+        }
+
+        variant :orientation, {
+          horizontal: "cn-attachment-orientation-horizontal items-center",
+          vertical: "cn-attachment-orientation-vertical flex-col"
+        }
+
+        element :media, "cn-attachment-media relative flex aspect-square shrink-0 items-center " \
+                        "justify-center overflow-hidden " \
+                        "group-data-[upload-state=error]/attachment:bg-destructive/10 " \
+                        "group-data-[upload-state=error]/attachment:text-destructive " \
+                        "group-data-[orientation=vertical]/attachment:*:data-[slot=spinner]:size-6! " \
+                        "[&_svg]:pointer-events-none " \
+                        "data-[variant=image]:opacity-60 " \
+                        "data-[variant=image]:group-data-[upload-state=done]/attachment:opacity-100 " \
+                        "data-[variant=image]:group-data-[upload-state=idle]/attachment:opacity-100 " \
+                        "data-[variant=image]:*:[img]:aspect-square data-[variant=image]:*:[img]:w-full " \
+                        "data-[variant=image]:*:[img]:object-cover"
+
+        element :content, "cn-attachment-content max-w-full min-w-0 flex-1"
+
+        element :title, "cn-attachment-title block max-w-full min-w-0 truncate " \
+                        "group-data-[upload-state=processing]/attachment:shimmer " \
+                        "group-data-[upload-state=uploading]/attachment:shimmer"
+
+        element :description, "cn-attachment-description block max-w-full min-w-0 truncate " \
+                              "group-data-[upload-state=error]/attachment:text-destructive/80 text-muted-foreground"
+
+        element :actions, "cn-attachment-actions flex shrink-0 items-center"
+
+        element :trigger, "cn-attachment-trigger"
+
+        element :group, "cn-attachment-group flex min-w-0 scroll-fade-x snap-x snap-mandatory " \
+                        "scrollbar-none overflow-x-auto overscroll-x-contain " \
+                        "*:data-[slot=attachment]:flex-none *:data-[slot=attachment]:snap-start"
+      end
+    end
+  end
+end

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

@@ -0,0 +1,16 @@
+<%= content_tag(:div, **root_attributes.to_attributes) do %>
+  <%= tag.input(**input_attributes, class: Poetry::Ui::Input::Style.css) %>
+  <%= tag.div(**content_attributes) do %>
+    <div data-slot="autocomplete-list" role="listbox" id="<%= list_id %>"
+         class="<%= Poetry::Ui::Command::Style.css(:list) %>"
+         <%= tag.attributes(stimulus_attributes_for(:list)) %>>
+      <% item_models.each_with_index do |item, index| %>
+        <%= tag.div(**item_attributes(item, index)) do %>
+          <span><%= item.label %></span>
+        <% end %>
+      <% end %>
+    </div>
+    <div data-slot="autocomplete-empty" class="<%= Poetry::Ui::Command::Style.css(:empty) %>" hidden
+         <%= tag.attributes(stimulus_attributes_for(:empty)) %>><%= empty_text %></div>
+  <% end %>
+<% end %>

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

@@ -0,0 +1,193 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Ui
+    # Free-text inputs with filtering suggestion popups.
+    module Autocomplete
+      # A text input that suggests from a server-rendered list, filtered
+      # as you type, while the text itself stays the form value: free text
+      # submits as an ordinary param, and picking a suggestion writes it
+      # into the input and closes the popup. When the value must be a
+      # selected item rather than free text, use Combobox instead.
+      #
+      # @example Free text with suggestions
+      #   render Poetry::Ui::Autocomplete::Component.new(name: "tag", label: "Search tags") do |auto|
+      #     auto.with_item(label: "feature")
+      #     auto.with_item(label: "fix")
+      #   end
+      class Component < Poetry::Core::Component
+        # Projected into the registry, llms.txt, and the agent surface.
+        AGENT_RULES = [
+          "The input IS the value: name: is the param key and free text submits as-is - " \
+          "suggestions are conveniences, not constraints (constrained pick = Combobox).",
+          "Items via with_item(label:) - label is what filtering matches and what commit " \
+          "writes; value: overrides the committed text when it differs from the label.",
+          "empty_text: renders the no-matches state (hidden while anything matches).",
+          "open_on_focus: false waits for typing before suggesting.",
+          "Server-side filtering stays yours: render fewer items on re-render - the client " \
+          "filter only narrows what the server sent."
+        ].freeze
+
+        use_stimulus do
+          on :root do
+            controller :autocomplete do
+              register
+              value :open_on_focus, "false", if: -> { !open_on_focus }
+            end
+            controller(:popper) { register }
+          end
+          on :input do
+            controller :autocomplete do
+              target :input
+              action :input, on: :input
+              action :focus, on: :focus
+              action :blurred, on: :focusout
+              action :keydown, on: :keydown
+            end
+            controller(:popper) { target :anchor }
+          end
+          on :content do
+            controller(:autocomplete) { target :content }
+            controller(:popper) { target :content }
+          end
+          on :list do
+            controller(:autocomplete) { target :list }
+          end
+          on :empty do
+            controller(:autocomplete) { target :empty }
+          end
+          on :item do
+            controller :autocomplete do
+              action :itemPress, on: :pointerdown
+              action :itemEnter, on: :pointerenter
+            end
+          end
+        end
+
+        option :name, :string, required: true, doc: "The form param key; the input's text submits under it as-is."
+        option :value, :string, doc: "The initial input text."
+        option :id, :string, doc: "Stable DOM id token for the root and list ids."
+        option :placeholder, :string, doc: "Placeholder text shown while the input is empty."
+        option :label, :string, doc: "The accessible name (or wire aria-labelledby via html attrs)."
+        option :empty_text, :string, default: "No results.",
+                                     doc: "The no-matches message; hidden while anything matches."
+        option :open, :boolean, default: false, doc: "Server-renders the suggestion popup open."
+        option :open_on_focus, :boolean, default: true, doc: "Opens the suggestions on focus; false waits for typing."
+
+        part "autocomplete", "Root wrapper carrying the controller + popper pair"
+        part "autocomplete-input", "The REAL text input - role=combobox with aria-expanded " \
+                                   "tracking the popup, the form value itself"
+        part "autocomplete-content", "The popper-positioned popup shell",
+             states: {
+               "data-open" => "popup visible",
+               "data-closed" => "popup hidden (the server-rendered default)",
+               "data-empty" => "no item matches the query - the empty state shows"
+             }
+        part "autocomplete-list", "role=listbox holding the options"
+        part "autocomplete-item", "One suggestion - role=option; commit writes its label " \
+                                  "(or value:) into the input",
+             states: {
+               "data-label" => "always - what filtering matches and commit writes",
+               "data-value" => "value: given - overrides the committed text",
+               "data-highlighted" => "the keyboard/pointer highlight",
+               "data-disabled" => "disabled: - skipped by filtering and commit"
+             }
+        part "autocomplete-empty", "The no-matches message (hidden while anything matches)"
+
+        # Forces the composition block so with_item calls land before the template renders.
+        # @api private
+        def before_render
+          content
+        end
+
+        # Hand-rolled builder: ViewComponent lambda slots nil-wrap
+        # non-component returns, so the builder collects plain models and
+        # before_render forces the composition block.
+
+        # Adds one suggestion to the popup list.
+        #
+        # @param label [String] what filtering matches and what commit writes into the input
+        # @param value [String, nil] overrides the committed text when it differs from the label
+        # @param disabled [Boolean] skipped by filtering and commit
+        # @param highlighted [Boolean] server-renders the item highlighted
+        def with_item(label:, value: nil, disabled: false, highlighted: false)
+          item_models << Item.new(label: label, value: value, disabled: disabled,
+                                  highlighted: highlighted)
+          self
+        end
+
+        # The collected suggestion models.
+        # @api private
+        def item_models = (@item_models ||= [])
+
+        # @api private
+        def autocomplete_id
+          @autocomplete_id ||= if (token = dom_id_token(id))
+                                 "poetry-autocomplete-#{token}"
+                               else
+                                 poetry_instance_id("poetry-autocomplete")
+                               end
+        end
+
+        # @api private
+        def list_id = "#{autocomplete_id}-list"
+
+        # @api private
+        def root_attributes
+          html_attributes.merge_if_not_set(
+            { "class" => css, "data-slot" => "autocomplete", "id" => autocomplete_id }
+              .merge(stimulus_attributes_for(:root))
+              .merge(component_data_attributes)
+          )
+        end
+
+        # @api private
+        def input_attributes
+          attrs = {
+            name: name, value: value, placeholder: placeholder, type: :text,
+            autocomplete: "off", role: "combobox",
+            "aria-autocomplete": "list", "aria-expanded": open.to_s, "aria-controls": list_id,
+            "data-slot": "autocomplete-input"
+          }
+          attrs[:"aria-label"] = label if label.present?
+          attrs.merge(stimulus_attributes_for(:input).transform_keys(&:to_sym))
+        end
+
+        # @api private
+        def content_attributes
+          attrs = {
+            "class" => css(:content), "data-slot" => "autocomplete-content"
+          }
+          if open
+            attrs["data-open"] = ""
+          else
+            attrs["data-closed"] = ""
+            attrs["hidden"] = "hidden"
+          end
+          attrs.merge(stimulus_attributes_for(:content))
+        end
+
+        # @api private
+        def item_attributes(item, index)
+          attrs = {
+            "class" => Poetry::Ui::Command::Style.css(:item), "data-slot" => "autocomplete-item",
+            "id" => "#{autocomplete_id}-item-#{index}", "role" => "option",
+            "data-label" => item.label
+          }
+          attrs["data-value"] = item.value if item.value.present?
+          attrs["data-highlighted"] = "" if item.highlighted
+          attrs["data-disabled"] = "" if item.disabled
+          attrs["aria-disabled"] = "true" if item.disabled
+          attrs.merge(stimulus_attributes_for(:item))
+        end
+
+        # One suggestion's plain data model, collected by with_item.
+        # @api private
+        Item = Struct.new(:label, :value, :disabled, :highlighted, keyword_init: true)
+
+        private :item_models, :autocomplete_id, :list_id, :root_attributes, :input_attributes, :content_attributes
+        private :item_attributes
+      end
+    end
+  end
+end

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

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Ui
+    module Autocomplete
+      # The Autocomplete matrix: the closed hero, the server-rendered open
+      # state with a highlight (the contract carrier for data-open /
+      # data-highlighted), a value-override item, and the empty state.
+      class Preview < Poetry::Core::Preview::Base
+        def default
+          render_component(name: "tag", placeholder: "e.g. feature", label: "Search tags",
+                           class: "w-64") do |auto|
+            auto.with_item(label: "feature")
+            auto.with_item(label: "fix")
+            auto.with_item(label: "docs")
+            auto.with_item(label: "internal")
+            auto.with_item(label: "mobile", disabled: true)
+          end
+        end
+
+        # Server-rendered open + highlighted (the states the contract holds).
+        def open_and_highlighted
+          render_component(name: "city", value: "sp", open: true, label: "City",
+                           class: "w-64") do |auto|
+            auto.with_item(label: "Springfield", highlighted: true)
+            auto.with_item(label: "Spokane")
+            auto.with_item(label: "São Paulo", value: "Sao Paulo")
+          end
+        end
+
+        # No items at all: the empty message is the whole popup.
+        def empty_state
+          render_component(name: "search", open: true, label: "Search", open_on_focus: false,
+                           empty_text: "Nothing matches.", class: "w-64")
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Ui
+    module Autocomplete
+      # The Autocomplete wears the Combobox/Command visual language (the
+      # popup shell and item treatments are the same family upstream);
+      # no autocomplete-specific theme rules exist in the upstream
+      # dictionaries, so every class here is already-emitted vocabulary.
+      class Style < Poetry::Core::Style
+        base "relative"
+
+        element :content, "cn-combobox-content cn-menu-translucent z-50 w-(--anchor-width) " \
+                          "origin-(--transform-origin) outline-hidden"
+      end
+    end
+  end
+end

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

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Ui
+    # Person images with initials fallbacks.
+    module Avatar
+      # A person's image over an always-rendered initials fallback. The
+      # image layers absolutely above the fallback with an empty alt, so a
+      # failed load paints nothing and the initials show through - zero
+      # JS, no layout shift. The accessible name lives on the root
+      # (role=img + aria-label via label:), never on the layered img.
+      #
+      # @example Image with initials fallback
+      #   render Poetry::Ui::Avatar::Component.new(src: user.avatar_url, label: "Ada Lovelace") { "AL" }
+      class Component < Poetry::Core::Component
+        requires_content "the initials fallback"
+
+        # The closed vocabulary for the size axis.
+        SIZES = %i[default sm lg].freeze
+
+        # Projected into the registry, llms.txt, and the agent surface.
+        AGENT_RULES = [
+          "label: (the person's name) is REQUIRED - it is the avatar's accessible name (role=img).",
+          "The content block is the fallback (initials) and is also required - it is what shows " \
+          "while the image loads or when it fails.",
+          "The badge slot is decorative (a presence dot); put the status meaning in label:, " \
+          "not in the badge.",
+          "Stack avatars with poetry_avatar_group; the overflow count is poetry_avatar_group_count."
+        ].freeze
+
+        renders_one :badge, doc: "Decorative presence dot, bottom-right; keep the status meaning in label:."
+
+        option :src, :string, doc: "The image URL; without it only the initials fallback shows."
+        option :label, :string, required: true,
+                                doc: "The person's name - the avatar's accessible name (blank raises). The required " \
+                                     "flag also carries the fact to the registry so static checks see it."
+        option :size, :symbol, default: :default, doc: "The diameter axis."
+
+        validates :size, inclusion: { in: SIZES }
+
+        part "avatar", "Root span (role=img carrying the accessible name) - fallback, image, " \
+                       "and badge layer inside it",
+             states: {
+               "data-size" => { condition: "always - the resolved size", values: SIZES.map(&:to_s) }
+             }
+        part "avatar-fallback", "The initials layer (the content block) - always in the DOM, " \
+                                "showing until the image covers it"
+        part "avatar-image", "The <img> layered absolutely over the fallback - only when src: " \
+                             "is given; a failed load paints nothing"
+        part "avatar-badge", "The decorative presence dot (the badge slot), bottom-right"
+
+        # Enforces label: and the initials content block.
+        # @api private
+        def before_render
+          raise ArgumentError, "Avatar requires label: (the person's name - its accessible name)" if label.blank?
+
+          ensure_content!
+        end
+
+        # @api private
+        def call
+          content_tag(:span, root_attributes.to_attributes) do
+            safe_join([fallback, image, badge_part].compact)
+          end
+        end
+
+        # @api private
+        def root_attributes
+          html_attributes.merge_if_not_set(
+            {
+              "data-slot" => "avatar", "data-size" => size,
+              "role" => "img", "aria-label" => label
+            }.merge(component_data_attributes)
+          )
+        end
+
+        private
+
+        def fallback
+          content_tag(:span, content, "data-slot" => "avatar-fallback", "aria-hidden" => "true",
+                                      class: css(:fallback))
+        end
+
+        def image
+          return if src.blank?
+
+          # alt="" on purpose: the root carries the name, and an empty alt
+          # keeps a FAILED load from painting a broken-image glyph over the
+          # initials - the layered-fallback contract.
+          tag.img(src: src, alt: "", "data-slot": "avatar-image", class: css(:image))
+        end
+
+        def badge_part
+          return unless badge?
+
+          content_tag(:span, badge, "data-slot" => "avatar-badge", "aria-hidden" => "true", class: css(:badge))
+        end
+
+        private :root_attributes
+      end
+    end
+  end
+end

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

@@ -0,0 +1,11 @@
+<%# The stacked group: overlapping avatars ringed by the background, with
+    the overflow count - the poetry_avatar_group / _group_count part
+    helpers. %>
+<div class="p-4">
+  <%= poetry_avatar_group do %>
+    <%= poetry_avatar(label: "Grace Hopper") { "GH" } %>
+    <%= poetry_avatar(label: "Ada Lovelace") { "AL" } %>
+    <%= poetry_avatar(label: "Annie Easley") { "AE" } %>
+    <%= poetry_avatar_group_count { "+3" } %>
+  <% end %>
+</div>