poetry-core 0.1.0 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ec837c1c31e39d20d47e278d7ae7dde0ff26f036f17e8bc33dcf81abd6daafdd
-  data.tar.gz: 650c0d9053220a0500ae619402dd92515248b0b6bfe960f85e874ace979f36af
+  metadata.gz: 68f26084516bebd43571b5f687d9fb07cce952f00aba8e41448715b66b996fba
+  data.tar.gz: d1ec44154a85d4c2b4fda384432f2e73349973dfc21862aeddf06bde0d09303b
 SHA512:
-  metadata.gz: d9e82544dcb308ba9feea37d8de5f2272bae3be011c59601c584f6b2b90f1156f6bfef8864d03b0d17c62308eba42e8f82572acfc55a7dd8ce3510c95266ca8a
-  data.tar.gz: b35b3d54fa5f02ebd98357a1c93cf4b89a0969a45c1793e15e782d23921cb670a52889fc888e0204dbde640bc0a83176c54ea8f285031f41802b12bbadbd45de
+  metadata.gz: 65965b0865ade83c8b778c3ba773c6d1272bd4da2139e68cd8ab5b798903d12e3224d75df0f77f849cd72403e782d5da87ba470a4597d8654c7ab72a6bdc90ea
+  data.tar.gz: e3b822469b4ed1253193dd331b9b43b7923aa5626265ec9f6d1cdc6c4112a7306eb93e37f3a7670b9985da406ef804b5eb4b5174b03263004eced90e306e03c3

data/CHANGELOG.md

@@ -1,6 +1,53 @@
 # Changelog
 
