poetry-ui 0.0.2

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

@@ -0,0 +1,185 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Ui
+    # Hover/focus text hints.
+    module Tooltip
+      # The placement vocabularies - the popper-consumer kit owns them.
+      SIDES = Poetry::Ui::PopperConsumer::SIDES
+      # The closed vocabulary for the align axis.
+      ALIGNS = Poetry::Ui::PopperConsumer::ALIGNS
+
+      # A hover/focus text hint. The bubble describes its trigger and
+      # never receives focus: content is role=tooltip, the trigger's
+      # aria-describedby exists only while open (a description pointing
+      # at hidden content mis-announces), and no aria-haspopup/expanded
+      # is written - a tooltip is a description, not a popup the user
+      # operates. Opening is delayed on hover but instant on keyboard
+      # focus; only one tooltip is open globally; Esc closes the tooltip
+      # first when overlays are stacked; touch never opens one, so
+      # essential information must never live only in a tooltip.
+      #
+      # Content must be plain text, never interactive - use Popover for
+      # links or controls. Wrap rows of triggers in one
+      # poetry_tooltip_provider so moving along the row skips the delay.
+      #
+      # @example A described icon button
+      #   render Poetry::Ui::Tooltip::Component.new do |tooltip|
+      #     tooltip.with_trigger(variant: :outline, size: :icon, label: "Print") do
+      #       poetry_icon(name: :printer)
+      #     end
+      #     "Print the current page"
+      #   end
+      class Component < Poetry::Core::Component
+        include Poetry::Ui::ComposableTrigger
+        include Poetry::Ui::PopperConsumer
+
+        # Projected into the registry, llms.txt, and the agent surface.
+        AGENT_RULES = [
+          ComposableTrigger::AGENT_RULE,
+          "Use poetry_tooltip - never hand-roll title-attribute replacements or hover divs.",
+          "Tooltip content is TEXT and never interactive/focusable - links, buttons, or inputs inside " \
+          "are a contract violation (use Popover).",
+          "Never put essential information only in a tooltip - touch users NEVER see it (no long-press " \
+          "path, by design).",
+          "The tooltip DESCRIBES; it never names. Icon-only triggers still require label: on the " \
+          "composed Button.",
+          "Wrap toolbar/button rows in ONE poetry_tooltip_provider so the warm grace makes the row " \
+          "feel continuous.",
+          "Rich visual content needs label: (the plain-text announcement).",
+          "Do not pin tooltips open as onboarding callouts - that is a Popover."
+        ].freeze
+
+        # The same facts the before_render raise enforces, stated statically:
+        # poetry check flags the omission without rendering.
+        REQUIRED_SLOTS = { trigger: "the described control" }.freeze
+
+        # The component behind the forwarding slot: with_trigger renders a Button.
+        SLOT_RENDERS = { trigger: Button::Component }.freeze
+
+        renders_one :trigger,
+                    doc: "The described control - commonly a poetry Button (with_trigger(variant: :outline) { " \
+                         "\"Hover\" }). The slot owns the state + timing wiring regardless of the composed content. " \
+                         "NO aria-haspopup/expanded/controls - the tooltip is invisible as a popup; " \
+                         "aria-describedby is written by the controller on open (and server-rendered only when " \
+                         "open: true).",
+                    renders: lambda { |**options, &block|
+                      wiring = {
+                        "id" => trigger_id, "data-slot" => "tooltip-trigger"
+                      }.merge(stimulus_attributes_for(:trigger))
+                      # Open state is a bare data-popup-open presence attribute -
+                      # absent while closed (absence IS the state).
+                      wiring["data-popup-open"] = "" if open
+                      wiring["aria-describedby"] = content_id if open
+                      composed_trigger(wiring, options, &block) ||
+                        Button::Component.new(**wiring, **options, &block)
+                    }
+
+        use_stimulus do
+          on :root do
+            # Full identifier: the bare :tooltip suffix is ambiguous the
+            # moment a host also loads poetry-charts (poetry--charts--
+            # tooltip joins the manifest catalog).
+            controller "poetry--core--tooltip" do
+              register
+              value :open
+              # Inherit-from-provider: unset renders NO attribute - the
+              # controller falls back to [data-slot=tooltip-provider].
+              value :delay_duration, unless: -> { delay_duration.nil? }
+              value :disable_hoverable_content, unless: -> { disable_hoverable_content.nil? }
+            end
+            controller :popper do
+              register
+              value :side
+              value :align
+              value :side_offset
+              value :align_offset
+              value :avoid_collisions
+            end
+          end
+          # The trigger handlers: pointermove opens (touch excluded, once
+          # per hover), pointerdown/click close, focus opens instantly /
+          # blur closes.
+          on :trigger do
+            controller "poetry--core--tooltip" do
+              action :pointer_move, on: :pointermove
+              action :pointer_leave, on: :pointerleave
+              action :pointer_down, on: :pointerdown
+              action :click_close, on: :click
+              action :focus_open, on: :focus
+              action :blur_close, on: :blur
+            end
+            controller(:popper) { target :anchor }
+          end
+          on :content do
+            controller(:popper) { target :content }
+          end
+          # The arrow's positioning target.
+          on :arrow do
+            controller(:popper) { target :arrow }
+          end
+        end
+
+        option :open, :boolean, default: false, doc: "Server-renders the tooltip open."
+        option :delay_duration, :integer, doc: "The hover-open delay in ms; nil inherits the provider's (default 0)."
+        option :disable_hoverable_content, :boolean,
+               doc: "When true the bubble closes as the pointer leaves the trigger - it cannot be hovered into; nil " \
+                    "inherits the provider."
+        # Placement defaults: :top with side_offset 0 (the arrow supplies the gap).
+        popper_placement_options(side: :top, side_offset: 0)
+        option :label, :string,
+               doc: "Plain-text announcement override for rich content (the visual children stay; the announced body " \
+                    "becomes this text)."
+        option :content_class, :string, doc: "The bubble's class merge seam (caller classes win on conflicts)."
+
+        part "tooltip", "Root wrapper around the trigger and the bubble"
+        part "tooltip-content", "The role=tooltip bubble - positioning, animation, and the open " \
+                                "state ride here",
+             states: {
+               "data-open" => "bubble is open (the controller flips the pair at runtime)",
+               "data-closed" => "bubble is closed (the server-rendered state; hidden rides along)",
+               "data-instant" => { condition: "the open skipped the delay - warm-grace/" \
+                                              "programmatic or keyboard focus (runtime-only; " \
+                                              "absent on a delayed open)",
+                                   values: %w[delay focus] },
+               "data-side" => { condition: "always - the side (initial placement, re-resolved " \
+                                           "live by popper after flip)",
+                                values: SIDES.map(&:to_s) },
+               "data-align" => { condition: "always - the alignment (re-resolved live by popper)",
+                                 values: ALIGNS.map(&:to_s) }
+             },
+             vars: Poetry::Ui::PopperConsumer.content_vars("bubble")
+        part "tooltip-arrow", "The arrow wrapper (aria-hidden) - popper pins it to the bubble's " \
+                              "anchor-facing edge and rotates it toward the anchor",
+             states: {
+               "data-side" => { condition: "written by popper alongside the content's - the " \
+                                           "resolved side, for per-side restyling",
+                                values: SIDES.map(&:to_s) }
+             }
+
+        # @api private
+        def before_render
+          raise ArgumentError, "Tooltip requires with_trigger (the described control)" unless trigger?
+        end
+
+        # @api private
+        def content_attributes
+          # A server-pinned open tooltip renders bare data-open; the
+          # controller adds data-instant on ITS opens - the reason
+          # attribute is runtime-only.
+          attrs = {
+            "id" => content_id, "role" => "tooltip",
+            "data-slot" => "tooltip-content", (open ? "data-open" : "data-closed") => "",
+            # Initial placement, re-resolved live by popper on open.
+            "data-side" => side, "data-align" => align,
+            "class" => css(:content, class: content_class)
+          }.merge(stimulus_attributes_for(:content))
+          attrs["hidden"] = true unless open
+          attrs
+        end
+
+        private :content_attributes
+      end
+    end
+  end
+end

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

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Ui
+    module Tooltip
+      # The Tooltip preview matrix: the ported tooltip-demo composition,
+      # the provider warm row (one scope, three controls), the label:
+      # announcement override, a placement sample, the provider-style opt-back
+      # delay, and the server-pinned open state.
+      class Preview < Poetry::Core::Preview::Base
+        # The tooltip-demo port: outline Button trigger, plain text hint.
+        def default
+          render_component do |tooltip|
+            tooltip.with_trigger(variant: :outline) { "Hover" }
+            "Add to library"
+          end
+        end
+
+        # ONE provider scope: the first open is delayed, sweeping along
+        # the row is instant (the warm grace), cold again 300ms after
+        # leaving - wrap toolbar rows exactly like this.
+        def provider_row
+          render_with_template
+        end
+
+        # Rich visual content with label: - the announced body is the
+        # plain-text label; the visual children stay (the kbd recipe).
+        def with_label
+          render_component(label: "Command S saves the document") do |tooltip|
+            tooltip.with_trigger(variant: :outline, label: "Save shortcut") { "Save" }
+            "Saves the document <kbd>⌘S</kbd>".html_safe
+          end
+        end
+
+        # Server-pinned open (controllable-state; the controller
+        # reconciles describedby + the layer on connect).
+        def open
+          render_component(open: true) do |tooltip|
+            tooltip.with_trigger(variant: :outline) { "Pinned" }
+            "Server-rendered open"
+          end
+        end
+
+        # Placement sample (the ported source defaults side: :top - the trio's
+        # odd one out; the arrow follows the resolved side).
+        def side_bottom
+          render_component(side: :bottom, align: :start) do |tooltip|
+            tooltip.with_trigger(variant: :outline) { "Below" }
+            "side: :bottom, align: :start"
+          end
+        end
+
+        # the provider-style opt-back for hint-dense screens: the source's provider
+        # default is 0ms; 700ms is the recommended delay when a page is
+        # dense with tooltips.
+        def delayed
+          render_component(delay_duration: 700) do |tooltip|
+            tooltip.with_trigger(variant: :outline) { "Patient hover" }
+            "Opens after 700ms"
+          end
+        end
+
+        # disable_hoverable_content: true - pointing at the card itself
+        # never holds it open (the strict hover mode).
+        def not_hoverable
+          render_component(disable_hoverable_content: true) do |tooltip|
+            tooltip.with_trigger(variant: :outline) { "Hover" }
+            "Closes the moment you leave the trigger"
+          end
+        end
+      end
+    end
+  end
+end

