stimulus_plumbers 0.4.8 → 0.4.9

data/lib/stimulus_plumbers/components/progress_ring.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module StimulusPlumbers
+  module Components
+    class ProgressRing < Plumber::Base
+      def render(...) = render_ring(...)
+
+      private
+
+      def render_ring(value:, max: 100, min: 0, indeterminate: false, **kwargs)
+        icon_options = merge_html_options(
+          theme.resolve(:progress_ring),
+          kwargs,
+          stimulus_data(value: value, min: min, max: max, indeterminate: indeterminate),
+          { role: "progressbar", aria: progress_aria(value: value, min: min, max: max, indeterminate: indeterminate) }
+        )
+        Components::Icon.new(template).render(name: "progress-ring", **icon_options)
+      end
+
+      def progress_aria(value:, min:, max:, indeterminate:)
+        aria = { valuemin: min, valuemax: max }
+        aria[:valuenow] = value unless indeterminate
+        aria
+      end
+
+      def stimulus_data(value:, min:, max:, indeterminate:)
+        {
+          data: {
+            controller:                     "progress",
+            "progress-variant-value":       "ring",
+            "progress-current-value":       value,
+            "progress-min-value":           min,
+            "progress-max-value":           max,
+            "progress-indeterminate-value": indeterminate
+          }
+        }
+      end
+    end
+  end
+end

data/lib/stimulus_plumbers/components/timeline/event.rb

@@ -107,11 +107,12 @@ module StimulusPlumbers
           if type == :icon && icon_name
             Components::Icon.new(template).render(
               name:    icon_name,
+              size:    :sm,
               classes: theme.resolve(:timeline_item_indicator_icon_slot).fetch(:classes, ""),
               aria:    { hidden: "true" }
             )
           else
-            template.content_tag(:span, nil, **merge_html_options(theme.resolve(:timeline_item_indicator_dot)))
+            Components::Indicator.new(template).render(type: :dot, variant: :primary)
           end
         end
 

data/lib/stimulus_plumbers/components/timeline/group.rb

@@ -4,7 +4,8 @@ module StimulusPlumbers
   module Components
     class Timeline
       class Group < Plumber::Base
-        def render(**kwargs, &block)
+        def render(orientation: :vertical, **kwargs, &block)
+          @orientation = orientation
           content = template.capture(self, &block)
           html_options = merge_html_options(theme.resolve(:timeline_group), kwargs)
           template.content_tag(:div, content, **html_options)
@@ -12,7 +13,7 @@ module StimulusPlumbers
 
         def section(date:, datetime: nil, **kwargs, &block)
           inner_tl = Timeline.new(template)
-          inner_tl.instance_variable_set(:@orientation, :vertical)
+          inner_tl.instance_variable_set(:@orientation, @orientation)
           inner_tl.instance_variable_set(:@interactive, false)
 
           events_html  = template.capture(inner_tl, &block)
@@ -29,10 +30,11 @@ module StimulusPlumbers
             theme.resolve(:timeline_group_section_date),
             datetime ? { datetime: datetime } : {}
           )
+          list_attrs = merge_html_options(theme.resolve(:timeline_group_section_list, orientation: @orientation))
           template.safe_join(
             [
               template.content_tag(:time, date, **date_attrs),
-              template.content_tag(:ol, events_html, **merge_html_options(theme.resolve(:timeline_group_section_list)))
+              template.content_tag(:ol, events_html, **list_attrs)
             ]
           )
         end

data/lib/stimulus_plumbers/form/fields/inputs/password.rb

@@ -51,6 +51,7 @@ module StimulusPlumbers
             build_reveal_button do
               Components::Icon.new(@template).render(
                 name: "reveal",
+                size: :sm,
                 aria: { hidden: "true" },
                 **theme.resolve(:button_icon)
               )

data/lib/stimulus_plumbers/form/fields/inputs/search.rb

@@ -83,6 +83,7 @@ module StimulusPlumbers
             build_clear_button do
               Components::Icon.new(@template).render(
                 name: "close",
+                size: :sm,
                 aria: { hidden: "true" },
                 **theme.resolve(:button_icon)
               )

data/lib/stimulus_plumbers/generators/css_entrypoint.rb

@@ -3,13 +3,21 @@
 module StimulusPlumbers
   module Generators
     module CssEntrypoint
-      STIMULUS_PLUMBERS_CSS_FILE = "STIMULUS_PLUMBERS_CSS_FILE"
+      STIMULUS_PLUMBERS_CSS_ENTRY = "STIMULUS_PLUMBERS_CSS_ENTRY"
 
