poetry-core 0.0.2

data/lib/poetry/core/config.rb

@@ -0,0 +1,286 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Core
+    # Manages configuration settings for the Poetry::Core module.
+    #
+    # This class provides a flexible configuration system using ActiveSupport::OrderedOptions
+    # under the hood, allowing access to configuration values using either hash-style or
+    # method-style syntax. It supports both a singleton pattern via {.current} for global
+    # configuration and the ability to create custom configuration instances.
+    #
+    # The configuration system is designed to be easily extensible while providing sensible
+    # defaults for all Poetry::Core components.
+    #
+    # @example Accessing global configuration
+    #   Poetry::Core::Config.current.classname_merger
+    #   # => #<Poetry::Core::CSS::TailwindMerger:0x00007f8b1c0a3b40>
+    #
+    # @example Modifying global configuration
+    #   Poetry::Core::Config.current.icon_library = :my_icons
+    #
+    # @example Creating a custom configuration instance
+    #   config = Poetry::Core::Config.new
+    #   config.classname_merger = MyCustomMerger.new
+    #
+    # @example Using hash-style access
+    #   Poetry::Core::Config.current[:classname_merger]
+    #   Poetry::Core::Config.current[:custom_setting] = "value"
+    #
+    # @see Poetry::Core::CSS::TailwindMerger
+    # @see Poetry::Core::Stimulus::Merger
+    class Config
+      class << self
+        # Creates a new configuration instance with default settings.
+        #
+        # This is aliased from the standard {#initialize} method to provide a more
+        # semantic way to create default configurations.
+        #
+        # @return [Poetry::Core::Config] A new configuration instance with default values
+        # @example
+        #   config = Poetry::Core::Config.default
+        alias default new
+
+        # Returns the default configuration values.
+        #
+        # These defaults are used when initializing new configuration instances and
+        # define the standard behavior for all Poetry::Core components.
+        #
+        # The keys and their defaults:
+        #
+        # - `classname_merger` ({Poetry::Core::CSS::TailwindMerger}) - resolves
+        #   conflicting utility classes when caller classes meet component
+        #   classes.
+        # - `stimulus_merger` ({Poetry::Core::Stimulus::Merger}) - combines
+        #   Stimulus data attributes without duplicating controllers or
+        #   actions.
+        # - `css_mode` (`:tailwind`) - `:tailwind` emits resolved utility
+        #   classes; `:bem` emits the BEM token IR for bring-your-own-CSS
+        #   hosts.
+        # - `icon_library` (`:lucide`) - the active icon set, by the key it
+        #   registered under ({Poetry::Core::Icons.register}).
+        # - `raise_on_missing_icon` (`nil`) - the policy for a dynamic icon
+        #   name that resolves to nothing: nil raises in local environments
+        #   and degrades to the fallback elsewhere; true/false force one
+        #   behavior.
+        # - `icon_fallback` (`:"circle-question-mark"`) - rendered instead
+        #   of a missing icon when not raising; nil re-raises.
+        # - `on_missing_icon` (`nil`) - an optional callable
+        #   `(name:, library:, error:)` fired before the fallback renders.
+        # - `webmcp_registration_budget` (`20`) - the per-document cap on
+        #   WebMCP tool registrations a page's opted-in instances may make;
+        #   poetry-agent's `registration_budget` setting writes through.
+        # - `stable_id_mode` (`:off`) - the opt-in `:sequence` mode seeds a
+        #   per-request deterministic id sequence (read the hazards in
+        #   StableId before enabling).
+        # - `stable_id_seed` - the request-to-seed callable for that mode
+        #   (defaults to the request path).
+        #
+        # @return [ActiveSupport::OrderedOptions] the default configuration
+        #
+        # @example Getting default values
+        #   defaults = Poetry::Core::Config.defaults
+        #   defaults.classname_merger # => #<Poetry::Core::CSS::TailwindMerger:0x00007f8b1c0a3b40>
+        #   defaults.css_mode # => :tailwind
+        def defaults
+          ActiveSupport::OrderedOptions.new.merge!({
+                                                     classname_merger: Poetry::Core::CSS::TailwindMerger.new,
+                                                     stimulus_merger: Poetry::Core::Stimulus::Merger.new,
+                                                     # :tailwind emits resolved utility classes (default);
+                                                     # :bem emits the BEM token IR for bring-your-own-CSS
+                                                     # hosts (no :both, deliberately).
+                                                     css_mode: :tailwind,
+                                                     # The active icon set (Lucide default; sets
+                                                     # register via Poetry::Core::Icons.register).
+                                                     icon_library: :lucide,
+                                                     # The missing-icon policy. Static literals
+                                                     # are caught by poetry check; a DYNAMIC name (a DB
+                                                     # value, a user setting) surfaces at render. nil =
+                                                     # auto: raise in Rails.env.local?, degrade to
+                                                     # icon_fallback elsewhere. true/false force it.
+                                                     raise_on_missing_icon: nil,
+                                                     # StableId sequence mode (OPT-IN, experimental):
+                                                     # :off (default) or :sequence - the engine's
+                                                     # around_action seeds a per-request deterministic
+                                                     # id sequence. Read the hazards in StableId before
+                                                     # enabling; keyed identity (key:) is the general
+                                                     # answer, this mode is for byte-stable content
+                                                     # pages only.
+                                                     stable_id_mode: :off,
+                                                     stable_id_seed: ->(request) { request.path }, # rubocop:disable Style/SymbolProc -- the documented override shape
+                                                     # Rendered instead of a missing icon when not
+                                                     # raising; nil re-raises. Must exist in every
+                                                     # registered set (Lucide ships it).
+                                                     icon_fallback: :"circle-question-mark",
+                                                     # Optional callable(name:, library:, error:) fired
+                                                     # before the fallback renders - the instrumentation
+                                                     # seam (log, notify, count). Fires per render.
+                                                     on_missing_icon: nil,
+                                                     # The per-document WebMCP registration budget
+                                                     # (Concerns::AgentTools::WEBMCP_DEFAULT_BUDGET):
+                                                     # the registrar drops registrations past it with
+                                                     # a console warning. Rides the opted-in root only
+                                                     # when it differs from the runtime's default.
+                                                     webmcp_registration_budget: 20
+                                                   })
+        end
+
+        # Returns the global singleton configuration instance.
+        #
+        # This method provides access to the shared configuration used throughout the
+        # application. The instance is created lazily on first access and persists for
+        # the lifetime of the application.
+        #
+        # @return [Poetry::Core::Config] The global configuration instance
+        #
+        # @example Accessing global settings
+        #   Poetry::Core::Config.current.css_mode
+        #   # => :tailwind
+        #
+        # @example Modifying global settings
+        #   Poetry::Core::Config.current.classname_merger = CustomMerger.new
+        #
+        # @note Changes to the global configuration will affect all Poetry::Core components
+        #   throughout the application.
+        def current
+          @current ||= default
+        end
+      end
+
+      # @!method classname_merger
+      #   The merger that resolves conflicting utility classes when caller
+      #   classes meet component classes.
+      #   @return [Poetry::Core::CSS::TailwindMerger] The CSS class merger instance
+      #
+      # @!method classname_merger=(merger)
+      #   Replaces the class merger.
+      #   @param merger [Poetry::Core::CSS::TailwindMerger] The CSS class merger instance to use
+      #   @return [Poetry::Core::CSS::TailwindMerger]
+      #
+      # @!method stimulus_merger
+      #   The merger that combines Stimulus data attributes without
+      #   duplicating controllers or actions.
+      #   @return [Poetry::Core::Stimulus::Merger] The Stimulus attribute merger instance
+      #
+      # @!method stimulus_merger=(merger)
+      #   Replaces the Stimulus attribute merger.
+      #   @param merger [Poetry::Core::Stimulus::Merger] The Stimulus attribute merger instance to use
+      #   @return [Poetry::Core::Stimulus::Merger]
+      #
+      # @!method css_mode
+      #   The class emission mode: `:tailwind` resolves style values to
+      #   utility classes, `:bem` emits the BEM token IR.
+      #   @return [Symbol] :tailwind or :bem
+      #
+      # @!method css_mode=(mode)
+      #   Sets the class emission mode.
+      #   @param mode [Symbol] :tailwind or :bem
+      #   @return [Symbol]
+      #
+      # @!method icon_library
+      #   The key of the active icon set ({Poetry::Core::Icons.register}).
+      #   @return [Symbol]
+      #
+      # @!method icon_library=(key)
+      #   Selects the active icon set.
+      #   @param key [Symbol, String] a registered library key
+      #   @return [Symbol, String]
+      #
+      # @!method raise_on_missing_icon
+      #   The policy for a dynamic icon name that resolves to nothing: nil
+      #   raises in local environments and degrades to the fallback
+      #   elsewhere; true/false force one behavior.
+      #   @return [Boolean, nil]
+      #
+      # @!method raise_on_missing_icon=(policy)
+      #   Sets the missing-icon policy.
+      #   @param policy [Boolean, nil]
+      #   @return [Boolean, nil]
+      #
+      # @!method icon_fallback
+      #   The icon rendered instead of a missing one when not raising; nil
+      #   re-raises. Must exist in every registered set.
+      #   @return [Symbol, nil]
+      #
+      # @!method icon_fallback=(name)
+      #   Sets the fallback icon.
+      #   @param name [Symbol, nil]
+      #   @return [Symbol, nil]
+      #
+      # @!method webmcp_registration_budget
+      #   The per-document WebMCP registration budget the registrar
+      #   enforces (default 20).
+      #   @return [Integer]
+      #
+      # @!method webmcp_registration_budget=(count)
+      #   Sets the per-document WebMCP registration budget.
+      #   @param count [Integer]
+      #   @return [Integer]
+      #
+      # @!method on_missing_icon
+      #   The instrumentation hook fired before a fallback icon renders,
+      #   called with `name:`, `library:`, and `error:`.
+      #   @return [#call, nil]
+      #
+      # @!method on_missing_icon=(callable)
+      #   Sets the missing-icon hook.
+      #   @param callable [#call, nil]
+      #   @return [#call, nil]
+      #
+      # @!method stable_id_mode
+      #   The StableId sequence mode: `:off`, or the opt-in `:sequence`.
+      #   @return [Symbol]
+      #
+      # @!method stable_id_mode=(mode)
+      #   Sets the StableId sequence mode.
+      #   @param mode [Symbol] :off or :sequence
+      #   @return [Symbol]
+      #
+      # @!method stable_id_seed
+      #   The request-to-seed callable the `:sequence` mode derives its
+      #   per-request id sequence from.
+      #   @return [#call]
+      #
+      # @!method stable_id_seed=(callable)
+      #   Sets the seed callable.
+      #   @param callable [#call] receives the request, returns the seed
+      #   @return [#call]
+
+      # The declared configuration surface: every key {.defaults} ships.
+      # Each is a real reader/writer pair (delegated just below); unknown
+      # keys still flow through delegate_missing_to, so hosts may stash
+      # their own values.
+      SETTINGS = %i[classname_merger stimulus_merger css_mode icon_library
+                    raise_on_missing_icon icon_fallback on_missing_icon
+                    stable_id_mode stable_id_seed
+                    webmcp_registration_budget].freeze
+
+      delegate(*SETTINGS, *SETTINGS.map { |key| :"#{key}=" }, to: :@config)
+
+      # Delegates all method calls to the internal configuration object.
+      #
+      # This allows the Config instance to act as a transparent wrapper around
+      # ActiveSupport::OrderedOptions, supporting both method-style and hash-style
+      # access to configuration values.
+      #
+      # @api private
+      delegate_missing_to :@config
+
+      # Initializes a new configuration instance with default values.
+      #
+      # The new instance gets a clone of the default configuration, ensuring each
+      # configuration object is independent and modifications won't affect the defaults
+      # or other instances.
+      #
+      # @return [Poetry::Core::Config] A new configuration instance
+      #
+      # @example Creating an isolated configuration
+      #   config = Poetry::Core::Config.new
+      #   config.css_mode = :bem
+      #   Poetry::Core::Config.current.css_mode # => :tailwind (unchanged)
+      def initialize
+        @config = self.class.defaults.clone
+      end
+    end
+  end
+end