data/app/components/poetry/ui/tooltip/previews/provider_row.html.erb

@@ -0,0 +1,25 @@
+<%# ONE provider scope wrapping a control row: the first tooltip opens
+    delayed, sweeping along the row opens instantly (the warm grace), and
+    the scope cools 300ms after leaving - the toolbar recipe. %>
+<div class="p-4">
+  <%= poetry_tooltip_provider(delay_duration: 700, class: "flex items-center gap-2") do %>
+    <%= poetry_tooltip do |tooltip| %>
+      <% tooltip.with_trigger(variant: :outline, size: :icon, label: "Add") do %>
+        <%= poetry_icon(name: :plus) %>
+      <% end %>
+      Add
+    <% end %>
+    <%= poetry_tooltip do |tooltip| %>
+      <% tooltip.with_trigger(variant: :outline, size: :icon, label: "Confirm") do %>
+        <%= poetry_icon(name: :check) %>
+      <% end %>
+      Confirm
+    <% end %>
+    <%= poetry_tooltip do |tooltip| %>
+      <% tooltip.with_trigger(variant: :outline, size: :icon, label: "Dismiss") do %>
+        <%= poetry_icon(name: :x) %>
+      <% end %>
+      Dismiss
+    <% end %>
+  <% end %>
+</div>

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

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Ui
+    module Tooltip
+      # Re-expressed through the cn-* theme layer. The inverse scheme
+      # (bg-foreground/text-background) stays INLINE per upstream's own
+      # split - it IS the treatment and upstream keeps it in markup; the
+      # box, type, and animation chain ride the theme (animate-in remains
+      # UNGATED there, source-exact).
+      class Style < Poetry::Core::Style
+        element :content, "cn-tooltip-content z-50 w-fit origin-(--transform-origin) bg-foreground " \
+                          "text-background max-w-xs"
+
+        # The arrow: popper positions/rotates the outer box; the visual
+        # size/rounding rides the theme, the paint + geometry stay inline.
+        # block: the diamond is a bare span - inline boxes IGNORE size-2.5,
+        # which left the arrow 0x0 (invisible) in every theme since the port.
+        element :arrow, "cn-tooltip-arrow z-50 block translate-y-[calc(-50%_-_2px)] rotate-45 " \
+                        "bg-foreground fill-foreground"
+      end
+    end
+  end
+end

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

