poetry-core 0.1.7 → 0.1.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bbcb8f5566d4740ebb19e9fc4e4ffed10332cff25bde4e807cf844ddee70770a
-  data.tar.gz: 82e4cbb3c6f3bb340ecb20fb3e0406e83b8b2008364467dc83c7deddda93331e
+  metadata.gz: be0bfa6a89f4e90c5ff4227fb55faae46a68c2d8b6a85fbe7b954fe1a859314b
+  data.tar.gz: 466897acf54b0ada006299af237b50c8d32fe5ee846c8cac5d4b29723e93d33a
 SHA512:
-  metadata.gz: 53de8890c3deeb5f377f4c9d825f9599c499ef4bc66becdfd3266864166a6119024486b32c385fd02ef452af27ec9eebac63c8ab54570bad6a0a758707164637
-  data.tar.gz: d761c54985f8e367c72b5b9c99d609303b787d8bf13c9857bffee008e2b633a3fd778f719e3a07e70c179c11b7ad9430ba75693c511a4c3f33eb2a7794c325a2
+  metadata.gz: d8d10b2fce56d3217292ff638aec3f3680202278f28144ed5a2a91c6f92fd51d2ea288b3b67987a9edc27fc3cb9e1c20e9fab94f44a22596553c98abb8ca69a6
+  data.tar.gz: 75db75e6f640a176bf84d99d64f8c4e354fcc563c1f01892b83af1d217ebd7879989d841cb62a4adef7e0a091c870e6bf5689f1410e0322b84fee7c3dc07fb2f

