twitter-bootstrap-rails 5.5.0 → 5.5.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e749f38d103c9081159cd686251b083119950e45ac05a07ffbec1fdc9998c718
-  data.tar.gz: b68354a498fbccd9f3332c3c28c1e34984d236cad0aaaaf24b521e32361700d2
+  metadata.gz: 875edfcbadfdb5b579da81a68c3a5dc44d7b14d208bcf7de6dc89a8dabe969d3
+  data.tar.gz: bc3f64fe1f6c45217d043887a9fbcab629e7161738b2c47c3ea46a0a830b1cb1
 SHA512:
-  metadata.gz: d89262fa8b657f75f13f3be3f0550f0999e06e14a2de6bc6d76fdab6171639b5785cd7167118d90aef0dae928ecff7f526d3c3daf1e2b31cb568c252ca391c4d
-  data.tar.gz: deb6bc95b028221c973918da2f69df302b862552e12f5744c7735fabf32c00eab231c82855e4beb2f52dcb15239c7a9325583bff128df349f7a7bcd235fe7fb4
+  metadata.gz: 18bd87131c776f3da869462fb6af504614dd708a91434881a9e46955a3e7817cdbcd8071e3d490a5bd18841b3601016e632e73163071786c026b5a2fb52cfc74
+  data.tar.gz: 75630ca82664a7956d088fbc90b48d2eb1f11e89087488dcb7a5b209221aff58ccabc2296546a4be9fc83595109b6b31fc41db9be8e931a23818ac8f6dea8841

data/CHANGELOG.md

@@ -1,3 +1,26 @@
+## 5.5.1
+
+### Added
+
+- **Bootstrap 6 migration support.** `rails g bootstrap:doctor --v6` adds a
+  `v6_migration` check and list: Bootstrap 5 classes, data attributes, Sass
+  `@import`s and JavaScript calls that change in Bootstrap 6, with file, line and
+  replacement. It follows the upstream `bootstrap-v5-v6-migration` skill from
+  `twbs/bootstrap`, scans views, helpers, components, `app/javascript` and
+  stylesheets, skips the Bootstrap files this gem vendored, and only warns.
+- The `bootstrap:agent` guide has a Bootstrap 6 section. It tells agents not to write
+  Bootstrap 6 markup on the Bootstrap 5 this gem ships, and gives the steps to migrate:
+  install the upstream skill with
+  `npx skills add twbs/bootstrap --skill bootstrap-v5-v6-migration`, run
+  `bootstrap:doctor --v6 --json`, and switch assets before markup.
+- The upstream migration skill is installed in this repository
+  (`.claude/skills/bootstrap-v5-v6-migration`, pinned in `skills-lock.json`) for work
+  on the gem itself. It is not packaged into the gem.
+
+### Changed
+
+- `bootstrap:doctor` prints a heading above each list of findings.
+
 ## 5.5.0
 
 ### Added

data/README.md

@@ -156,6 +156,7 @@ knows instead. The gem doesn't call any AI service and needs no API key.
 rails g bootstrap:agent          # write a guide tailored to this app
 rails g bootstrap:doctor         # check how Bootstrap is set up
 rails g bootstrap:doctor --json  # the same report, for agents and CI
+rails g bootstrap:doctor --v6    # also list what changes in Bootstrap 6
 rails g bootstrap:header --json  # list a snippet's variants as JSON
 ```
 
@@ -179,6 +180,37 @@ In an existing app, `legacy_markup` works as a migration to-do list. Plain names
 If Bootstrap comes from `package.json` or your importmap, the doctor warns that it
 can't verify it rather than reporting an error.
 
+### Preparing for Bootstrap 6
+
+This gem ships Bootstrap 5.3.8. Bootstrap 6 is in alpha (`6.0.0-alpha.1` on npm),
+and the Bootstrap team publishes an agent skill for the move from 5 to 6. Install it
+into your app alongside the gem's own guide:
+
+```bash
+npx skills add twbs/bootstrap --skill bootstrap-v5-v6-migration
+rails g bootstrap:agent             # the guide tells agents to stay on Bootstrap 5 markup until you migrate
+rails g bootstrap:doctor --v6       # the migration worklist
+rails g bootstrap:doctor --v6 --json
+```
+
+`--v6` adds a `v6_migration` check and list: every Bootstrap 5 class, data attribute,
+Sass `@import` and JavaScript call that changes in Bootstrap 6, with file, line and
+replacement. For example `modal-body` becomes `dialog-body`, `col-md-6` becomes
+`md:col-6`, `btn-primary` becomes `btn-solid theme-primary`, and
+`data-bs-toggle="dropdown"` becomes `data-bs-toggle="menu"`. It scans `app/views`,
+`app/helpers`, `app/components`, `app/javascript` and your stylesheets, and skips the
+Bootstrap files this gem vendored. It reports a warning, never an error, and is off
+unless you ask for it.
+
+Things the scan can't do for you:
+
+- The vendored assets, `bootstrap:install` and every generator are still Bootstrap 5.
+  Switch the assets to Bootstrap 6 before changing markup, and don't re-run the
+  generators afterwards.
+- The view helpers (`nav_bar`, `modal_dialog`, `badge` and the rest) render Bootstrap 5
+  markup at runtime, so their output isn't scanned.
+- Bootstrap 6 changes the spacing scale, so check `p-*`/`m-*` utilities by eye.
+
 ## Quick Start
 
 ```bash

