poetry-ui 0.1.4 → 0.1.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1dc3d057d2a1fd8016bbf07932226f34cc1cb43ae92fab30787e8111790d7737
-  data.tar.gz: dc55e865b56c2616c1b3bc071aebb6b6ef1d597159e468972be626b45242e65d
+  metadata.gz: 2ba8f8052a42b9369be8d97fb6e751471cf5e058080a0cb517d77d186883ece2
+  data.tar.gz: 22de85bd6a2f822bb9f9ff051cad36fb78a03d21b08e24d9766944d21b2ff045
 SHA512:
-  metadata.gz: '011951d31c612220f1b733879608a7c47fba2e713b293b651cd615fe240018000eae5118a391aeb87141c0c20132b9a55fa96a9fb205c8090e5896ca7f7b11a8'
-  data.tar.gz: 43ffba5aa6ee261bfee9f0b7d6e8283069672f62fc38666c9572a76ce18720a6d9622f84a1db07d155f7e6bf427fe5594ae69b71d15170110442eec1465d57b1
+  metadata.gz: 2668065dbf0776b50fb721b5feb212d56b3062171ff0de0c0551ba094469cab0c810ec2ef26e4be21b2d8c98d8503fddaabbcc287befa37711f7111b6478df21
+  data.tar.gz: 3b3b38c3242ebb5ef265551bc008e5d44bff9e2f37b083a4b237a7f9b779f319625c23d7403b28b0f78151e7715b309ea90c0465fc47c303a7a1deffead9504c

data/.mcp.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "rubydex": {
+      "command": "bundle",
+      "args": ["exec", "rdx", "mcp"]
+    }
+  }
+}

data/.yard-lint.yml

@@ -0,0 +1,25 @@
+# yard-lint: the documentation tier YARD's own gates miss - a documented
+# method missing a @param, an @example that does not parse, option tags,
+# tag order, invalid types. Runs as rake yard:lint (in the default task).
+# UndocumentedObjects stays off: yard:coverage gates public objects at its
+# recorded floor, and this validator counts the @api private internals the
+# gems hide on purpose (--hide-api is not honoured here). MissingReturn is
+# off until the @param backlog is cleared; revisit then.
+AllValidators:
+  YardOptions:
+    - --no-private
+Documentation/UndocumentedObjects:
+  Enabled: false
+Documentation/MissingReturn:
+  Enabled: false
+Tags/InvalidTypes:
+  Enabled: true
+# A **options splat passed through to a control is documented as @param
+# options [Hash], not one @option per key; and @example blocks here are
+# ERB as often as Ruby, which this validator cannot parse.
+Documentation/UndocumentedOptions:
+  Enabled: false
+Tags/OptionTags:
+  Enabled: false
+Tags/ExampleSyntax:
+  Enabled: false

data/.yard_coverage_all

@@ -0,0 +1 @@
+0

data/Archspec.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+# The architecture the family enforces by review, as checks (rake arch:check).
+# ui depends on core alone. lib reaches the components only through the
+# registry; the test helpers under lib/poetry/ui/testing drive components
+# by name and may name them; the generators are install tooling nothing
+# in a component depends on.
+root "."
+source "app/**/*.rb", "lib/**/*.rb"
+
+component :components, in: "app/components/**/*.rb"
+component :lib, in: "lib/**/*.rb", except: ["lib/generators/**/*", "lib/poetry/ui/testing/**/*"]
+component :testing, in: "lib/poetry/ui/testing/**/*.rb"
+component :generators, in: "lib/generators/**/*.rb"
+
+lib.cannot_use :components, because: "lib reaches the components through the registry"
+components.cannot_use :generators, because: "a component never depends on the install tooling"
+lib.cannot_reference_constants "Poetry::Charts", "Poetry::Agent", "ApplicationController",
+                               because: "ui depends on core alone and never names the host"
+components.cannot_reference_constants "Poetry::Charts", "Poetry::Agent", "ApplicationController",
+                                      because: "ui depends on core alone and never names the host"
+no_cycles among: %i[lib components]