data/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## [0.1.8] - 2026-09-22
+
+### Added
+
+- `ActiveModel::Type::HtmlSafeString`, the type behind every `option :name, :string` declaration: an html-safe value (a hint built with `link_to`, a translated `_html` key) stays html-safe where ActiveModel's String type copied it into a plain String, so a Field's `hint:` or `error:` renders the markup it was given; a plain String still escapes at render. The type is substituted inside the option DSL only, never registered, and reports `:string`, so the registry reads every declaration unchanged.
+
+### Changed
+
+- A content block that returns a scalar (a number, a symbol, a boolean) while writing nothing to the buffer captures as nothing, so `poetry_badge { count }` rendered an empty badge without a word. A component that declares `requires_content` now raises in development and test naming the value and the fix (call `to_s` on it, or write it with `<%= %>`) and logs in production; every other component logs. A block that wrote to the buffer, returned a String or nil, or returned a collection (an empty loop's `each`) is untouched.
+- `poetry check`'s stable-identity rules skip a pathless helper whose registry `helpers` entry declares `identity: false` (a table part helper stamps no poetry-minted id, so `key:` had nothing to stabilize and the warning was noise), and read a double-splat of an id-bearing hash (`**field.control_attributes`, `**attrs`) as identity: the id arrives through the splat.
+
 ## [0.1.7] - 2026-09-20
 
 ### Changed

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

@@ -382,7 +382,63 @@ module Poetry
                              "(#{self.class.required_content})"
       end
 
+      # ViewComponent's render_in, with the content block wrapped once so
+      # #content can read what the block RETURNED - capture keeps only what
+      # the block wrote to the buffer, and a scalar return vanishes there.
+      #
+      # @param view_context [ActionView::Base] the rendering view
+      # @return [ActiveSupport::SafeBuffer] the rendered component
+      def render_in(view_context, **)
+        @content_guarded = false
+        remove_instance_variable(:@content_return) if defined?(@content_return)
+        return super unless block_given?
+
+        recorded = proc { |*args| @content_return = yield(*args) }
+        super(view_context, **, &recorded)
+      end
+
+      # The captured content block, guarded once per render: a block that
+      # returned a scalar (a number, a symbol, a boolean) while writing
+      # nothing to the buffer captures as nothing at all - `poetry_badge {
+      # count }` renders an empty badge - so a requires_content component
+      # raises in development and test naming the value and the fix, and
+      # logs everywhere else; a component without the declaration logs. A
+      # block that wrote to the buffer, returned a String, returned nil,
+      # returned a collection (an empty loop's each) or composed slots
+      # (its last call a with_* setter, which returns the slot or the
+      # component) is fine.
+      #
+      # @return [ActiveSupport::SafeBuffer, nil] the captured content
+      def content
+        captured = super
+        guard_content_return(captured) unless @content_guarded
+        captured
+      end
+
+      # The content-return guard behind #content.
+      #
+      # @param captured [ActiveSupport::SafeBuffer, nil] what capture kept
+      # @return [void]
+      # @raise [ArgumentError] a scalar return on a requires_content
+      #   component, in development and test
+      def guard_content_return(captured)
+        @content_guarded = true
+        return unless defined?(@content_return)
+
+        value = @content_return
+        return if value.nil? || value.is_a?(::String) || value.respond_to?(:each) || captured.present?
+        return if value.is_a?(ViewComponent::Base) || value.is_a?(ViewComponent::Slot)
+
+        message = "#{passthrough_owner} content block returned #{value.inspect.truncate(60)} (#{value.class}), " \
+                  "which captures as nothing - return a String (call to_s on it) or write it with <%= %>"
+        raise ArgumentError, message if strict_passthrough? && self.class.required_content
+
+        Rails.logger&.warn("poetry: #{message}") if defined?(Rails) && Rails.respond_to?(:logger)
+      end
+      private :guard_content_return
+
       # Indicates whether this component instance is persisted.
+
       # Always returns false as components are not persisted entities.
       #
       # @return [Boolean] always returns false

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

@@ -90,8 +90,9 @@ module Poetry
             required, default_value = extract_declared_defaults(options)
             register_option_format(name, options.delete(:format))
 
-            attribute(name, type, **options)
+            attribute(name, option_cast_type(type), **options)
             add_option_validations(name, type, required)
+
             setup_declared_tracking(:option, name, default_value)
             define_type_getter(name, type)
           end
@@ -200,6 +201,18 @@ module Poetry
             validates name, presence: true if required
           end
 
+          # The ActiveModel type an option declaration casts with. A :string
+          # option casts with ActiveModel::Type::HtmlSafeString, which keeps
+          # an html-safe value (a link, a translated `_html` key) html-safe
+          # where the String type copied it into a plain String; every other
+          # type is looked up by name as ActiveModel does.
+          #
+          # @param type [Symbol] the declared type
+          # @return [Symbol, ActiveModel::Type::Value] what `attribute` receives
+          def option_cast_type(type)
+            type == :string ? ActiveModel::Type::HtmlSafeString.new : type
+          end
+
           # Defines a singleton method to access the type for this attribute.
           #
           # @param name [Symbol] the attribute name

data/lib/active_model/type/html_safe_string.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require "active_model/type"
+
+module ActiveModel
+  module Type
+    # The string type behind every `option :name, :string` declaration:
+    # ActiveModel's String type copies each value into a fresh String,
+    # which drops the html_safe mark a SafeBuffer carries, so a caller's
+    # `hint: link_to(...)` or `t(".hint_html")` arrived escaped. This
+    # type keeps an html-safe value as it is and casts everything else
+    # exactly as the String type does; a plain String still escapes at
+    # render, because nothing here marks anything safe.
+    #
+    # Substituted inside the option DSL only - never registered, so
+    # `attribute :x, :string` in a host model keeps Rails' own type - and
+    # it reports :string, so the registry and every introspection surface
+    # read the declaration unchanged.
+    class HtmlSafeString < ActiveModel::Type::String
+      private
+
+      # An html-safe String passes through untouched; everything else casts
+      # as a String does.
+      #
+      # @param value [Object] the raw option value
+      # @return [::String]
+      def cast_value(value)
+        return value if value.is_a?(::String) && value.html_safe?
+
+        super
+      end
+    end
+  end
+end

data/lib/poetry/core/check/stable_identity.rb

@@ -24,8 +24,12 @@ module Poetry
       #
       # A component whose registry entry declares "identity" => false
       # renders no poetry-minted id - key:/id: would have nothing to
-      # stabilize - so both rules skip it. The registry derivation owns
-      # that fact per gem; legacy entries without the key keep warning.
+      # stabilize - so both rules skip it (a pathless helper declares the
+      # same in the registry helpers section). The registry derivation
+      # owns that fact per gem; legacy entries without the key keep
+      # warning. A double-splat of an id-bearing hash (`**field.control_attributes`,
+      # `**attrs`) counts as identity too: the id arrives through the splat,
+      # and the scan reads the name, not the hash.
       #
       # @api private
       class StableIdentity
@@ -36,7 +40,8 @@ module Poetry
         CACHE_OPENER = /\A\s*cache[\s(]/
         LOOP_OPENER =
           /\.(?:each|each_with_index|each_with_object|each_slice|map|collect|flat_map)\b.*\bdo\b|\Afor\s.+\sin\s/
-        IDENTITY_ARG = /(?:\bkey:|\bid:|["']key["']\s*=>|["']id["']\s*=>)/
+        IDENTITY_ARG =
+          /(?:\bkey:|\bid:|["']key["']\s*=>|["']id["']\s*=>|\*\*[\w.@]*(?:control_attributes|attributes|attrs)\b)/
 
         # A stable-identity linter over the catalog.
         def initialize(catalog)

data/lib/poetry/core/check.rb

@@ -197,12 +197,16 @@ module Poetry
         # that yields its slot builder.
         def helper_yields?(helper) = !@helper_entries.dig(helper, "yields").nil?
 
-        # A helper whose component entry declares "identity" => false:
-        # its rendered output carries no poetry-minted id, so key:/id:
-        # have nothing to stabilize and the stable-identity rules skip
-        # it. Pathless helpers and legacy entries (no key) read as
-        # minting - their warnings stand.
-        def identity_free?(helper) = @components.dig(@path_by_helper[helper], "identity") == false
+        # A helper whose component entry declares "identity" => false, or
+        # a pathless helper whose registry helpers-section entry declares
+        # it (a table part helper stamps no poetry-minted id): its rendered
+        # output carries no random id, so key:/id: have nothing to
+        # stabilize and the stable-identity rules skip it. Legacy entries
+        # (no key) read as minting - their warnings stand.
+        def identity_free?(helper)
+          @components.dig(@path_by_helper[helper], "identity") == false ||
+            @helper_entries.dig(helper, "identity") == false
+        end
 
         # The element-level wiring projection: which elements of
         # a component carry which controllers, values, actions, and
@@ -1373,9 +1377,10 @@ module Poetry
         # A click target that is not a button: an inert element carrying
         # onclick or wearing role=button. A real <button> brings focus,
         # keyboard activation, and the role for free, which is the first
-        # rule of ARIA. Anchors stay out (a role=button link is an accepted
-        # pattern), and so does a Stimulus click on a bare div - a backdrop
-        # or a row is a legitimate click target without a role.
+        # rule of ARIA. Anchors stay out (a link is a link - the Button's
+        # anchor form renders no role, and an author who adds one has
+        # chosen it), and so does a Stimulus click on a bare div - a
+        # backdrop or a row is a legitimate click target without a role.
         def fake_button_findings(node)
           tag = open_tag_name(node)
           attributes = node.child_nodes.compact.grep(Herb::AST::HTMLAttributeNode)

data/lib/poetry/core/version.rb

@@ -4,6 +4,6 @@ module Poetry
   module Core
     # The gem version. Every gem in the family carries the same version
     # and pins poetry-core to it exactly.
-    VERSION = "0.1.7"
+    VERSION = "0.1.8"
   end
 end

data/lib/poetry/core.rb

@@ -5,6 +5,7 @@ require "zeitwerk"
 require "active_support/concern"
 require "active_model/type/symbol"
 require "active_model/type/list"
+require "active_model/type/html_safe_string"
 
 ActiveModel::Type.register(:symbol, ActiveModel::Type::Symbol)
 ActiveModel::Type.register(:list, ActiveModel::Type::List)

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: poetry-core
 version: !ruby/object:Gem::Version
-  version: 0.1.7
+  version: 0.1.8
 platform: ruby
 authors:
 - Matt Solt
 bindir: exe
 cert_chain: []
-date: 2026-09-20 00:00:00.000000000 Z
+date: 2026-09-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -180,6 +180,7 @@ files:
 - config/importmap.rb
 - config/state_vocabulary.json
 - eslint.config.mjs
+- lib/active_model/type/html_safe_string.rb
 - lib/active_model/type/list.rb
 - lib/active_model/type/symbol.rb
 - lib/poetry-core.rb