-      def entry_css_file(candidates:, env_var:, fallback_env_var: nil)
-        [env_var, fallback_env_var].compact.each do |var|
-          next unless ENV[var]
+      # Shared with stimulus_plumbers_tailwind's InstallGenerator — checked in order,
+      # each path is another gem/tool's own default entry file. Detection is theme-
+      # agnostic: any of these may be the CSS entry regardless of which theme is active.
+      ENTRY_CANDIDATES = [
+        "app/assets/stylesheets/application.tailwind.css", # tailwindcss-rails 2.x default
+        "app/assets/tailwind/application.css",             # tailwindcss-rails 3.x+ default
+        "app/assets/stylesheets/application.css",          # Rails/Propshaft default manifest
+        "app/javascript/entrypoints/application.css"       # jsbundling-rails (esbuild/webpack) default
+      ].freeze
 
-          path = File.expand_path(ENV.fetch(var, nil))
+      def entry_css_file(candidates:, env_var:)
+        if ENV[env_var]
+          path = File.expand_path(ENV.fetch(env_var, nil))
           return path if File.exist?(path)
         end
 
@@ -18,11 +26,9 @@ module StimulusPlumbers
           .find { |f| File.exist?(f) }
       end
 
-      def warn_entry_css_not_found(candidates:, env_var:, label:, fallback_env_var: nil)
+      def warn_entry_css_not_found(candidates:, env_var:, label:)
         tried = candidates.map { |c| File.join(destination_root, c) }
-        [env_var, fallback_env_var].compact.each do |var|
-          tried.unshift(File.expand_path(ENV[var])) if ENV[var]
-        end
+        tried.unshift(File.expand_path(ENV[env_var])) if ENV[env_var]
         say "Could not find a #{label} entry file. Tried: #{tried.join(", ")}. " \
             "Set #{env_var}=/path/to/entry.css and re-run.",
             :red

data/lib/stimulus_plumbers/generators/tokens_directive.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "pathname"
+
 module StimulusPlumbers
   module Generators
     module TokensDirective
@@ -8,8 +10,10 @@ module StimulusPlumbers
 
       module_function
 
-      def directive
-        %(@import "#{GEM_ROOT}/#{TOKENS_CSS_REL_PATH}";)
+      def directive(from:)
+        path = Pathname.new(GEM_ROOT).join(TOKENS_CSS_REL_PATH)
+        rel  = path.relative_path_from(Pathname.new(from))
+        %(@import "#{rel}";)
       end
 
       def stale_pattern

data/lib/stimulus_plumbers/helpers/avatar_helper.rb

@@ -4,13 +4,7 @@ module StimulusPlumbers
   module Helpers
     module AvatarHelper
       def sp_avatar(...)
-        avatar_renderer.render(...)
-      end
-
-      private
-
-      def avatar_renderer
-        Components::Avatar.new(self)
+        Components::Avatar.new(self).render(...)
       end
     end
   end

data/lib/stimulus_plumbers/helpers/button_helper.rb

@@ -4,18 +4,12 @@ module StimulusPlumbers
   module Helpers
     module ButtonHelper
       def sp_button(content = nil, **kwargs, &block)
-        button_renderer.render(content, **kwargs, &block)
+        Components::Button.new(self).render(content, **kwargs, &block)
       end
 
       def sp_button_group(...)
         Components::Button::Group.new(self).render(...)
       end
-
-      private
-
-      def button_renderer
-        Components::Button.new(self)
-      end
     end
   end
 end

data/lib/stimulus_plumbers/helpers/calendar_helper.rb

@@ -9,20 +9,13 @@ module StimulusPlumbers
                          kwargs.deep_merge(
                            data: {
                              "calendar-month-year-value":  date.year,
-                             "calendar-month-month-value": date.month - 1,
-                             "calendar-month-day-value":   date.day
+                             "calendar-month-month-value": date.month - 1
                            }
                          )
                        else
                          kwargs
                        end
-        calendar_renderer.month(**html_options)
-      end
-
-      private
-
-      def calendar_renderer
-        Components::Calendar.new(self)
+        Components::Calendar.new(self).month(**html_options)
       end
     end
   end

data/lib/stimulus_plumbers/helpers/calendar_turbo_helper.rb