data/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## [0.1.5] - 2026-09-18
+
+### Changed
+
+- The registry carries the gem's internal namespaces (`internals`), so `poetry check` can warn a host that names one.
+- 36 methods the reference already hid with `@api private` are Ruby-private now: each was called only by its own class or template, so the runtime enforces what the tag only stated. A host that reached one gets a NoMethodError instead of an internal that may change without notice. The tag remains on the internals the family shares between its gems and on whole internal classes.
+- Every class, module and method carries a one-sentence description, private helpers included: `rake yard:coverage:all` measures the whole tree (a tag-only docstring counts as blank) and the committed floor now stands at zero.
+- DateTimeField and TimeField render through DateField's template (their verbatim copies are gone); Calendar and DatePicker share `DateParsing`; the four value-field form builder methods ride one `control_field` helper; the chat turn compiler builds its frames through `Chat::AssistantTurn::Timeline`. No rendered markup changed.
+- Every component's root rides the core default: `root_attributes` is the public `Poetry::Core::Component` method, and a component's override passes only its own markup up (`super("data-variant" => variant)`); the slot name, `data-component` and the root's Stimulus wiring come from the default. Twelve overrides that added nothing are gone, and the shared `FamilyIdentity` override passes the family's slot prefix the same way. The rendered attributes are unchanged apart from their order on the element.
+- The part builders (a popup's content, a field's group, a tree row, a dialog panel, and the rest) return `element_attributes(...)`, the part's attributes with its Stimulus wiring merged safely, named after their part so the slot, the dictionary classes and the wiring come stamped, and the templates splat the result (`tag.div(**content_attributes)`); `to_attributes` and the `Poetry::Core::HTML::Attributes.new(...)` wrap at every call site are gone.
+
 ## [0.1.4] - 2026-09-15
 
 ### Fixed

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

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

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

@@ -132,21 +132,19 @@ module Poetry
           Array(open).map(&:to_s)
         end
 
-        # @api private
+        # The root's attributes: this component's markup over the core default.
         def root_attributes
-          html_attributes.merge_if_not_set(
-            { "data-slot" => "accordion", "data-orientation" => "vertical" }
-              .merge(stimulus_attributes_for(:root))
-              .merge(component_data_attributes)
-          )
+          super({ "data-orientation" => "vertical" })
         end
 
         private
 
+        # The server-stable id every item id derives from.
         def instance_id
           @instance_id ||= poetry_instance_id("poetry-accordion")
         end
 
