poetry-core 0.1.3 → 0.1.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 74940c713a7f81772d930f9581313847ec1a4044f36c3b31774efafd31bd07ef
-  data.tar.gz: 9e869c5574bef206ee03a998d31beda8cc10cf6f70e429134fb80b70fec8e2be
+  metadata.gz: af029ac85cadd2b3906f885dc1123ca58a73bcd55ffe07041abde3933a5a08f4
+  data.tar.gz: 3c5efbc74950c59708605ee7d77371d4c1b3f47e3fefc661042cfe9ce4179a34
 SHA512:
-  metadata.gz: 6bfcc4296038b8766014f1ed52cda1e9c365a9242aabcc0f8bac7a864e63c64a01438ec58d46c48ed1525d0191f7d1e0e9b4826932f996cb0184de123a19f856
-  data.tar.gz: c5c56a37ae235c3d88b155a9197138c9f583187814431d957f78efb430c8e925a86fc039111df305fec8d00b90e0b4cfe46eb897eca3415e8bc97b7d0182b670
+  metadata.gz: f4a190f5aec965c7defb6ce6005cf5ba388f393ee7955fd72e8ccc9d615442f7d37e7e105a7e51380826e5c7c9d22d10a5ca50400bd7a9da23bc8068be207c30
+  data.tar.gz: 9487e4788dac96cc7bc8212cb519c0dfd6d7e6ebdab6e34f7ba6fd2fc598c6bb00905974bb9370692d84ee01cf103f339eabc94884d9f45372ebedccfce33913

data/.controller_docs

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

data/.jsdoc_floor

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

data/.mcp.json

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

data/.yard-lint.yml

@@ -0,0 +1,28 @@
+# 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
+    - --load
+    - yard/poetry_yard.rb
+
+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).
+# Core is the root of the family: nothing here names a sibling gem or the
+# host application, and lib reaches the components only through the
+# registry and the base class.
+root "."
+source "app/**/*.rb", "lib/**/*.rb"
+
+component :kernel, constants: %w[Poetry::Core::Component Poetry::Core::Wrapper::Component]
+component :components, in: "app/components/**/*.rb",
+                       except: ["app/components/poetry/core/component.rb", "app/components/poetry/core/wrapper/**/*"]
+component :lib, in: "lib/**/*.rb"
+
+lib.cannot_use :components, because: "lib reaches the components through the registry and the base class"
+lib.cannot_reference_constants "Poetry::Ui", "Poetry::Charts", "Poetry::Agent", "Poetry::Extract",
+                               "ApplicationController",
+                               because: "core is the root of the family and never names the host"
+components.cannot_reference_constants "Poetry::Ui", "Poetry::Charts", "Poetry::Agent", "Poetry::Extract",
+                                      "ApplicationController",
+                                      because: "core is the root of the family and never names the host"
+no_cycles among: %i[lib components]

data/CHANGELOG.md

@@ -1,5 +1,28 @@
 # Changelog
 