-## [Unreleased]
+## [0.1.2] - 2026-09-13
+
+### Added
+
+- `helper :name` on a component: an application's (or an engine's) own component written on the DSL names its view helper. The engine defines that helper on Action View at boot and on every reload, and `Poetry::Core::HostComponents` discovers the app's components by convention (under `app/`, outside the `poetry/` namespace, published), builds their registry live, and reads their declared helpers boot-free from source. The registry entry carries `helper`; `poetry check` lints a declared helper under its own name (options, variants, arity, stable identity); llms.txt and the generated skill take an app registry and render an App components section and a `references/app.md`.
+- The runtime values tier. A component built with an off-list style value or a missing required option raises at construction in development and test, naming the allowed values with a did-you-mean, and logs in production while rendering as before (the passthrough guard's posture, at the same seam, so it holds whatever a component does in `before_render`). Only the DSL's own validations are enforced; a component's custom validators keep their own policy. An omitted style is nil, not an off-list value (`allow_nil` on the inclusion validations). The check is a direct lookup over the declared vocabulary (`style` variants, `required`, and `validates ... inclusion: { in: [...] }` on a declared attribute), not an ActiveModel validation pass.
+- Render cost. Measured on 200 Buttons in one view context, a Button went from 0.122 ms to 0.089 ms: the values tier is a direct lookup instead of a validation pass, construction converts the caller's attributes once, and the Style resolver memoises its dictionary walk per variant tuple (bounded by the variant space, cleared when the dictionary changes). The remaining time is ViewComponent's own render (about forty percent) and attribute assignment (a quarter).
+- The class-name merger follows the kit's CSS mode (`Poetry::Core::CSS::Modes.merger_for`): a `:bem` kit merges with a `BemMerger`, a `:tailwind` kit with a `TailwindMerger`. The global `classname_merger` is honoured whenever it is of the right kind, so a customised Tailwind merger still reaches poetry-ui and a host's BEM merger still reaches its BEM kit; a mismatch falls back to the stock merger of the mode. A host that set the global mode to `:bem` without a merger now gets the BEM merger on its kit, the pairing the guide always asked for. Attribute objects keep their assigned merger across copies.
+- `css_mode` is decided per kit. A component class declares it (`css_mode :bem`, inherited), or a kit pins its namespace (`Poetry::Core::CSS::Modes.pin("Acme::Ui", :bem)`); the global `Config.current.css_mode` is the default for kits that declare nothing, and a `css_mode:` keyword on a `css` call still wins over all of them. poetry-ui and poetry-charts pin `:tailwind`, so a host's global never reaches them and a BEM kit on the DSL renders beside them in one app. Before, the global was the only switch and setting it to `:bem` silently stripped poetry-ui's styling.
+- `OverrideScan` takes `owned:`, the theme-owned `cn-*` names; only a rule against one of those is an override. A host's own `cn-*` classes (a kit's dictionary, a page helper) are never findings. Nil keeps the old meaning (every `cn-*` name).
+- The host controllers manifest. `Poetry::Core::Stimulus::HostManifest` reads `app/javascript/controllers` (static targets, values in both forms, classes, `static events`, the class body's own methods) and writes `config/controllers_manifest.json`, the file a gem commits; the engine registers every loaded engine's and the app's manifest by convention before components load. A host controller then validates like poetry's: `use_stimulus` by Symbol at class load, template wiring in `poetry check` (the value-attribute rule now covers any registered controller), and its API in the registry's controllers section. The reader masks comments and string, template and regex literals before it reads structure, so a comment inside `static values`, a brace in a string, a one-line method body or an arrow-function class field all read correctly; it scrubs stray bytes and a BOM. An entry is complete or absent: a parent that is another host controller (relative import) or a poetry controller (`@poetry/controllers`, file or barrel import; charts and agent by their packages) merges child-first; an unresolvable parent, a computed static, a getter or a spread yields no entry and a named skip. A hand-written entry for a skipped identifier survives regeneration and never reads as stale (the gate compares only the controllers the reader read). Events are validated only from a literal `static events`; a controller that only calls `dispatch()` keeps them unknown, never empty. A Symbol declaration resolves to a gem's namespaced controller before a host controller of the same bare name, so a host `tabs_controller.js` never hijacks `controller :tabs`; the unknown-Symbol message names `bin/rails poetry:stimulus:manifest`. `Manifest.register_roots`, `Manifest.forget`; `Registry.gem_roots(registry: false)` lists every bundled root for the manifest walk.
+- Registry roots by convention. `Poetry::Core::Registry.roots` (booted: every loaded engine whose root carries a published registry, then the app when it committed one), `.gem_roots` (boot-free, from the bundle, plus an app root), and `.merged` (one view over several roots, block templates resolved to absolute paths). A registry can mark itself `internal: true` and consumers skip it; poetry-core's own is now marked, since its building blocks have no helpers. `HostComponents.committed_state` reports the app's committed registry as missing, fresh, or stale against the live build.
+- `Poetry::Core::CSS::TokenCollisions`: scans a host app's stylesheets for declarations of Poetry's token names (`--primary`, `--accent`, `--radius`, ...) and Tailwind theme keys (`--color-*`, `--radius-*`), and reports each with its location and what the role paints in Poetry's components. `poetry:install` and `poetry:check` run it.
+
+### Changed
+
+- A namespace pin follows the dictionary: a component's mode is its own declaration, else the pin of the root-most pinned ancestor (`Modes.inherited_for`), else the global, so a host subclass of a poetry-ui component stays Tailwind inside a BEM-pinned namespace while a host component written on the DSL takes the pin.
+- A dictionary merges by its own mode at every level: the resolver takes its class merger from the Style's sidecar component (its declaration, its kit's pin, or the global), so a host's global BEM merger never reaches a Tailwind kit's element-level joins, not only its root. A style redeclared without variants is open, whatever the parent listed: an inherited inclusion validator no longer narrows it. The "Style class not found" debug line is logged once per class.
+
+- `poetry check` validates every descriptor of a `data-action`, not only the last (a bogus first descriptor was invisible); a `data-<controller>-<name>-value` or `-target` attribute resolves to the controller the element declares when several registered identifiers fit (`foo` and `foo-bar`), a plain `data-foo-value` is the host's own attribute, a host controller's targets validate like poetry's, and an attribute whose value carries ERB skips the wiring rules instead of type-checking its fragments. A declared app helper matches bare calls only (`u.badge` is somebody's method); the stable-identity pass agrees. A file the runner cannot read or decode is one `unreadable` warning naming it, never the end of the sweep. `Check.mail_template?(path, root:)` judges the path inside the app root (an app checked out under a folder called `acme_mailer` keeps its pages) and knows Devise's `devise/mailer/`.
+
+- Every registry names every helper. A gem entry carries its `poetry_` convention name and an app entry the name it declared with `helper :name`; `Registry.helper_for(path, entry)` is the one resolver every surface reads (llms.txt, the check, the skill, the MCP server), so an app component that declared no helper is listed by class and no surface invents a `poetry_` name for it. The committed gem registries regenerate with the added key and nothing else.
+- Host helpers are checked before any is defined: a clash (a name Action View, poetry-ui, or the app's own `ApplicationController` helpers already carry, private methods included) or two components declaring one name raises naming both sides, leaves the module untouched, and the next reload after the fix starts clean. `Registry.read_file` is the one validated reader of a committed registry file; an empty, malformed, or wrong-shaped file reads as no registry (`Registry.invalid_at?`) instead of raising in whichever surface opened it first. The boot-free `HostComponents.declared_helpers` parses component sources with Prism, so a mention in a string, heredoc, or comment is not a declaration and `helper(:x)`, `helper "x"`, and `self.helper :x` are. `poetry:registry` leaves an engine's own components to that engine's registry.
+
+- `poetry check` leaves a mailer template's colors alone: under a `*_mailer/` directory or in the mailer layout, an inline hex or a color literal in a utility class is the only paint an email client honours (no stylesheet, no tokens), so the raw-color rule stays quiet there while every other rule runs as on a page. `Check.lint` takes `mail:` for a source string; the runner derives it from the path (`Check.mail_template?`).
+
+- The generated Tailwind theme mapping is `@theme inline default`. A host `@theme` value for the same key (its own `--color-primary`, a `--radius-sm` it set before Poetry arrived) wins whether it is declared before or after the mapping; Poetry's value still applies wherever the host set nothing. Before, the mapping replaced the host's keys wholesale, so every `rounded-sm` in an existing app changed size.
+
+## [0.1.1] - 2026-09-08
+
+### Added
+
+- `identity:` on every component: the one sanctioned way for a component that renders as another component's root to name it (its `data-component`). Universal like `key:`, never an HTML attribute.
+- `poetry check` rule `reserved-attribute`: `data-component` passed through a helper, as a string key or `data: { component: }`, is an error.
+
+### Changed
+
+- The passthrough contract is enforced at render. A keyword that is not an option still renders as an HTML attribute on the root, but a near miss of a declared option (`varient:`) raises in development and test with a did-you-mean and logs in production; `data-component` is never overridable (raised in development and test, dropped in production); `data-slot` stays open as a composition seam. `poetry check`'s `unknown-option` finding is an error, no longer a warning.
+- `poetry--core--hover-card`: `touchGuard` (on touchstart) is replaced by `pointerDown` (on pointerdown). `poetry--core--number-field`: the `focus` action is removed. A host that wired either by hand updates the action strings; poetry-ui's components already have.
+- `css_mode :bem` is documented as the mode for kits authored on the DSL that write their own templates; poetry-ui is Tailwind-native and not a `:bem` consumer.
+
+### Fixed
+
+- HoverCard: a tap on the trigger keeps its click on touch devices. The touchstart guard cancelled the click; a pointerdown latch held through the tap's compatibility mouse events replaces it.
+- MessageScroller: `data-pending-scroll` holds the root and the viewport until the opening position (`end` or `last-anchor`) is applied, releases at once for an empty transcript, is stripped when a Turbo morph re-stamps it, and is re-armed at `turbo:before-cache`, so a server-rendered or restored transcript never shows the top of the thread first.
+- NumberField: a sideways trackpad gesture over a wheel-enabled field scrolls the page instead of stepping, Shift on the horizontal axis steps large, and an event with no movement is neither stepped nor cancelled. Focus keeps the browser's own selection (Tab selects the value, a click places the caret); the steppers park the caret at the end.
+- NavigationMenu: a disabled trigger never opens, by hover or click, and the arrows step over it; ArrowDown on a trigger opens its panel with focus staying on the trigger; removing the open trigger's item, as a morph can, closes the bar and drops its orphaned panel.
+- Drawer: the click that follows a press inside the panel never dismisses, so a drag against the clamp released over the backdrop no longer closes the sheet.
 
 ## [0.1.0] - 2026-09-05
 

data/README.md

@@ -20,10 +20,6 @@ After checking out the repo, run `bin/setup` to install dependencies, then `bund
 
 Releases publish to [RubyGems.org](https://rubygems.org) via GitHub Actions OIDC **trusted publishing** (no API keys). Run `bundle exec rake "version:bump[X.Y.Z]"` (sets `Poetry::Core::VERSION` and package.json together; `rake version:verify` in the default chain fails on drift), commit, then push a `vX.Y.Z` tag — the `Release` workflow checks the tag against the version and publishes the gem.
 
-## Lineage
-
-poetry-core evolves the framework layer of `view_component_plus` (the `Plus` gem) — itself a synthesis of view_component-contrib and fox_tail.
-
 ## License
 
 Available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

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

@@ -54,6 +54,14 @@ module Poetry
       # a subclass of an internal component stays internal.
       class_attribute :internal_component, default: false, instance_predicate: false
 
+      # The declared vocabulary the runtime values tier checks:
+      # name => { variants: [...] or nil, required: true/false }, recorded
+      # by `style` and `option` at declaration (copy-on-write per class, so
+      # a subclass's declarations never leak up). A direct lookup, not an
+      # ActiveModel validation pass - measured at nine percent of a
+      # Button's render when it ran through `valid?`.
+      class_attribute :declared_values, instance_accessor: false, default: {}.freeze
+
       class << self
         # Marks this class (and its descendants) as an implementation
         # detail - full machinery, no registry entry.
@@ -66,6 +74,86 @@ module Poetry
         def internal_component!
           self.internal_component = true
         end
+
+        # The vocabulary the runtime values tier checks, computed once per
+        # class at first construction (the class body is complete by then):
+        # the recorded `style`/`option` declarations plus every inclusion
+        # validator with an Array (`validates :side, inclusion: { in: SIDES }`
+        # is how options declare a closed vocabulary). Method validators are
+        # not vocabulary and stay the component's own (Icon's unknown-name
+        # policy).
+        #
+        # @return [Hash{Symbol => Hash}]
+        # @api private
+        def runtime_vocabulary
+          @runtime_vocabulary ||= begin
+            vocabulary = declared_values.dup
+            names = attribute_names.map(&:to_sym)
+            validators.each do |validator|
+              next unless validator.is_a?(ActiveModel::Validations::InclusionValidator)
+              next unless (allowed = validator.options[:in]).is_a?(Array)
+
+              validator.attributes.each do |attribute|
+                attribute = attribute.to_sym
+                next unless names.include?(attribute)
+
+                spec = vocabulary[attribute] || { variants: nil, required: false }
+                # A style declared open (no variants) stays open: an inherited
+                # inclusion validator from a parent's closed declaration never
+                # narrows it again.
+                next if spec[:open]
+
+                vocabulary[attribute] = spec.merge(variants: allowed).freeze unless spec[:variants]
+              end
+            end
+            vocabulary.freeze
+          end
+        end
+
+        # Records a declared attribute's vocabulary for the runtime values
+        # tier ({#guard_declared_values}).
+        #
+        # @param name [Symbol]
+        # @param variants [Array, nil] the closed vocabulary, nil for open values
+        # @param required [Boolean]
+        # @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
+        end
+
+        # Names the view helper that renders this component - for a
+        # component the host application (or an engine) defines on the
+        # DSL. The poetry-core engine defines the method on Action View at
+        # boot and on every reload, and the app's registry carries the name
+        # so `poetry check`, llms.txt and the generated skill know the
+        # helper. Own-class only: a subclass declares its own or has none.
+        # The gems' components do not declare one; their helpers follow the
+        # `poetry_<name>` convention.
+        #
+        # @example
+        #   class Demo::Badge::Component < Poetry::Core::Component
+        #     helper :demo_badge
+        #   end
+        #   # <%= demo_badge(tone: :loud) { "New" } %>
+        # @param name [Symbol, String] a Ruby method name
+        # @return [void]
+        # @raise [ArgumentError] when the name is not a plain method name
+        def helper(name)
+          name = name.to_s
+          unless name.match?(/\A[a-z_][a-z0-9_]*\z/)
+            raise ArgumentError, "helper name #{name.inspect} must be a plain method name (a-z, 0-9, _)"
+          end
+
+          @helper_name = name
+        end
+
+        # The declared helper name, or nil (the gems' components; a
+        # subclass that declares none).
+        #
+        # @return [String, nil]
+        attr_reader :helper_name
       end
 
       class << self
@@ -145,14 +233,36 @@ module Poetry
         end
       end
 
+      # Keywords that are never options and never typos - the passthrough
+      # vocabulary the static check exempts too (Check::Catalog::PASSTHROUGH).
+      PASSTHROUGH_KEYS = %w[class id key webmcp identity data aria role style].freeze
+
+      # HTML attribute names a caller passes through on purpose. Exempt from
+      # the near-miss guard so `for:` never reads as a typo of a `form`
+      # option, `size:` on a component without a size axis stays the native
+      # attribute, and so on. Only keys that are NOT declared options reach
+      # the guard, so a declared option of the same name is untouched.
+      HTML_ATTRIBUTE_KEYS = %w[
+        accept accesskey action alt autocapitalize autocomplete autofocus checked cite cols colspan
+        contenteditable crossorigin datetime decoding dir dirname disabled download draggable enctype
+        enterkeyhint for form headers height hidden href hreflang inert inputmode is itemid itemprop
+        itemref itemscope itemtype label lang list loading max maxlength method min minlength multiple
+        name nonce novalidate open part pattern ping placeholder popover readonly referrerpolicy rel
+        required reversed rows rowspan scope selected size sizes slot span spellcheck src srcset start
+        step tabindex target title translate type value width wrap
+      ].freeze
+
       # The self-identification markup contract, the convention every
       # component follows: `data-component` on the component root maps live DOM
       # back to the component that rendered it - the hook agents, the
       # Verifier, and the browser-verification loop key on.
       #
+      # A component rendering as another's root passes identity: (the
+      # composition seam), and the root wears that name instead.
+      #
       # @return [Hash] e.g. { "data-component" => "button" }
       def component_data_attributes
-        { "data-component" => self.class.component_title }
+        { "data-component" => (@identity || self.class.component_title).to_s }
       end
 
       # `data-slot` for a named part of the component's anatomy
@@ -224,6 +334,14 @@ module Poetry
         @webmcp = attributes[:webmcp] || attributes["webmcp"]
         attributes = attributes.except(:webmcp, "webmcp") unless @webmcp.nil?
 
+        # identity: is the composition seam for a component that renders AS
+        # another component's root (ToastTrigger renders as a Button): the
+        # inner root wears the outer's data-component. Universal like key:,
+        # never an HTML attribute - and the ONLY sanctioned way to set
+        # data-component (the raw attribute is reserved, see guard_passthrough).
+        @identity = attributes[:identity] || attributes["identity"]
+        attributes = attributes.except(:identity, "identity") unless @identity.nil?
+
         # Initialize a fresh Set for this instance
         self.registered_styles = Set.new
         self.registered_options = Set.new
@@ -249,12 +367,124 @@ module Poetry
         end
 
         @attributes = self.class._default_attributes.deep_dup
-        html_attrs = attributes.with_indifferent_access.except(*attribute_names)
-        @html_attributes = Poetry::Core::HTML::Attributes.new(html_attrs)
+        given = attributes.with_indifferent_access
+        names = attribute_names
+        @html_attributes = Poetry::Core::HTML::Attributes.new(guard_passthrough(given.except(*names)))
+        # The root merges classes with the kit's merger (its CSS mode's).
+        @html_attributes.classname_merger = classname_merger
+
+        assign_attributes given.slice(*names)
+        guard_declared_values
+      end
+
+      # The passthrough contract, enforced at the seam. A keyword that is not
+      # an option renders as an HTML attribute on the root (title:, tabindex:,
+      # colspan:) - so a NEAR-MISS of a declared option (varient:) would
+      # silently render a bogus attribute while the default applied. That
+      # raises in development and test with the did-you-mean the static check
+      # gives, and only logs in production (the render still succeeds).
+      # data-component is the component's own identity - the hook agents,
+      # the Verifier and the browser loop key on - and is never overridable:
+      # dropped in production, raised the same way in development and test.
+      # data-slot is NOT reserved: re-slotting an embedded root is the
+      # composition seam a part contract allows; re-identifying one goes
+      # through identity:, the sanctioned spelling.
+      #
+      # @param html_attrs [ActiveSupport::HashWithIndifferentAccess]
+      # @return [ActiveSupport::HashWithIndifferentAccess] the attributes, minus a reserved override
+      def guard_passthrough(html_attrs)
+        problems = []
+
+        if html_attrs.key?("data-component")
+          problems << "data-component is #{passthrough_owner}'s own identity attribute and is never overridable"
+          html_attrs = html_attrs.except("data-component")
+        end
+        data = html_attrs["data"]
+        if data.respond_to?(:key?) && data.key?("component")
+          problems << "data: { component: } is #{passthrough_owner}'s own identity attribute and is never overridable"
+          html_attrs["data"] = data.except("component")
+        end
 
-        assign_attributes attributes.with_indifferent_access.slice(*attribute_names)
+        html_attrs.each_key do |key|
+          next if PASSTHROUGH_KEYS.include?(key) || HTML_ATTRIBUTE_KEYS.include?(key) || key.include?("-")
+
+          suggestion = option_suggestion(key)
+          next unless suggestion
+
+          problems << "#{passthrough_owner} has no option #{key}: (did you mean #{suggestion}:?) - " \
+                      "unknown keywords render as HTML attributes"
+        end
+        return html_attrs if problems.empty?
+
+        raise ArgumentError, problems.join("; ") if strict_passthrough?
+
+        Rails.logger&.warn("poetry: #{problems.join("; ")}") if defined?(Rails) && Rails.respond_to?(:logger)
+        html_attrs
+      end
+
+      # The did-you-mean against this component's declared options and
+      # styles, the same checker the static check runs.
+      def option_suggestion(key)
+        require "did_you_mean"
+        DidYouMean::SpellChecker.new(dictionary: self.class.attribute_names.map(&:to_s)).correct(key.to_s).first
       end
 
+      # The component named in a passthrough problem - an anonymous class
+      # (a test double) has no path to title.
+      def passthrough_owner
+        self.class.name ? self.class.component_title : "this component"
+      end
+
+      # The runtime values tier, beside the passthrough guard: the declared
+      # vocabulary (`style ... variants:`, `required:`) is checked at
+      # construction, where every component - gem or app, whatever it does
+      # in before_render - passes. Off-list values raise in development and
+      # test with the allowed values and a did-you-mean; in production they
+      # log and render as before. `poetry check` catches the same mistakes
+      # in templates statically; this tier catches the value that arrives
+      # from data. A direct lookup over {.declared_values}; a component's
+      # custom validators keep their own policy.
+      def guard_declared_values
+        problems = nil
+        self.class.runtime_vocabulary.each do |name, spec|
+          value = public_send(name)
+          if value.nil? || (value.respond_to?(:empty?) && value.empty?)
+            (problems ||= []) << "#{passthrough_owner} requires #{name}:" if spec[:required]
+          elsif spec[:variants] && !spec[:variants].include?(value)
+            (problems ||= []) << off_list_problem(name, value, spec[:variants])
+          end
+        end
+        return unless problems
+
+        message = problems.join("; ")
+        raise ArgumentError, message if strict_passthrough?
+
+        Rails.logger&.warn("poetry: #{message}") if defined?(Rails) && Rails.respond_to?(:logger)
+      end
+
+      # The message a developer reads for an off-list value: the declared
+      # vocabulary and a did-you-mean.
+      def off_list_problem(name, value, allowed)
+        "#{passthrough_owner} #{name}: #{value.inspect} is not one of " \
+          "#{allowed.map(&:inspect).join(", ")}#{variant_suggestion(value, allowed)}"
+      end
+
+      def variant_suggestion(value, allowed)
+        return "" if allowed.empty? || value.nil?
+
+        require "did_you_mean"
+        suggestion = DidYouMean::SpellChecker.new(dictionary: allowed.map(&:to_s)).correct(value.to_s).first
+        suggestion ? " (did you mean #{suggestion.to_sym.inspect}?)" : ""
+      end
+
+      # Raise (development, test) or log (everything else).
+      def strict_passthrough?
+        defined?(Rails) && Rails.respond_to?(:env) && Rails.env.local?
+      end
+
+      private :guard_passthrough, :option_suggestion, :passthrough_owner, :strict_passthrough?,
+              :guard_declared_values, :off_list_problem, :variant_suggestion
+
       # Returns all component attributes, ensuring proc defaults are evaluated.
       #
       # This method overrides ActiveModel's attributes method to trigger evaluation
@@ -326,15 +556,24 @@ module Poetry
 
       # Merges multiple class name values into a single string.
       #
-      # Uses the configured classname merger (typically Tailwind Merge) to
-      # intelligently combine CSS class names, handling conflicts and duplicates.
+      # Uses the kit's classname merger (Tailwind Merge in :tailwind mode,
+      # the BEM merger in :bem mode - {Poetry::Core::CSS::Modes.merger_for})
+      # to combine CSS class names, handling conflicts and duplicates.
       #
       # @param classnames [Array<String, nil>] class names to merge
       # @return [String] the merged class names
       # @example
       #   classnames("text-red-500", "text-blue-500") # => "text-blue-500"
       def classnames(*classnames)
-        self.class.config.classname_merger.merge(*classnames)
+        classname_merger.merge(*classnames)
+      end
+
+      # The class-name merger this component merges with: the one that
+      # matches its CSS mode ({Poetry::Core::CSS::Modes.merger_for}).
+      #
+      # @return [#merge]
+      def classname_merger
+        Poetry::Core::CSS::Modes.merger_for(css_mode)
       end
 
       # HTML-safe JSON for embedding in a `<script type="application/json">`

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

@@ -195,6 +195,7 @@ module Poetry
           # @param _type [Symbol] the attribute type (unused; kept for signature parity)
           # @param required [Boolean] whether the attribute is required
           def add_option_validations(name, _type, required)
+            record_declared_value(name, variants: nil, required: required)
             # Type validation is automatic via ActiveModel::Type
             validates name, presence: true if required
           end

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

@@ -53,6 +53,8 @@ module Poetry
         STYLE_CLASS_SUFFIX = "::Style"
 
         included do
+          # The kit-level mode declaration (`css_mode :bem`), inherited.
+          class_attribute :declared_css_mode, instance_accessor: false, default: nil
           class_attribute :registered_styles,
                           instance_writer: true,
                           instance_predicate: false,
@@ -60,6 +62,28 @@ module Poetry
         end
 
         class_methods do
+          # The CSS mode this component renders in, declared per kit
+          # (inherited by subclasses): `css_mode :bem` on a kit's base
+          # class, and every component in it emits the BEM token IR. With
+          # no argument, the resolved mode: the declaration, else the mode
+          # pinned for the namespace ({Poetry::Core::CSS::Modes} - poetry-ui
+          # pins `:tailwind`), else the global
+          # `Poetry::Core::Config.current.css_mode`. A `css_mode:` keyword
+          # on a `css` call still wins over all of them.
+          #
+          # @example A kit that brings its own CSS
+          #   class Acme::Ui::Base < Poetry::Core::Component
+          #     css_mode :bem
+          #   end
+          # @param mode [Symbol, nil] :tailwind or :bem to declare; nil to read
+          # @return [Symbol] the declared or resolved mode
+          # @raise [Poetry::Core::Error] for an unknown mode
+          def css_mode(mode = nil)
+            return self.declared_css_mode = Poetry::Core::CSS::Modes.validate!(mode) unless mode.nil?
+
+            declared_css_mode || Poetry::Core::CSS::Modes.inherited_for(self) || Poetry::Core::Config.current.css_mode
+          end
+
           # Defines a style attribute for the component.
           #
           # @param name [Symbol, String] the name of the style attribute
@@ -145,7 +169,12 @@ module Poetry
             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)
+            # Once per class: a component with no dictionary (Icon) is a
+            # design, not a line per render in the development log.
+            unless @style_class_miss_logged
+              @style_class_miss_logged = true
+              log_style_class_not_found(style_class_name, e) if defined?(Rails)
+            end
             nil
           end
 
@@ -177,10 +206,14 @@ module Poetry
           # @param variants [Object] the allowed variants
           # @param required [Boolean] whether the attribute is required
           def add_style_validations(name, type, variants, required)
+            record_declared_value(name, variants: type == :boolean ? nil : variants, required: required,
+                                        open: type != :boolean && variants.nil?)
+            # nil is an omitted value, not an off-list one; `required` adds
+            # presence for the styles that may not be omitted.
             if type == :boolean
-              validates name, inclusion: { in: [true, false] }
+              validates name, inclusion: { in: [true, false] }, allow_nil: true
             elsif variants
-              validates name, inclusion: { in: variants }
+              validates name, inclusion: { in: variants }, allow_nil: true
             end
             validates name, presence: true if required
           end
@@ -274,7 +307,7 @@ module Poetry
         # @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
+          mode = options.delete(:css_mode) || css_mode
 
           case mode
           when :tailwind
@@ -288,10 +321,18 @@ module Poetry
             extra = options.delete(:class)
             [bem(element, **options), extra].compact.join(" ")
           else
-            raise Poetry::Core::Error, "unknown css_mode #{mode.inspect} (expected :tailwind or :bem)"
+            Poetry::Core::CSS::Modes.validate!(mode)
           end
         end
 
+        # The CSS mode this instance renders in (the class's resolved mode;
+        # see the class-level `css_mode`).
+        #
+        # @return [Symbol] :tailwind or :bem
+        def css_mode
+          self.class.css_mode
+        end
+
         # The component's BEM block name - the stable, framework-agnostic
         # class contract of the token IR ("poetry/core/dot" -> "poetry-core-dot").
         #

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

@@ -27,7 +27,38 @@ module Poetry
         #
         # @return [CSS::Resolver]
         def resolver
-          @resolver ||= superclass.respond_to?(:resolver) ? superclass.resolver.dup : CSS::Resolver.new
+          @resolver ||= begin
+            dictionary = superclass.respond_to?(:resolver) ? superclass.resolver.dup : CSS::Resolver.new
+            dictionary.owner = self
+            dictionary
+          end
+        end
+
+        # The class merger for this dictionary's mode: the sidecar
+        # component's resolved `css_mode` (its own declaration, its kit's
+        # pin, or the global), else this class's own namespace pin, else the
+        # global mode - so `Acme::Pill::Style` under a `:bem` pin merges like
+        # BEM while poetry-ui's dictionaries merge like Tailwind whatever the
+        # host set globally.
+        #
+        # @return [Object] a class-name merger
+        def merger
+          component = sidecar_component
+          mode = if component.respond_to?(:css_mode)
+                   component.css_mode
+                 else
+                   CSS::Modes.inherited_for(self) || Poetry::Core::Config.current.css_mode
+                 end
+          CSS::Modes.merger_for(mode)
+        end
+
+        # The `X::Component` beside this `X::Style`, when it exists.
+        def sidecar_component
+          return nil unless name&.end_with?("::Style")
+
+          Object.const_get("#{name.delete_suffix("::Style")}::Component")
+        rescue NameError
+          nil
         end
 
         # -- The dictionary DSL (delegates to the resolver) --------------------

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

@@ -49,6 +49,10 @@ export default class DrawerController extends DialogController {
   }
 
   #swipe = null
+  // Where the last press landed (inside the panel or on the backdrop) -
+  // the click that follows a press is never a backdrop dismissal when the
+  // press started inside, however far the pointer travelled since.
+  #pressInside = false
   #closing = false
   #snapIndex = 0
 
@@ -114,6 +118,29 @@ export default class DrawerController extends DialogController {
     })
   }
 
+  /**
+   * The inherited backdrop click, minus the ghost: a press that started
+   * inside the panel can end over the backdrop (a drag against the
+   * clamp, a slip off an inner control) and the click the browser then
+   * fires is a backdrop click by target and coordinates, never by intent.
+   *
+   * @param {MouseEvent} event
+   */
+  backdropClose(event) {
+    if (this.#pressInside) return
+
+    super.backdropClose(event)
+  }
+
+  // The dialog's own inside test (a press on the backdrop targets the
+  // <dialog> too - only the rect tells them apart).
+  #insidePanel(event) {
+    const rect = this.dialogTarget.getBoundingClientRect()
+
+    return rect.top <= event.clientY && event.clientY <= rect.bottom &&
+      rect.left <= event.clientX && event.clientX <= rect.right
+  }
+
   // --- the swipe -----------------------------------------------------------
 
   /**
@@ -124,6 +151,7 @@ export default class DrawerController extends DialogController {
    * @param {PointerEvent} event
    */
   swipeStart(event) {
+    this.#pressInside = this.#insidePanel(event)
     if (event.button !== 0 && event.pointerType === "mouse") return
     if (this.#closing) return