data/lib/generators/bootstrap/agent/agent_generator.rb

@@ -1,6 +1,7 @@
 require 'erb'
 require 'rails/generators'
 require 'twitter/bootstrap/rails/doctor'
+require 'twitter/bootstrap/rails/v6_migration'
 require 'generators/bootstrap/snippets/snippet_catalog'
 
 module Bootstrap
@@ -66,6 +67,10 @@ module Bootstrap
         Twitter::Bootstrap::Rails::LegacyMarkup
       end
 
+      def v6
+        Twitter::Bootstrap::Rails::V6Migration
+      end
+
       def pipeline_note
         case facts[:asset_pipeline]
         when "propshaft"

data/lib/generators/bootstrap/agent/templates/guide.md.erb

@@ -45,6 +45,18 @@ Snippets are always written as ERB partials. They render from any template engin
 - Modals: `modal_dialog`, `modal_toggle`, `modal_cancel_button`
 - Other: `badge`, `tag_label`, `render_breadcrumbs`, `add_breadcrumb`, and `error_span` on form builders
 
+## Bootstrap 6
+
+This app runs Bootstrap <%= facts[:bootstrap_version] %>. Don't write Bootstrap 6 markup (`dialog`, `drawer`, `menu`, `md:col-6`, `btn-solid theme-primary`) unless the app is being moved to Bootstrap 6: none of it works on <%= facts[:bootstrap_version] %>. The gem's generators and helpers produce Bootstrap 5 markup.
+
+To move the app to Bootstrap 6:
+
+1. Install the upstream migration skill: `<%= v6::SKILL_COMMAND %>`. Follow it alongside this guide.
+2. Run `rails g bootstrap:doctor --v6 --json`. It lists every Bootstrap 5 class, data attribute, Sass import and JavaScript call that changes, with file, line and replacement, under `v6_migration`.
+3. Switch the Bootstrap assets before changing markup, because the vendored files and `bootstrap:install` are Bootstrap 5. Re-running `bootstrap:layout`, `bootstrap:themed` or a snippet generator writes Bootstrap 5 markup again.
+4. The helpers in "View helpers" render Bootstrap 5 markup at runtime, so the scan can't see their output. Replace them with Bootstrap 6 markup in the views that use them.
+5. v6 changes the spacing scale (`p-3` is smaller), so check spacing utilities by eye; the scan doesn't flag them.
+
 ## Markup to avoid
 
 These come from older Bootstrap versions and do nothing on this one. `bootstrap:doctor` reports them, with file and line, under `legacy_markup`. Plain names like `close` or `well` may be the app's own CSS classes, so check those before changing them.

data/lib/generators/bootstrap/doctor/doctor_generator.rb

@@ -11,9 +11,11 @@ module Bootstrap
 
       class_option :json, :type => :boolean, :default => false,
                    :desc => 'Print the report as JSON'
+      class_option :v6, :type => :boolean, :default => false,
+                   :desc => 'Also list Bootstrap 5 code that changes in Bootstrap 6'
 
       def diagnose
-        report = Twitter::Bootstrap::Rails::Doctor.new(destination_root).report
+        report = Twitter::Bootstrap::Rails::Doctor.new(destination_root).report(:v6 => options[:v6])
 
         options[:json] ? say(JSON.pretty_generate(report)) : print_report(report)
         exit(1) if report[:status] == "error"
@@ -30,7 +32,15 @@ module Bootstrap
           say "         #{' ' * 20} Fix: #{check[:fix]}" if check[:fix]
         end
 