@@ -0,0 +1,32 @@
+<%# The flat treegrid: every row a sibling, hierarchy in aria-* computed
+    server-side, rows under collapsed ancestors hidden. %>
+<%= content_tag(:div, **root_attributes.to_attributes) do %>
+  <% if rows.any? %>
+    <% rows.each_with_index do |row, index| %>
+      <%= content_tag(:div, **Poetry::Core::HTML::Attributes.new(row_attributes(row, index)).to_attributes) do %>
+        <span role="gridcell" class="<%= css(:cell) %>">
+          <% if row.expandable %>
+            <%= content_tag(:button, **Poetry::Core::HTML::Attributes.new(toggle_attributes(row, index)).to_attributes) do %>
+              <%= render Poetry::Ui::Icon::Component.new(name: :"chevron-right") %>
+            <% end %>
+          <% else %>
+            <span class="<%= css(:toggle_spacer) %>" aria-hidden="true"></span>
+          <% end %>
+          <% if row.href.present? && !row.disabled %>
+            <a href="<%= row.href %>" data-slot="tree-item-label" class="<%= css(:label) %>" tabindex="-1"><%= row.text %></a>
+          <% else %>
+            <span data-slot="tree-item-label" class="<%= css(:label) %>"><%= row.text %></span>
+          <% end %>
+        </span>
+      <% end %>
+    <% end %>
+  <% else %>
+    <%# An empty treegrid with bare content is invalid ARIA - the empty
+        state wraps in a placeholder row > gridcell (the contract). %>
+    <div role="row" aria-level="1" data-slot="tree-item" data-value tabindex="-1" class="<%= css(:item) %>" style="--poetry-tree-level: 1">
+      <span role="gridcell" class="<%= css(:cell) %>">
+        <span data-slot="tree-item-label" class="text-muted-foreground"><%= t("poetry.tree.empty") %></span>
+      </span>
+    </div>
+  <% end %>
+<% end %>

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

