poetry-core 0.0.2

data/config/importmap.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+# poetry-core's importmap pins (the importmap-first channel): the
+# host app's importmap merges these, so `import { registerPoetryControllers }
+# from "@poetry/controllers"` works with zero build. Subpath specifiers
+# (@poetry/controllers/helpers/state) resolve here via pin_all_from and in
+# bundler hosts via the npm package's exports map - one source, two channels.
+
+pin "@poetry/controllers", to: "poetry/core/index.js"
+pin_all_from File.expand_path("../app/javascript/poetry/core", __dir__),
+             under: "@poetry/controllers", to: "poetry/core"

data/config/state_vocabulary.json

@@ -0,0 +1,31 @@
+{
+  "keys": [
+    "active",
+    "checked",
+    "closed",
+    "inactive",
+    "indeterminate",
+    "open",
+    "panel-closed",
+    "panel-open",
+    "popup-closed",
+    "popup-open",
+    "pressed",
+    "selected",
+    "unchecked",
+    "unpressed",
+    "unselected"
+  ],
+  "attributes": [
+    "data-active",
+    "data-checked",
+    "data-closed",
+    "data-indeterminate",
+    "data-open",
+    "data-panel-open",
+    "data-popup-open",
+    "data-pressed",
+    "data-selected",
+    "data-unchecked"
+  ]
+}

data/lib/active_model/type/list.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require "active_model/type"
+
+# Reopened to register poetry's option types alongside Rails' own.
+module ActiveModel
+  # Reopened: poetry registers its list (and symbol) attribute types here
+  # so the option/style DSLs can declare them.
+  module Type
+    # A string-array option type (Accordion's open:, future multi-selects).
+    # Casts scalars to one-element arrays and stringifies members, so
+    # open: :shipping and open: %w[a b] both normalize.
+    class List < ActiveModel::Type::Value
+      # Reports :list to introspection (prop_definitions, the registry).
+      #
+      # @return [Symbol]
+      def type
+        :list
+      end
+
+      # Normalizes any value to an array of strings: nil becomes [], a
+      # scalar becomes a one-element array, and members are stringified.
+      #
+      # @param value [Object] the declared option value
+      # @return [Array<String>]
+      def cast(value)
+        return [] if value.nil?
+
+        Array(value).map(&:to_s)
+      end
+    end
+  end
+end

data/lib/active_model/type/symbol.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require "active_model/type"
+
+module ActiveModel
+  module Type
+    # A symbol option type for the option DSL: casts anything responding
+    # to #to_sym and reports :symbol to introspection.
+    #
+    # Strict by design: a value that cannot become a Symbol raises at
+    # assignment - poetry surfaces bad option values where they are
+    # written, not as a validation error nothing reads at render.
+    # Leniency is List's job, not this type's.
+    class Symbol < ActiveModel::Type::String
+      # Without this the type reports :string (inherited) - introspection
+      # (prop_definitions, the registry) must see :symbol.
+      #
+      # @return [Symbol] :symbol
+      def type
+        :symbol
+      end
+
+      # Casts a value to a Symbol; nil stays nil.
+      #
+      # @param value [#to_sym, nil] the raw option value
+      # @return [Symbol, nil]
+      # @raise [ArgumentError] when the value cannot become a Symbol
+      def cast(value)
+        return nil if value.nil?
+        raise ArgumentError, "#{value.inspect} can't become a Symbol (no #to_sym)" unless value.respond_to?(:to_sym)
+
+        value.to_sym
+      end
+    end
+  end
+end

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

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Core
+    module Check
+      # The StableId heuristics: two WARNING-severity rules over
+      # raw ERB text, each catching a render that escapes the per-request
+      # id story and therefore needs explicit identity (key: or id:).
+      #
+      # HEURISTIC, by design and by documentation: block extents are
+      # matched by scanning scriptlet openers/closers, which covers
+      # conventional ERB and misses exotic structure; cross-template
+      # composition (a cached partial rendering components defined
+      # elsewhere) is invisible to any static check - the dev-mode
+      # composed-DOM tripwire is the runtime complement.
+      #
+      # - stable-identity/cache: a poetry component inside a `<% cache %>`
+      #   block without key:/id: freezes a random id into the fragment;
+      #   replays can collide and morphs can't pair it.
+      # - stable-identity/collection: a poetry component inside an
+      #   each/map loop without key:/id: gets a fresh random id per
+      #   render, so Turbo morph replaces it on any reorder instead of
+      #   following the record.
+      #
+      # 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.
+      #
+      # @api private
+      class StableIdentity
+        # A scriptlet that OPENS a Ruby block (needs its own <% end %>):
+        # trailing `do |...|`, or a non-modifier if/unless/case/begin.
+        BLOCK_OPENER =
+          /(?:\bdo\s*(?:\|[^|]*\|)?\s*\z)|(?:\A\s*(?:if|unless|case|while|until|for|begin)\b)/
+        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*=>)/
+
+        def initialize(catalog)
+          @catalog = catalog
+        end
+
+        # Returns [Finding] for one ERB source. Tracks a stack of open
+        # blocks (tagged cache/loop/other) and flags poetry helper calls
+        # rendered while a cache or loop frame is open.
+        def lint(source)
+          findings = []
+          stack = []
+
+          source.each_line.with_index(1) do |line, number|
+            line.scan(/<%(?:=|-)?\s*(.*?)\s*(?:-)?%>/m).each do |(code)|
+              next if code.nil?
+
+              flag_helpers(code, number, stack, findings)
+
+              if code.match?(/\A\s*end\b/)
+                stack.pop
+              elsif code.match?(BLOCK_OPENER)
+                stack << frame_for(code)
+              end
+            end
+          end
+
+          findings
+        end
+
+        private
+
+        def frame_for(code)
+          return :cache if code.match?(CACHE_OPENER)
+          return :loop if code.match?(LOOP_OPENER)
+
+          :other
+        end
+
+        def flag_helpers(code, line, stack, findings)
+          code.scan(/\b(poetry_[a-z0-9_]+)\b/) do |(helper)|
+            next unless @catalog.helper?(helper)
+            next if @catalog.identity_free?(helper)
+            next if code.match?(IDENTITY_ARG)
+
+            if stack.include?(:cache)
+              findings << Finding.new(
+                rule: "stable-identity/cache", severity: :warning, line: line,
+                message: "#{helper} inside a cache block without key:/id: freezes a random id " \
+                         "into the fragment - replays can collide and Turbo morph can't pair it " \
+                         "(heuristic: block extents are scanned, not parsed)"
+              )
+            elsif stack.include?(:loop)
+              findings << Finding.new(
+                rule: "stable-identity/collection", severity: :warning, line: line,
+                message: "#{helper} inside a collection loop without key:/id: re-randomizes " \
+                         "per render - a Turbo morph reorder replaces it instead of following " \
+                         "the record; pass key: record (heuristic)"
+              )
+            end
+          end
+        end
+      end
+    end
+  end
+end