@@ -31,8 +31,7 @@ module StimulusPlumbers
           [
             content_tag(
               :turbo_frame,
-              id:   "calendar-month-frame",
-              data: { "combobox-date-target": "monthView" }
+              id: "calendar-month-frame"
             ) do
               calendar_turbo_renderer.month(
                 date:              date,
@@ -48,8 +47,7 @@ module StimulusPlumbers
             content_tag(
               :turbo_frame,
               id:     "calendar-year-frame",
-              hidden: true,
-              data:   { "combobox-date-target": "yearView" }
+              hidden: true
             ) do
               calendar_turbo_renderer.year(
                 date:            date,
@@ -63,8 +61,7 @@ module StimulusPlumbers
             content_tag(
               :turbo_frame,
               id:     "calendar-decade-frame",
-              hidden: true,
-              data:   { "combobox-date-target": "decadeView" }
+              hidden: true
             ) do
               calendar_turbo_renderer.decade(
                 date:           date,

data/lib/stimulus_plumbers/helpers/checklist_helper.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module StimulusPlumbers
+  module Helpers
+    module ChecklistHelper
+      def sp_checklist(...)
+        Components::Checklist.new(self).render(...)
+      end
+    end
+  end
+end

data/lib/stimulus_plumbers/helpers/indicator_helper.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module StimulusPlumbers
+  module Helpers
+    module IndicatorHelper
+      def sp_indicator(variant: :primary, type: :dot, pulse: false, **kwargs, &block)
+        Components::Indicator.new(self).render(type: type, variant: variant, pulse: pulse, **kwargs, &block)
+      end
+    end
+  end
+end

data/lib/stimulus_plumbers/helpers/ordered_list_helper.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module StimulusPlumbers
+  module Helpers
+    module OrderedListHelper
+      def sp_ordered_list(...)
+        Components::OrderedList.new(self).render(...)
+      end
+    end
+  end
+end

data/lib/stimulus_plumbers/helpers/popover_helper.rb

@@ -4,13 +4,7 @@ module StimulusPlumbers
   module Helpers
     module PopoverHelper
       def sp_popover(...)
-        popover_renderer.render(...)
-      end
-
-      private
-
-      def popover_renderer
-        Components::Popover.new(self)
+        Components::Popover.new(self).render(...)
       end
     end
   end

data/lib/stimulus_plumbers/helpers/progress_helper.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module StimulusPlumbers
+  module Helpers
+    module ProgressHelper
+      def sp_progress_bar(value:, min: 0, max: 100, indeterminate: false, **kwargs)
+        Components::ProgressBar.new(self).render(value: value, min: min, max: max, indeterminate: indeterminate, **kwargs)
+      end
+
+      def sp_progress_ring(value:, min: 0, max: 100, indeterminate: false, **kwargs)
+        Components::ProgressRing.new(self).render(value: value, min: min, max: max, indeterminate: indeterminate, **kwargs)
+      end
+
+      def sp_progress_meter(value:, min: 0, max: 100, low: nil, high: nil, optimum: nil, **kwargs)
+        Components::ProgressMeter.new(self).render(
+          value: value, min: min, max: max, low: low, high: high, optimum: optimum, **kwargs
+        )
+      end
+    end
+  end
+end

data/lib/stimulus_plumbers/helpers.rb

@@ -2,7 +2,10 @@
 
 require_relative "helpers/plumber_helper"
 require_relative "helpers/icon_helper"
+require_relative "helpers/indicator_helper"
 require_relative "helpers/list_helper"
+require_relative "helpers/checklist_helper"
+require_relative "helpers/ordered_list_helper"
 require_relative "helpers/avatar_helper"
 require_relative "helpers/button_helper"
 require_relative "helpers/calendar_helper"
@@ -12,13 +15,17 @@ require_relative "helpers/combobox_helper"
 require_relative "helpers/divider_helper"
 require_relative "helpers/link_helper"
 require_relative "helpers/popover_helper"
+require_relative "helpers/progress_helper"
 require_relative "helpers/timeline_helper"
 
 module StimulusPlumbers
   module Helpers
     include PlumberHelper
     include IconHelper
+    include IndicatorHelper
     include ListHelper
+    include ChecklistHelper
+    include OrderedListHelper
     include AvatarHelper
     include ButtonHelper
     include CalendarHelper
@@ -28,6 +35,7 @@ module StimulusPlumbers
     include DividerHelper
     include LinkHelper
     include PopoverHelper
+    include ProgressHelper
     include TimelineHelper
   end
 end

data/lib/stimulus_plumbers/themes/base.rb

@@ -8,6 +8,8 @@ module StimulusPlumbers
     class Base
       SCHEMA = {
         **Schema::LIST,
+        **Schema::CHECKLIST,
+        **Schema::ORDERED_LIST,
         **Schema::AVATAR,
         **Schema::BUTTON,
         **Schema::CALENDAR,
@@ -15,9 +17,11 @@ module StimulusPlumbers
         **Schema::COMBOBOX,
         **Schema::FORM,
         **Schema::ICON,
+        **Schema::INDICATOR,
         **Schema::INPUT_GROUP,
         **Schema::LAYOUT,
         **Schema::LINK,
+        **Schema::PROGRESS,
         **Schema::TIMELINE
       }.freeze
 

data/lib/stimulus_plumbers/themes/schema/icon.rb

@@ -23,7 +23,7 @@ module StimulusPlumbers
 
         ELEMENT_ATTRS = {
           path:     %i[d fill fill_rule clip_rule stroke_linecap stroke_linejoin opacity].freeze,
-          circle:   %i[cx cy r].freeze,
+          circle:   %i[cx cy r class stroke stroke_width stroke_linecap].freeze,
           ellipse:  %i[cx cy rx ry].freeze,
           rect:     %i[x y width height rx ry].freeze,
           line:     %i[x1 y1 x2 y2].freeze,
@@ -64,9 +64,26 @@ module StimulusPlumbers
         end
 
         def resolve_element_attrs(element_data)
-          element_data.slice(*ELEMENT_ATTRS[element_data[:tag]])
-                      .transform_keys { |key| ELEMENT_ATTR_NAMES.fetch(key, key.to_s) }
-                      .transform_values(&:to_s)
+          element_data.filter_map do |key, value|
+            next if key == :tag
+            next unless element_attr_allowed?(element_data[:tag], key)
+
+            [element_attr_name(key), value.to_s]
+          end.to_h
+        end
+
+        def element_attr_allowed?(tag, key)
+          ELEMENT_ATTRS.fetch(tag, []).include?(key) || data_or_aria_attr?(key)
+        end
+
+        def element_attr_name(key)
+          return key.to_s.tr("_", "-") if data_or_aria_attr?(key)
+
+          ELEMENT_ATTR_NAMES.fetch(key, key.to_s)
+        end
+
+        def data_or_aria_attr?(key)
+          key.to_s.start_with?("data_", "aria_")
         end
       end
     end

data/lib/stimulus_plumbers/themes/schema/indicator/ranges.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module StimulusPlumbers
+  module Themes
+    module Schema
+      module Indicator
+        module Ranges
+          TYPE    = %i[dot pulse badge].freeze
+          VARIANT = %i[primary secondary tertiary success destructive warning info].freeze
+        end
+      end
+    end
+  end
+end

data/lib/stimulus_plumbers/themes/schema.rb

@@ -5,6 +5,7 @@ require_relative "schema/ranges"
 require_relative "schema/avatar/ranges"
 require_relative "schema/button/ranges"
 require_relative "schema/card/ranges"
+require_relative "schema/indicator/ranges"
 require_relative "schema/link/ranges"
 require_relative "schema/form/ranges"
 require_relative "schema/form/checkbox/ranges"
@@ -27,6 +28,24 @@ module StimulusPlumbers
         list_item_description:    {}.freeze
       }.freeze
 
+      CHECKLIST = {
+        checklist:                  {}.freeze,
+        checklist_item:             {}.freeze,
+        checklist_item_input:       {}.freeze,
+        checklist_item_content:     {}.freeze,
+        checklist_item_title:       {}.freeze,
+        checklist_item_description: {}.freeze
+      }.freeze
+
+      ORDERED_LIST = {
+        ordered_list:                  {}.freeze,
+        ordered_list_item:             {}.freeze,
+        ordered_list_item_handle:      {}.freeze,
+        ordered_list_item_content:     {}.freeze,
+        ordered_list_item_title:       {}.freeze,
+        ordered_list_item_description: {}.freeze
+      }.freeze
+
       AVATAR = {
         avatar:       {
           size:    { default: :md, validate: Avatar::Ranges::SIZE },
@@ -169,7 +188,16 @@ module StimulusPlumbers
       }.freeze
 
       ICON = {
-        icon: {}.freeze
+        icon: { size: { default: :lg, validate: %i[sm md lg] } }.freeze
+      }.freeze
+
+      INDICATOR = {
+        indicator:         {
+          type:    { default: :dot,     validate: Indicator::Ranges::TYPE },
+          variant: { default: :primary, validate: Indicator::Ranges::VARIANT }
+        }.freeze,
+        indicator_wrapper: {}.freeze,
+        indicator_pulse:   {}.freeze
       }.freeze
 
       INPUT_GROUP = {
@@ -196,6 +224,13 @@ module StimulusPlumbers
         popover:           {}.freeze
       }.freeze
 
+      PROGRESS = {
+        progress_bar:      {}.freeze,
+        progress_bar_fill: {}.freeze,
+        progress_ring:     {}.freeze,
+        progress_meter:    {}.freeze
+      }.freeze
+
       TIMELINE = {
         timeline:                          {
           orientation: { default: :vertical, validate: %i[vertical horizontal] }
@@ -216,7 +251,6 @@ module StimulusPlumbers
         timeline_item_description:         {}.freeze,
         timeline_item_detail:              {}.freeze,
         timeline_item_actions:             {}.freeze,
-        timeline_item_indicator_dot:       {}.freeze,
         timeline_item_connector:           {}.freeze,
         timeline_item_content:             {}.freeze,
         timeline_track_line:               {}.freeze,
@@ -224,7 +258,9 @@ module StimulusPlumbers
         timeline_group:                    {}.freeze,
         timeline_group_section:            {}.freeze,
         timeline_group_section_date:       {}.freeze,
-        timeline_group_section_list:       {}.freeze
+        timeline_group_section_list:       {
+          orientation: { default: :vertical, validate: %i[vertical horizontal] }
+        }.freeze
       }.freeze
     end
   end

data/lib/stimulus_plumbers/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module StimulusPlumbers
-  VERSION = "0.4.8"
+  VERSION = "0.4.9"
 end

data/lib/stimulus_plumbers.rb

@@ -17,6 +17,7 @@ require_relative "stimulus_plumbers/plumber/base"
 
 # -- UI components --
 require_relative "stimulus_plumbers/components/icon"
+require_relative "stimulus_plumbers/components/indicator"
 require_relative "stimulus_plumbers/components/avatar"
 require_relative "stimulus_plumbers/components/button"
 require_relative "stimulus_plumbers/components/button/slots"
@@ -25,10 +26,16 @@ require_relative "stimulus_plumbers/components/link"
 require_relative "stimulus_plumbers/components/link/slots"
 require_relative "stimulus_plumbers/components/card"
 require_relative "stimulus_plumbers/components/card/slots"
+require_relative "stimulus_plumbers/components/checklist"
+require_relative "stimulus_plumbers/components/checklist/item"
+require_relative "stimulus_plumbers/components/checklist/item/slots"
 require_relative "stimulus_plumbers/components/list"
 require_relative "stimulus_plumbers/components/list/section"
 require_relative "stimulus_plumbers/components/list/item"
 require_relative "stimulus_plumbers/components/list/item/slots"
+require_relative "stimulus_plumbers/components/ordered_list"
+require_relative "stimulus_plumbers/components/ordered_list/item"
+require_relative "stimulus_plumbers/components/ordered_list/item/slots"
 require_relative "stimulus_plumbers/components/timeline"
 require_relative "stimulus_plumbers/components/timeline/event"
 require_relative "stimulus_plumbers/components/timeline/event/slots"
@@ -38,6 +45,9 @@ require_relative "stimulus_plumbers/components/input_group"
 require_relative "stimulus_plumbers/components/popover"
 require_relative "stimulus_plumbers/components/popover/trigger"
 require_relative "stimulus_plumbers/components/popover/panel"
+require_relative "stimulus_plumbers/components/progress_bar"
+require_relative "stimulus_plumbers/components/progress_ring"
+require_relative "stimulus_plumbers/components/progress_meter"
 
 # -- Calendar --
 require_relative "stimulus_plumbers/components/calendar"

data/vendor/ARIA.md

@@ -30,6 +30,7 @@ Two helper classes handle keyboard navigation in controllers — see [`stimulus-
 - `role="dialog"`, `aria-modal="true"`, `aria-labelledby` pointing to heading
 - Focus moves into dialog on open; returns to trigger on close
 - Focus trapped inside — Tab/Shift+Tab cycle within; Escape closes
+- Status announcements ("Modal opened"/"Modal closed") via `aria-live` on open/close (WCAG 4.1.3)
 
 #### Popover (`popover_controller`)
 - `role="dialog"` or `role="tooltip"` depending on interactivity
@@ -57,9 +58,15 @@ Two helper classes handle keyboard navigation in controllers — see [`stimulus-
 - Invalid fields: `aria-invalid="true"` + `aria-describedby` pointing to error message
 - Error message element: `role="alert"` or `aria-live="polite"` so it's announced
 
-#### Password Reveal (`password_reveal_controller`)
+#### Password Reveal (`input-formatter_controller`, `"password"` formatter)
 - Toggle button: `aria-label` describes action ("Show password" / "Hide password")
-- Or: `aria-pressed` on toggle button
+- `aria-pressed` managed on toggle button, reflecting revealed state
+
+#### Input Clearable (`input_clearable_controller`)
+- Clear button: `hidden` attribute while the input is empty, removing it from the keyboard/AT tab order until there's something to clear
+- Escape inside the input clears it (keyboard equivalent to clicking the clear button, WCAG 2.1.1); default is prevented so it doesn't also close a parent overlay
+- Focus returns to the input after clearing (WCAG 2.4.3 Focus Order)
+- No `aria-live` announcement — clearing is user-initiated and the button's disappearance is self-explanatory
 
 #### Flipper / Visibility / Dismisser
 - Trigger: `aria-expanded="true/false"` when toggling a region
@@ -75,6 +82,13 @@ Two helper classes handle keyboard navigation in controllers — see [`stimulus-
 - Static list: `role="list"` + `role="listitem"` (explicitly set to preserve semantics when CSS resets strip list role)
 - Active item: `aria-current="page"` on `<a>` links; `aria-current="true"` on `<button>` items — the value differs by element type per the ARIA spec
 
+#### Checklist (`checklist_controller`, `sp_checklist`)
+- Each item: native `<input type="checkbox">` inside a `<label>` — role, keyboard activation (Space), focus, and checked-state announcement are all handled by the browser. The component sets no ARIA attributes on items.
+- Read-only item (`readonly: true`): native `disabled` attribute — removes the control from the tab order and announces it as unavailable to assistive tech. No `aria-readonly`/`tabindex` hack.
+- Master "select all" toggle (`select_all:`): same `<input type="checkbox">` shape as an item. Its `indeterminate` property (JS-only, no HTML attribute) is set client-side by the `checklist` controller when some but not all enabled items are checked — modern browsers map `indeterminate` to the accessibility tree's `mixed` checked state automatically, satisfying WCAG 4.1.2 with no manual ARIA.
+- Accepted tradeoff: because `indeterminate` has no HTML attribute, the server can only render the master's initial `checked` state for the all-true case; every other case (including mixed) renders unchecked and is corrected to `indeterminate` once the `checklist` controller connects — a brief, accepted flash for the mixed case only.
+- Disabled (readonly) items are excluded from the master's aggregate and from bulk toggling — the `checklist` controller filters them out via their own `.disabled` property, mirroring their exclusion from tab order and AT interaction.
+
 #### Avatar / Card / Icon
 - Decorative images/icons: `aria-hidden="true"` or `alt=""`
 - Meaningful images: descriptive `alt` text
@@ -86,3 +100,9 @@ Two helper classes handle keyboard navigation in controllers — see [`stimulus-
 - Expandable items: trigger `<button>` with `aria-expanded="false/true"` + `aria-controls` → detail element id; detail has `hidden` attribute toggled by controller
 - Trigger lives inside `<h3>` (`<h3><button aria-expanded>Title</button></h3>`) — WAI-ARIA Accordion pattern
 - Keyboard (interactive): Up/Down arrows move focus between item triggers; Home/End jump to first/last trigger; Enter/Space toggle expansion (native button behaviour)
+
+#### Reorderable (`reorderable_controller`)
+- Roving tabindex on `item` targets (`RovingTabIndex`) — plain Arrow/Home/End move focus only, unaffected by editing state
+- Keyboard move (`Alt+Arrow` on the axis matching `orientation`, default `ArrowUp`/`ArrowDown`; configurable modifier via `moveKey`; horizontal move-key meaning flips under `dir="rtl"`): moves the focused item, keeps focus on it, announces the new position via `role="status"`/`aria-live` (WCAG 4.1.3) — satisfies the keyboard-equivalent requirement (WCAG 2.1.1) for pointer drag
+- Pointer drag: does not move focus or announce — avoids stealing focus from a mouse user who never asked for it
+- `editingValue` gates both drag and keyboard-move; while `true`, every `trigger` target (`<a>`/`<button>` inside an item) gets `aria-disabled="true"` + `tabindex="-1"` — removes it from keyboard/AT activation and tab order without touching pointer clicks (apps/themes add their own `pointer-events: none` CSS rule for that half)