data/lib/poetry/core/contrib/wrapped_helper.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Core
+    # Opt-in helper mixins shipped alongside the core.
+    module Contrib
+      # Provides a convenient method to wrap components with custom HTML code.
+      # Adapted from an MIT-licensed source (source and license in
+      # THIRD_PARTY_NOTICES.md).
+      #
+      # This module adds the `#wrapped` method to components, allowing them to be
+      # easily wrapped with a {Poetry::Core::Wrapper::Component}. The wrapper component
+      # enables adding custom HTML around a component without modifying the
+      # component itself, and respects the component's `render?` conditional logic.
+      #
+      # @example Basic usage
+      #   class MyComponent < Poetry::Core::Component
+      #     # WrappedHelper is already included via Poetry::Core::Component
+      #   end
+      #
+      #   # In a view or template
+      #   component = MyComponent.new(title: "Hello")
+      #   wrapper = component.wrapped
+      #
+      # @example Using in a view template with custom wrapper HTML
+      #   <%# app/components/my_component/component.html.erb %>
+      #   <% component = MyComponent.new(title: "Hello") %>
+      #   <%= render component.wrapped do |wrapper| %>
+      #     <div class="custom-wrapper">
+      #       <h2>Wrapped Content:</h2>
+      #       <%= wrapper.component %>
+      #     </div>
+      #   <% end %>
+      #
+      # @example Conditional rendering
+      #   # The wrapper only renders if the wrapped component's render? returns true
+      #   class ConditionalComponent < Poetry::Core::Component
+      #     def render?
+      #       @show_content
+      #     end
+      #   end
+      #
+      #   # If @show_content is false, neither the wrapper nor component will render
+      #   <%= render component.wrapped do |wrapper| %>
+      #     <div class="wrapper"><%= wrapper.component %></div>
+      #   <% end %>
+      #
+      # @see Poetry::Core::Wrapper::Component
+      module WrappedHelper
+        # Wraps the current component instance in a {Poetry::Core::Wrapper::Component}.
+        #
+        # This creates a wrapper that can be rendered with custom HTML surrounding
+        # the component. The wrapper respects the wrapped component's `render?`
+        # method, only rendering if it returns true.
+        #
+        # @return [Poetry::Core::Wrapper::Component] a wrapper component containing self
+        #
+        # @example
+        #   component = MyComponent.new
+        #   wrapper = component.wrapped
+        #   wrapper.component_instance # => the original component
+        def wrapped
+          Poetry::Core::Wrapper::Component.new(self)
+        end
+      end
+    end
+  end
+end