+        # One item's header: the trigger button with its chevron, wired to the controller.
         def accordion_header(item_id, title, open_item, disabled: false)
           trigger_attrs = {
             type: "button", id: "#{item_id}-trigger", class: css(:trigger),
@@ -173,6 +171,7 @@ module Poetry
           end
         end
 
+        # One item's panel region, hidden when closed, labelled by its trigger.
         def accordion_panel(item_id, open_item, &)
           attrs = {
             id: "#{item_id}-panel", role: "region", class: css(:content),
@@ -185,12 +184,13 @@ module Poetry
           end
         end
 
+        # The trigger's chevron icon.
         def chevron
           render(Icon::Component.new(name: :"chevron-down", class: css(:indicator),
                                      data: { slot: "accordion-trigger-icon" }))
         end
 
-        private :open_values, :root_attributes
+        private :open_values
       end
     end
   end

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

@@ -1,4 +1,4 @@
-<%= content_tag(:div, **root_attributes.to_attributes) do %>
+<%= content_tag(:div, **root_attributes) do %>
   <%= icon %>
   <% if title? %><div data-slot="alert-title" class="<%= css(:title) %>"><%= title %></div><% end %>
   <div data-slot="alert-description" class="<%= css(:description) %>"><%= content %></div>

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

@@ -43,18 +43,15 @@ module Poetry
                              "pinned to the top-right by the theme"
         part "alert-description", "The body copy - the content block renders here"
 
-        # @api private
+        # The root's attributes: this component's markup over the core default.
         def root_attributes
-          html_attributes.merge_if_not_set(
+          super(
             {
-              "data-slot" => "alert",
               "data-variant" => variant,
               "role" => (variant == :destructive ? "alert" : "status")
-            }.merge(component_data_attributes)
+            }
           )
         end
-
-        private :root_attributes
       end
     end
   end

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

@@ -1,6 +1,6 @@
-<%= content_tag(:div, **root_attributes.to_attributes) do %>
+<%= content_tag(:div, **root_attributes) do %>
   <%= trigger %>
-  <%= content_tag(:dialog, **Poetry::Core::HTML::Attributes.new(dialog_attributes).to_attributes) do %>
+  <%= content_tag(:dialog, **dialog_attributes) do %>
     <div data-slot="alert-dialog-header" class="<%= header_classes %>">
       <% if media? %>
         <div data-slot="alert-dialog-media" class="<%= media_classes %>"><%= media %></div>

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

@@ -148,29 +148,32 @@ module Poetry
           raise ArgumentError, "AlertDialog requires with_cancel (the safe way out)" unless cancel?
         end
 
+        # The title element's id.
         # @api private
         def title_id
           "#{instance_id}-title"
         end
 
+        # The description element's id.
         # @api private
         def description_id
           "#{instance_id}-description"
         end
 
+        # The dialog element's attributes: the alertdialog role, size, closed state and wiring.
         # @api private
         def dialog_attributes
-          {
+          attrs = {
             "class" => css(:content, class: content_class),
             # Explicit role: overrides the implicit dialog role (aria-modal
             # still comes from showModal).
             "role" => "alertdialog",
-            "data-slot" => "alert-dialog-content",
             "data-size" => size,
             "data-closed" => "",
             "aria-labelledby" => title_id,
             "aria-describedby" => description_id
-          }.merge(stimulus_attributes_for(:content))
+          }
+          element_attributes(:content, attrs)
         end
 
         # The media/size layout branches emitted as explicit server-side
@@ -185,16 +188,19 @@ module Poetry
           ].compact.join(" "))
         end
 
+        # The media slot's classes, sized for the default dialog.
         # @api private
         def media_classes
           css(:media, class: (css(:media_size_default) if size == :default))
         end
 
+        # The title's classes, placed beside the media in the default size.
         # @api private
         def title_classes
           css(:title, class: (css(:title_beside_media) if media? && size == :default))
         end
 
+        # The footer's classes, tightened in the small size.
         # @api private
         def footer_classes
           css(:footer, class: (css(:footer_size_sm) if size == :sm))

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

@@ -41,22 +41,20 @@ module Poetry
                 "AspectRatio ratio: must be a CSS ratio ('16/9', '1', '1.5') - got #{ratio.inspect}"
         end
 
+        # Renders the ratio box around the content.
         # @api private
         def call
-          content_tag(:div, content, **root_attributes.to_attributes)
+          content_tag(:div, content, **root_attributes)
         end
 
-        # @api private
+        # The root's attributes: this component's markup over the core default.
         def root_attributes
-          html_attributes.merge_if_not_set(
+          super(
             {
-              "data-slot" => "aspect-ratio",
               "style" => "--ratio: #{ratio}"
-            }.merge(component_data_attributes)
+            }
           )
         end
-
-        private :root_attributes
       end
     end
   end

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

@@ -1,4 +1,4 @@
-<%= content_tag(:div, **root_attributes.to_attributes) do %>
+<%= content_tag(:div, **root_attributes) do %>
   <%= trigger %>
   <%= media %>
   <% if title? || description? %>

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

@@ -122,17 +122,17 @@ module Poetry
           ANNOUNCED_STATES.include?(state)
         end
 
-        # @api private
+        # The root's attributes: this component's markup over the core default.
         def root_attributes
-          html_attributes.merge_if_not_set(
+          super(
             {
-              "data-slot" => "attachment", "data-upload-state" => state,
+              "data-upload-state" => state,
               "data-size" => size, "data-orientation" => orientation
-            }.merge(component_data_attributes)
+            }
           )
         end
 
-        private :announced?, :root_attributes
+        private :announced?
       end
     end
   end

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

