poetry-ui 0.0.2

data/lib/poetry/ui/recipes.rb

@@ -0,0 +1,157 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Ui
+    # The recipes channel: multi-file payloads served
+    # through the registry beside components and blocks. Every definition's
+    # files are LAZY callables over gem-shipped sources - the same files
+    # the generators install - so the projection cannot drift from the
+    # generator path. Names share the flat kebab namespace (RegistryIndex
+    # collision-checks recipes against components and blocks at first
+    # touch).
+    module Recipes
+      # Gem-relative path of the scaffold override template set.
+      SCAFFOLD_TEMPLATES = "lib/generators/poetry/scaffold_templates/templates"
+      # Gem-relative path holding the screen-slice and embed sources.
+      SCREEN_SOURCES = "lib/generators/poetry/recipes"
+
+      class << self
+        # Every recipe definition, in registry order: the agent embed, the
+        # three skill bundles, the scaffold-template set, and the screen
+        # slices.
+        #
+        # @return [Array<Hash>] name/title/description + lazy "files"
+        def definitions
+          [agent_embed, skill_poetry, skill_poetry_design, skill_poetry_component, scaffold_templates,
+           screen(
+             "screen-data-index", title: "Data index screen",
+                                  description: "The data-index block as a working feature slice: OrdersController, " \
+                                               "its index view rendering the block, and a system test. Add " \
+                                               "`resources :orders, only: :index` to routes.",
+                                  dependencies: ["data-index"]
+           ),
+           screen(
+             "screen-settings", title: "Settings screen",
+                                description: "A settings page composed from the page-header, section-card, and " \
+                                             "destructive-panel blocks: SettingsController, the composed view, " \
+                                             "and a system test. Add `resource :settings, only: :show` to routes.",
+                                dependencies: %w[page-header section-card destructive-panel]
+           )]
+        end
+
+        private
+
+        def skill_poetry
+          {
+            "name" => "skill-poetry",
+            "title" => "poetry skill bundle",
+            "description" => "The component-usage Claude Code skill (SKILL.md + per-family " \
+                             "references), generated from the live registry - the same files " \
+                             "`bin/rails g poetry:skill` installs.",
+            "files" => lambda {
+              Poetry::Ui.runtime_skill_files.map do |rel, content|
+                { "path" => rel, "target" => ".claude/skills/poetry/#{rel}", "content" => content }
+              end
+            }
+          }
+        end
+
+        def skill_poetry_design
+          {
+            "name" => "skill-poetry-design",
+            "title" => "poetry-design skill bundle",
+            "description" => "The design-taste Claude Code skill (theme / compose / audit / study " \
+                             "references) - the same files `bin/rails g poetry:skill` installs.",
+            "files" => lambda {
+              require "generators/poetry/skills_section"
+              files = Object.new.extend(Poetry::Generators::SkillsSection).design_skill_files
+              files.map do |rel, content|
+                { "path" => rel, "target" => ".claude/skills/poetry-design/#{rel}", "content" => content }
+              end
+            }
+          }
+        end
+
+        def skill_poetry_component
+          {
+            "name" => "skill-poetry-component",
+            "title" => "poetry-component skill bundle",
+            "description" => "The component-authoring Claude Code skill (anatomy / documentation / " \
+                             "audit references) - the same files `bin/rails g poetry:skill` installs.",
+            "files" => lambda {
+              require "generators/poetry/skills_section"
+              files = Object.new.extend(Poetry::Generators::SkillsSection).component_skill_files
+              files.map do |rel, content|
+                { "path" => rel, "target" => ".claude/skills/poetry-component/#{rel}", "content" => content }
+              end
+            }
+          }
+        end
+
+        # The scaffold override set: static .tt files whose targets mirror
+        # `poetry:scaffold_templates` exactly - Rails does the
+        # parameterization later, so the payload needs none.
+        def scaffold_templates
+          {
+            "name" => "scaffold-templates",
+            "title" => "poetry scaffold templates",
+            "description" => "The lib/templates override set that makes the STANDARD `rails g " \
+                             "scaffold` emit poetry-composed views and a matching controller - " \
+                             "the same files `bin/rails g poetry:scaffold_templates` copies.",
+            "files" => lambda {
+              base = Poetry::Ui.root.join(SCAFFOLD_TEMPLATES)
+              base.glob("*.tt").sort.map do |file|
+                name = file.basename.to_s
+                target = if name == "controller.rb.tt"
+                           "lib/templates/rails/scaffold_controller/controller.rb.tt"
+                         else
+                           "lib/templates/erb/scaffold/#{name}"
+                         end
+                { "path" => name, "target" => target, "content" => file.read }
+              end
+            }
+          }
+        end
+
+        # The in-page GUI agent loader: the Turbo-hardened page-agent
+        # embed as a copy-in Stimulus controller - CDN-pinned script,
+        # opt-in, BYO key, and the poetry operator ground rules embedded
+        # as fallback instructions.
+        def agent_embed
+          {
+            "name" => "agent-embed",
+            "title" => "In-page agent embed",
+            "description" => "An opt-in page-agent loader for a poetry app as a Stimulus " \
+                             "controller: pinned CDN script (?autoInit=false), session-only " \
+                             "BYO key, Turbo-hardened (remounts on turbo:load, idle-only " \
+                             "rebuild, module-init catch-up), poetry operator instructions " \
+                             "built in. Wire a form with targets model/baseUrl/apiKey/status.",
+            "files" => lambda {
+              base = Poetry::Ui.root.join(SCREEN_SOURCES, "agent_embed")
+              base.glob("**/*").select(&:file?).sort.map do |file|
+                rel = file.relative_path_from(base).to_s
+                { "path" => rel, "target" => rel, "content" => file.read }
+              end
+            }
+          }
+        end
+
+        def screen(name, title:, description:, dependencies:)
+          {
+            "name" => name,
+            "title" => title,
+            "description" => description,
+            "registry_dependencies" => dependencies,
+            "files" => lambda {
+              base = Poetry::Ui.root.join(SCREEN_SOURCES, name.tr("-", "_"))
+              base.glob("**/*").select(&:file?).sort.map do |file|
+                rel = file.relative_path_from(base).to_s
+                { "path" => rel, "target" => rel, "content" => file.read }
+              end
+            }
+          }
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,167 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Ui
+    module Testing
+      # The Combobox interaction contract, both modes: open, FILTER by
+      # typing into the command input, commit an option; single-select
+      # closes on commit and the native select serializes, multiple keeps
+      # the popover open, grows chips, and serializes name[] through a
+      # native select-multiple.
+      #
+      # CONTENT RESOLVES THROUGH THE ID PAIR, document-wide: portal-on-open
+      # moves the open popup to body (docs/portal-on-open.md), so root
+      # scoping stops holding for the content and its items. The trigger
+      # (single) or the chips inline input (multiple) carries aria-controls
+      # naming the listbox; the content wrapper is its ancestor -
+      # id-anchored selectors keep Capybara's waiting semantics.
+      #
+      # @example Filtering, then committing
+      #   combo = poetry_combobox("#assignee")
+      #   combo.filter("Ada").select_option("Ada Lovelace")
+      #   assert_equal "ada", combo.value
+      class Combobox < Tester
+        # Whether the popup 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 popup (no-op when already open). via: :keyboard focuses
+        # the trigger and presses ArrowDown; :mouse presses it.
+        #
+        # @return [Combobox] 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='combobox-content'][data-open][data-side]")
+          self
+        end
+
+        # Escape-closes the open popup and waits for the closed state.
+        #
+        # @return [Combobox] self
+        def close
+          keys(:escape) if open?
+          session.assert_selector("##{content_id}[data-closed]", visible: :all)
+          self
+        end
+
+        # Type into the filter input (opens first when closed). Single mode
+        # keeps the input inside the (portaled) popup; multiple keeps it
+        # inline in the chips field at home.
+        #
+        # @return [Combobox] self
+        def filter(query)
+          open
+          filter_input.set(query)
+          self
+        end
+
+        # Commit by exact visible text; single-select waits for the close,
+        # multiple leaves the popover up (assert on values/chips instead).
+        #
+        # @return [Combobox] 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
+
+          self
+        end
+
+        # Single: the committed value. Multiple: the committed value list.
+        #
+        # @return [String, Array<String>]
+        def value
+          native = hidden_part("combobox-native")
+          native.multiple? ? native.value : native.value.to_s
+        end
+
+        # The visible chip texts (multiple mode).
+        #
+        # @return [Array<String>]
+        def chips
+          parts("combobox-chip").map(&:text)
+        end
+
+        # Remove a chip by its accessible text (multiple mode).
+        #
+        # @return [Combobox] self
+        def remove_chip(text)
+          press(root.find("[data-slot='combobox-chip']", text: text).find("button"))
+          self
+        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='combobox-item']", visible: :all)
+
+          (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("combobox-trigger")
+        end
+
+        # The aria-controls anchor stays HOME in both modes: the trigger
+        # button (single) or the chips frame's inline input (multiple).
+        def list_id
+          @list_id ||= root.first(
+            "[data-slot='combobox-trigger'], [data-slot='combobox-chips'] [data-slot='combobox-chip-input']",
+            minimum: 1, visible: :all
+          )["aria-controls"]
+        end
+
+        def content_id
+          @content_id ||= session.find("##{list_id}", visible: :all)
+                                 .ancestor("[data-slot='combobox-content']", visible: :all)[:id]
+        end
+
+        def content
+          session.find("##{content_id}", visible: :all)
+        end
+
+        def filter_input
+          content.first("[data-slot='combobox-input']", minimum: 0, visible: :all) || part("combobox-input")
+        end
+
+        def option(text)
+          content.find("[data-slot='combobox-item']", text: text, exact_text: true)
+        end
+
+        def highlighted_text
+          content.find("[data-slot='combobox-item'][data-highlighted]", wait: 1).text
+        rescue Capybara::ElementNotFound
+          nil
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Ui
+    module Testing
+      # The Dialog interaction contract: the trigger opens, focus is
+      # trapped inside, Escape (or the close affordance) dismisses, and
+      # focus RETURNS to the trigger. The root you hand this tester is the
+      # element carrying data-component=dialog (trigger + content).
+      #
+      # @example Opening, asserting, dismissing
+      #   dialog = poetry_dialog("[data-component='dialog']")
+      #   dialog.open(via: :keyboard)
+      #   assert_equal "Are you sure?", dialog.title
+      #   dialog.close
+      class Dialog < Tester
+        # Whether the dialog is currently open.
+        #
+        # @return [Boolean]
+        def open?(wait: 0)
+          part?("dialog-content", wait: wait) &&
+            !hidden_part("dialog-content")["data-open"].nil?
+        rescue Capybara::ElementNotFound
+          false
+        end
+
+        # Opens the dialog (no-op when already open). via: :keyboard
+        # focuses the trigger and presses Enter; :mouse presses it.
+        #
+        # @return [Dialog] self
+        def open(via: :mouse)
+          return self if open?
+
+          case via
+          when :keyboard
+            focus(trigger)
+            keys(:enter)
+          else
+            press(trigger)
+          end
+
+          root.assert_selector("[data-slot='dialog-content'][data-open]")
+          self
+        end
+
+        # Escape-closes the open dialog and waits for the closed state.
+        #
+        # @return [Dialog] self
+        def close
+          keys(:escape) if open?
+          root.assert_selector("[data-slot='dialog-content'][data-closed]", visible: :all)
+          self
+        end
+
+        # The dialog's accessible title text.
+        #
+        # @return [String]
+        def title
+          part("dialog-title").text
+        end
+
+        private
+
+        # The trigger has no slot of its own - it is the consumer's Button
+        # wired to the dialog controller's open action (the contract).
+        def trigger
+          root.find("[data-action*='#{Poetry::Ui::Dialog::Component.stimulus_action(:open)}']",
+                    match: :first)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Ui
+    module Testing
+      # The DropdownMenu interaction contract: trigger toggles, open lands
+      # focus in the menu, arrows move data-highlighted, Enter activates
+      # the highlighted item, Escape closes with focus returned to the
+      # trigger.
+      #
+      # CONTENT RESOLVES THROUGH THE ID PAIR, document-wide: portal-on-open
+      # moves the open menu to body (docs/portal-on-open.md), so root
+      # scoping stops holding for the 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 Activating a menu item
+      #   menu = poetry_dropdown_menu("#row-actions")
+      #   menu.choose("Archive", via: :keyboard)
+      class Menu < Tester
+        # Whether the menu 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 menu (no-op when already open). via: :keyboard focuses
+        # the trigger and presses ArrowDown; :mouse presses it.
+        #
+        # @return [Menu] 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='dropdown-menu-content'][data-open][data-side]")
+          self
+        end
+
+        # Escape-closes the open menu and waits for the closed state.
+        #
+        # @return [Menu] self
+        def close
+          keys(:escape) if open?
+          session.assert_selector("##{content_id}[data-closed]", visible: :all)
+          self
+        end
+
+        # Opens first when closed; activates by exact visible text.
+        #
+        # @return [Menu] self
+        def choose(text, via: :mouse)
+          self.open(via: via)
+
+          if via == :keyboard
+            walk_highlight_to(text)
+            keys(:enter)
+          else
+            press(item(text))
+          end
+
+          self
+        end
+
+        # The visible item texts (opens the menu first when closed).
+        #
+        # @return [Array<String>]
+        def items
+          open unless open?
+          content.all("[data-slot='dropdown-menu-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)
+          list = content.all("[data-slot='dropdown-menu-item']")
+
+          (list.size + 1).times do
+            return if highlighted_text == text
+
+            keys(:down)
+          end
+
+          raise Capybara::ElementNotFound,
+                "no option #{text.inspect} reached by ArrowDown - " \
+                "options: #{list.map(&:text).inspect}"
+        end
+
+        def trigger
+          part("dropdown-menu-trigger")
+        end
+
+        # The trigger's aria-controls names the menu wherever it sits.
+        def content_id
+          @content_id ||= trigger["aria-controls"]
+        end
+
+        def content
+          session.find("##{content_id}", visible: :all)
+        end
+
+        # Substring match, not exact: menu items legitimately carry more
+        # than their label (shortcut glyphs, badges).
+        def item(text)
+          content.find("[data-slot='dropdown-menu-item']", text: text, match: :first)
+        end
+
+        def highlighted_text
+          content.find("[data-slot='dropdown-menu-item'][data-highlighted]", wait: 1).text
+        rescue Capybara::ElementNotFound
+          nil
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Ui
+    module Testing
+      # Raised by assert_poetry_controllers_registered outside Minitest.
+      class RegistrationError < StandardError; end
+
+      # The page-wide registration guard behind
+      # {Testing#poetry_unregistered_controllers}: every `data-controller`
+      # identifier with poetry's prefix must be registered on the host's
+      # Stimulus application, or the element is silently inert - Stimulus
+      # never errors on an unknown identifier, and one failed import in
+      # the controllers graph takes every poetry controller down with it.
+      #
+      # @api private
+      module Registration
+        PREFIX = "poetry--"
+
+        # The JS run in the page: `application` is an expression naming
+        # the Stimulus application (window.Stimulus in Rails' default
+        # controllers/application.js).
+        #
+        # @return [String]
+        def self.script(application)
+          <<~JS
+            (() => {
+              const application = #{application};
+              if (!application) return { error: "no Stimulus application at #{application} - the controllers module never ran (one failed import kills the whole graph)" };
+              const registry = application.router && application.router.modulesByIdentifier;
+              const registered = registry ? Array.from(registry.keys()) : (application.controllers || []).map((c) => c.identifier);
+              const known = new Set(registered);
+              const missing = new Set();
+              for (const element of document.querySelectorAll("[data-controller]")) {
+                for (const identifier of element.getAttribute("data-controller").split(/\\s+/)) {
+                  if (identifier.startsWith(#{PREFIX.inspect}) && !known.has(identifier)) missing.add(identifier);
+                }
+              }
+              return { missing: Array.from(missing).sort(), registered: registered.filter((id) => id.startsWith(#{PREFIX.inspect})).length };
+            })()
+          JS
+        end
+
+        # The failure text: the identifiers, and the two causes worth
+        # checking first.
+        #
+        # @return [String]
+        def self.message(result)
+          return result["error"] if result["error"]
+
+          "#{result["missing"].size} poetry controller(s) on the page are not registered on the Stimulus " \
+            "application: #{result["missing"].join(", ")} (#{result["registered"]} poetry controllers are). " \
+            "Check the importmap pins and that every poetry gem's register call runs in controllers/index.js."
+        end
+      end
+    end
+  end
+end