poetry-ui 0.0.2

data/lib/generators/poetry/editor/templates/poetry-check-hook

@@ -0,0 +1,81 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# poetry's editor hook, written by `bin/rails g poetry:editor`: runs
+# `poetry check` on the app template an agent just edited and hands the
+# findings straight back to the agent, so the check runs after EVERY edit
+# instead of when the agent remembers to. Stdlib only; the check itself runs
+# through bin/rails, so it sees the same registry, icon set, and charts the
+# rake task sees.
+#
+# Two hook dialects, told apart by the payload:
+#   Claude Code (PostToolUse): errors -> exit 2 with the report on stderr (fed
+#     back to the agent); warnings -> exit 0 with additionalContext.
+#   Cursor (postToolUse): any findings -> exit 0 with additional_context.
+# Anything that is not an app template exits 0 without booting Rails; a check
+# that cannot run at all exits 1, so the loop fails open, never closed.
+
+require "json"
+require "open3"
+
+payload = begin
+  JSON.parse($stdin.read)
+rescue JSON::ParserError
+  {}
+end
+payload = {} unless payload.is_a?(Hash)
+tool_input = payload["tool_input"].is_a?(Hash) ? payload["tool_input"] : {}
+edited = tool_input["file_path"] || tool_input["path"] || payload["file_path"]
+exit 0 unless edited.is_a?(String) && !edited.empty?
+
+project = ENV["CLAUDE_PROJECT_DIR"] || Array(payload["workspace_roots"]).first || payload["cwd"] || Dir.pwd
+root = File.expand_path(project)
+full = File.expand_path(edited, root)
+exit 0 unless full.start_with?("#{root}/app/") && full.end_with?(".html.erb") && File.file?(full)
+template = full.delete_prefix("#{root}/")
+
+cursor = payload.key?("conversation_id") || payload["hook_event_name"] == "postToolUse"
+
+begin
+  stdout, stderr, status = Open3.capture3({ "POETRY_CHECK_JSON" => "1" }, "bin/rails", "poetry:check[#{template}]",
+                                          chdir: root)
+rescue SystemCallError => e
+  warn "poetry check hook: could not run bin/rails (#{e.message})"
+  exit 1
+end
+findings = begin
+  JSON.parse(stdout)
+rescue JSON::ParserError
+  nil
+end
+unless findings.is_a?(Array)
+  warn "poetry check hook: poetry:check did not run (exit #{status.exitstatus})\n#{stderr.lines.last(10).join}"
+  exit 1
+end
+if findings.empty?
+  puts "{}" if cursor
+  exit 0
+end
+
+errors = findings.count { |finding| finding["severity"] == "error" }
+warnings = findings.size - errors
+lines = findings.map do |finding|
+  hint = finding["suggestion"] ? " (did you mean #{finding["suggestion"]}?)" : ""
+  "- [#{finding["severity"]}] line #{finding["line"]}: #{finding["message"]}#{hint}"
+end
+headline = if errors.positive?
+             "poetry check: #{errors} error(s), #{warnings} warning(s) in #{template} - " \
+               "an error raises or misrenders at render time; fix it, then re-run poetry check"
+           else
+             "poetry check: #{warnings} warning(s) in #{template} - advisory; fix unless the deviation is deliberate"
+           end
+report = [headline, *lines].join("\n")
+
+if cursor
+  puts JSON.generate("additional_context" => report)
+elsif errors.positive?
+  warn report
+  exit 2
+else
+  puts JSON.generate("hookSpecificOutput" => { "hookEventName" => "PostToolUse", "additionalContext" => report })
+end

data/lib/generators/poetry/install/install_generator.rb