@@ -1,4 +1,4 @@
-<%= content_tag(:div, **root_attributes.to_attributes) do %>
+<%= content_tag(:div, **root_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 %>"

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

@@ -125,6 +125,7 @@ module Poetry
         # @api private
         def item_models = (@item_models ||= [])
 
+        # The root id: the given id as a token, else a stable instance id.
         # @api private
         def autocomplete_id
           @autocomplete_id ||= if (token = dom_id_token(id))
@@ -134,18 +135,16 @@ module Poetry
                                end
         end
 
+        # The listbox's id.
         # @api private
         def list_id = "#{autocomplete_id}-list"
 
-        # @api private
+        # The root's attributes: this component's markup over the core default.
         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)
-          )
+          super({ "class" => css, "id" => autocomplete_id })
         end
 
+        # The text input's attributes: the combobox role, its list and open state, and the wiring.
         # @api private
         def input_attributes
           attrs = {
@@ -158,6 +157,7 @@ module Poetry
           attrs.merge(stimulus_attributes_for(:input).transform_keys(&:to_sym))
         end
 
+        # The popup's attributes with its open or closed state.
         # @api private
         def content_attributes
           attrs = {
@@ -172,6 +172,7 @@ module Poetry
           attrs.merge(stimulus_attributes_for(:content))
         end
 
+        # One option's attributes: its id, value, label and highlighted state.
         # @api private
         def item_attributes(item, index)
           attrs = {
@@ -190,7 +191,7 @@ module Poetry
         # @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_models, :autocomplete_id, :list_id, :input_attributes, :content_attributes
         private :item_attributes
       end
     end

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

@@ -57,30 +57,33 @@ module Poetry
           ensure_content!
         end
 
+        # Renders the avatar: the fallback, the image and the badge.
         # @api private
         def call
-          content_tag(:span, root_attributes.to_attributes) do
+          content_tag(:span, root_attributes) do
             safe_join([fallback, image, badge_part].compact)
           end
         end
 
-        # @api private
+        # The root's attributes: this component's markup over the core default.
         def root_attributes
-          html_attributes.merge_if_not_set(
+          super(
             {
-              "data-slot" => "avatar", "data-size" => size,
+              "data-size" => size,
               "role" => "img", "aria-label" => label
-            }.merge(component_data_attributes)
+            }
           )
         end
 
         private
 
+        # The initials fallback span.
         def fallback
           content_tag(:span, content, "data-slot" => "avatar-fallback", "aria-hidden" => "true",
                                       class: css(:fallback))
         end
 
+        # The image, or nil without a source.
         def image
           return if src.blank?
 
@@ -90,13 +93,12 @@ module Poetry
           tag.img(src: src, alt: "", "data-slot": "avatar-image", class: css(:image))
         end
 
+        # The badge span, or nil without a badge.
         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

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

@@ -54,19 +54,18 @@ module Poetry
           ensure_content!
         end
 
+        # Renders the badge as a link when it has an href, else as a span.
         # @api private
         def call
-          content_tag(href.present? ? :a : :span, content, **root_attributes.to_attributes)
+          content_tag(href.present? ? :a : :span, content, **root_attributes)
         end
 
-        # @api private
+        # The root's attributes: this component's markup over the core default.
         def root_attributes
-          attrs = { "data-slot" => "badge", "data-variant" => variant }
+          attrs = { "data-variant" => variant }
           attrs["href"] = href if href.present?
-          html_attributes.merge_if_not_set(attrs.merge(component_data_attributes))
+          super(attrs)
         end
-
-        private :root_attributes
       end
     end
   end

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

@@ -1,4 +1,4 @@
-<%= content_tag(:nav, **root_attributes.to_attributes) do %>
+<%= content_tag(:nav, **root_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) %>">

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

@@ -18,7 +18,6 @@ module Poetry
       #   <% 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.
@@ -84,18 +83,17 @@ module Poetry
           @entries ||= []
         end
 
-        # @api private
+        # The root's attributes: this component's markup over the core default.
         def root_attributes
-          html_attributes.merge_if_not_set(
-            { "aria-label" => "breadcrumb", "data-slot" => "breadcrumb" }.merge(component_data_attributes)
-          )
+          super({ "aria-label" => "breadcrumb" })
         end
 
         # One declared crumb.
         # @api private
         Entry = Data.define(:label, :href, :ellipsis, :block)
 
-        private :entries, :root_attributes
+        private :entries
+        private :separator_block
       end
     end
   end

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

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

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

@@ -76,12 +76,9 @@ module Poetry
           ensure_content!
         end
 
-        # @api private
+        # The root's attributes: this component's markup over the core default.
         def root_attributes
-          html_attributes.merge_if_not_set(
-            { "data-slot" => "bubble", "data-variant" => variant, "data-align" => align }
-              .merge(component_data_attributes)
-          )
+          super({ "data-variant" => variant, "data-align" => align })
         end
 
         # href: implies the anchor - an href on the default :div would
@@ -91,6 +88,7 @@ module Poetry
           href.present? ? :a : tag
         end
 
+        # The content element's attributes, with the href or button type its tag needs.
         # @api private
         def content_attributes
           attrs = { class: css(:content), "data-slot" => "bubble-content" }
@@ -99,7 +97,7 @@ module Poetry
           attrs
         end
 
-        private :root_attributes, :content_tag_name, :content_attributes
+        private :content_tag_name, :content_attributes
       end
     end
   end

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

@@ -1,4 +1,4 @@
-<%= content_tag(root_tag, **root_attributes.to_attributes) do %>
+<%= content_tag(root_tag, **root_attributes) do %>
   <% if loading %>
     <span data-slot="spinner" aria-hidden="true"><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" class="animate-spin"><path d="M21 12a9 9 0 1 1-6.219-8.56" /></svg></span>
   <% end %>

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

@@ -113,18 +113,20 @@ module Poetry
           tag == :a || href.present?
         end
 
+        # The root tag: an anchor for a link, else a button.
         # @api private
         def root_tag
           link_tag? ? :a : :button
         end
 
-        # @api private
+        # The root's attributes: the base and the tag's own, over the caller's.
         def root_attributes
-          html_attributes.merge_if_not_set(base_attributes.merge(tag_attributes))
+          html_attributes.merge_if_not_set(base_attributes.merge(tag_attributes)).to_attributes
         end
 
         private
 
+        # The attributes every button root carries: identity, variant, size, label and loading state.
         def base_attributes
           attrs = { "data-slot" => "button", "data-variant" => variant, "data-size" => size }
                   .merge(component_data_attributes)
@@ -143,6 +145,7 @@ module Poetry
           link_tag? ? link_attributes : button_attributes
         end
 
+        # The anchor's attributes: the button role, and the href or the disabled state.
         def link_attributes
           attrs = { "role" => "button" }
           if disabled || loading
@@ -153,15 +156,14 @@ module Poetry
           attrs
         end
 
+        # The button's attributes: its type and disabled state.
         def button_attributes
           attrs = { "type" => type }
           attrs["disabled"] = true if disabled || loading
           attrs
         end
 
-        private :icon_only?, :link_tag?, :root_tag, :root_attributes
-
-        private :icon_only?, :link_tag?, :root_tag, :root_attributes
+        private :icon_only?, :link_tag?, :root_tag
       end
     end
   end

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

@@ -48,22 +48,20 @@ module Poetry
           ensure_content!
         end
 
+        # Renders the group around its content.
         # @api private
         def call
-          content_tag(:div, content, **root_attributes.to_attributes)
+          content_tag(:div, content, **root_attributes)
         end
 
-        # @api private
+        # The root's attributes: this component's markup over the core default.
         def root_attributes
-          html_attributes.merge_if_not_set(
+          super(
             {
-              "role" => "group", "data-slot" => "button-group",
-              "data-orientation" => orientation
-            }.merge(component_data_attributes)
+              "role" => "group", "data-orientation" => orientation
+            }
           )
         end
-
-        private :root_attributes
       end
     end
   end

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

@@ -1,4 +1,4 @@
-<%= content_tag(:div, **root_attributes.to_attributes) do %>
+<%= content_tag(:div, **root_attributes) do %>
   <div data-slot="calendar-nav" class="<%= css(:nav) %>">
     <%= render Poetry::Ui::Button::Component.new(**previous_options) do |button| %>
       <% button.with_leading { render Poetry::Ui::Icon::Component.new(name: :"chevron-left") } %>