poetry-ui 0.0.2

data/lib/poetry/ui/testing/select.rb

@@ -0,0 +1,147 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Ui
+    module Testing
+      # The Select interaction contract, executable: open lands focus on
+      # the SELECTED option (unlike the menu family, which moves
+      # data-highlighted), committing syncs the native <select> and closes
+      # with focus back on the trigger, and the closed trigger typeaheads
+      # without opening (native parity). Asserts ride
+      # data-open/aria-expanded/the native
+      # value - the public attribute contract, not markup internals.
+      #
+      # CONTENT RESOLVES THROUGH THE ID PAIR, document-wide: portal-on-open
+      # moves the open listbox to body (docs/portal-on-open.md), so root
+      # scoping stops holding for content and its items - the trigger's
+      # aria-controls id is the production controllers' own resolution
+      # rule, and id-anchored selectors keep Capybara's waiting semantics.
+      #
+      # @example Committing an option through the real keyboard path
+      #   select = poetry_select("#plan")
+      #   select.select_option("Pro", via: :keyboard)
+      #   assert_equal "pro", select.value
+      class Select < Tester
+        # Whether the listbox is currently open.
+        #
+        # @return [Boolean]
+        def open?(wait: 0)
+          session.has_selector?("##{content_id}[data-open]", visible: :all, wait: wait)
+        rescue Capybara::ElementNotFound
+          false
+        end
+
+        # Opens the listbox (no-op when already open). via: :keyboard
+        # focuses the trigger and presses ArrowDown; :mouse presses it.
+        #
+        # @return [Select] self
+        def open(via: :mouse)
+          return self if open?
+
+          case via
+          when :keyboard
+            focus(trigger)
+            keys(:down)
+          else
+            press(trigger)
+          end
+
+          session.assert_selector("##{content_id}[data-slot='select-content'][data-open][data-side]")
+          self
+        end
+
+        # Escape-closes the open listbox and waits for the closed state.
+        #
+        # @return [Select] self
+        def close
+          keys(:escape) if open?
+          session.assert_selector("##{content_id}[data-closed]", visible: :all)
+          self
+        end
+
+        # Opens first when closed; exact visible-text match; waits for the
+        # commit to land on the native select before returning.
+        #
+        # @return [Select] self
+        def select_option(text, via: :mouse)
+          self.open(via: via)
+
+          if via == :keyboard
+            walk_highlight_to(text)
+            keys(:enter)
+          else
+            press(option(text))
+          end
+
+          session.assert_selector("##{content_id}[data-closed]", visible: :all)
+          self
+        end
+
+        # The submitted value - the native <select> is the serialization
+        # truth, so this is what the server would receive.
+        #
+        # @return [String]
+        def value
+          hidden_part("select-native").value
+        end
+
+        # The trigger's visible value text.
+        #
+        # @return [String]
+        def text
+          part("select-value").text
+        end
+
+        # The visible option texts (opens the listbox first when closed).
+        #
+        # @return [Array<String>]
+        def options
+          open unless open?
+          content.all("[data-slot='select-item']").map(&:text)
+        end
+
+        private
+
+        # Bounded highlight walk: at most one pass over the items - a
+        # missing/mistyped label raises instead of arrowing forever.
+        def walk_highlight_to(text)
+          items = content.all("[data-slot='select-item']")
+
+          (items.size + 1).times do
+            return if highlighted_text == text
+
+            keys(:down)
+          end
+
+          raise Capybara::ElementNotFound,
+                "no option #{text.inspect} reached by ArrowDown - options: #{items.map(&:text).inspect}"
+        end
+
+        def trigger
+          part("select-trigger")
+        end
+
+        # The trigger's aria-controls names the listbox wherever it sits.
+        def content_id
+          @content_id ||= trigger["aria-controls"]
+        end
+
+        def content
+          session.find("##{content_id}", visible: :all)
+        end
+
+        def option(text)
+          content.find("[data-slot='select-item']", text: text, exact_text: true)
+        end
+
+        # Select's active option is REAL FOCUS (the menu family marks
+        # data-highlighted instead).
+        def highlighted_text
+          content.find("[data-slot='select-item']:focus", wait: 1).text
+        rescue Capybara::ElementNotFound
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/poetry/ui/testing/tester.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Ui
+    module Testing
+      # The tester base: root resolution, part lookup by data-slot (the
+      # contract surface - never CSS classes), and Capybara-native waiting.
+      # Subclasses encode one component's real interaction sequences.
+      class Tester
+        # @return [Capybara::Session] the session driving the browser
+        attr_reader :session
+
+        def initialize(root, session:)
+          @session = session
+          @root_locator = root
+        end
+
+        # The component root node, re-found on every access so Turbo
+        # re-renders never leave the tester holding a stale element.
+        #
+        # @return [Capybara::Node::Element]
+        def root
+          case @root_locator
+          when String then session.find(@root_locator)
+          else @root_locator
+          end
+        end
+
+        private
+
+        # A part under the root, by its data-slot name. The error names
+        # the missing slot so a wrong root reads as "not a poetry_select",
+        # not as an opaque Capybara timeout.
+        def part(slot, **)
+          root.find(slot_selector(slot), **)
+        rescue Capybara::ElementNotFound
+          raise Capybara::ElementNotFound,
+                "no [data-slot=#{slot}] under #{describe_root} - is this the right component root?"
+        end
+
+        def part?(slot, **)
+          root.has_selector?(slot_selector(slot), **)
+        end
+
+        def parts(slot, **)
+          root.all(slot_selector(slot), **)
+        end
+
+        # Overlay content PORTALS to body while open (portal-on-open,
+        # docs/portal-on-open.md) - root-scoped lookups only hold for
+        # closed content and non-overlay parts. Component testers resolve
+        # open content document-wide through the trigger's aria-controls
+        # id (the production controllers' own rule); visibility flips via
+        # hidden/data-open, so look through visibility for closed content.
+        def hidden_part(slot)
+          root.find(slot_selector(slot), visible: :all)
+        end
+
+        def slot_selector(slot)
+          "[data-slot='#{slot}']"
+        end
+
+        def describe_root
+          @root_locator.is_a?(String) ? @root_locator.inspect : "the given node"
+        end
+
+        # Real keyboard focus WITHOUT a press (the Tab-arrival reality the
+        # keyboard path simulates) - a click would run the pointer seams.
+        def focus(node)
+          session.execute_script("arguments[0].focus()", node)
+          node
+        end
+
+        # A real pointer press. Under Cuprite the raw mouse is driven at
+        # the element's LIVE center (Cuprite's cached quads can disagree
+        # with the settled layout and hit-test the wrong point) - still a
+        # genuine CDP pointerdown/up/click sequence, never a synthetic
+        # dispatch. Other drivers take Capybara's own click.
+        def press(node)
+          mouse = session.driver.respond_to?(:browser) && session.driver.browser.respond_to?(:mouse) &&
+                  session.driver.browser.mouse
+
+          if mouse
+            node.scroll_to(node) if node.respond_to?(:scroll_to)
+            x, y = session.evaluate_script(<<~JS, node)
+              (() => { const r = arguments[0].getBoundingClientRect();
+                       return [r.x + r.width / 2, r.y + r.height / 2]; })()
+            JS
+            mouse.click(x: x, y: y)
+          else
+            node.click
+          end
+
+          node
+        end
+
+        # Keys go to whatever HAS focus (the keyboard reality). Under
+        # Cuprite the raw Ferrum keyboard types - pure key events with
+        # Ferrum's own simple names (:down, :enter, :escape); a Capybara
+        # NODE#send_keys would click-to-focus first, which runs the
+        # pointer seams the keyboard path exists to avoid.
+        def keys(*sequence)
+          keyboard = session.driver.respond_to?(:browser) &&
+                     session.driver.browser.respond_to?(:keyboard) &&
+                     session.driver.browser.keyboard
+
+          if keyboard
+            sequence.each { |key| keyboard.type(key) }
+          elsif session.respond_to?(:send_keys)
+            session.send_keys(*sequence)
+          else
+            active_element.send_keys(*sequence)
+          end
+        end
+
+        def active_element
+          session.evaluate_script("document.activeElement") if session.driver.respond_to?(:evaluate_script)
+        end
+
+        def wait_until(message)
+          Timeout.timeout(Capybara.default_max_wait_time) do
+            sleep 0.05 until yield
+          end
+        rescue Timeout::Error
+          raise Capybara::ExpectationNotMet, message
+        end
+      end
+    end
+  end
+end