@@ -0,0 +1,364 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require_relative "../agents_section"
+require_relative "../skills_section"
+
+module Poetry
+  # `rails g poetry:install` - wires poetry into a host app:
+  #
+  #   app/assets/tailwind/poetry/tokens.css   the design tokens (:root + .dark)
+  #   app/assets/tailwind/poetry/theme.css    the Tailwind v4 @theme mapping
+  #   app/assets/tailwind/poetry/animate.css  the vendored animation
+  #                                           utility layer (Rails hosts
+  #                                           have no npm)
+  #   app/assets/tailwind/poetry/safelist.txt every dictionary + template class
+  #                                           (so the host build never purges
+  #                                           classes resolved in Ruby)
+  #   config/initializers/poetry.rb           commented configuration
+  #   config/poetry_components.yml            the copy-in manifest (empty)
+  #
+  # plus idempotent @import/@source injection into the host's Tailwind entry
+  # (append-unless-present - re-running install is always safe).
+  #
+  # `--charts` additionally wires poetry-charts (the gem must already be in
+  # the bundle - its engine merges the @poetry/charts importmap pins and the
+  # safelist pass picks the chart dictionaries up on its own; what a host
+  # still needs by hand is the motion stylesheet in the Tailwind entry and
+  # the Stimulus registration, and that is exactly what the flag does).
+  #
+  # @example
+  #   bin/rails g poetry:install --theme vega
+  class InstallGenerator < Rails::Generators::Base
+    include Generators::AgentsSection
+    include Generators::SkillsSection
+
+    # The host's Tailwind entry stylesheet (import/@source injection).
+    TAILWIND_ENTRY = "app/assets/tailwind/application.css"
+    # The theme slot: --theme swaps its CONTENT, the filename stays put.
+    STYLE_SLOT = "app/assets/tailwind/poetry/style-default.css"
+    # Every shipped fragment opens with `/* poetry <name> theme` - the sniff
+    # reads the slot's first line back so a plain re-run keeps the theme.
+    THEME_HEADER = %r{\A/\* poetry ([a-z0-9-]+) theme\b}
+
+    class_option :charts, type: :boolean, default: false,
+                          desc: %(Also wire poetry-charts (requires gem "poetry-charts" in the bundle))
+
+    # Install-time theme selection. Every themes/<name>.css fragment is
+    # a complete visual theme; the chosen one fills the style-default.css
+    # slot (the SLOT filename never changes - that keeps ENTRY_LINES
+    # idempotent and makes switching themes a re-run with a different
+    # --theme, overwriting in place). One theme per build; the multi-theme
+    # .style-<name> wrapper arrives with the docs switcher, not here.
+    #
+    # The upgrade-path contract: the default is nil, not "default" -
+    # a plain re-run sniffs the theme already in the slot and keeps it, so
+    # upgrading (bundle update + re-run) never swaps an app's design. An
+    # explicit --theme always wins; only a first install falls to "default".
+    class_option :theme, type: :string, default: nil,
+                         desc: "Visual theme fragment to install (a themes/<name>.css shipped by poetry-ui); " \
+                               "defaults to the theme already installed, or \"default\" on a first install"
+
+    # Injected line by line (not as one block) so a re-run after an upgrade
+    # appends any line a previous poetry version didn't know about.
+    ENTRY_LINES = [
+      %(@import "./poetry/tokens.css";),
+      %(@import "./poetry/theme.css";),
+      %(@import "./poetry/animate.css";),
+      %(@import "./poetry/utilities.css";),
+      %(@import "./poetry/aliases.css";),
+      %(@import "./poetry/style-default.css" layer(base);),
+      %(@import "./poetry/base.css";),
+      %(@import "./poetry/typeset.css";),
+      %(@source "./poetry/safelist.txt";)
+    ].freeze
+
+    # The base layer (upstream's init writes the same defaults into the
+    # host stylesheet):
+    # without it body/border/outline don't ride the tokens and dark mode
+    # only flips the components. Seeded once,
+    # user-owned - re-install never overwrites.
+    BASE_CSS = <<~CSS
+      /* poetry base layer (source-parity defaults) - yours to edit. */
+      @layer base {
+        * {
+          border-color: var(--border);
+          outline-color: color-mix(in oklab, var(--ring) 50%, transparent);
+        }
+        body {
+          background-color: var(--background);
+          color: var(--foreground);
+        }
+      }
+    CSS
+
+    desc "Install poetry: tokens, Tailwind theme, safelist, initializer, and the component manifest"
+
+    # Fails fast BEFORE any file lands: --charts against a bundle without
+    # the gem would otherwise half-install (css copied, dead registration).
+    # @api private
+    def verify_charts_gem
+      return if !options[:charts] || charts_available?
+
+      raise Thor::Error, "--charts needs poetry-charts in the bundle - add " \
+                         '`gem "poetry-charts"` to the Gemfile, bundle, and re-run'
+    end
+
+    # Same fail-fast for --theme: an unknown name (or one poetry-charts
+    # doesn't ship when --charts is on) must not half-install.
+    # @api private
+    def verify_theme_choice
+      unless ui_theme_path.exist?
+        available = Dir[Poetry::Ui.root.join("themes/*.css").to_s].map { |f| File.basename(f, ".css") }.sort
+        raise Thor::Error, "unknown poetry theme #{resolved_theme.inspect} - poetry-ui ships: #{available.join(", ")}"
+      end
+
+      return if !options[:charts] || !charts_available? || charts_theme_path.exist?
+
+      raise Thor::Error, "poetry-charts does not ship theme #{resolved_theme.inspect} - " \
+                         "every installed poetry gem must provide themes/#{resolved_theme}.css"
+    end
+
+    # Step: copies tokens, the Tailwind theme mapping, the vendored css,
+    # and the theme slot.
+    # @api private
+    def copy_tokens_and_theme
+      create_file "app/assets/tailwind/poetry/tokens.css",
+                  Poetry::Core.root.join("tokens/tokens.css").read, force: true
+      create_file "app/assets/tailwind/poetry/theme.css",
+                  Poetry::Core.root.join("tokens/tailwind-theme.css").read, force: true
+      create_file "app/assets/tailwind/poetry/animate.css",
+                  Poetry::Core.root.join("vendor/tw-animate-css/tw-animate.css").read, force: true
+      # The upstream first-party utility layer (shimmer / scroll-fade
+      # families + the chat-set keyframes), vendored verbatim at a pinned
+      # SHA - provenance in THIRD_PARTY_NOTICES.md (host filename stays
+      # utilities.css).
+      create_file "app/assets/tailwind/poetry/utilities.css",
+                  Poetry::Core.root.join("vendor/shadcn-tailwind/tailwind.css").read, force: true
+      create_file "app/assets/tailwind/poetry/aliases.css",
+                  Poetry::Core.root.join("tokens/aliases.css").read, force: true
+      # The cn-* theme layer: the named-class design source, imported
+      # layer(base) so host utilities always win. Vendored like tokens
+      # (force) - a host restyles by overriding .cn-* rules in its OWN css
+      # (any utilities-layer or unlayered rule beats layer(base)), never by
+      # editing this file, so theme updates keep flowing on re-install.
+      # --theme swaps the CONTENT; the slot filename stays put.
+      create_file "app/assets/tailwind/poetry/style-default.css",
+                  ui_theme_path.read, force: true
+      create_file "app/assets/tailwind/poetry/base.css", BASE_CSS, skip: true
+      # poetry/typeset (the vendored prose-styling port - provenance in
+      # THIRD_PARTY_NOTICES.md): prose styling for
+      # rendered markdown. App-OWNED like base.css (skip, never force) -
+      # the whole point of the artifact is that the file is yours to tune.
+      create_file "app/assets/tailwind/poetry/typeset.css",
+                  Poetry::Ui.root.join("typeset/typeset.css").read, skip: true
+    end
+
+    # Step: writes the dictionary + template-class safelist.
+    # @api private
+    def generate_safelist
+      # Style.descendants is empty until the component classes load - under
+      # `rails g` nothing has autoloaded them (the fresh-app proof caught
+      # this; the dummy suite masked it by eager-loading first).
+      Rails.application.eager_load!
+      styles = Poetry::Core::Style.descendants.select(&:name)
+      # Template-static classes (sr-only, animate-spin) come from the
+      # COMMITTED list - herb-extracted and drift-gated in poetry's CI,
+      # never required in a host (the browser pass caught the live-scan
+      # skip purging them).
+      safelist = Poetry::Core::CSS::Safelist.new(style_classes: styles,
+                                                 template_classes: Poetry::Ui.template_classes)
+      create_file "app/assets/tailwind/poetry/safelist.txt", safelist.text, force: true
+    end
+
+    # Step: injects the poetry @import/@source lines into the host's
+    # Tailwind entry.
+    # @api private
+    def wire_tailwind_entry
+      unless File.exist?(File.join(destination_root, TAILWIND_ENTRY))
+        create_file TAILWIND_ENTRY, %(@import "tailwindcss";\n)
+      end
+      ENTRY_LINES.each { |line| inject_unless_present(TAILWIND_ENTRY, line) }
+    end
+
+    # Step: writes the commented configuration initializer.
+    # @api private
+    def create_initializer
+      create_file "config/initializers/poetry.rb", <<~RUBY, skip: true
+        # frozen_string_literal: true
+
+        # poetry configuration. Defaults shown commented.
+        #
+        # Poetry::Core::Config.current.css_mode = :tailwind   # or :bem (bring your own CSS)
+        # Poetry::Core::Config.current.icon_library = :lucide
+      RUBY
+    end
+
+    # Step: writes the empty copy-in manifest.
+    # @api private
+    def create_manifest
+      create_file "config/poetry_components.yml", "components: {}\n", skip: true
+    end
+
+    # Pins alone don't register controllers: without this call every poetry
+    # controller is dead JS (the browser pass caught the dialog trigger
+    # doing nothing in a fresh host).
+    # @api private
+    def register_controllers
+      index = "app/javascript/controllers/index.js"
+      unless File.exist?(File.join(destination_root, index))
+        say_status :note, "no #{index} - register poetry's controllers yourself: " \
+                          "registerPoetryControllers(application) from \"@poetry/controllers\" " \
+                          "(and registerPoetryAgent(application) from \"@poetry/agent\" " \
+                          "when poetry-agent is bundled)", :yellow
+        return
+      end
+
+      inject_unless_present(index, <<~JS.strip)
+        import { registerPoetryControllers } from "@poetry/controllers"
+        registerPoetryControllers(application)
+      JS
+      register_agent_runtime(index)
+    end
+
+    # --charts: the two host-side wires the charts engine cannot do itself.
+    # The motion stylesheet is COPIED (tailwindcss-rails compiles standalone;
+    # a gem-path @import would not resolve) - vendored artifact, force like
+    # tokens; the entry @import and the Stimulus registration ride the same
+    # idempotent primitives as the core wiring.
+    # @api private
+    def wire_charts
+      return unless options[:charts]
+
+      create_file "app/assets/tailwind/poetry/charts.css",
+                  Poetry::Charts.root.join("app/assets/stylesheets/poetry-charts.css").read,
+                  force: true
+      inject_unless_present(TAILWIND_ENTRY, %(@import "./poetry/charts.css";))
+      # The charts cn-* theme fragment - vendored like style-default,
+      # same --theme selection.
+      create_file "app/assets/tailwind/poetry/style-charts.css",
+                  charts_theme_path.read, force: true
+      inject_unless_present(TAILWIND_ENTRY, %(@import "./poetry/style-charts.css" layer(base);))
+
+      index = "app/javascript/controllers/index.js"
+      unless File.exist?(File.join(destination_root, index))
+        say_status :note, "no #{index} - register the chart controllers yourself: " \
+                          "registerPoetryChartsControllers(application) from \"@poetry/charts\"", :yellow
+        return
+      end
+
+      inject_unless_present(index, <<~JS.strip)
+        import { registerPoetryChartsControllers } from "@poetry/charts"
+        registerPoetryChartsControllers(application)
+      JS
+    end
+
+    # The llms.txt / llms-full.txt agent docs are engine routes - without
+    # the mount they are unreachable (the fresh-app proof caught this).
+    # @api private
+    def mount_engine
+      routes = File.join(destination_root, "config/routes.rb")
+      return unless File.exist?(routes)
+      return if File.read(routes).include?("Poetry::Ui::Engine")
+
+      route %(mount Poetry::Ui::Engine => "/poetry" # llms.txt + llms-full.txt (agent-facing docs))
+    end
+
+    # The AGENTS.md pointer section - marker-bounded so a re-run
+    # refreshes it in place. Standalone refresh: `rails g poetry:agents`.
+    # @api private
+    def write_agents_md
+      apply_agents_section
+    end
+
+    # The Claude Code skills - part of the standard
+    # install surface, like AGENTS.md. Standalone refresh:
+    # `rails g poetry:skill` (re-run after updating poetry gems).
+    # @api private
+    def write_skills
+      apply_poetry_skills
+    end
+
+    # Dark mode is one layout line, but nothing else in the install touches
+    # the layout - without the pointer the theme never applies before first
+    # paint and hosts rediscover the flash-of-light-mode pothole.
+    # @api private
+    def announce_color_scheme
+      say_status :note, "dark mode: render <%= poetry_color_scheme_script %> in your layout <head> " \
+                        "(the Theming guide, \"Color scheme\")", :cyan
+    end
+
+    # poetry_optimistic_form reconciles failures via a Turbo refresh, which
+    # must MORPH to be seamless - two layout metas the install cannot add
+    # for the host (the redirect trap and server contract live in
+    # the doc).
+    # @api private
+    def announce_optimistic_form
+      say_status :note, "optimistic forms: add <meta name=\"turbo-refresh-method\" content=\"morph\"> " \
+                        "+ <meta name=\"turbo-refresh-scroll\" content=\"preserve\"> to your layout " \
+                        "<head> before using poetry_optimistic_form (the Optimistic Forms guide)", :cyan
+    end
+
+    private
+
+    def resolved_theme
+      @resolved_theme ||= options[:theme] || installed_theme || "default"
+    end
+
+    # Which theme fills the slot right now. Unreadable header (a
+    # hand-edited file, or an install predating theme selection) falls back
+    # to "default" WITH a warning - never silently.
+    def installed_theme
+      path = File.join(destination_root, STYLE_SLOT)
+      return nil unless File.exist?(path)
+
+      name = File.foreach(path).first.to_s[THEME_HEADER, 1]
+      if name.nil?
+        say_status :theme, "could not identify the installed theme from #{STYLE_SLOT} - " \
+                           "installing \"default\" (pass --theme <name> to keep yours)", :yellow
+      elsif name != "default"
+        say_status :theme, "keeping installed theme #{name.inspect} (pass --theme to switch)", :cyan
+      end
+      name
+    end
+
+    def charts_available?
+      defined?(Poetry::Charts::Engine) ? true : false
+    end
+
+    def agent_available?
+      defined?(Poetry::Agent::Engine) ? true : false
+    end
+
+    # poetry-agent's WebMCP runtime registers beside the controllers when
+    # the gem is bundled (the engine already pins @poetry/agent); without
+    # it, `webmcp:` opt-ins have nothing to register with. Private: Thor
+    # would otherwise expose an argument-taking method as a command.
+    def register_agent_runtime(index)
+      return unless agent_available?
+
+      inject_unless_present(index, <<~JS.strip)
+        import { registerPoetryAgent } from "@poetry/agent"
+        registerPoetryAgent(application)
+      JS
+    end
+
+    def ui_theme_path
+      Poetry::Ui.root.join("themes/#{resolved_theme}.css")
+    end
+
+    def charts_theme_path
+      Poetry::Charts.root.join("themes/#{resolved_theme}.css")
+    end
+
+    # The idempotency lives in the file-mutation primitive, not the
+    # generator: appending is a no-op when
+    # the line is already present.
+    def inject_unless_present(relative, line)
+      path = File.join(destination_root, relative)
+      return if File.exist?(path) && File.read(path).include?(line)
+
+      append_to_file relative, "#{line}\n"
+    end
+  end
+end

data/lib/generators/poetry/pagination/pagination_generator.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+
+module Poetry
+  module Generators
+    # `rails g poetry:pagination [kaminari|pagy|will_paginate]` - copies a
+    # poetry adapter for the host's paginator(s) as OWNED host-app code
+    # (the copied-source doctrine; poetry:diff tracks drift). No argument:
+    # every paginator loaded in this app gets its adapter.
+    #
+    # The doctrine baked into every adapter: poetry owns the window
+    # (siblings/edges compute the visible pages) - the paginator's own
+    # window options deliberately do not apply, so pagination looks the
+    # same whichever gem drives it.
+    #
+    # @example
+    #   bin/rails g poetry:pagination pagy
+    class PaginationGenerator < Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      # Per-paginator adapter wiring: how to detect the gem, which
+      # template to copy, and where it lands.
+      ADAPTERS = {
+        "kaminari" => { detect: -> { defined?(::Kaminari) },
+                        template: "kaminari_paginator.html.erb",
+                        destination: "app/views/kaminari/_paginator.html.erb" },
+        "pagy" => { detect: -> { defined?(::Pagy) },
+                    template: "poetry_pagy_helper.rb",
+                    destination: "app/helpers/poetry_pagy_helper.rb" },
+        "will_paginate" => { detect: -> { defined?(::WillPaginate) },
+                             template: "poetry_link_renderer.rb",
+                             destination: "app/lib/poetry_link_renderer.rb" }
+      }.freeze
+
+      argument :paginator, type: :string, required: false,
+                           banner: "kaminari|pagy|will_paginate",
+                           desc: "the paginator to adapt (omit to detect every installed one)"
+
+      # Step: copies the adapter(s) for the requested or detected
+      # paginator(s).
+      # @api private
+      def install_adapters
+        names = requested_adapters
+        if names.empty?
+          say_status :skip, "no paginator detected (kaminari / pagy / will_paginate) - " \
+                            "add one to the Gemfile first, or name it explicitly", :yellow
+          return
+        end
+
+        names.each do |name|
+          spec = ADAPTERS.fetch(name)
+          copy_file spec[:template], spec[:destination]
+        end
+      end
+
+      private
+
+      def requested_adapters
+        if paginator.present?
+          unless ADAPTERS.key?(paginator)
+            raise Thor::Error, "unknown paginator #{paginator.inspect} - " \
+                               "one of: #{ADAPTERS.keys.join(", ")}"
+          end
+          unless ADAPTERS.fetch(paginator)[:detect].call
+            raise Thor::Error, "#{paginator} is not loaded in this app - add the gem, bundle, and re-run"
+          end
+
+          [paginator]
+        else
+          ADAPTERS.select { |_name, spec| spec[:detect].call }.keys
+        end
+      end
+    end
+  end
+end

data/lib/generators/poetry/pagination/templates/kaminari_paginator.html.erb

@@ -0,0 +1,29 @@
+<%# generated by `bin/rails g poetry:pagination kaminari` - this file is
+    yours: edit freely. ONE monolithic template replaces kaminari's seven
+    theme partials. page_url_for (via a bare Tag) honors param_name (incl.
+    nested), the canonical param-less page 1, and kaminari's param
+    blocklist. (No paginator.render block here: its method_missing
+    delegation drops Ruby keyword arguments - call helpers directly.)
+
+    Doctrine: poetry owns the window - kaminari's window:/outer_window:
+    options do not apply. Pass poetry options straight through paginate:
+      paginate @records, siblings: 2, edges: :arrows
+    (unrecognized paginate options arrive here as locals). The
+    total_pages guard mirrors kaminari's own nil-at-one-page behavior. %>
+<% if total_pages > 1 %>
+  <%# URL duty rides a bare Tag (the abstract base with public
+      page_url_for): released kaminari's Paginator skips Tag#initialize,
+      so page_url_for only works on the Paginator on unreleased master.
+      The Tag inherits param_name/params from the paginate call's options
+      (they arrive here as locals). %>
+  <% url_tag = Kaminari::Helpers::Tag.new(
+       self, **{ params: local_assigns[:params],
+                 param_name: local_assigns[:param_name] }.compact) %>
+  <%= poetry_pagination(
+        current: current_page.to_i,
+        total: total_pages,
+        path: ->(page) { url_tag.page_url_for(page) },
+        **local_assigns.slice(:siblings, :edges, :pages, :current_variant,
+                              :label, :previous_label, :next_label).compact
+      ) %>
+<% end %>