-        report[:legacy_markup].each do |finding|
+        print_findings("Older Bootstrap markup", report[:legacy_markup])
+        print_findings("Changes in Bootstrap 6", report[:v6_migration])
+      end
+
+      def print_findings(title, findings)
+        return if findings.nil? || findings.empty?
+
+        say "\n#{title}:"
+        findings.each do |finding|
           say "  #{finding[:file]}:#{finding[:line]}  #{finding[:found]} -> #{finding[:replacement]}"
         end
       end

data/lib/twitter/bootstrap/rails/doctor.rb

@@ -1,6 +1,7 @@
 require 'twitter/bootstrap/rails/version'
 require 'twitter/bootstrap/rails/config'
 require 'twitter/bootstrap/rails/legacy_markup'
+require 'twitter/bootstrap/rails/v6_migration'
 
 module Twitter
   module Bootstrap
@@ -14,19 +15,27 @@ module Twitter
         SCANNED_EXTENSIONS = %w[.erb .haml .slim .rb].freeze
         PLACEHOLDER_IMAGES = ["bootstrap-docs.png", "bootstrap-themes.png", "/docs/5.3/assets/", "unsplash-photo-"].freeze
         SEVERITY = %w[ok warn error].freeze
+        # What `--v6` scans on top of views and helpers. The gem's own vendored
+        # Bootstrap files are skipped: replacing them is the first migration step.
+        V6_EXTRA_FILES = "app/{javascript,assets/javascripts,assets/stylesheets}/**/*".freeze
+        V6_EXTENSIONS = %w[.js .mjs .ts .css .scss .sass].freeze
+        VENDORED_DIR = %r{/twitter/bootstrap/}
 
         def initialize(root)
           @root = root
         end
 
-        def report
+        # v6: true adds a v6_migration check and list for apps moving to Bootstrap 6.
+        def report(v6: false)
           checks = [css_check, js_check, version_check, sprite_check, placeholder_check, legacy_check]
+          checks << v6_check if v6
 
