poetry-core 0.0.2

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

@@ -0,0 +1,363 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Core
+    module Concerns
+      # The use_stimulus contract: a class-level, element-major declaration
+      # of the component's Stimulus wiring, replacing both the hand-rolled
+      # `<element>_stimulus_attributes` methods and the previous
+      # `stimulated_with` DSL (controller-major, root-only - it could not
+      # express multi-element wiring, and no component ever adopted it).
+      #
+      #   use_stimulus do
+      #     on :root do
+      #       controller :hover_card do
+      #         register
+      #         value :open
+      #         value :open_delay, unless: -> { open_delay.nil? }
+      #       end
+      #       controller :popper do
+      #         register
+      #         value :side
+      #       end
+      #     end
+      #     on :trigger do
+      #       controller :hover_card do
+      #         action :pointer_enter, on: :pointerenter
+      #       end
+      #       controller :popper do
+      #         target :anchor
+      #       end
+      #     end
+      #   end
+      #
+      # Render side: `stimulus_attributes_for(:trigger)` returns the
+      # element's merged attribute hash (public - templates and slot
+      # lambdas call it directly); `stimulus_action(:open)` /
+      # `stimulus_event(:change)` build validated descriptor strings for
+      # forwarding; `stimulus_attributes(:a, :b) { |a, b| ... }` is the
+      # escape hatch for wiring too dynamic to declare - every builder
+      # shares ONE Attributes instance, so multi-controller merges are
+      # correct by construction.
+      #
+      # Declarations validate against the controllers manifest at CLASS
+      # LOAD (unknown controller/value/action/target/event raises at boot,
+      # not first render) and are declared once per element: a subclass
+      # redeclaring an element REPLACES it wholesale (the Ruby-override
+      # intuition; Sheet/Drawer re-controller their roots this way), while
+      # `on :root, extend: true` merges into the inherited element
+      # (date_field -> time_field adds values). Untouched elements inherit.
+      module Stimulus
+        extend ActiveSupport::Concern
+
+        class_methods do
+          # Declares (part of) the component's stimulus wiring. Multiple
+          # blocks compose additively within a class; shared wiring modules
+          # call this from their `included` hook.
+          #
+          # @yield evaluates the block as a
+          #   {Poetry::Core::Stimulus::Declarations::RootDSL}:
+          #   `on :element do controller :name do ... end end`
+          # @return [void]
+          # @raise [ArgumentError] without a block
+          def use_stimulus(&block)
+            raise ArgumentError, "use_stimulus requires a block" unless block
+
+            dsl = Poetry::Core::Stimulus::Declarations::RootDSL.new(name || to_s)
+            dsl.instance_exec(&block)
+            dsl.elements.each { |element| store_stimulus_element(element) }
+          end
+
+          # This class's own declarations, element name -> Element.
+          #
+          # @return [Hash{Symbol => Poetry::Core::Stimulus::Declarations::Element}]
+          def own_stimulus_elements
+            @own_stimulus_elements ||= {}
+          end
+
+          # The effective wiring after inheritance: walk the superclass
+          # chain root-first, folding each class's declarations over the
+          # inherited set - redeclared elements replace wholesale unless
+          # declared with extend: true, which appends to the inherited
+          # element's wirings.
+          #
+          # @return [Hash{Symbol => Poetry::Core::Stimulus::Declarations::Element}]
+          def stimulus_elements
+            chain = []
+            klass = self
+            while klass.respond_to?(:own_stimulus_elements)
+              chain.unshift(klass)
+              klass = klass.superclass
+            end
+
+            chain.each_with_object({}) do |ancestor, resolved|
+              ancestor.own_stimulus_elements.each do |name, element|
+                resolved[name] =
+                  if element.extend_inherited && resolved[name]
+                    Poetry::Core::Stimulus::Declarations::Element.new(
+                      name: name, extend_inherited: false, conditions: element.conditions,
+                      wirings: resolved[name].wirings + element.wirings
+                    )
+                  else
+                    element
+                  end
+              end
+            end
+          end
+
+          # Every controller identifier declared anywhere on the class, in
+          # declaration order - the search space for unqualified
+          # stimulus_action / stimulus_event resolution.
+          #
+          # @return [Array<String>]
+          def stimulus_identifiers
+            stimulus_elements.values.flat_map { |element| element.wirings.map(&:identifier) }.uniq
+          end
+
+          # Resolves a declaration-style identifier (Symbol suffix, String,
+          # or Array) to its full manifest identifier - see
+          # {Poetry::Core::Stimulus::Declarations.resolve_identifier}.
+          #
+          # @param identifier [Symbol, String, Array] the declaration-style identifier
+          # @return [String] the full Stimulus identifier
+          def resolve_stimulus_identifier(identifier)
+            Poetry::Core::Stimulus::Declarations.resolve_identifier(identifier)
+          end
+
+          # The registry-shaped projection of the RESOLVED wiring (post-
+          # inheritance, so Sheet publishes sheet controllers) - plain data
+          # for the registry, skill text, and docs tables.
+          #
+          # @return [Array<Hash>] one serialized element per declared element
+          def stimulus_definitions
+            stimulus_elements.values.map do |element|
+              Poetry::Core::Stimulus::Declarations.serialize_element(element)
+            end
+          end
+
+          # Descriptor builders are STATIC facts of the declarations, so
+          # they exist at class level - helpers, generator templates, and
+          # test selectors consume them without an instance. on:/at: build
+          # the evented token ("click->id#method"); without on: the bare
+          # descriptor (element-default event).
+          #
+          # @param args [Array<Symbol, String>] `(method)` resolves the method
+          #   across the declared controllers; `(controller, method)` pins one
+          # @param on [Symbol, String, Array<Symbol>, nil] the event(s) to listen for
+          # @param at [Symbol, String, nil] the event target (:window, :document)
+          # @return [String] the action descriptor ("click->poetry--core--x#open")
+          def stimulus_action(*args, on: nil, at: nil)
+            controller, method = unpack_stimulus_descriptor_args(args, :action)
+            identifier = resolve_stimulus_descriptor(controller, method, kind: :action)
+            Poetry::Core::Stimulus::Builder.new(identifier, Poetry::Core::HTML::Attributes.new)
+                                           .action(method, on: on, at: at)
+          end
+
+          # A validated event-name string for listening markup;
+          # stimulus_event(:change) resolves across the declared
+          # controllers, stimulus_event(:controller, :change) pins one.
+          #
+          # @param args [Array<Symbol, String>] `(name)` or `(controller, name)`
+          # @return [String] the full event name
+          def stimulus_event(*args)
+            controller, name = unpack_stimulus_descriptor_args(args, :event)
+            identifier = resolve_stimulus_descriptor(controller, name, kind: :event)
+            Poetry::Core::Stimulus::Declarations.event_name(identifier, name)
+          end
+
+          private
+
+          def unpack_stimulus_descriptor_args(args, kind)
+            case args.size
+            when 1 then [nil, args.first]
+            when 2 then args
+            else
+              raise ArgumentError,
+                    "stimulus_#{kind}(#{kind}) or stimulus_#{kind}(:controller, #{kind})"
+            end
+          end
+
+          def resolve_stimulus_descriptor(controller, name, kind:)
+            return resolve_stimulus_identifier(controller) if controller
+
+            identifiers = stimulus_identifiers
+            if identifiers.empty?
+              raise ArgumentError,
+                    "no use_stimulus declarations on #{self} - pass the controller: " \
+                    "stimulus_#{kind}(:controller, #{name.inspect})"
+            end
+            return identifiers.first if identifiers.size == 1
+
+            matches = identifiers.select { |id| stimulus_descriptor_match?(id, name, kind) }
+            return matches.first if matches.size == 1
+
+            raise ArgumentError,
+                  "#{matches.empty? ? "no declared controller defines" : "ambiguous"} " \
+                  "#{kind} #{name.inspect} (declared: #{identifiers.join(", ")}) - qualify: " \
+                  "stimulus_#{kind}(:controller, #{name.inspect})"
+          end
+
+          def stimulus_descriptor_match?(identifier, name, kind)
+            definition = Poetry::Core::Stimulus::Manifest.definition(identifier)
+            return false unless definition
+
+            case kind
+            when :action
+              definition.fetch("methods", []).include?(Poetry::Core::Stimulus::Declarations.camelize(name))
+            when :event
+              # Real emitted names (poetry:<component>:<event> for component
+              # events; identifier-prefixed for layer events) - match by the
+              # ":<name>" suffix, the same rule event_name resolves by.
+              definition.fetch("events", []).any? { |event| event.end_with?(":#{name}") }
+            end
+          end
+
+          def store_stimulus_element(element)
+            existing = own_stimulus_elements[element.name]
+            own_stimulus_elements[element.name] =
+              if existing
+                Poetry::Core::Stimulus::Declarations::Element.new(
+                  name: element.name,
+                  extend_inherited: existing.extend_inherited || element.extend_inherited,
+                  conditions: element.conditions || existing.conditions,
+                  wirings: existing.wirings + element.wirings
+                )
+              else
+                element
+              end
+          end
+        end
+
+        # The declared wiring for one element as a plain attributes hash,
+        # ready to merge into the element's tag or forward as component
+        # kwargs. Public by design - templates call it, ending the
+        # `public :inner_stimulus_attributes` juggling.
+        #
+        # @param element_name [Symbol, String] a declared element (:root, ...)
+        # @return [Hash] the element's data attributes; empty when the
+        #   element's if:/unless: conditions do not hold
+        # @raise [ArgumentError] for an element no use_stimulus block declared
+        def stimulus_attributes_for(element_name)
+          element = self.class.stimulus_elements[element_name.to_sym]
+          unless element
+            known = self.class.stimulus_elements.keys
+            raise ArgumentError,
+                  "undeclared stimulus element #{element_name.inspect} on #{self.class}" \
+                  "#{known.any? ? " - declared: #{known.join(", ")}" : " (no use_stimulus declarations)"}"
+          end
+          return {} unless stimulus_conditions_met?(element.conditions)
+
+          attrs = Poetry::Core::HTML::Attributes.new
+          element.wirings.each do |wiring|
+            next unless stimulus_conditions_met?(wiring.conditions)
+
+            builder = Poetry::Core::Stimulus::Builder.new(wiring.identifier, attrs)
+            wiring.entries.each do |entry|
+              apply_stimulus_entry(builder, entry) if stimulus_conditions_met?(entry.conditions)
+            end
+          end
+          # The agent-tool registrar rides the root's shared Attributes
+          # instance (Concerns::AgentTools) - a per-instance opt-in.
+          apply_webmcp_wiring(attrs) if element_name.to_sym == :root && respond_to?(:apply_webmcp_wiring)
+          attrs.to_attributes
+        end
+
+        # The escape hatch for wiring too dynamic to declare: yields one
+        # Builder per controller, all sharing ONE Attributes instance.
+        # Controllers resolve like declarations (Symbol -> manifest,
+        # String/Array -> verbatim).
+        #
+        # @param controllers [Array<Symbol, String, Array>] one or more
+        #   controller identifiers
+        # @yield [*builders] one {Poetry::Core::Stimulus::Builder} per
+        #   controller, in order
+        # @return [Hash] the accumulated attributes
+        # @raise [ArgumentError] with no controllers
+        def stimulus_attributes(*controllers)
+          raise ArgumentError, "stimulus_attributes needs at least one controller" if controllers.empty?
+
+          attrs = Poetry::Core::HTML::Attributes.new
+          builders = controllers.map do |controller|
+            Poetry::Core::Stimulus::Builder.new(
+              self.class.resolve_stimulus_identifier(controller), attrs
+            )
+          end
+          yield(*builders) if block_given?
+          attrs.to_attributes
+        end
+
+        # Delegates to the class-level builder (descriptors are static
+        # facts of the declarations); stimulus_action(:open) resolves
+        # across declared controllers, on:/at: build the evented token.
+        #
+        # @param on [Symbol, String, Array<Symbol>, nil] the event(s) to listen for
+        # @param at [Symbol, String, nil] the event target (:window, :document)
+        # @return [String] the action descriptor
+        def stimulus_action(*, on: nil, at: nil)
+          self.class.stimulus_action(*, on: on, at: at)
+        end
+
+        # Delegates to the class-level builder: stimulus_event(:change)
+        # resolves across the declared controllers,
+        # stimulus_event(:controller, :change) pins one.
+        #
+        # @return [String] the full event name
+        def stimulus_event(*)
+          self.class.stimulus_event(*)
+        end
+
+        # Replays one declared Entry onto the element's attribute builder.
+        #
+        # @api private
+        def apply_stimulus_entry(builder, entry)
+          case entry.kind
+          when :register then builder.register_controller
+          when :value then builder.with_value(entry.name, stimulus_value_for(entry))
+          when :action then builder.with_action(entry.name, on: entry.on, at: entry.at)
+          when :target then builder.with_target(entry.name)
+          end
+        end
+
+        # The rendered value of a declared value entry: the literal, or the
+        # named/implicit method's return.
+        #
+        # @api private
+        def stimulus_value_for(entry)
+          source = entry.source
+          case source[:type]
+          when :literal then source[:value]
+          else send(source[:value])
+          end
+        end
+
+        # Whether a declaration's if:/unless: conditions hold for this
+        # instance; nil conditions always hold.
+        #
+        # @param conditions [Hash{Symbol => Symbol, Proc}, nil] the if:/unless: pair
+        # @return [Boolean]
+        # @api private
+        def stimulus_conditions_met?(conditions)
+          return true if conditions.nil?
+
+          if (condition = conditions[:if]) && !evaluate_stimulus_condition(condition)
+            return false
+          end
+          if (condition = conditions[:unless]) && evaluate_stimulus_condition(condition)
+            return false
+          end
+
+          true
+        end
+
+        # Evaluates one if:/unless: condition in instance context.
+        #
+        # @api private
+        def evaluate_stimulus_condition(condition)
+          condition.is_a?(Proc) ? instance_exec(&condition) : send(condition)
+        end
+
+        private :apply_stimulus_entry, :stimulus_value_for, :stimulus_conditions_met?, :evaluate_stimulus_condition
+      end
+    end
+  end
+end

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