data/lib/generators/poetry/pagination/templates/poetry_link_renderer.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+# generated by `bin/rails g poetry:pagination will_paginate` - this file is
+# yours: edit freely. Usage (the renderer: option per call - will_paginate
+# deprecates the global default):
+#
+#   <%= will_paginate @records, renderer: PoetryLinkRenderer %>
+#
+# to_html is replaced wholesale (the upstream comment invites it); the
+# inherited url(page) keeps will_paginate's GET-param merging and nested
+# param_name support. Doctrine: poetry owns the window - inner_window/
+# outer_window do not apply; will_paginate's container options are
+# absorbed by poetry's own <nav> landmark. Upstream behavior kept: the
+# helper returns nil when total_pages <= 1 (this class is never called).
+#
+# Note: will_paginate itself is in maintenance mode (no new features or
+# releases since mid-2024). This adapter supports apps that already use
+# it; for a new project, prefer kaminari or pagy.
+
+# will_paginate wires its ActionView integration on_load(:action_view);
+# eager-loading contexts (generators, some rake tasks) can autoload this
+# class before that hook fires, so pull the superclass in explicitly.
+require "will_paginate/view_helpers/action_view"
+
+class PoetryLinkRenderer < WillPaginate::ActionView::LinkRenderer
+  def to_html
+    @template.poetry_pagination(
+      current: @collection.current_page.to_i,
+      total: @collection.total_pages,
+      path: ->(page) { url(page) },
+      **(@options[:poetry] || {})
+    )
+  end
+end

data/lib/generators/poetry/pagination/templates/poetry_pagy_helper.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+# generated by `bin/rails g poetry:pagination pagy` - this file is yours:
+# edit freely. Usage, anywhere a view holds a @pagy:
+#
+#   <%= poetry_pagy_nav(@pagy) %>
+#
+# Doctrine: poetry owns the window (siblings:/edges: options here) -
+# pagy's slots: does not apply. Mirrors the other paginators' behavior of
+# rendering nothing at a single page. Needs pagy >= 43 (the leap-version
+# redesign: instance-method navs, page_url); pagy's *_js navs are
+# deliberately not adapted - their token protocol couples to pagy.js.
+module PoetryPagyHelper
+  def poetry_pagy_nav(pagy, **options)
+    unless Pagy::VERSION.to_i >= 43
+      raise "poetry_pagy_nav needs pagy >= 43 (found #{Pagy::VERSION}) - " \
+            "the pre-43 extras API is a different world"
+    end
+    return "".html_safe if pagy.last <= 1
+
+    poetry_pagination(
+      current: pagy.page.to_i,
+      total: pagy.last,
+      path: ->(page) { pagy.page_url(page) },
+      **options
+    )
+  end
+end