-          facts.merge(
+          result = facts.merge(
             :status => checks.map { |c| c[:status] }.max_by { |s| SEVERITY.index(s) },
             :checks => checks,
             :legacy_markup => legacy_markup
           )
+          v6 ? result.merge(:v6_migration => v6_migration) : result
         end
 
         def facts
@@ -169,6 +178,28 @@ module Twitter
           end
         end
 
+        def v6_check
+          count = v6_migration.size
+          return check("v6_migration", "ok", "Nothing found that changes in Bootstrap 6.") if count.zero?
+
+          check("v6_migration", "warn",
+                "#{count} use(s) of Bootstrap 5 markup, Sass or JavaScript that change in Bootstrap 6, listed in v6_migration. " \
+                "This gem still ships Bootstrap #{BOOTSTRAP_VERSION}, so only change them as part of moving the app to Bootstrap 6.",
+                "Install the upstream migration skill (`#{V6Migration::SKILL_COMMAND}`) and follow it, " \
+                "or read #{V6Migration::GUIDE_URL}. Switch the Bootstrap assets first.")
+        end
+
+        def v6_migration
+          @v6_migration ||= v6_files.flat_map do |file|
+            V6Migration.scan(read(file), File.extname(file)).map { |finding| { :file => file }.merge(finding) }
+          end
+        end
+
+        def v6_files
+          extra = relative_files(V6_EXTRA_FILES, V6_EXTENSIONS).reject { |file| file.match?(VENDORED_DIR) }
+          (scanned_files + extra).uniq.sort
+        end
+
         def check(id, status, message, fix = nil)
           result = { :id => id, :status => status, :message => message }
           result[:fix] = fix if fix
@@ -187,9 +218,9 @@ module Twitter
           relative_files("app/{views,helpers,components}/**/*")
         end
 
-        def relative_files(pattern)
+        def relative_files(pattern, extensions = SCANNED_EXTENSIONS)
           Dir[File.join(@root, pattern)]
-            .select { |file| File.file?(file) && SCANNED_EXTENSIONS.include?(File.extname(file)) }
+            .select { |file| File.file?(file) && extensions.include?(File.extname(file)) }
             .map { |file| file.delete_prefix("#{@root}/") }
             .sort
         end

data/lib/twitter/bootstrap/rails/v6_migration.rb

@@ -0,0 +1,156 @@
+require 'twitter/bootstrap/rails/legacy_markup'
+
+module Twitter
+  module Bootstrap
+    module Rails
+      # Finds Bootstrap 5 markup, Sass and JavaScript that changes in Bootstrap 6,
+      # following the upstream migration skill
+      # (npx skills add twbs/bootstrap --skill bootstrap-v5-v6-migration).
+      # The gem still ships Bootstrap 5, so this is a worklist for an app that is
+      # moving to 6, not markup to avoid today. `bootstrap:doctor --v6` reports it.
+      module V6Migration
+        SKILL_COMMAND = "npx skills add twbs/bootstrap --skill bootstrap-v5-v6-migration".freeze
+        GUIDE_URL = "https://getbootstrap.com/docs/6.0/guides/migration/".freeze
+
+        BREAKPOINTS = { "sm" => "sm", "md" => "md", "lg" => "lg", "xl" => "xl", "xxl" => "2xl" }.freeze
+        THEMES = %w[primary secondary success danger warning info].freeze
+        FONT_SIZES = { "1" => "4xl", "2" => "3xl", "3" => "2xl", "4" => "xl", "5" => "lg", "6" => "md" }.freeze
+        RENAMED_COMPONENTS = { "modal" => "dialog", "offcanvas" => "drawer", "dropdown" => "menu" }.freeze
+        # Classes that take a breakpoint as a suffix in v5 (navbar-expand-lg).
+        SUFFIXED = %w[container navbar-expand offcanvas table-responsive list-group-horizontal vstack hstack col].freeze
+
+        CLASSES = {
+          "modal" => "dialog on a <dialog> element",
+          "modal-dialog" => "nothing (remove the wrapper; use one <dialog class=\"dialog\">)",
+          "modal-content" => "nothing (remove the wrapper; use one <dialog class=\"dialog\">)",
+          "offcanvas" => "drawer on a <dialog> element",
+          "dropdown" => "nothing (remove the wrapper; the toggle and .menu are siblings)",
+          "dropdown-menu" => "menu",
+          "dropdown-item" => "menu-item",
+          "dropdown-divider" => "menu-divider",
+          "dropdown-header" => "menu-header",
+          "dropdown-toggle" => "nothing (the menu toggle needs no class)",
+          "dropdown-toggle-split" => "nothing (remove it)",
+          "text-muted" => "fg-secondary",
+          "form-select" => "form-control (on the select)",
+          "form-check" => "form-field",
+          "form-check-input" => "check or radio (on the input)",
+          "form-check-label" => "nothing (a plain label)",
+          "form-switch" => "a switch wrapper around the input",
+          "needs-validation" => "data-bs-validate on the form",
+          "was-validated" => "nothing (:user-invalid handles it)",
+          "has-validation" => "nothing (remove it)",
+          "clearfix" => "d-flow-root",
+          "lh-base" => "lh-md",
+          "lead" => "fs-* and fw-* utilities",
+          "placeholder-glow" => "placeholder-pulse (or placeholder-wave)",
+          "btn-close-white" => "nothing (set the text colour instead)",
+          "card-link" => "a plain link",
+          "accordion-button" => "nothing (put the title in summary.accordion-header)",
+          "accordion-collapse" => "nothing (use details.accordion-item)",
+          "navbar-light" => "nothing (remove it)",
+          "navbar-dark" => "nothing (use data-bs-theme=\"dark\")",
+          "carousel-control-prev" => "btn-icon with data-bs-slide=\"prev\"",
+          "carousel-control-next" => "btn-icon with data-bs-slide=\"next\"",
+          "carousel-control-prev-icon" => "carousel-icon-prev",
+          "carousel-control-next-icon" => "carousel-icon-next",
+          "carousel-caption" => "your own markup",
+          "carousel-dark" => "data-bs-theme=\"dark\""
+        }.freeze
+
+        # [pattern, block turning the match into its replacement, example for docs]
+        CLASS_PATTERNS = [
+          [/\Amodal-(header|body|footer|title|sm|lg|xl|fullscreen)\z/, ->(m) { "dialog-#{m[1]}" }, "modal-body becomes dialog-body"],
+          [/\Aoffcanvas-(header|body|title|start|end|top|bottom)\z/, ->(m) { "drawer-#{m[1]}" }, "offcanvas-start becomes drawer-start"],
+          [/\Adropdown-menu-(start|end)\z/, ->(m) { "menu-#{m[1]}" }, "dropdown-menu-end becomes menu-end"],
+          [/\Amodal-fullscreen-(sm|md|lg|xl|xxl)-down\z/,
+           ->(m) { "#{BREAKPOINTS[m[1]]}-down:dialog-fullscreen" }, "modal-fullscreen-sm-down becomes sm-down:dialog-fullscreen"],
+          [/\A([a-z][\w-]*)-hover\z/,
+           ->(m) { "hover:#{V6Migration.class_replacement(m[1])}" }, "opacity-50-hover becomes hover:opacity-50"],
+          [/\Abtn-(outline-)?(#{THEMES.join('|')})\z/,
+           ->(m) { "btn-#{m[1] ? 'outline' : 'solid'} theme-#{m[2]}" }, "btn-primary and btn-outline-primary become btn-solid theme-primary and btn-outline theme-primary"],
+          [/\Aalert-(#{THEMES.join('|')})\z/, ->(m) { "alert theme-#{m[1]}" }, "alert-info becomes alert theme-info"],
+          [/\Atext-bg-(#{THEMES.join('|')})\z/, ->(m) { "bg-#{m[1]} fg-contrast-#{m[1]}" }, "text-bg-warning becomes bg-warning fg-contrast-warning"],
+          [/\Atext-(#{THEMES.join('|')})\z/, ->(m) { "fg-#{m[1]}" }, "text-danger becomes fg-danger"],
+          [/\A(?:btn|btn-outline|alert|text|text-bg)-(light|dark)\z/,
+           ->(_) { "a neutral surface, a colour mode or theme-inverse (v6 has no theme-light or theme-dark)" },
+           "btn-light and text-dark become a neutral surface, a colour mode or theme-inverse"],
+          [/\Afs-([1-6])\z/, ->(m) { "fs-#{FONT_SIZES[m[1]]}" }, "fs-1 and fs-6 become fs-4xl and fs-md"],
+          [/\Adisplay-[1-6]\z/, ->(_) { "fs-* and fw-* utilities" }, "display-1 becomes fs-* and fw-* utilities"],
+          [/\Am(h|w)-(.+)\z/, ->(m) { "max-#{m[1]}-#{m[2]}" }, "mw-100 becomes max-w-100"],
+          [/\Alink-(offset|underline)(-.+)?\z/,
+           ->(m) { "underline#{m[1] == 'offset' ? '-offset' : ''}#{m[2]}" }, "link-offset-2 becomes underline-offset-2"],
+          [/\Am[tbsexy]?-n\d\z/, ->(_) { "ms--1, ms--2, me--1, me--2 or your own style" }, "mt-n1 becomes ms--1 / me--1 or your own style"],
+          [/\A(#{SUFFIXED.join('|')})-(sm|md|lg|xl|xxl)\z/,
+           ->(m) { "#{BREAKPOINTS[m[2]]}:#{V6Migration.class_replacement(m[1])}" }, "navbar-expand-lg becomes lg:navbar-expand"],
+          [/\A([a-z][\w-]*?)-print-([\w-]+)\z/,
+           ->(m) { "print:#{V6Migration.class_replacement("#{m[1]}-#{m[2]}")}" }, "d-print-none becomes print:d-none"],
+          [/\A([a-z][\w-]*?)-(sm|md|lg|xl|xxl)-([\w-]+)\z/,
+           ->(m) { "#{BREAKPOINTS[m[2]]}:#{V6Migration.class_replacement("#{m[1]}-#{m[3]}")}" },
+           "col-md-6 and d-xxl-none become md:col-6 and 2xl:d-none"]
+        ].freeze
+
+        TOGGLE = /(?:data-bs-|\bbs[_-])(toggle|dismiss)["']?\s*(?:=>|=|:)\s*(["'])(#{RENAMED_COMPONENTS.keys.join('|')})\2/
+
+        # [pattern, replacement, example for docs]. Applied to every scanned file.
+        LINE_PATTERNS = [
+          [/(?:data-bs-|\bbs[_-])ride(?![\w-])/, %{data-bs-autoplay="true" (carousels no longer start on their own)}],
+          [/@import\s+(["'])bootstrap/, %{@use "bootstrap/scss/bootstrap" (add `as *` to keep v5 names)}],
+          [/\bbootstrap\.(?:Modal|Offcanvas|Dropdown)\b/, "import { Dialog, Drawer, Menu } from Bootstrap's module build"],
+          [/\bpopperConfig\b/, "floatingConfig"],
+          [/@popperjs\/core/, "@floating-ui/dom"],
+          [/--bs-[\w-]+-rgb\b/, "color-mix(in oklab, var(--bs-…), transparent N%)"]
+        ].freeze
+
+        # Files whose class attributes and shorthand are read for class names.
+        MARKUP_EXTENSIONS = %w[.erb .haml .slim .rb .html].freeze
+
+        module_function
+
+        # Returns [{ :line, :found, :replacement }, ...] for a file's contents.
+        def scan(text, extension)
+          text.each_line.with_index(1).flat_map do |line, number|
+            scan_line(line, extension).map { |found, replacement| { :line => number, :found => found, :replacement => replacement } }
+          end
+        end
+
+        def scan_line(line, extension)
+          classes = MARKUP_EXTENSIONS.include?(extension) ? LegacyMarkup.class_names(line, extension) : []
+          renamed = classes.filter_map do |name|
+            replacement = replacement_for(name)
+            [name, replacement] if replacement
+          end
+
+          toggles = line.scan(TOGGLE).map do |attribute, _quote, value|
+            [%{data-bs-#{attribute}="#{value}"}, %{data-bs-#{attribute}="#{RENAMED_COMPONENTS[value]}"}]
+          end
+
+          other = LINE_PATTERNS.flat_map do |pattern, replacement|
+            matches = []
+            line.scan(pattern) { matches << [Regexp.last_match(0).sub(/\Abs[_-]/, "data-bs-"), replacement] }
+            matches
+          end
+
+          renamed + toggles + other
+        end
+
+        def replacement_for(name)
+          return CLASSES[name] if CLASSES.key?(name)
+
+          CLASS_PATTERNS.each do |pattern, replacement, _example|
+            match = pattern.match(name)
+            return replacement.call(match) if match
+          end
+          nil
+        end
+
+        # The v6 name for a class when it is a plain rename, otherwise the class itself.
+        # Used under a breakpoint prefix, where a sentence would make no sense.
+        def class_replacement(name)
+          replacement = RENAMED_COMPONENTS[name] || replacement_for(name)
+          replacement && replacement.match?(/\A[\w:-]+\z/) ? replacement : name
+        end
+      end
+    end
+  end
+end

data/lib/twitter/bootstrap/rails/version.rb

@@ -1,7 +1,7 @@
 module Twitter
   module Bootstrap
     module Rails
-      VERSION = "5.5.0"
+      VERSION = "5.5.1"
 
       # The Bootstrap release this gem vendors and links to. The gem version no
       # longer tracks it; this constant is the authoritative statement.

data/spec/lib/generators/agent_generator_spec.rb

@@ -107,5 +107,14 @@ describe Bootstrap::Generators::AgentGenerator do
 
       expect(skill).to include("rails g bootstrap:doctor --json")
     end
+
+    it "keeps agents on the shipped Bootstrap and points them at the upstream skill for Bootstrap 6" do
+      run_generator(described_class)
+      section = skill[/^## Bootstrap 6\n.*?(?=^## |\z)/m]
+
+      expect(section).to include("Don't write Bootstrap 6 markup")
+      expect(section).to include(Twitter::Bootstrap::Rails::V6Migration::SKILL_COMMAND)
+      expect(section).to include("rails g bootstrap:doctor --v6 --json")
+    end
   end
 end

data/spec/lib/generators/doctor_generator_spec.rb

@@ -166,6 +166,55 @@ describe Bootstrap::Generators::DoctorGenerator do
     end
   end
 
+  describe "Bootstrap 6 migration" do
+    def v6_report
+      rails_mod::Doctor.new(destination_root).report(:v6 => true)
+    end
+
+    it "is left out unless asked for" do
+      write_destination("app/views/tasks/index.html.erb", %{<div class="modal-body"></div>})
+
+      expect(report).not_to have_key(:v6_migration)
+      expect(report[:checks].map { |c| c[:id] }).not_to include("v6_migration")
+    end
+
+    it "lists what changes in Bootstrap 6, with the location" do
+      write_destination("app/views/tasks/index.html.erb", %{<p>ok</p>\n<button data-bs-toggle="modal" class="btn btn-primary">x</button>})
+
+      expect(v6_report[:v6_migration]).to contain_exactly(
+        a_hash_including(:file => "app/views/tasks/index.html.erb", :line => 2, :found => "btn-primary"),
+        a_hash_including(:file => "app/views/tasks/index.html.erb", :line => 2, :found => %{data-bs-toggle="modal"})
+      )
+      check = v6_report[:checks].find { |c| c[:id] == "v6_migration" }
+      expect(check).to include(:status => "warn", :fix => a_string_including("bootstrap-v5-v6-migration"))
+    end
+
+    it "scans the app's JavaScript and stylesheets" do
+      write_destination("app/javascript/controllers/menu_controller.js", "new bootstrap.Dropdown(this.element)")
+      write_destination("app/assets/stylesheets/custom.scss", %{@import "bootstrap/scss/functions";})
+
+      expect(v6_report[:v6_migration].map { |f| f[:file] })
+        .to eq(%w[app/assets/stylesheets/custom.scss app/javascript/controllers/menu_controller.js])
+    end
+
+    it "skips the Bootstrap files the gem vendored" do
+      install_static_on_propshaft
+      layout_findings = v6_report[:v6_migration].reject { |f| f[:file].start_with?("app/views/") }
+
+      expect(layout_findings).to be_empty
+    end
+
+    it "finds the Bootstrap 5 markup in a layout the generators wrote" do
+      install_static_on_propshaft
+
+      expect(v6_report[:v6_migration].map { |f| f[:found] }).to include("navbar-expand-lg")
+    end
+
+    it "is happy when nothing needs to change" do
+      expect(v6_report[:checks].find { |c| c[:id] == "v6_migration" }[:status]).to eq("ok")
+    end
+  end
+
   describe "facts" do
     it "states the versions and template engine" do
       expect(report).to include(
@@ -207,6 +256,13 @@ describe Bootstrap::Generators::DoctorGenerator do
         .to raise_error(SystemExit) { |e| expect(e.status).to eq(1) }
     end
 
+    it "adds the Bootstrap 6 worklist with --v6" do
+      parsed = JSON.parse(run_generator(described_class, %w[--v6 --json]))
+
+      expect(parsed["v6_migration"]).to include(a_hash_including("found" => "navbar-expand-lg", "replacement" => "lg:navbar-expand"))
+      expect(run_generator(described_class, %w[--v6])).to match(%r{\[warn\]\s+v6_migration.*\n(.*\n)*\s+app/views/layouts/application\.html\.erb:\d+\s+navbar-expand-lg -> lg:navbar-expand})
+    end
+
     it "exits normally on warnings" do
       write_destination("app/views/tasks/index.html.erb", %{<a class="btn-default"></a>})
 

data/spec/lib/twitter_bootstrap_rails/v6_migration_spec.rb

@@ -0,0 +1,98 @@
+require 'spec_helper'
+require 'twitter/bootstrap/rails/v6_migration'
+
+describe Twitter::Bootstrap::Rails::V6Migration do
+  def scan(text, extension = ".erb")
+    described_class.scan(text, extension)
+  end
+
+  def found(text, extension = ".erb")
+    scan(text, extension).map { |f| f[:found] }
+  end
+
+  def replacements(text, extension = ".erb")
+    scan(text, extension).map { |f| f[:replacement] }
+  end
+
+  it "reports the line and the replacement" do
+    finding = scan(%{<p>ok</p>\n<div class="modal-body">x</div>}).first
+
+    expect(finding).to include(:line => 2, :found => "modal-body", :replacement => "dialog-body")
+  end
+
+  it "renames modal, offcanvas and dropdown classes" do
+    expect(replacements(%{<div class="offcanvas offcanvas-start dropdown-menu dropdown-item"></div>}))
+      .to eq(["drawer on a <dialog> element", "drawer-start", "menu", "menu-item"])
+  end
+
+  it "renames components under a breakpoint prefix" do
+    expect(replacements(%{<div class="offcanvas-lg dropdown-menu-md-end"></div>})).to eq(%w[lg:drawer md:menu-end])
+  end
+
+  it "moves breakpoints to a prefix" do
+    expect(replacements(%{<div class="col-md-6 d-lg-none p-sm-3 offset-xxl-2 sticky-md-top"></div>}))
+      .to eq(%w[md:col-6 lg:d-none sm:p-3 2xl:offset-2 md:sticky-top])
+  end
+
+  it "moves breakpoint suffixes to a prefix" do
+    expect(replacements(%{<nav class="navbar navbar-expand-lg"><div class="container-xxl table-responsive-sm"></div></nav>}))
+      .to eq(%w[lg:navbar-expand 2xl:container sm:table-responsive])
+  end
+
+  it "moves hover and print states to a prefix" do
+    expect(replacements(%{<a class="opacity-50-hover link-underline-opacity-75-hover d-print-none"></a>}))
+      .to eq(%w[hover:opacity-50 hover:underline-opacity-75 print:d-none])
+  end
+
+  it "replaces colour variants with theme classes" do
+    expect(replacements(%{<a class="btn btn-primary btn-outline-danger alert-info text-muted text-success"></a>}))
+      .to eq(["btn-solid theme-primary", "btn-outline theme-danger", "alert theme-info", "fg-secondary", "fg-success"])
+  end
+
+  it "maps font sizes to the t-shirt scale" do
+    expect(replacements(%{<p class="fs-1 fs-6"></p>})).to eq(%w[fs-4xl fs-md])
+  end
+
+  it "finds renamed toggle values in HTML and Ruby" do
+    expect(replacements(%{<button data-bs-toggle="modal" data-bs-dismiss='offcanvas'></button>}))
+      .to eq([%{data-bs-toggle="dialog"}, %{data-bs-dismiss="drawer"}])
+    expect(replacements(%{<%= link_to "x", "#", data: { bs_toggle: "dropdown" } %>}))
+      .to eq([%{data-bs-toggle="menu"}])
+    expect(replacements(%{<%= button_tag "x", data: { "bs-dismiss" => "modal" } %>}))
+      .to eq([%{data-bs-dismiss="dialog"}])
+  end
+
+  it "finds carousel autoplay" do
+    expect(found(%{<div class="carousel" data-bs-ride="carousel"></div>})).to eq(%w[data-bs-ride])
+  end
+
+  it "finds Sass and JavaScript that changed" do
+    expect(found(%{@import "bootstrap/scss/bootstrap";}, ".scss")).to eq([%{@import "bootstrap}])
+    expect(found("new bootstrap.Modal(el, { popperConfig: {} })", ".js")).to eq(%w[bootstrap.Modal popperConfig])
+    expect(found("color: rgba(var(--bs-primary-rgb), .5);", ".css")).to eq(%w[--bs-primary-rgb])
+  end
+
+  it "only reads class names in markup and Ruby files" do
+    expect(found(%{const html = '<div class="modal-body">'}, ".js")).to be_empty
+  end
+
+  it "finds class shorthand in Haml and Slim" do
+    expect(found("%button.btn.btn-primary Save", ".haml")).to eq(%w[btn-primary])
+    expect(found(".modal-dialog\n  .modal-content", ".slim")).to eq(%w[modal-dialog modal-content])
+  end
+
+  it "leaves Bootstrap 6 markup alone" do
+    v6 = %{<dialog class="dialog"><div class="dialog-body md:col-6 btn-solid theme-primary fg-secondary fs-4xl"></div></dialog>}
+
+    expect(found(v6)).to be_empty
+    expect(found(%{<button data-bs-toggle="dialog"></button>})).to be_empty
+  end
+
+  it "matches whole class names only" do
+    expect(found(%{<div class="my-modal modal-bodywork"></div>})).to be_empty
+  end
+
+  it "has an example for every pattern, for the agent guide" do
+    expect(described_class::CLASS_PATTERNS.map(&:last)).to all(match(/ becomes? /))
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: twitter-bootstrap-rails
 version: !ruby/object:Gem::Version
-  version: 5.5.0
+  version: 5.5.1
 platform: ruby
 authors:
 - Seyhun Akyurek
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-11-06 00:00:00.000000000 Z
+date: 2026-11-09 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: railties
@@ -196,6 +196,7 @@ files:
 - lib/twitter/bootstrap/rails/doctor.rb
 - lib/twitter/bootstrap/rails/engine.rb
 - lib/twitter/bootstrap/rails/legacy_markup.rb
+- lib/twitter/bootstrap/rails/v6_migration.rb
 - lib/twitter/bootstrap/rails/version.rb
 - spec/lib/breadcrumbs_spec.rb
 - spec/lib/generators/agent_generator_spec.rb
@@ -215,6 +216,7 @@ files:
 - spec/lib/twitter_bootstrap_rails/modal_helper_spec.rb
 - spec/lib/twitter_bootstrap_rails/navbar_helper_spec.rb
 - spec/lib/twitter_bootstrap_rails/uri_state_spec.rb
+- spec/lib/twitter_bootstrap_rails/v6_migration_spec.rb
 - spec/spec_helper.rb
 - spec/support/generator_spec_helper.rb
 - vendor/assets/javascripts/twitter/bootstrap/bootstrap.bundle.min.js
@@ -261,5 +263,6 @@ test_files:
 - spec/lib/twitter_bootstrap_rails/modal_helper_spec.rb
 - spec/lib/twitter_bootstrap_rails/navbar_helper_spec.rb
 - spec/lib/twitter_bootstrap_rails/uri_state_spec.rb
+- spec/lib/twitter_bootstrap_rails/v6_migration_spec.rb
 - spec/spec_helper.rb
 - spec/support/generator_spec_helper.rb