+## [0.1.5] - 2026-09-18
+
+### Added
+
+- The controllers manifest carries the prose beside each controller: its purpose (a JSDoc block above the class), the meaning of every value, and a summary of every action method, harvested when the manifest is generated; `rake stimulus:docs` holds the count of gaps at a committed floor, now zero.
+- `poetry check` warns when app Ruby or a template names one of the family's internal namespaces (`internal-constant`): a class or module the reference hides with `@api private` works today and may change without notice. The registries carry the list (`internals`, read from source by `Poetry::Core::ApiInternals` at generation), so the check, the MCP `check` tool and a host's editor hook all read the same contract without booting; core's own internals join every catalog.
+- `Poetry::Core::Component#root_attributes`, the root element's attributes ready to splat: the caller's `html_attributes` (classes already merged with the dictionary's) over the component's own root markup - `data-slot` (`root_slot`, the component title in kebab form, or the one passed), `data-component`, and the root's Stimulus wiring whenever a `use_stimulus` block declares `:root`. A component adds its markup by overriding and passing it up (`super("role" => "status")`); the template writes `tag.div(**root_attributes)`. The private `root_attributes` every component and the guide's sample wrote by hand is the default now.
+- `Poetry::Core::Component#element_attributes(part, markup, stimulus:)`, the builder for a part's attributes, ready to splat: the part's `data-slot` (the root slot and the part name), the dictionary's classes for it when the Style declares the element, the part's Stimulus wiring when a `use_stimulus` block declares an element of that name, and the markup over all three (its own `"data-slot"` or `"class"` wins; `stimulus:` names another element, or `false` for none). The wiring merges the safe way: plain `Hash#merge` of markup with wiring dropped one side's `data-controller` or `data-action` when both carried one, and this concatenates them. Build every part here and write `tag.div(**content_attributes)`; `to_attributes` leaves the templates.
+
+### Fixed
+
+- A message scroller opening at the end (or the last anchor) no longer settles at the top of the thread when its controller connects before the page's render-blocking stylesheet lands. The opening position counted as applied against a viewport that had nothing to scroll yet; it now finalizes only against a laid-out viewport, else on the first resize pass, and the opening hold (`data-pending-scroll`) releases there.
+
+### Changed
+
+- 133 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.
+- `Poetry::Core::RequiresAny.phrase` states an any-of contract once for `poetry check`, llms.txt and the MCP server; the registry entry builder, the slot surface builder and the host manifest's literal scanner are split into named steps with no change in output (the committed registries rebuild byte for byte).
+
+## [0.1.4] - 2026-09-15
+
+Lockstep release with the family; no changes in this gem.
+
 ## [0.1.3] - 2026-09-13
 
 ### Fixed

data/app/components/poetry/core/component.rb

@@ -62,6 +62,11 @@ module Poetry
       # Button's render when it ran through `valid?`.
       class_attribute :declared_values, instance_accessor: false, default: {}.freeze
 
+      # The caller-supplied semantic identity (key:), if any.
+      #
+      # @return [Object, nil]
+      attr_reader :stable_key
+
       class << self
         # Marks this class (and its descendants) as an implementation
         # detail - full machinery, no registry entry.
@@ -116,8 +121,9 @@ module Poetry
         # @param name [Symbol]
         # @param variants [Array, nil] the closed vocabulary, nil for open values
         # @param required [Boolean]
+        # @param open [Boolean] a style redeclared without variants: any value passes,
+        #   the vocabulary is not enforced
         # @return [void]
-        # @api private
         def record_declared_value(name, variants:, required:, open: false)
           spec = { variants: variants, required: required, open: open }.freeze
           self.declared_values = declared_values.merge(name.to_sym => spec).freeze
@@ -274,6 +280,94 @@ module Poetry
         { "data-slot" => part.to_s }
       end
 
+      # The root element's attributes, ready to splat: the caller's
+      # {#html_attributes} (its classes already merged with the dictionary's)
+      # over the component's own root markup - `data-slot` (the component
+      # title, or the one in +extra+), `data-component`, and the root's
+      # Stimulus wiring when a `use_stimulus` block declares `:root`. The
+      # caller's attributes win: a class, id or data-* passed in is kept and
+      # the component's default fills the gaps.
+      #
+      # A component adds its own root markup by overriding and passing it up;
+      # the template splats the result.
+      #
+      # @example A component's override
+      #   def root_attributes
+      #     super("role" => "status", "data-variant" => variant)
+      #   end
+      # @example The template
+      #   <%= tag.div(**root_attributes) do %>
+      #
+      # @param extra [Hash] the component's own root attributes; a
+      #   `"data-slot"` here replaces the default
+      # @return [Hash] the root's attributes, flat (`data-x`, `aria-x`,
+      #   booleans as the attribute name), for `tag` and `content_tag`
+      def root_attributes(extra = {})
+        own = { "data-slot" => root_slot }.merge(extra).merge(component_data_attributes)
+        wired = self.class.stimulus_elements.key?(:root) ? :root : nil
+        html_attributes.merge_if_not_set(element_markup(own, stimulus: wired)).to_attributes
+      end
+
+      # The root's `data-slot`: the component title in kebab form (a
+      # ToggleGroup roots as "toggle-group").
+      #
+      # @return [String] the slot name
+      def root_slot
+        self.class.component_title.to_s.tr("_", "-")
+      end
+
+      # A part's attributes, ready to splat. Named after a part, it carries
+      # the part's `data-slot` (the root slot and the part name: a
+      # DropdownMenu's `:content` is "dropdown-menu-content"), the
+      # dictionary's classes for it (`css(part)`, when the Style declares the
+      # element), and the part's Stimulus wiring when a `use_stimulus` block
+      # declares an element of that name - each of which the markup may
+      # override (its own `"data-slot"` or `"class"` wins; `stimulus:` names
+      # another element, or `false` for none). The wiring merges beneath the
+      # markup the safe way: plain `Hash#merge` drops one side's
+      # `data-controller` or `data-action` when both carry one, and this
+      # concatenates them. Rendered more than once (a row, an addon), the
+      # builder takes its arguments and the part stays the same.
+      #
+      # @example A part builder, and its template
+      #   def content_attributes
+      #     attrs = { "id" => content_id, "role" => "menu" }
+      #     attrs["hidden"] = true unless open
+      #     element_attributes(:content, attrs)
+      #   end
+      #   # <%= tag.div(**content_attributes) do %>
+      #
+      # @param part [Symbol, String, nil] the part; nil (or a Hash in its
+      #   place) for markup with no part of its own
+      # @param attrs [Hash] the element's markup, in braces after a part
+      # @param stimulus [Symbol, String, false, nil] the `use_stimulus`
+      #   element whose wiring joins the markup: nil takes the part's own when
+      #   one is declared, false takes none
+      # @return [Hash] the element's attributes, flat, for `tag` and `content_tag`
+      def element_attributes(part = nil, attrs = {}, stimulus: nil)
+        if part.is_a?(Hash)
+          attrs = part
+          part = nil
+        end
+        own = attrs
+        if part
+          own = { "data-slot" => "#{root_slot}-#{part.to_s.tr("_", "-")}", "class" => css(part) }.compact.merge(attrs)
+          stimulus = part.to_sym if stimulus.nil? && self.class.stimulus_elements.key?(part.to_sym)
+        end
+        element_markup(own, stimulus: stimulus || nil).to_attributes
+      end
+
+      # The merge-aware form of an element's markup with its wiring.
+      #
+      # @param attrs [Hash] the element's markup
+      # @param stimulus [Symbol, String, nil] a declared element, or nil
+      # @return [Poetry::Core::HTML::Attributes]
+      def element_markup(attrs, stimulus:)
+        attributes = Poetry::Core::HTML::Attributes.new(attrs)
+        stimulus ? attributes.merge(stimulus_attributes_for(stimulus)) : attributes
+      end
+      private :element_markup
+
       # Enforces the class-level requires_content declaration - call from
       # before_render. The message is built from the declaration so the
       # runtime raise and the registry's static contract can never disagree.
@@ -469,6 +563,7 @@ module Poetry
           "#{allowed.map(&:inspect).join(", ")}#{variant_suggestion(value, allowed)}"
       end
 
+      # The did-you-mean suffix for an off-list value, or an empty string.
       def variant_suggestion(value, allowed)
         return "" if allowed.empty? || value.nil?
 
@@ -527,11 +622,6 @@ module Poetry
         attributes
       end
 
-      # The caller-supplied semantic identity (key:), if any.
-      #
-      # @return [Object, nil]
-      attr_reader :stable_key
-
       # The instance-id ladder: an explicit caller root id wins; a key:
       # derives a stable component-namespaced token (Turbo morph pairs it
       # across renders, cached fragments stay composable); otherwise
@@ -624,6 +714,8 @@ module Poetry
         controller.request = ActionDispatch::TestRequest.create
         render_in(controller.view_context)
       end
+
+      private_class_method :record_declared_value
     end
   end
 end

data/app/components/poetry/core/concerns/agent_tools.rb

@@ -218,6 +218,7 @@ module Poetry
             words[0].upcase + words[1..]
           end
 
+          # Raises unless the tool name is a symbol or string in the allowed shape and length.
           # @api private
           def validate_tool_name!(name)
             unless name.is_a?(Symbol) || name.is_a?(String)
@@ -233,6 +234,7 @@ module Poetry
             text.to_sym
           end
 
+          # The description trimmed, raising when it is missing or too long.
           # @api private
           def validate_tool_description!(name, description)
             text = description.to_s.strip
@@ -269,6 +271,7 @@ module Poetry
             end
           end
 
+          # The tool's input schema as string-keyed JSON Schema, from params: or input_schema: but never both.
           # @api private
           def normalize_tool_schema!(name, params, input_schema)
             if params && input_schema
@@ -301,6 +304,7 @@ module Poetry
             schema
           end
 
+          # Raises when a parameter's description is blank or too long.
           # @api private
           def validate_param_description!(name, param, description)
             return if description.nil?
@@ -313,6 +317,7 @@ module Poetry
                   "and at most #{PARAM_DESCRIPTION_LIMIT} characters"
           end
 
+          # The input schema as given, raising unless it is a hash with a type.
           # @api private
           def validate_input_schema!(name, input_schema)
             unless input_schema.is_a?(Hash) && (input_schema[:type] || input_schema["type"])
@@ -323,6 +328,7 @@ module Poetry
             input_schema
           end
 
+          # The value with every hash key and symbol turned into a string, recursively.
           # @api private
           def deep_stringify_tool_keys(value)
             case value

data/app/components/poetry/core/concerns/declared_attributes.rb

@@ -62,7 +62,7 @@ module Poetry
           # stays in the hash for `attribute` to install.
           #
           # @param options [Hash] the original options hash
-          # @return [Array<(Boolean, Object)>] required and default_value
+          # @return [Array(Boolean, Object)] required and default_value
           def extract_declared_defaults(options)
             default_value = options[:default]
             options.delete(:default) if default_value.is_a?(Proc)

data/app/components/poetry/core/concerns/introspection.rb

@@ -139,6 +139,7 @@ module Poetry
             callable || renders || (opts unless opts.empty?)
           end
 
+          # One style attribute's registry definition: type, variants, default, required and doc.
           def style_definition(name)
             definition = { name: name, type: attribute_types[name.to_s].type }
             variants = respond_to?("#{name}_variants") ? public_send("#{name}_variants") : nil
@@ -151,6 +152,7 @@ module Poetry
             definition
           end
 
+          # One option's registry definition: type, the inclusion validator as its enum, default, required and doc.
           def option_definition(name)
             definition = { name: name, type: attribute_types[name.to_s].type }
             # An inclusion validator IS the option's enum contract:
@@ -203,6 +205,7 @@ module Poetry
             end
           end
 
+          # Whether a presence validator makes the attribute required.
           def required_attribute?(name)
             validators_on(name).any? { |validator| validator.kind == :presence }
           end
@@ -282,42 +285,14 @@ module Poetry
           def slot_surface(klass, seen: [])
             return [] unless klass.respond_to?(:registered_slots)
 
-            builders = declared_builders(klass)
-            required_content = declared_required_content(klass)
-            block_yields = declared_constant(klass, :SLOT_BLOCK_YIELDS)
-            renders = declared_constant(klass, :SLOT_RENDERS)
-            slot_docs = klass.respond_to?(:slot_docs) ? klass.slot_docs : {}
-            klass.registered_slots.map do |slot_name, config|
-              definition = { name: slot_name, many: config[:collection] == true }
-              doc = slot_docs[slot_name.to_sym]
-              definition[:description] = doc if doc
-              renderable = config[:renderable]
-              definition[:component] = renderable.component_path if renderable.respond_to?(:component_path)
-              # A declared pure-forwarding lambda (SLOT_RENDERS) restores
-              # the component fact a wrapping lambda hides.
-              # Polymorphic slots stay out - their types are their contract.
-              if config[:renderable_hash].nil? &&
-                 (declared = renders[slot_setters(slot_name, config).first&.to_sym])
-                unless declared.respond_to?(:component_path)
-                  raise Poetry::Core::Error,
-                        "#{klass}::SLOT_RENDERS[#{slot_name}] must be a poetry component class"
-                end
-
-                definition[:component] ||= declared.component_path
-              end
-              definition[:types] = config[:renderable_hash].keys if config[:renderable_hash]
-              setter_args = setter_positional_args(slot_name, config)
-              definition[:setter_args] = setter_args unless setter_args.empty?
-              setter_kwargs = setter_keyword_args(slot_name, config)
-              definition[:setter_kwargs] = setter_kwargs unless setter_kwargs.empty?
-              yieldless = yieldless_setters(slot_name, config) - block_yields.keys
-              definition[:yieldless] = yieldless unless yieldless.empty?
-              required = required_content.slice(*slot_setters(slot_name, config).map(&:to_sym))
-              definition[:required_content] = required unless required.empty?
-              surfaces = builder_surfaces(slot_name, config, builders, seen + [klass])
-              definition[:builders] = surfaces unless surfaces.empty?
-              definition
-            end
+            context = {
+              klass: klass, seen: seen + [klass],
+              builders: declared_builders(klass), required_content: declared_required_content(klass),
+              block_yields: declared_constant(klass, :SLOT_BLOCK_YIELDS),
+              renders: declared_constant(klass, :SLOT_RENDERS),
+              slot_docs: klass.respond_to?(:slot_docs) ? klass.slot_docs : {}
+            }
+            klass.registered_slots.map { |slot_name, config| slot_definition(slot_name, config, context) }
           end
 
           # The validated REQUIRED_SLOTS declaration of a slot-owning class:
@@ -399,14 +374,66 @@ module Poetry
 
           private
 
+          # One slot's registry definition: its name and arity, its doc, its
+          # component fact, its polymorphic types, then its setter facts.
+          def slot_definition(slot_name, config, context)
+            definition = { name: slot_name, many: config[:collection] == true }
+            doc = context[:slot_docs][slot_name.to_sym]
+            definition[:description] = doc if doc
+            renderable = config[:renderable]
+            definition[:component] = renderable.component_path if renderable.respond_to?(:component_path)
+            declared = declared_component(slot_name, config, context)
+            definition[:component] ||= declared if declared
+            definition[:types] = config[:renderable_hash].keys if config[:renderable_hash]
+            definition.merge!(setter_facts(slot_name, config, context))
+          end
+
+          # The component path a SLOT_RENDERS entry declares for a slot's
+          # first setter, or nil: a declared pure-forwarding lambda restores
+          # the component fact a wrapping lambda hides. Polymorphic slots
+          # stay out - their types are their contract.
+          def declared_component(slot_name, config, context)
+            return if config[:renderable_hash]
+
+            declared = context[:renders][slot_setters(slot_name, config).first&.to_sym]
+            return unless declared
+            unless declared.respond_to?(:component_path)
+              raise Poetry::Core::Error,
+                    "#{context[:klass]}::SLOT_RENDERS[#{slot_name}] must be a poetry component class"
+            end
+
+            declared.component_path
+          end
+
+          # A slot's setter facts, each present only when it says something:
+          # positional arity, keyword names, the yieldless setters, the
+          # required content, and the builder surfaces.
+          def setter_facts(slot_name, config, context)
+            facts = {}
+            setter_args = setter_positional_args(slot_name, config)
+            facts[:setter_args] = setter_args unless setter_args.empty?
+            setter_kwargs = setter_keyword_args(slot_name, config)
+            facts[:setter_kwargs] = setter_kwargs unless setter_kwargs.empty?
+            yieldless = yieldless_setters(slot_name, config) - context[:block_yields].keys
+            facts[:yieldless] = yieldless unless yieldless.empty?
+            required = context[:required_content].slice(*slot_setters(slot_name, config).map(&:to_sym))
+            facts[:required_content] = required unless required.empty?
+            surfaces = builder_surfaces(slot_name, config, context[:builders], context[:seen])
+            facts[:builders] = surfaces unless surfaces.empty?
+            facts
+          end
+
+          # The class's SLOT_BUILDERS map, or an empty one.
           def declared_builders(klass)
             declared_constant(klass, :SLOT_BUILDERS)
           end
 
+          # The class's SLOT_REQUIRED_CONTENT map, or an empty one.
           def declared_required_content(klass)
             declared_constant(klass, :SLOT_REQUIRED_CONTENT)
           end
 
+          # A constant on the class as a hash, or an empty hash when it is absent or unresolvable.
           def declared_constant(klass, name)
             klass.const_defined?(name) ? klass.const_get(name) : {}
           rescue NameError
@@ -431,6 +458,7 @@ module Poetry
             [config[:collection] ? name.delete_suffix("s") : name]
           end
 
+          # Each setter's positional arity for a slot, per polymorphic type when it has them.
           def setter_positional_args(slot_name, config)
             if (types = config[:renderable_hash])
               types.filter_map do |type, definition|
@@ -444,6 +472,7 @@ module Poetry
             end
           end
 
+          # Each setter's keyword names for a slot, per polymorphic type when it has them.
           def setter_keyword_args(slot_name, config)
             if (types = config[:renderable_hash])
               types.filter_map do |type, definition|
@@ -457,6 +486,7 @@ module Poetry
             end
           end
 
+          # The slot's setters whose lambda consumes the block, so a caller's block param would be nil.
           def yieldless_setters(slot_name, config)
             if (types = config[:renderable_hash])
               types.filter_map do |type, definition|
@@ -510,6 +540,7 @@ module Poetry
             nil
           end
 
+          # The slot surfaces of the builder classes a slot's setters yield, recursing once per builder.
           def builder_surfaces(slot_name, config, builders, seen)
             slot_setters(slot_name, config).filter_map do |setter|
               builder = builders[setter.to_sym]

data/app/components/poetry/core/concerns/parts.rb

@@ -91,6 +91,7 @@ module Poetry
 
           private
 
+          # Raises unless the part name is a kebab-case data-slot value.
           def validate_name!(klass, name)
             return if name.is_a?(String) && name.match?(PART_NAME)
 
@@ -98,6 +99,7 @@ module Poetry
                   "#{klass}: part name #{name.inspect} must be a kebab-case data-slot value"
           end
 
+          # One declared state for a part: the data attribute, its condition and its values, validated.
           def build_state(klass, part, attr, spec)
             unless attr.is_a?(String) && attr.match?(STATE_ATTRIBUTE)
               raise Poetry::Core::Error,
@@ -122,6 +124,7 @@ module Poetry
             state
           end
 
+          # A state spec's condition and values, from a bare condition or a hash.
           def unpack_state(spec)
             return [spec, nil] unless spec.is_a?(Hash)
 
@@ -129,6 +132,7 @@ module Poetry
             [normalized["condition"], normalized["values"]]
           end
 
+          # One declared custom property for a part, validated with its description.
           def build_var(klass, part, var, description)
             unless var.is_a?(String) && var.match?(VAR_NAME)
               raise Poetry::Core::Error,

data/app/components/poetry/core/concerns/stimulus.rb

@@ -167,6 +167,7 @@ module Poetry
 
           private
 
+          # The controller and name from a one- or two-argument descriptor call.
           def unpack_stimulus_descriptor_args(args, kind)
             case args.size
             when 1 then [nil, args.first]
@@ -177,6 +178,7 @@ module Poetry
             end
           end
 
+          # The controller identifier a descriptor names, or the one declaration that owns the name.
           def resolve_stimulus_descriptor(controller, name, kind:)
             return resolve_stimulus_identifier(controller) if controller
 
@@ -197,6 +199,7 @@ module Poetry
                   "stimulus_#{kind}(:controller, #{name.inspect})"
           end
 
+          # Whether a controller's manifest lists the name as an action method or an event.
           def stimulus_descriptor_match?(identifier, name, kind)
             definition = Poetry::Core::Stimulus::Manifest.definition(identifier)
             return false unless definition
@@ -212,6 +215,7 @@ module Poetry
             end
           end
 
+          # Records an element's declaration, merging its wirings into an earlier declaration of the same name.
           def store_stimulus_element(element)
             existing = own_stimulus_elements[element.name]
             own_stimulus_elements[element.name] =

data/app/components/poetry/core/concerns/styles.rb

@@ -183,7 +183,7 @@ module Poetry
           # Extracts and processes style-specific options from the options hash.
           #
           # @param options [Hash] the original options hash
-          # @return [Array<(Object, Boolean, Object)>] variants, required, and default_value
+          # @return [Array(Object, Boolean, Object)] variants, required, and default_value
           def extract_style_options(options)
             variants = options.delete(:variants)
             required, default_value = extract_declared_defaults(options)

data/app/javascript/poetry/core/accordion_controller.js

@@ -2,13 +2,6 @@ import { Controller } from "@hotwired/stimulus"
 import { enterPresence, exitPresence, measurePresence } from "@poetry/controllers/helpers/presence"
 import { setState, stateOf } from "@poetry/controllers/helpers/state"
 
-// The accordion open-set machine: single (optionally collapsible)
-// or multiple. Composes with poetry--core--roving-focus (manageTabindex:
-// false - APG keeps every trigger tabbable) attached separately on the
-// same root. Panels ride the presence helper; the measured
-// --accordion-panel-height var feeds the vendored accordion-down/up
-// keyframes.
-
 // Safety net (ms) for clearing the data-transitioning window when
 // animationend never arrives - reduced motion or a zero-length animation.
 // Comfortably longer than the 0.2s accordion keyframe.
@@ -17,13 +10,23 @@ const TRANSITION_FALLBACK_MS = 400
 // The component-facing event namespace (the poetry:<component> rule).
 const EVENT_PREFIX = "poetry:accordion"
 
+/**
+ * The accordion open-set machine: single (optionally collapsible)
+ * or multiple. Composes with poetry--core--roving-focus (manageTabindex:
+ * false - APG keeps every trigger tabbable) attached separately on the
+ * same root. Panels ride the presence helper; the measured
+ * --accordion-panel-height var feeds the vendored accordion-down/up
+ * keyframes.
+ */
 export default class extends Controller {
   // The events this controller dispatches (manifest surface;
   // events_declaration.test.js enforces the list stays honest).
   static events = ["poetry:accordion:change"]
 
   static values = {
+    // single keeps one item open at a time; multiple lets any number stay open.
     type: { type: String, default: "single" },
+    // In single mode, whether the open item can be closed by its own trigger.
     collapsible: { type: Boolean, default: false }
   }
 

data/app/javascript/poetry/core/action_bar_controller.js

@@ -2,14 +2,16 @@ import { Controller } from "@hotwired/stimulus"
 import { announce } from "@poetry/controllers/helpers/announce"
 import { isImeKeydown } from "@poetry/controllers/helpers/escape"
 
-// The floating bulk-actions bar (the ActionBar contract): shows
-// while its table's selection is non-empty, and holds the contract rules -
-// focus NEVER moves in on show; if focus was inside when the bar hides,
-// it returns to where it was before entering (the FocusScope restoreFocus
-// equivalent, scoped small); "Actions available." is announced ONCE per
-// appearance; the visible count RETAINS its last non-zero value while the
-// bar animates out (never a "None selected" flash); Escape anywhere
-// inside clears the selection (the table's engine listens for
+/**
+ * The floating bulk-actions bar (the ActionBar contract): shows
+ * while its table's selection is non-empty, and holds the contract rules -
+ * focus NEVER moves in on show; if focus was inside when the bar hides,
+ * it returns to where it was before entering (the FocusScope restoreFocus
+ * equivalent, scoped small); "Actions available." is announced ONCE per
+ * appearance; the visible count RETAINS its last non-zero value while the
+ * bar animates out (never a "None selected" flash); Escape anywhere
+ * inside clears the selection (the table's engine listens for
+ */
 export default class ActionBarController extends Controller {
   // The events this controller dispatches (manifest surface;
   // events_declaration.test.js enforces the list stays honest).
@@ -17,6 +19,8 @@ export default class ActionBarController extends Controller {
 
   static targets = ["count"]
   static values = {
+    // The count announcement, with %{count} replaced by the number of selected
+    // rows.
     label: { type: String, default: "%{count} selected" }
   }