@@ -0,0 +1,323 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Core
+    # The concerns composed into {Poetry::Core::Component}: styles, options,
+    # slots, Stimulus wiring, introspection, and part declarations.
+    module Concerns
+      # The Styles concern provides a powerful DSL for defining style attributes in components.
+      # It extends the basic attribute functionality with support for variants, proc defaults,
+      # and tracking of which attributes have been explicitly set vs using defaults.
+      #
+      # The registration, tracking, and hierarchy machinery lives in
+      # DeclaredAttributes (shared with Options); this concern owns the
+      # style-specific surface: variants, inclusion validation, and CSS
+      # emission.
+      #
+      # @example Basic usage with variants
+      #   class MyComponent < Poetry::Core::Component
+      #     style :color, default: :primary, variants: [:primary, :secondary, :success]
+      #     style :size, default: :md, variants: [:sm, :md, :lg]
+      #   end
+      #
+      # @example Proc defaults that reference other attributes
+      #   class Badge::Component < Poetry::Core::Component
+      #     style :color, default: :gray, variants: [...colors]
+      #     style :dot_color, default: -> { color }, variants: [...colors]
+      #   end
+      #
+      #   badge = Badge::Component.new(color: :red)
+      #   badge.dot_color  # => :red (inherits from color)
+      #   badge.color = :blue
+      #   badge.dot_color  # => :blue (still follows color)
+      #
+      #   badge2 = Badge::Component.new(color: :red, dot_color: :green)
+      #   badge2.color = :blue
+      #   badge2.dot_color  # => :green (explicitly set, doesn't follow color)
+      #
+      # @example Required attributes
+      #   class MyComponent < Poetry::Core::Component
+      #     style :type, required: true, variants: [:button, :link]
+      #   end
+      #
+      # @example Boolean styles
+      #   class MyComponent < Poetry::Core::Component
+      #     style :outlined, variants: :boolean, default: false
+      #   end
+      module Styles
+        extend ActiveSupport::Concern
+        include DeclaredAttributes
+
+        # The naming convention joining a component to its sidecar style
+        # dictionary (Dot::Component -> Dot::Style).
+        STYLE_CLASS_SUFFIX = "::Style"
+
+        included do
+          class_attribute :registered_styles,
+                          instance_writer: true,
+                          instance_predicate: false,
+                          default: nil
+        end
+
+        class_methods do
+          # Defines a style attribute for the component.
+          #
+          # @param name [Symbol, String] the name of the style attribute
+          # @param options [Hash] configuration options
+          # @option options [Object, Proc] :default the default value (can be a proc for dynamic defaults)
+          # @option options [Array<Symbol>, :boolean] :variants the allowed values for this attribute
+          # @option options [Boolean] :required whether this attribute must be provided
+          #
+          # @example Static default
+          #   style :color, default: :primary, variants: [:primary, :secondary]
+          #
+          # @example Proc default
+          #   style :dot_color, default: -> { color }, variants: [:primary, :secondary]
+          #
+          # @example Required attribute
+          #   style :type, required: true, variants: [:button, :link]
+          #
+          # @example Boolean attribute
+          #   style :outlined, variants: :boolean, default: false
+          # @return [void]
+          def style(name, **options)
+            register_declared_attribute(:style, name, options)
+
+            variants, required, default_value = extract_style_options(options)
+            type = determine_attribute_type(variants)
+
+            attribute(name, type, **options)
+            add_style_validations(name, type, variants, required)
+            setup_declared_tracking(:style, name, default_value)
+            define_variants_getter(name, variants)
+          end
+
+          # Returns all style attributes that have default values (static or proc).
+          #
+          # @return [Array<Symbol>] sorted array of attribute names with defaults
+          def style_attributes_with_defaults
+            declared_attributes_with_defaults(:style)
+          end
+
+          # Returns style attributes that have static (non-proc) default values.
+          #
+          # @return [Array<Symbol>] sorted array of attribute names with static defaults
+          def style_attributes_with_static_defaults
+            declared_attributes_with_static_defaults(:style)
+          end
+
+          # Returns style attributes that have proc default values.
+          # Proc defaults allow dynamic defaults that can reference other attributes.
+          #
+          # @return [Array<Symbol>] sorted array of attribute names with proc defaults
+          def style_attributes_with_proc_defaults
+            declared_attributes_with_proc_defaults(:style)
+          end
+
+          # Returns all style attributes defined on this component and its ancestors.
+          #
+          # @return [Array<Symbol>] sorted array of all style attribute names
+          def style_attributes
+            declared_attributes(:style)
+          end
+
+          # The doc: strings declared on this component's styles,
+          # hierarchy-wide (nearest declaration wins).
+          #
+          # @return [Hash{Symbol => String}]
+          def style_docs
+            declared_docs(:style)
+          end
+
+          # Checks if the given name is a defined style attribute.
+          #
+          # @param name [Symbol, String] the attribute name to check
+          # @return [Boolean] true if the attribute is a style attribute
+          def has_style_attribute?(name)
+            style_attributes.include?(name.to_sym)
+          end
+
+          # Automatically determines the corresponding Style class for this component.
+          # Example: Poetry::Core::Dot::Component -> Poetry::Core::Dot::Style
+          #
+          # @return [Class, nil] the style class if it exists, nil otherwise
+          def style_class
+            style_class_name = component_module + STYLE_CLASS_SUFFIX
+            style_class_name.constantize
+          rescue NameError => e
+            log_style_class_not_found(style_class_name, e) if defined?(Rails)
+            nil
+          end
+
+          private
+
+          # 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
+          def extract_style_options(options)
+            variants = options.delete(:variants)
+            required, default_value = extract_declared_defaults(options)
+
+            [variants, required, default_value]
+          end
+
+          # Determines the attribute type based on the variants option.
+          #
+          # @param variants [Object] the variants option value
+          # @return [Symbol] :boolean or :symbol
+          def determine_attribute_type(variants)
+            variants == :boolean ? :boolean : :symbol
+          end
+
+          # Adds validations for the style attribute.
+          #
+          # @param name [Symbol] the attribute name
+          # @param type [Symbol] the attribute type
+          # @param variants [Object] the allowed variants
+          # @param required [Boolean] whether the attribute is required
+          def add_style_validations(name, type, variants, required)
+            if type == :boolean
+              validates name, inclusion: { in: [true, false] }
+            elsif variants
+              validates name, inclusion: { in: variants }
+            end
+            validates name, presence: true if required
+          end
+
+          # Defines a singleton method to access the variants for this attribute.
+          #
+          # @param name [Symbol] the attribute name
+          # @param variants [Object] the variants value
+          def define_variants_getter(name, variants)
+            define_singleton_method("#{name}_variants") { variants }
+          end
+
+          # Logs when a style class cannot be found.
+          #
+          # @param style_class_name [String] the name of the style class that was not found
+          # @param error [NameError] the error that was raised
+          def log_style_class_not_found(style_class_name, error)
+            Rails.logger.debug { "Style class not found: #{style_class_name} (#{error.message})" }
+          end
+        end
+
+        # Checks if the given attribute is a style attribute.
+        #
+        # @param name [Symbol, String] the attribute name to check
+        # @return [Boolean] true if the attribute is a style attribute
+        def style_attribute?(name)
+          self.class.has_style_attribute?(name.to_sym)
+        end
+
+        # Returns all style attributes defined on this component's class.
+        #
+        # @return [Array<Symbol>] sorted array of all style attribute names
+        def style_attributes
+          self.class.style_attributes
+        end
+
+        # Returns only the style attributes that have been explicitly set (not using defaults).
+        #
+        # @return [Array<Symbol>] sorted array of initialized attribute names
+        def initialized_style_attributes
+          initialized_declared_attributes(registered_styles)
+        end
+
+        # Checks if a style attribute has been explicitly initialized.
+        #
+        # @param name [Symbol, String] the attribute name to check
+        # @return [Boolean] true if the attribute was explicitly set
+        def style_attribute_initialized?(name)
+          declared_attribute_registered?(registered_styles, name)
+        end
+
+        # Returns all style attributes with their initialization status.
+        #
+        # @return [Hash{Symbol => Boolean}] map of attribute names to initialized status
+        def style_attributes_status
+          style_attributes.to_h do |attr|
+            [attr, style_attribute_initialized?(attr)]
+          end
+        end
+
+        # Returns a hash of all style attributes with their current values.
+        #
+        # @return [Hash{Symbol => Object}] map of attribute names to their values
+        def styles
+          style_attributes.to_h do |attr|
+            [attr, send(attr)]
+          end
+        end
+
+        # Returns the style class for this component.
+        #
+        # @return [Class, nil] the style class if it exists
+        def styler
+          self.class.style_class
+        end
+
+        # Generates CSS classes based on style attributes and additional options.
+        #
+        # The emission is governed by `css_mode`: `:tailwind` (default)
+        # resolves the style values to utility classes through the sidecar
+        # Style dictionary; `:bem` emits the stable BEM token IR instead, for
+        # hosts that bring their own CSS (styled against the generated
+        # reference stylesheet). Override per call with `css_mode:`, or
+        # globally via `Poetry::Core::Config.current.css_mode`.
+        #
+        # @param element [Symbol, nil] a named element (BEM `block__element`)
+        # @param options [Hash] additional style options to merge
+        # @yield optional block passed to the style class
+        # @return [String, nil] the generated CSS classes; nil in :tailwind
+        #   mode for a component without a sidecar Style class
+        # @raise [Poetry::Core::Error] for a css_mode other than :tailwind
+        #   or :bem
+        def css(element = nil, **options, &)
+          mode = options.delete(:css_mode) || Poetry::Core::Config.current.css_mode
+
+          case mode
+          when :tailwind
+            # A component with no sidecar Style class has no dictionary -
+            # it renders unstyled (caught dogfooding poetry-ui's Icon).
+            return nil unless styler
+
+            style_attributes = styles.merge(options)
+            styler.css(element, **style_attributes, &)
+          when :bem
+            extra = options.delete(:class)
+            [bem(element, **options), extra].compact.join(" ")
+          else
+            raise Poetry::Core::Error, "unknown css_mode #{mode.inspect} (expected :tailwind or :bem)"
+          end
+        end
+
+        # The component's BEM block name - the stable, framework-agnostic
+        # class contract of the token IR ("poetry/core/dot" -> "poetry-core-dot").
+        #
+        # @return [String]
+        def bem_block
+          self.class.component_path.tr("/", "-")
+        end
+
+        # The BEM token IR for this component (the pipeline's Step 2): the
+        # block class plus one modifier class per style value - symbols as
+        # `block--attr-value`, booleans as presence modifiers (`block--attr`).
+        # A named element returns `block__element`.
+        #
+        # @param element [Symbol, nil] a named element
+        # @param overrides [Hash] style overrides merged over the resolved values
+        # @return [String] space-separated BEM classes
+        def bem(element = nil, **overrides)
+          return "#{bem_block}__#{element}" if element
+
+          styles.merge(overrides).each_with_object([bem_block]) do |(attr, value), tokens|
+            next if value.nil? || value == false
+
+            tokens << (value == true ? "#{bem_block}--#{attr}" : "#{bem_block}--#{attr}-#{value}")
+          end.join(" ")
+        end
+      end
+    end
+  end
+end