data/lib/poetry/core/css/bem_merger.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Core
+    module CSS
+      # The BEM-mode classname merger: the classname_merger a host pairs
+      # with `css_mode = :bem`. Same contract as {TailwindMerger}
+      # (flatten, stringify, drop blanks, nil for empty input) with
+      # exactly two behaviors on top: order-preserving token dedupe and
+      # a space join - no Tailwind conflict semantics applied to a BEM
+      # host's classes.
+      #
+      # Deliberately NO modifier-axis conflict resolution: the BEM
+      # modifier grammar is dictionary-dependent at the string level
+      # (values carry dashes - `--align-inline-start` - and names carry
+      # underscores), so a string merger guessing axes would be wrong.
+      # Style axes are driven through component options; conflicts
+      # between raw caller classes belong to the host stylesheet's
+      # cascade.
+      #
+      # @example Pairing with BEM mode (config/initializers/poetry.rb)
+      #   Poetry::Core::Config.current.css_mode = :bem
+      #   Poetry::Core::Config.current.classname_merger =
+      #     Poetry::Core::CSS::BemMerger.new
+      #
+      # @example Dedupe without Tailwind semantics
+      #   Poetry::Core::CSS::BemMerger.new.merge("pill pill--variant-danger", "pill", "p-4 p-2")
+      #   # => "pill pill--variant-danger p-4 p-2"
+      class BemMerger
+        # Merges class lists BEM-style: normalize, dedupe at the token
+        # level (first occurrence keeps its position), join.
+        #
+        # @param classes [Array<String, Symbol, Array, nil>] class names,
+        #   arrays of class names, or nils
+        # @return [String, nil] the merged classes, or nil when empty
+        def merge(*classes)
+          normalized = classes.flatten.compact_blank.map(&:to_s)
+          return nil if normalized.empty?
+
+          normalized.flat_map(&:split).uniq.join(" ")
+        end
+      end
+    end
+  end
+end