@@ -0,0 +1,233 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Ui
+    # Hierarchical expandable lists.
+    module Tree
+      # A hierarchical expandable list - file navigators, nested
+      # categories, org structures. The DOM is a flat list of sibling
+      # rows; hierarchy lives entirely in server-computed
+      # aria-level/posinset/setsize, so no nested markup is needed and
+      # the whole tree server-renders. Rows under a collapsed ancestor
+      # render hidden. Arrow keys move over visible rows,
+      # ArrowLeft/Right collapse and expand (ArrowLeft on a leaf walks to
+      # the parent), Enter/press toggles, and typing jumps to a matching
+      # row.
+      #
+      # Items build through a nested builder (see with_item). Expansion
+      # state lives in the DOM - persist it by listening for
+      # poetry:tree:toggle and re-rendering with expanded: from your
+      # store. href: items navigate; a Tree offers no selection modes.
+      #
+      # @example
+      #   <%= poetry_tree(label: "Files") do |tree| %>
+      #     <% tree.with_item(text: "docs", value: "docs", expanded: true) do |docs| %>
+      #       <% docs.with_item(text: "intro.md", value: "intro", href: "/docs/intro") %>
+      #     <% end %>
+      #   <% end %>
+      class Component < Poetry::Core::Component
+        # Projected into the registry, llms.txt, and the agent surface.
+        AGENT_RULES = [
+          "Hierarchical expandable lists are a Tree - never hand-rolled nested <ul>s with " \
+          "click handlers; the treegrid semantics, expansion keys, and focus rules ride the " \
+          "controller.",
+          "label: is REQUIRED (the treegrid's accessible name).",
+          "Items: tree.with_item(text:, value:, expanded:, disabled:, href:) with nesting via " \
+          "the block - the component flattens and computes aria-level/posinset/setsize.",
+          "Expansion is client state; persist it by listening for poetry:tree:toggle and " \
+          "re-rendering with expanded: from your store.",
+          "Navigation destinations take href: (the label renders as a link); a Tree is not a " \
+          "menu - actions belong to DropdownMenu, picking to Select/Combobox."
+        ].freeze
+
+        use_stimulus do
+          on :root do
+            controller :tree do
+              register
+              action :keydown, on: :keydown
+              action :press, on: :click
+            end
+          end
+          on :toggle do
+            controller :tree do
+              action :pressStart, on: :pointerdown
+              action :toggle, on: :click
+            end
+          end
+        end
+
+        option :label, :string, required: true, doc: "The tree's accessible name. Required."
+
+        part "tree", "The treegrid container (role=treegrid, the accessible name) - roving " \
+                     "focus, expansion keys, and typeahead ride here; rows are FLAT siblings"
+        part "tree-item", "One row (role=row > gridcell) - hierarchy in aria-level/posinset/" \
+                          "setsize, indentation via --poetry-tree-level; rows under a " \
+                          "collapsed ancestor render hidden",
+             states: {
+               "data-expanded" => "the row's subtree is open (parents only; aria-expanded " \
+                                  "is the canonical twin)",
+               "data-disabled" => "the item is disabled (skipped by arrows and typeahead)",
+               "data-value" => { condition: "always - the toggle event's identity" },
+               "data-level" => { condition: "always - the 1-based depth (aria-level's twin; " \
+                                            "--poetry-tree-level drives the indent)" }
+             },
+             vars: {
+               "--poetry-tree-level" => "the 1-based depth - indentation is " \
+                                        "calc((level - 1) * step) in the dictionary"
+             }
+        part "tree-item-toggle", "The chevron (parents only): tabindex -1, never steals " \
+                                 "focus, aria-label flips Expand/Collapse",
+             states: {
+               "data-expand-label" => "always - the localized Expand string the controller " \
+                                      "swaps in on collapse",
+               "data-collapse-label" => "always - the localized Collapse string the " \
+                                        "controller swaps in on expand"
+             }
+        part "tree-item-label", "The row's text - a link when href: is given"
+
+        # @api private
+        def before_render
+          raise ArgumentError, "Tree requires label: (the treegrid's accessible name)" if label.blank?
+
+          # Consume the content block: it runs for its with_item side
+          # effects (the builder API), never for output.
+          content
+        end
+
+        # Declares one row. Nest children by calling with_item again on the
+        # yielded builder. Keywords: text: (the row's label, required), value:
+        # (the toggle event's identity, defaults to text:), expanded: (render
+        # the subtree open), disabled:, href: (the label renders as a link).
+        #
+        # @example
+        #   tree.with_item(text: "docs", value: "docs", expanded: true) do |docs|
+        #     docs.with_item(text: "intro.md", href: "/docs/intro")
+        #   end
+        def with_item(**, &block)
+          root_items << Item.new(**).tap { |item| block&.call(item) }
+          nil
+        end
+
+        # @api private
+        def root_items
+          @root_items ||= []
+        end
+
+        # @api private
+        def rows
+          @rows ||= flatten(root_items, level: 1, hidden: false)
+        end
+
+        # @api private
+        def root_attributes
+          html_attributes.merge_if_not_set(
+            {
+              "data-slot" => "tree", "role" => "treegrid",
+              "aria-label" => label, "class" => css
+            }.merge(component_data_attributes).merge(stimulus_attributes_for(:root))
+          )
+        end
+
+        # @api private
+        def row_attributes(row, index)
+          attrs = {
+            "id" => row_id(index), "role" => "row", "data-slot" => "tree-item",
+            "data-value" => row.value, "data-level" => row.level,
+            "aria-level" => row.level, "aria-posinset" => row.posinset,
+            "aria-setsize" => row.setsize,
+            "tabindex" => index == first_visible_index ? "0" : "-1",
+            "style" => "--poetry-tree-level: #{row.level}",
+            "class" => css(:item)
+          }
+          attrs["aria-expanded"] = row.expanded.to_s if row.expandable
+          attrs["data-expanded"] = "" if row.expandable && row.expanded
+          if row.disabled
+            attrs["data-disabled"] = ""
+            attrs["aria-disabled"] = "true"
+          end
+          attrs["hidden"] = "" if row.hidden
+          attrs
+        end
+
+        # @api private
+        def toggle_attributes(row, index)
+          {
+            "type" => "button", "tabindex" => "-1",
+            "data-slot" => "tree-item-toggle", "class" => css(:toggle),
+            "aria-label" => row.expanded ? t("poetry.tree.collapse") : t("poetry.tree.expand"),
+            "aria-labelledby" => "#{row_id(index)}-toggle #{row_id(index)}",
+            "id" => "#{row_id(index)}-toggle",
+            "data-expand-label" => t("poetry.tree.expand"),
+            "data-collapse-label" => t("poetry.tree.collapse")
+          }.merge(stimulus_attributes_for(:toggle))
+        end
+
+        # @api private
+        def row_id(index)
+          "#{tree_id}-item-#{index}"
+        end
+
+        # @api private
+        def tree_id
+          @tree_id ||= poetry_instance_id("poetry-tree")
+        end
+
+        # @api private
+        def first_visible_index
+          @first_visible_index ||= rows.index { |row| !row.hidden } || 0
+        end
+
+        # One flattened row (built by #flatten below).
+        # @api private
+        Row = Struct.new(
+          :text, :value, :href, :level, :posinset, :setsize,
+          :expanded, :expandable, :disabled, :hidden,
+          keyword_init: true
+        )
+
+        # The nested builder yielded to item blocks - call with_item on it
+        # to declare children. Never constructed directly.
+        class Item
+          # @api private
+          attr_reader :options, :children
+
+          # @api private
+          def initialize(**options)
+            @options = options
+            @children = []
+          end
+
+          # Declares a child row; takes the same keywords as the
+          # component's with_item and yields its own builder for nesting.
+          def with_item(**)
+            child = Item.new(**)
+            @children << child
+            yield child if block_given?
+            child
+          end
+        end
+
+        private
+
+        def flatten(items, level:, hidden:)
+          items.flat_map.with_index do |item, index|
+            expandable = item.children.any?
+            expanded = expandable && item.options.fetch(:expanded, false)
+            row = Row.new(
+              text: item.options.fetch(:text), value: item.options[:value] || item.options.fetch(:text),
+              href: item.options[:href], level: level,
+              posinset: index + 1, setsize: items.size,
+              expanded: expanded, expandable: expandable,
+              disabled: item.options.fetch(:disabled, false), hidden: hidden
+            )
+
+            [row] + flatten(item.children, level: level + 1, hidden: hidden || !expanded)
+          end
+        end
+
+        private :root_items, :rows, :root_attributes, :row_attributes, :toggle_attributes, :row_id, :tree_id
+        private :first_visible_index
+      end
+    end
+  end
+end

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

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Ui
+    module Tree
+      class Preview < Poetry::Core::Preview::Base
+        def default
+          render_component(label: "Files") do |tree|
+            tree.with_item(text: "docs", value: "docs", expanded: true) do |docs|
+              docs.with_item(text: "guides", value: "guides") do |guides|
+                guides.with_item(text: "intro.md", value: "intro")
+                guides.with_item(text: "advanced.md", value: "advanced")
+              end
+              docs.with_item(text: "README.md", value: "docs-readme")
+            end
+            tree.with_item(text: "src", value: "src") do |src|
+              src.with_item(text: "main.rb", value: "main")
+            end
+            tree.with_item(text: "LICENSE", value: "license")
+          end
+        end
+
+        # Server-persisted expansion: collapsed parents render their
+        # subtree hidden; nested collapsed state survives cycles.
+        def deeply_nested
+          render_component(label: "Organization") do |tree|
+            tree.with_item(text: "Engineering", value: "eng", expanded: true) do |eng|
+              eng.with_item(text: "Platform", value: "platform", expanded: true) do |platform|
+                platform.with_item(text: "Infra", value: "infra") do |infra|
+                  infra.with_item(text: "On-call", value: "oncall")
+                end
+              end
+              eng.with_item(text: "Product", value: "product", disabled: true)
+            end
+            tree.with_item(text: "Design", value: "design")
+          end
+        end
+
+        # href: items render their labels as links (a file navigator).
+        def with_links
+          render_component(label: "Pages") do |tree|
+            tree.with_item(text: "Getting started", value: "start", expanded: true) do |start|
+              start.with_item(text: "Install", value: "install", href: "#install")
+              start.with_item(text: "Theming", value: "theming", href: "#theming")
+            end
+          end
+        end
+
+        def empty
+          render_component(label: "Files")
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Ui
+    module Tree
+      # Utility-only (the Separator/Spinner rule): rows indent off the
+      # server-stamped --poetry-tree-level custom property, the chevron
+      # rotates on the row's data-expanded (group-scoped), and focus rides
+      # a ring on the row itself. data-slot selectors are the restyle seam.
+      class Style < Poetry::Core::Style
+        base "flex w-full flex-col gap-px outline-none"
+
+        element :item, "group/tree-item flex cursor-default items-center gap-1.5 rounded-md " \
+                       "py-1.5 pr-2 text-sm outline-none " \
+                       "pl-[calc(0.5rem+(var(--poetry-tree-level)-1)*1.25rem)] " \
+                       "hover:bg-accent/50 " \
+                       "focus-visible:ring-[3px] focus-visible:ring-ring/50 " \
+                       "data-disabled:pointer-events-none data-disabled:opacity-50"
+        element :cell, "contents"
+        element :toggle, "inline-flex size-4 shrink-0 items-center justify-center rounded-sm " \
+                         "text-muted-foreground outline-none transition-transform " \
+                         "group-data-[expanded]/tree-item:rotate-90 [&_svg]:size-3.5"
+        # Leaves keep the chevron's footprint so labels align across levels.
+        element :toggle_spacer, "inline-flex size-4 shrink-0"
+        element :label, "truncate text-foreground no-underline"
+      end
+    end
+  end
+end