data/lib/poetry/ui/testing.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+require_relative "testing/tester"
+require_relative "testing/select"
+require_relative "testing/combobox"
+require_relative "testing/menu"
+require_relative "testing/dialog"
+require_relative "testing/registration"
+
+module Poetry
+  module Ui
+    # Consumer-facing interaction testers: drive poetry components
+    # through their REAL keyboard/pointer
+    # sequences in a Capybara system test and assert against the public
+    # attribute contract (data-open, aria-expanded, data-highlighted) -
+    # never against markup internals. Each tester is an executable spec of
+    # its component's interaction contract; agents are taught to test
+    # through them (the usage skill), so generated tests are correct by
+    # construction.
+    #
+    #   require "poetry/ui/testing"
+    #
+    #   class PlanTest < ApplicationSystemTestCase
+    #     include Poetry::Ui::Testing
+    #
+    #     test "picking a plan" do
+    #       visit settings_path
+    #       select = poetry_select("#plan")
+    #       select.select_option("Pro", via: :keyboard)
+    #       assert_equal "pro", select.value
+    #     end
+    #   end
+    #
+    # Testers locate parts by data-slot from the root you hand them, and
+    # wait with Capybara's own retry discipline - no sleeps. `via:` swaps
+    # the ENTIRE event sequence (:mouse clicks, :keyboard focuses the
+    # trigger and drives keys), because the two paths exercise different
+    # controller seams.
+    module Testing
+      # Each entry point takes the component ROOT: a CSS selector string
+      # or a Capybara node, and an optional session (defaults to
+      # Capybara.current_session, or the including test's `page`).
+
+      # A Select tester rooted at the component.
+      #
+      # @param root [String, Capybara::Node::Element] the component root
+      # @param session [Capybara::Session, nil] defaults to the test's
+      #   `page` (or Capybara.current_session)
+      # @return [Select]
+      def poetry_select(root, session: nil)
+        Select.new(root, session: session || testing_session)
+      end
+
+      # A Combobox tester rooted at the component (single or multiple).
+      #
+      # @param root [String, Capybara::Node::Element] the component root
+      # @param session [Capybara::Session, nil] defaults to the test's
+      #   `page` (or Capybara.current_session)
+      # @return [Combobox]
+      def poetry_combobox(root, session: nil)
+        Combobox.new(root, session: session || testing_session)
+      end
+
+      # A DropdownMenu tester rooted at the component.
+      #
+      # @param root [String, Capybara::Node::Element] the component root
+      # @param session [Capybara::Session, nil] defaults to the test's
+      #   `page` (or Capybara.current_session)
+      # @return [Menu]
+      def poetry_dropdown_menu(root, session: nil)
+        Menu.new(root, session: session || testing_session)
+      end
+
+      # A Dialog tester rooted at the component.
+      #
+      # @param root [String, Capybara::Node::Element] the element carrying
+      #   data-component=dialog (trigger + content)
+      # @param session [Capybara::Session, nil] defaults to the test's
+      #   `page` (or Capybara.current_session)
+      # @return [Dialog]
+      def poetry_dialog(root, session: nil)
+        Dialog.new(root, session: session || testing_session)
+      end
+
+      # Every poetry controller identifier on the current page that the
+      # host's Stimulus application has NOT registered - empty when the
+      # wiring is healthy. Stimulus never errors on an unknown identifier
+      # (the element just stays inert), and one failed import in the
+      # controllers graph silently takes every poetry controller with it,
+      # so nothing else surfaces this.
+      #
+      # @param session [Capybara::Session, nil] defaults to the test's
+      #   `page` (or Capybara.current_session)
+      # @param application [String] JS expression naming the Stimulus
+      #   application (Rails' default controllers/application.js exposes
+      #   window.Stimulus)
+      # @return [Array<String>] the unregistered identifiers, sorted
+      # @raise [RegistrationError] when no application is reachable at all
+      def poetry_unregistered_controllers(session: nil, application: "window.Stimulus")
+        result = (session || testing_session).evaluate_script(Registration.script(application))
+        raise RegistrationError, result["error"] if result["error"]
+
+        result["missing"]
+      end
+
+      # Asserts that every poetry controller on the page is registered.
+      # Flunks under Minitest, raises {RegistrationError} elsewhere, with
+      # the identifiers and the two causes to check first.
+      #
+      # @param session [Capybara::Session, nil] defaults to the test's
+      #   `page` (or Capybara.current_session)
+      # @param application [String] JS expression naming the Stimulus
+      #   application (default window.Stimulus)
+      # @return [true]
+      def assert_poetry_controllers_registered(session: nil, application: "window.Stimulus")
+        result = (session || testing_session).evaluate_script(Registration.script(application))
+        return true if !result["error"] && result["missing"].empty?
+
+        message = Registration.message(result)
+        respond_to?(:flunk, true) ? flunk(message) : raise(RegistrationError, message)
+      end
+
+      private
+
+      def testing_session
+        respond_to?(:page) ? page : Capybara.current_session
+      end
+    end
+  end
+end