data/lib/poetry/core/css/bem_reference.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Core
+    module CSS
+      # Generates the reference stylesheet for `css_mode = :bem` from a Style
+      # dictionary: every BEM class the component emits, as a documented CSS
+      # selector skeleton the consumer fills with their own rules. Each
+      # selector carries a `tailwind-equivalent` comment - the utilities the
+      # default (Tailwind) theme resolves that token to - so the reference
+      # doubles as the class contract's documentation.
+      #
+      # The header embeds the dictionary's capsule digest as a leak-guard:
+      # CSS written against an older dictionary is detectable by digest
+      # mismatch instead of silently drifting on upgrade.
+      #
+      # @example
+      #   Poetry::Core::CSS::BemReference.new(MyApp::Button::Style).css
+      #   # => "/* poetry BEM reference for `.button` - capsule 1a2b3c... */\n.button { ... }"
+      #
+      # @api private
+      class BemReference
+        def initialize(style_class, block: style_class.bem_block)
+          raise ArgumentError, "#{style_class} has no derivable BEM block" unless block
+
+          @resolver = style_class.resolver
+          @block = block
+        end
+
+        def css
+          [header, root_rule, element_rules, variant_rules, compound_rules]
+            .flatten.compact.join("\n")
+        end
+
+        private
+
+        def header
+          <<~CSS
+            /* poetry BEM reference for `.#{@block}` - capsule #{@resolver.digest}
+               Generated from the Style dictionary; consumers on css_mode = :bem
+               style these selectors with their own CSS. The tailwind-equivalent
+               comments show what the default (Tailwind) theme resolves each
+               token to. */
+          CSS
+        end
+
+        def root_rule
+          rule(".#{@block}", @resolver.bases.join(" "))
+        end
+
+        def element_rules
+          @resolver.elements.map do |name, classes|
+            rule(".#{@block}__#{name}", classes.join(" "))
+          end
+        end
+
+        def variant_rules
+          @resolver.variants.flat_map do |attr, mapping|
+            mapping.map { |value, classes| rule(modifier_selector(attr, value), classes) }
+          end.compact
+        end
+
+        def compound_rules
+          @resolver.compounds.map do |compound|
+            selector = compound.criteria.map { |attr, value| modifier_selector(attr, value) }.join
+            rule(selector, compound.classes)
+          end
+        end
+
+        # Boolean modifiers are presence classes (`block--attr`); `false` has
+        # no class and produces no rule.
+        def modifier_selector(attr, value)
+          return nil if value == false
+
+          value == true ? ".#{@block}--#{attr}" : ".#{@block}--#{attr}-#{value}"
+        end
+
+        def rule(selector, classes)
+          return nil if selector.nil?
+
+          body = classes.to_s.strip.empty? ? "/* (no default styles) */" : "/* tailwind-equivalent: #{classes} */"
+          "#{selector} { #{body} }"
+        end
+      end
+    end
+  end
+end

