stimulus_plumbers 0.4.8 → 0.4.10

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 },
@@ -100,76 +119,106 @@ module StimulusPlumbers
       }.freeze
 
       FORM = {
-        form_group:                     {
+        form_group:                             {
           layout: { default: :stacked, validate: Form::Ranges::LAYOUT },
           error:  { default: false,    validate: Ranges::BOOL }
         }.freeze,
-        form_field_label:               {
+        form_field_label:                       {
           required: { default: false, validate: Ranges::BOOL },
           hidden:   { default: false, validate: Ranges::BOOL },
           floating: { default: nil,   validate: [nil, *Form::Floating::Ranges::TYPE] },
           error:    { default: false, validate: Ranges::BOOL }
         }.freeze,
-        form_field_required_mark:       {}.freeze,
-        form_field_hint:                {}.freeze,
-        form_field_error:               {}.freeze,
-        form_field_choice_items:        {
+        form_field_required_mark:               {}.freeze,
+        form_field_hint:                        {}.freeze,
+        form_field_error:                       {}.freeze,
+        form_field_choice_items:                {
           layout: { default: :stacked, validate: Form::Ranges::LAYOUT }
         }.freeze,
-        form_field_checkbox_label:      {
+        form_field_checkbox_label:              {
           type:    { default: :default,  validate: Form::Checkbox::Ranges::TYPE },
           variant: { default: :tertiary, validate: Form::Checkbox::Ranges::VARIANT }
         }.freeze,
-        form_field_radio_label:         {
+        form_field_radio_label:                 {
           type:    { default: :default,  validate: Form::Radio::Ranges::TYPE },
           variant: { default: :tertiary, validate: Form::Radio::Ranges::VARIANT }
         }.freeze,
-        form_field_radio_item_group:    {}.freeze,
-        form_field_input:               {
+        form_field_radio_item_group:            {}.freeze,
+        form_field_input:                       {
           error:    { default: false, validate: Ranges::BOOL },
           floating: { default: nil,   validate: [nil, *Form::Floating::Ranges::TYPE] }
         }.freeze,
-        form_field_input_group:         {
+        form_field_input_group:                 {
           floating: { default: nil, validate: [nil, *Form::Floating::Ranges::TYPE] }
         }.freeze,
-        form_field_input_textarea:      {
+        form_field_input_textarea:              {
           error:    { default: false, validate: Ranges::BOOL },
           floating: { default: nil,   validate: [nil, *Form::Floating::Ranges::TYPE] }
         }.freeze,
-        form_field_input_file:          {
+        form_field_input_file:                  {
           error:    { default: false, validate: Ranges::BOOL },
           floating: { default: nil,   validate: [nil, *Form::Floating::Ranges::TYPE] }
         }.freeze,
-        form_field_input_select:        {
+        form_field_input_select:                {
           error:    { default: false, validate: Ranges::BOOL },
           floating: { default: nil,   validate: [nil, *Form::Floating::Ranges::TYPE] }
         }.freeze,
-        form_field_input_checkbox:      {
+        form_field_input_checkbox:              {
           error:   { default: false,     validate: Ranges::BOOL },
           type:    { default: :default,  validate: Form::Checkbox::Ranges::TYPE },
           variant: { default: :tertiary, validate: Form::Checkbox::Ranges::VARIANT }
         }.freeze,
-        form_field_input_radio:         {
+        form_field_input_radio:                 {
           error:   { default: false,     validate: Ranges::BOOL },
           type:    { default: :default,  validate: Form::Radio::Ranges::TYPE },
           variant: { default: :tertiary, validate: Form::Radio::Ranges::VARIANT }
         }.freeze,
-        form_field_input_combobox:      {
+        form_field_input_combobox:              {
           error:    { default: false, validate: Ranges::BOOL },
           floating: { default: nil,   validate: [nil, *Form::Floating::Ranges::TYPE] }
         }.freeze,
-        form_field_input_reveal:        { error: { default: false, validate: Ranges::BOOL } }.freeze,
-        form_field_input_clearable:     {}.freeze,
-        form_field_input_button_reveal: {}.freeze,
-        form_field_input_button_clear:  {}.freeze,
-        form_submit:                    {
+        form_field_input_reveal:                { error: { default: false, validate: Ranges::BOOL } }.freeze,
+        form_field_input_clearable:             {}.freeze,
+        form_field_input_code:                  {
+          error: { default: false, validate: Ranges::BOOL }
+        }.freeze,
+        form_field_input_code_cells:            {}.freeze,
+        form_field_input_code_cell:             {
+          error: { default: false, validate: Ranges::BOOL }
+        }.freeze,
+        form_field_input_code_overlay:          {
+          error: { default: false, validate: Ranges::BOOL }
+        }.freeze,
+        form_field_input_credit_card:           {
+          error: { default: false, validate: Ranges::BOOL }
+        }.freeze,
+        form_field_input_credit_card_cells:     {}.freeze,
+        form_field_input_credit_card_cell:      {
+          error: { default: false, validate: Ranges::BOOL }
+        }.freeze,
+        form_field_input_credit_card_separator: {}.freeze,
+        form_field_input_credit_card_overlay:   {
+          error: { default: false, validate: Ranges::BOOL }
+        }.freeze,
+        form_field_input_button_reveal:         {}.freeze,
+        form_field_input_button_clear:          {}.freeze,
+        form_submit:                            {
           type:    { default: :default, validate: Button::Ranges::TYPE },
           variant: { default: :primary, validate: Button::Ranges::VARIANT }
         }.freeze
       }.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 +245,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 +272,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 +279,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.10"
 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,22 @@ 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
+
+#### Code Input (`input_formatter_controller` + `character_cells`)
+
+- The real `<input>` is the entire accessible surface; cells are stamped `aria-hidden="true"` automatically.
+- The input requires a `<label>` (visually hidden allowed), `autocomplete="one-time-code"` for OTP (WCAG 1.3.5), `inputmode` matching the charset, and `maxlength` matching the code length.
+- Overlay the input with `opacity: 0` — never `display: none`/`visibility: hidden`, which remove it from the tab order (WCAG 2.1.1).
+- Focus visibility (WCAG 2.4.7): the caret cell (`data-caret`) appears only while the input has focus; style the wrapper with `:focus-within` plus `[data-caret]`.
+
+#### 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 +89,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 +107,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)

data/vendor/component/manifest.json

@@ -0,0 +1,215 @@
+{
+  "calendar-decade": {
+    "actions": [],
+    "listens": [
+      "selected"
+    ],
+    "targets": [
+      "grid"
+    ],
+    "values": []
+  },
+  "calendar-decade-selector": {
+    "actions": [],
+    "listens": [],
+    "targets": [],
+    "values": []
+  },
+  "calendar-month": {
+    "actions": [],
+    "listens": [
+      "selected"
+    ],
+    "targets": [
+      "daysOfMonth",
+      "daysOfWeek"
+    ],
+    "values": [
+      "month",
+      "year"
+    ]
+  },
+  "calendar-month-selector": {
+    "actions": [],
+    "listens": [],
+    "targets": [],
+    "values": []
+  },
+  "calendar-year": {
+    "actions": [],
+    "listens": [
+      "selected"
+    ],
+    "targets": [
+      "grid"
+    ],
+    "values": []
+  },
+  "calendar-year-selector": {
+    "actions": [],
+    "listens": [],
+    "targets": [],
+    "values": []
+  },
+  "checklist": {
+    "actions": [
+      "onChange"
+    ],
+    "listens": [],
+    "targets": [],
+    "values": []
+  },
+  "clipboard": {
+    "actions": [],
+    "listens": [],
+    "targets": [],
+    "values": []
+  },
+  "combobox-date": {
+    "actions": [],
+    "listens": [
+      "selected"
+    ],
+    "targets": [],
+    "values": []
+  },
+  "combobox-dropdown": {
+    "actions": [
+      "onNavigate",
+      "select"
+    ],
+    "listens": [
+      "selected"
+    ],
+    "targets": [],
+    "values": []
+  },
+  "combobox-time": {
+    "actions": [
+      "onNavigate",
+      "select"
+    ],
+    "listens": [
+      "selected"
+    ],
+    "targets": [],
+    "values": []
+  },
+  "dismisser": {
+    "actions": [],
+    "listens": [],
+    "targets": [],
+    "values": []
+  },
+  "flipper": {
+    "actions": [],
+    "listens": [],
+    "targets": [],
+    "values": []
+  },
+  "input-clearable": {
+    "actions": [
+      "clear"
+    ],
+    "listens": [],
+    "targets": [],
+    "values": []
+  },
+  "input-combobox": {
+    "actions": [
+      "onInput"
+    ],
+    "listens": [
+      "changed"
+    ],
+    "targets": [],
+    "values": []
+  },
+  "input-formatter": {
+    "actions": [
+      "onBlur",
+      "onFocus",
+      "onInput",
+      "toggle"
+    ],
+    "listens": [],
+    "targets": [],
+    "values": []
+  },
+  "modal": {
+    "actions": [],
+    "listens": [],
+    "targets": [],
+    "values": []
+  },
+  "panner": {
+    "actions": [],
+    "listens": [],
+    "targets": [],
+    "values": []
+  },
+  "popover": {
+    "actions": [
+      "close",
+      "open",
+      "toggle"
+    ],
+    "listens": [],
+    "targets": [],
+    "values": []
+  },
+  "progress": {
+    "actions": [],
+    "listens": [],
+    "targets": [
+      "fill",
+      "meter"
+    ],
+    "values": [
+      "current",
+      "high",
+      "indeterminate",
+      "low",
+      "max",
+      "min",
+      "optimum",
+      "variant"
+    ]
+  },
+  "reorderable": {
+    "actions": [
+      "onPointerDown",
+      "onPointerMove",
+      "onPointerUp"
+    ],
+    "listens": [],
+    "targets": [
+      "handle",
+      "item",
+      "trigger"
+    ],
+    "values": [
+      "editing",
+      "moveKey",
+      "orientation"
+    ]
+  },
+  "timeline": {
+    "actions": [
+      "toggle"
+    ],
+    "listens": [],
+    "targets": [
+      "detail",
+      "time",
+      "trigger"
+    ],
+    "values": []
+  },
+  "visibility": {
+    "actions": [],
+    "listens": [],
+    "targets": [],
+    "values": []
+  }
+}

data/vendor/controller/docs/calendar.md

@@ -100,11 +100,8 @@ Click-handling is wired internally — `calendar-month` handles clicks on its ow
 
 ## Accessibility
 
-- Grid uses `role="grid"` → `role="row"` → `role="gridcell"`
 - Weekday headers use `role="columnheader"` with `title` for the long name
-- Today is marked with `aria-current="date"`
-- Disabled dates use `disabled` (buttons) or `aria-disabled="true"` (non-interactive)
-- Selected dates use `aria-selected="true"`
+- See [ARIA.md's Calendar / Date Picker pattern](../../../ARIA.md) for grid roles, selection/disabled state, and keyboard navigation
 
 ---
 
@@ -196,7 +193,7 @@ Decade-view grid controller — renders a 12-year grid and dispatches a `calenda
 
 Thin SSR/Turbo adapter for server-rendered month grids. Attaches click-to-select behaviour to a server-rendered day grid — no targets or values. The server renders each view as a `<turbo-frame>`; this controller handles day selection and emits the same `calendar-month:selected` event as `calendar-month`.
 
-Used with `sp_calendar_turbo_month` (Rails). Pair with `combobox-date` exactly as you would `calendar-month`.
+Used with `sp_calendar_turbo_month` (Rails). Pair with `combobox-date` exactly as you would `calendar-month`. See [docs/plumber/calendar-selector.md](../plumber/calendar-selector.md) for the underlying plumber.
 
 ---
 
@@ -204,7 +201,7 @@ Used with `sp_calendar_turbo_month` (Rails). Pair with `combobox-date` exactly a
 
 Thin SSR/Turbo adapter for server-rendered year (month-grid) views. Attaches click-to-select behaviour — no targets or values. Emits `calendar-year:selected` on month click.
 
-Used with `sp_calendar_turbo_year` (Rails).
+Used with `sp_calendar_turbo_year` (Rails). See [docs/plumber/calendar-selector.md](../plumber/calendar-selector.md) for the underlying plumber.
 
 ---
 
@@ -212,4 +209,4 @@ Used with `sp_calendar_turbo_year` (Rails).
 
 Thin SSR/Turbo adapter for server-rendered decade (year-grid) views. Attaches click-to-select behaviour — no targets or values. Emits `calendar-decade:selected` on year click.
 
-Used with `sp_calendar_turbo_decade` (Rails).
+Used with `sp_calendar_turbo_decade` (Rails). See [docs/plumber/calendar-selector.md](../plumber/calendar-selector.md) for the underlying plumber.