data/lib/poetry/ui/themes.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Ui
+    # The theme roster + per-theme DESIGN.md metadata.
+    #
+    # Every poetry theme shares ONE token source (poetry-core's DTCG file) -
+    # a theme is a component-treatment layer (themes/<name>.css), never a
+    # palette. What varies per theme, and therefore what this module knows:
+    # the treatment provenance line and the typography PAIRING - which is
+    # app-level metadata, not CSS (no poetry theme moves a font
+    # token; upstream's create flow biases lyra to JetBrains Mono with
+    # radius none and pairs sera with Noto Serif / Instrument Serif; the
+    # poetry docs render system stacks keyed off the same story).
+    module Themes
+      # The system sans stack sans-paired themes report.
+      SANS = "ui-sans-serif, system-ui, sans-serif"
+      # The system mono stack mono-biased themes report.
+      MONO = %(ui-monospace, SFMono-Regular, Menlo, Consolas, "Liberation Mono", monospace)
+      # The system serif stack serif-paired themes report.
+      SERIF = %(ui-serif, Georgia, Cambria, "Times New Roman", serif)
+
+      # The provenance line template for ported treatments,
+      # format-interpolated with the upstream style name.
+      PORTED = "ported from the source style-%s.css at pin shadcn@4.19.0 (1773ecfe)"
+
+      # Per-theme DESIGN.md metadata: the typography pairing and the
+      # treatment provenance line.
+      DETAILS = {
+        "default" => {
+          "typography" => { "pairing" => "system sans", "family" => SANS },
+          "treatment" => "the neutral source-parity treatment (the ported baseline)"
+        },
+        "vega" => {
+          "typography" => { "pairing" => "system sans", "family" => SANS },
+          "treatment" => "the vega treatment, #{format(PORTED, "vega")}"
+        },
+        "nova" => {
+          "typography" => { "pairing" => "system sans", "family" => SANS },
+          "treatment" => "the nova treatment, #{format(PORTED, "nova")}"
+        },
+        "mira" => {
+          "typography" => { "pairing" => "system sans", "family" => SANS },
+          "treatment" => "the mira treatment, #{format(PORTED, "mira")}"
+        },
+        "rhea" => {
+          "typography" => { "pairing" => "system sans", "family" => SANS },
+          "treatment" => "the rhea treatment (tinted surfaces), #{format(PORTED, "rhea")}"
+        },
+        "maia" => {
+          "typography" => { "pairing" => "system sans", "family" => SANS },
+          "treatment" => "the maia treatment, #{format(PORTED, "maia")}"
+        },
+        "luma" => {
+          "typography" => { "pairing" => "system sans", "family" => SANS },
+          "treatment" => "the luma treatment, #{format(PORTED, "luma")}"
+        },
+        "lyra" => {
+          "typography" => { "pairing" => "system mono (upstream: JetBrains Mono, radius none)", "family" => MONO },
+          "treatment" => "the lyra treatment (flat, mono-biased), #{format(PORTED, "lyra")}"
+        },
+        "sera" => {
+          "typography" => { "pairing" => "system serif (upstream: Noto Serif / Instrument Serif)",
+                            "family" => SERIF },
+          "treatment" => "the sera treatment (serif-paired), #{format(PORTED, "sera")}"
+        }
+      }.freeze
+
+      # A host whose installed theme slot matches no shipped fragment
+      # (hand-customized bytes) still exports honestly.
+      CUSTOM_DETAILS = {
+        "typography" => { "pairing" => "system sans", "family" => SANS },
+        "treatment" => "a customized component treatment (no byte match with a shipped poetry theme)"
+      }.freeze
+
+      class << self
+        # The shipped roster, from the fragment files themselves.
+        #
+        # @return [Array<String>] theme names, sorted
+        def names
+          Dir[Poetry::Ui.root.join("themes/*.css").to_s].map { |file| File.basename(file, ".css") }.sort
+        end
+
+        # The DESIGN.md metadata for one theme; unknown names (customized
+        # host bytes) fall back to CUSTOM_DETAILS.
+        #
+        # @param name [String] the theme name
+        # @return [Hash] "typography" pairing + "treatment" provenance
+        def details(name)
+          DETAILS.fetch(name) { CUSTOM_DETAILS }
+        end
+
+        # theme name -> serialized DESIGN.md, for every shipped theme - the
+        # single builder rake design:export_all, the drift gate, and the
+        # tests all share.
+        def design_md_exports(components_count:, generator: "bin/rake design:export_all")
+          tokens = Poetry::Core::Tokens.load
+          names.to_h do |name|
+            doc = Poetry::Core::DesignMd.build(
+              tokens: tokens, theme: name,
+              details: details(name).merge("components_count" => components_count, "generator" => generator)
+            )
+            [name, Poetry::Core::DesignMd.serialize(doc)]
+          end
+        end
+      end
+    end
+  end
+end