data/lib/poetry/core/css/override_scan.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Core
+    module CSS
+      # The .cn-* override contract - an intent-vs-accident distinction for
+      # poetry's one un-contracted styling surface. Hosts MAY restyle
+      # theme-owned cn-* classes from their own CSS (any unlayered rule
+      # beats the theme's layer(base)) - but every such override must be
+      # DECLARED: a dated, reasoned, scoped entry under `overrides:` in
+      # config/poetry_components.yml. Undeclared overrides are drift;
+      # declared ones are design intent that travels into DESIGN.md's
+      # "Intentional deviations" section.
+      #
+      # Pure logic: {relative_path => css} sources + raw declaration hashes
+      # in, findings out. The poetry:design:overrides task feeds and prints
+      # it. Declaration rules: `reason` is required; `cn: "*"` must be
+      # file-scoped - a repo-wide blanket cannot happen by accident.
+      #
+      # @example
+      #   scan = Poetry::Core::CSS::OverrideScan.new(
+      #     sources: { "app/assets/site.css" => css },
+      #     declarations: YAML.load_file("config/poetry_components.yml")["overrides"]
+      #   )
+      #   scan.ok? || scan.undeclared # => [["app/assets/site.css", ["cn-button"]]]
+      #
+      # @api private
+      class OverrideScan
+        CN_TOKEN = /\.(cn-[a-z0-9-]+)/
+        COMMENT = %r{/\*.*?\*/}m
+
+        Declaration = Struct.new(:cn, :files, :reason, :created, :index, :matched, keyword_init: true) do
+          def wildcard? = cn == "*"
+
+          def covers?(path, cn_class)
+            return false unless wildcard? || Array(cn).include?(cn_class)
+            return true if files.nil? || files.empty?
+
+            files.any? { |glob| File.fnmatch(glob, path, File::FNM_PATHNAME | File::FNM_EXTGLOB) }
+          end
+        end
+
+        attr_reader :undeclared, :invalid, :stale, :declared_count
+
+        def initialize(sources:, declarations:)
+          @declarations, @invalid = normalize(Array(declarations))
+          @undeclared = []
+          @declared_count = 0
+          scan(sources)
+          @stale = @declarations.reject(&:matched)
+        end
+
+        def ok? = @undeclared.empty? && @invalid.empty?
+
+        # The exact YAML to paste for an undeclared override - a finding
+        # ships its own exception command.
+        def snippet_for(path, classes)
+          cn = classes.size == 1 ? classes.first.inspect : "\"*\""
+          <<~YAML
+            - cn: #{cn}
+              files: ["#{path}"]
+              reason: "TODO - why this override is intentional"
+              created: #{Time.now.strftime("%Y-%m-%d")}
+          YAML
+        end
+
+        private
+
+        def normalize(raw)
+          valid = []
+          invalid = []
+          raw.each_with_index do |entry, index|
+            unless entry.is_a?(Hash)
+              invalid << "overrides[#{index}]: not a mapping"
+              next
+            end
+            files = Array(entry["files"]).map(&:to_s)
+            declaration = Declaration.new(cn: entry["cn"] || "*", files: files,
+                                          reason: entry["reason"].to_s, created: entry["created"],
+                                          index: index, matched: false)
+            if declaration.reason.strip.empty?
+              invalid << "overrides[#{index}]: `reason` is required - an override without a why is drift"
+            elsif declaration.wildcard? && files.empty?
+              invalid << "overrides[#{index}]: `cn: \"*\"` must be file-scoped (add `files:`) - " \
+                         "a repo-wide blanket cannot happen by accident"
+            else
+              valid << declaration
+            end
+          end
+          [valid, invalid]
+        end
+
+        def scan(sources)
+          sources.each do |path, css|
+            classes = css.gsub(COMMENT, "").scan(CN_TOKEN).flatten.uniq.sort
+            next if classes.empty?
+
+            open = classes.reject do |cn_class|
+              hit = @declarations.select { |declaration| declaration.covers?(path, cn_class) }
+              hit.each { |declaration| declaration.matched = true }
+              @declared_count += 1 if hit.any?
+              hit.any?
+            end
+            @undeclared << [path, open] if open.any?
+          end
+        end
+      end
+    end
+  end
+end