data/lib/poetry/ui/version.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Ui
+    # The gem version.
+    VERSION = "0.0.2"
+  end
+end

data/lib/poetry/ui/webmcp.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Ui
+    # The declarative WebMCP form contract: the attribute vocabulary
+    # Chrome's declarative API registers straight from markup - a <form>
+    # carrying `toolname` + `tooldescription` IS an agent-callable tool,
+    # its controls are the parameters (the browser synthesizes the JSON
+    # Schema from control types, `required`, and select options, reading
+    # each parameter's description from the associated <label>), and
+    # `toolparamdescription` overrides a label where the label alone is
+    # not agent-sufficient. No JavaScript, inert markup without an agent.
+    #
+    # Safety by construction: `toolautosubmit` (the agent submits without
+    # the user pressing Submit) is only allowed on GET forms - read-only
+    # lookups. A mutating form keeps the user in the loop, always.
+    #
+    # Consumers: {ComponentsHelper#poetry_webmcp_form} (the form), the
+    # FormBuilder's `tool_description:` field option (the override), and
+    # poetry-agent's imperative runtime, which shares this vocabulary.
+    module Webmcp
+      # The WebMCP tool-name grammar: 1-128 ASCII alphanumerics, `_`,
+      # `-`, `.` (declarative forms register their full name directly).
+      TOOL_NAME_PATTERN = /\A[A-Za-z0-9_.-]{1,128}\z/
+      # The agent-legibility budget for descriptions.
+      DESCRIPTION_LIMIT = 500
+      # The keys a `tool:` declaration may carry.
+      TOOL_KEYS = %i[name description autosubmit].freeze
+      # poetry-agent's declarative-form controller (the respondWith path);
+      # emitted as a plain token so the markup stays inert without the gem.
+      FORM_CONTROLLER = "poetry--agent--webmcp-form"
+
+      module_function
+
+      # The <form> attributes for a declarative tool.
+      #
+      # @param tool [Hash] `name:` (tool-name grammar), `description:`
+      #   (present, at most {DESCRIPTION_LIMIT} chars), optional
+      #   `autosubmit: true`
+      # @param method [Symbol, String, nil] the form's HTTP method -
+      #   autosubmit requires :get
+      # @return [Hash{Symbol => String}] `toolname`, `tooldescription`,
+      #   and `toolautosubmit` (empty-valued boolean attribute) when set
+      # @raise [ArgumentError] for an unknown key, an invalid name or
+      #   description, or autosubmit on a non-GET form
+      # @example
+      #   Poetry::Ui::Webmcp.form_attributes({ name: "find_order", description: "Find an order." }, method: :get)
+      #   # => { toolname: "find_order", tooldescription: "Find an order." }
+      def form_attributes(tool, method: nil)
+        tool = tool.to_h.transform_keys(&:to_sym)
+        unknown = tool.keys - TOOL_KEYS
+        raise ArgumentError, "tool: unknown key(s) #{unknown.inspect} - allowed: #{TOOL_KEYS.inspect}" if unknown.any?
+
+        name = tool[:name].to_s
+        unless TOOL_NAME_PATTERN.match?(name)
+          raise ArgumentError, "tool: name #{tool[:name].inspect} must be 1-128 chars of [A-Za-z0-9_.-]"
+        end
+
+        attributes = { toolname: name, tooldescription: description!(tool[:description], "tool: description") }
+        if tool[:autosubmit]
+          unless method.to_s.casecmp?("get")
+            raise ArgumentError,
+                  "tool: autosubmit is only allowed on GET forms (read-only lookups) - a mutating form " \
+                  "keeps the user's confirmation"
+          end
+          attributes[:toolautosubmit] = ""
+        end
+        attributes
+      end
+
+      # The control attribute for a parameter-description override.
+      #
+      # @param description [String] the parameter's description for agents
+      # @return [Hash{Symbol => String}] `toolparamdescription`
+      # @raise [ArgumentError] for a blank or over-budget description
+      def param_attributes(description)
+        { toolparamdescription: description!(description, "tool_description:") }
+      end
+
+      # @api private
+      def description!(value, context)
+        text = value.to_s.strip
+        if text.empty? || text.length > DESCRIPTION_LIMIT
+          raise ArgumentError, "#{context} must be present and at most #{DESCRIPTION_LIMIT} characters"
+        end
+
+        text
+      end
+    end
+  end
+end