phlex_kit 0.8.0 → 0.9.0

data/app/components/phlex_kit/button/button.css

@@ -37,8 +37,8 @@
 /* Glyphs default to size-4; explicit width attrs (Icon size:) win. */
 .pk-button svg { flex-shrink: 0; pointer-events: none; }
 .pk-button svg:not([width]) { width: 1rem; height: 1rem; }
-.pk-button:has(> [data-icon="inline-start"]) { padding-left: .5rem; }
-.pk-button:has(> [data-icon="inline-end"]) { padding-right: .5rem; }
+.pk-button:has(> [data-icon="inline-start"]) { padding-inline-start: .5rem; }
+.pk-button:has(> [data-icon="inline-end"]) { padding-inline-end: .5rem; }
 
 /* Sizes (md is the base above). */
 .pk-button.xs {
@@ -46,15 +46,15 @@
   border-radius: min(calc(var(--pk-radius) - 2px), 10px);
 }
 .pk-button.xs svg:not([width]) { width: .75rem; height: .75rem; }
-.pk-button.xs:has(> [data-icon="inline-start"]) { padding-left: .375rem; }
-.pk-button.xs:has(> [data-icon="inline-end"]) { padding-right: .375rem; }
+.pk-button.xs:has(> [data-icon="inline-start"]) { padding-inline-start: .375rem; }
+.pk-button.xs:has(> [data-icon="inline-end"]) { padding-inline-end: .375rem; }
 .pk-button.sm {
   height: 1.75rem; gap: .25rem; padding: .25rem .625rem; font-size: .8rem;
   border-radius: min(calc(var(--pk-radius) - 2px), 12px);
 }
 .pk-button.sm svg:not([width]) { width: .875rem; height: .875rem; }
-.pk-button.sm:has(> [data-icon="inline-start"]) { padding-left: .375rem; }
-.pk-button.sm:has(> [data-icon="inline-end"]) { padding-right: .375rem; }
+.pk-button.sm:has(> [data-icon="inline-start"]) { padding-inline-start: .375rem; }
+.pk-button.sm:has(> [data-icon="inline-end"]) { padding-inline-end: .375rem; }
 .pk-button.lg { height: 2.25rem; padding: .375rem .625rem; }
 .pk-button.xl { height: 3rem; padding: .625rem 1.5rem; font-size: 1rem; }
 

data/app/components/phlex_kit/button_group/button_group.css

@@ -14,7 +14,7 @@
 .pk-button-group:not(.vertical) > :not(:first-child) {
   border-top-left-radius: 0;
   border-bottom-left-radius: 0;
-  border-left: 0;
+  border-inline-start: 0;
 }
 .pk-button-group:not(.vertical) > :not(:last-child) {
   border-top-right-radius: 0;
@@ -47,7 +47,7 @@
 .pk-button-group:not(.vertical) > :not(:first-child) > :is(.pk-select-trigger, .pk-combobox-trigger) {
   border-top-left-radius: 0;
   border-bottom-left-radius: 0;
-  border-left: 0;
+  border-inline-start: 0;
 }
 .pk-button-group:not(.vertical) > :not(:last-child) > :is(.pk-dropdown-menu-trigger, .pk-popover-trigger, .pk-hover-card-trigger, .pk-tooltip-trigger) > .pk-button,
 .pk-button-group:not(.vertical) > :not(:last-child) > :is(.pk-select-trigger, .pk-combobox-trigger) {

data/app/components/phlex_kit/button_group/button_group_separator.rb

@@ -8,7 +8,9 @@ module PhlexKit
     end
 
     def view_template
-      div(**mix({ class: "pk-button-group-separator", role: "separator", aria: { hidden: true } }, @attrs))
+      # Purely decorative — aria-hidden only (role="separator" would
+      # contradict aria-hidden and confuse AT).
+      div(**mix({ class: "pk-button-group-separator", aria: { hidden: true } }, @attrs))
     end
   end
 end

data/app/components/phlex_kit/calendar/calendar.css

@@ -53,8 +53,8 @@
   opacity: .5;
   transition: background-color .15s ease, opacity .15s ease;
 }
-.pk-calendar-prev { left: .25rem; }
-.pk-calendar-next { right: .25rem; }
+.pk-calendar-prev { inset-inline-start: .25rem; }
+.pk-calendar-next { inset-inline-end: .25rem; }
 .pk-calendar-prev:hover, .pk-calendar-next:hover { background: var(--pk-accent); opacity: 1; }
 .pk-calendar-prev:focus-visible, .pk-calendar-next:focus-visible {
   outline: none;

data/app/components/phlex_kit/calendar/calendar.rb

@@ -64,7 +64,9 @@ module PhlexKit
     private
 
     def render_dropdown_caption
-      view_year = parse_year(@selected_date) || parse_year(@range_start) || Time.now.year
+      view_seed = @selected_date || @range_start || @selected_dates.first
+      view_year = parse_year(view_seed) || Time.now.year
+      view_month = parse_month(view_seed) || Time.now.month # 1-12
       first_year = @from_year || parse_year(@min_date) || (view_year - 10)
       last_year = @to_year || parse_year(@max_date) || (view_year + 10)
 
@@ -74,14 +76,15 @@ module PhlexKit
           aria: { label: "Month" },
           data: { phlex_kit__calendar_target: "monthSelect", action: "change->phlex-kit--calendar#setMonth" }
         ) do
-          MONTHS.each_with_index { |name, index| option(value: index.to_s) { name } }
+          # Mark the view month selected so the caption is right pre-JS.
+          MONTHS.each_with_index { |name, index| option(value: index.to_s, selected: index == view_month - 1) { name } }
         end
         select(
           class: "pk-native-select-field pk-calendar-dropdown",
           aria: { label: "Year" },
           data: { phlex_kit__calendar_target: "yearSelect", action: "change->phlex-kit--calendar#setYear" }
         ) do
-          (first_year..last_year).each { |year| option(value: year.to_s) { year.to_s } }
+          (first_year..last_year).each { |year| option(value: year.to_s, selected: year == view_year) { year.to_s } }
         end
       end
     end
@@ -90,6 +93,10 @@ module PhlexKit
       value.to_s[/\A(\d{4})/, 1]&.to_i
     end
 
+    def parse_month(value)
+      value.to_s[/\A\d{4}-(\d{2})/, 1]&.to_i
+    end
+
     def calendar_attrs
       data = {
         controller: "phlex-kit--calendar",

data/app/components/phlex_kit/calendar/calendar_body.rb

@@ -7,7 +7,18 @@ module PhlexKit
     end
 
     def view_template
-      table(**mix({ class: "pk-calendar-body", data: { phlex_kit__calendar_target: "calendar" } }, @attrs))
+      table(**mix({
+        class: "pk-calendar-body",
+        # The day grid is a real ARIA grid: this table is role="grid", the
+        # controller-rendered rows are role="row", the <td>s gridcells.
+        role: "grid",
+        data: {
+          phlex_kit__calendar_target: "calendar",
+          # Delegated arrow-key/Home/End navigation for the day grid (the
+          # buttons are re-rendered wholesale, so the action lives here).
+          action: "keydown->phlex-kit--calendar#onKeydown"
+        }
+      }, @attrs))
     end
   end
 end

data/app/components/phlex_kit/calendar/calendar_controller.js

@@ -17,6 +17,8 @@ export default class extends Controller {
     "title",
     "monthSelect",
     "yearSelect",
+    "prevButton",
+    "nextButton",
     "weekdaysTemplate",
     "disabledDateTemplate",
     "selectedDateTemplate",
@@ -42,18 +44,18 @@ export default class extends Controller {
   };
   static outlets = ["phlex-kit--calendar-input"];
 
-  initialize() {
-    this.updateCalendar(); // Initial calendar render
-  }
+  // No initialize() render: Stimulus fires every value's `…ValueChanged`
+  // callback once during value initialization (before connect()), so
+  // viewDateValueChanged already performs the initial updateCalendar().
 
   nextMonth(e) {
     e.preventDefault();
-    this.viewDateValue = this.adjustMonth(1);
+    this.viewDateValue = this.clampViewIso(this.adjustMonth(1));
   }
 
   prevMonth(e) {
     e.preventDefault();
-    this.viewDateValue = this.adjustMonth(-1);
+    this.viewDateValue = this.clampViewIso(this.adjustMonth(-1));
   }
 
   // month/year dropdown caption (native selects)
@@ -61,14 +63,62 @@ export default class extends Controller {
     const date = this.viewDate();
     date.setDate(2);
     date.setMonth(Number(e.target.value));
-    this.viewDateValue = this.isoDate(date);
+    this.viewDateValue = this.clampViewIso(this.isoDate(date));
   }
 
   setYear(e) {
     const date = this.viewDate();
     date.setDate(2);
     date.setFullYear(Number(e.target.value));
-    this.viewDateValue = this.isoDate(date);
+    this.viewDateValue = this.clampViewIso(this.isoDate(date));
+  }
+
+  // --- month-navigation bounds (min/max dates + the year dropdown's range) ---
+
+  // Earliest/latest navigable months. min/max dates bound directly; a year
+  // dropdown additionally bounds the view to its option range (from_year /
+  // to_year) so navigation can't drive the select out of range (blank).
+  monthBounds() {
+    let min = this.minDate();
+    let max = this.maxDate();
+    if (this.hasYearSelectTarget) {
+      const years = [...this.yearSelectTarget.options].map((o) => Number(o.value)).filter(Number.isFinite);
+      if (years.length) {
+        const yearMin = new Date(Math.min(...years), 0, 1);
+        const yearMax = new Date(Math.max(...years), 11, 31);
+        if (!min || yearMin > min) min = yearMin;
+        if (!max || yearMax < max) max = yearMax;
+      }
+    }
+    return { min, max };
+  }
+
+  monthIndexOf(date) {
+    return date.getFullYear() * 12 + date.getMonth();
+  }
+
+  clampViewIso(iso) {
+    const date = this.parseDate(iso);
+    if (!date) return iso;
+    const { min, max } = this.monthBounds();
+    if (min && this.monthIndexOf(date) < this.monthIndexOf(min)) {
+      return this.isoDate(new Date(min.getFullYear(), min.getMonth(), 2));
+    }
+    if (max && this.monthIndexOf(date) > this.monthIndexOf(max)) {
+      return this.isoDate(new Date(max.getFullYear(), max.getMonth(), 2));
+    }
+    return iso;
+  }
+
+  syncNavButtons() {
+    const { min, max } = this.monthBounds();
+    const view = this.monthIndexOf(this.viewDate());
+    if (this.hasPrevButtonTarget) {
+      this.prevButtonTarget.disabled = Boolean(min && view <= this.monthIndexOf(min));
+    }
+    if (this.hasNextButtonTarget) {
+      this.nextButtonTarget.disabled = Boolean(max && view >= this.monthIndexOf(max));
+    }
   }
 
   selectDay(e) {
@@ -119,6 +169,7 @@ export default class extends Controller {
     }
     this.selectedDatesValue = current;
     this.updateCalendar();
+    this.pushToOutlets();
     this.dispatchChange();
   }
 
@@ -161,6 +212,9 @@ export default class extends Controller {
       return end ? `${this.formatDate(start)} – ${this.formatDate(end)}` : this.formatDate(start);
     }
     if (this.modeValue === "multiple") {
+      // Deselecting the last date must clear the bound input: return ""
+      // (pushed to outlets), not null (skipped by pushToOutlets' guard).
+      if (!this.selectedDatesValue.length) return "";
       return this.selectedDatesValue.map((d) => this.formatDate(this.parseDate(d))).join(", ");
     }
     const selected = this.selectedDate();
@@ -192,7 +246,75 @@ export default class extends Controller {
       this.titleTarget.textContent = this.monthAndYear();
     }
     this.syncDropdowns();
+    this.syncNavButtons();
+    // innerHTML replacement drops focus — remember the focused day so
+    // keyboard selection/month hops don't strand focus on <body>.
+    const focusedDay = this.calendarTarget.contains(document.activeElement)
+      ? document.activeElement.dataset?.day
+      : null;
     this.calendarTarget.innerHTML = this.calendarHTML();
+    this.ensureGridTabStop(focusedDay);
+  }
+
+  // Roving tabindex: exactly one day button is tabbable — the previously
+  // focused day (refocused across re-renders), else the selected day (its
+  // template ships tabindex="0"), else today, else the first enabled day of
+  // the current month. Without this, a calendar with no selection has no
+  // keyboard entry point at all.
+  ensureGridTabStop(focusedDay) {
+    const days = [...this.calendarTarget.querySelectorAll(".pk-calendar-day:not([disabled])")];
+    if (!days.length) return;
+    const focused = focusedDay ? days.find((d) => d.dataset.day === focusedDay) : null;
+    const stop =
+      focused ||
+      days.find((d) => d.getAttribute("tabindex") === "0") ||
+      days.find((d) => d.classList.contains("today")) ||
+      days.find((d) => !d.classList.contains("other")) ||
+      days[0];
+    days.forEach((d) => d.setAttribute("tabindex", d === stop ? "0" : "-1"));
+    if (focused) stop.focus({ preventScroll: true });
+  }
+
+  // Arrow keys move by day/week, PageUp/PageDown by month (Shift: by year,
+  // per APG), Home/End jump within the rendered week row; crossing a month
+  // boundary re-renders the grid on the target month. Enter/Space activate
+  // natively (the days are real <button>s).
+  onKeydown(e) {
+    const STEPS = { ArrowLeft: -1, ArrowRight: 1, ArrowUp: -7, ArrowDown: 7 };
+    const day = e.target.closest?.("[data-day]");
+    if (!day) return;
+
+    let target;
+    if (e.key in STEPS) {
+      target = this.parseDate(day.dataset.day);
+      target.setDate(target.getDate() + STEPS[e.key]);
+    } else if (e.key === "PageUp" || e.key === "PageDown") {
+      const base = this.parseDate(day.dataset.day);
+      const months = (e.key === "PageUp" ? -1 : 1) * (e.shiftKey ? 12 : 1);
+      target = new Date(base.getFullYear(), base.getMonth() + months, 1);
+      // land on the same day-of-month, clamped to the target month's length
+      const lastDay = new Date(target.getFullYear(), target.getMonth() + 1, 0).getDate();
+      target.setDate(Math.min(base.getDate(), lastDay));
+    } else if (e.key === "Home" || e.key === "End") {
+      const rowDays = [...day.closest("tr").querySelectorAll("[data-day]")];
+      target = this.parseDate(rowDays[e.key === "Home" ? 0 : rowDays.length - 1].dataset.day);
+    } else {
+      return;
+    }
+    e.preventDefault();
+
+    const iso = this.isoDate(target);
+    if (this.isDateDisabled(iso)) return; // min/max/booked boundary: stay put
+
+    if (target.getMonth() !== this.viewDate().getMonth() || target.getFullYear() !== this.viewDate().getFullYear()) {
+      this.viewDateValue = iso; // re-renders the grid on the target month
+    }
+    const next = this.calendarTarget.querySelector(`[data-day="${iso}"]:not([disabled])`);
+    if (!next) return;
+    this.calendarTarget.querySelectorAll(".pk-calendar-day").forEach((d) => {
+      d.setAttribute("tabindex", d === next ? "0" : "-1");
+    });
+    next.focus({ preventScroll: true });
   }
 
   syncDropdowns() {
@@ -200,7 +322,15 @@ export default class extends Controller {
       this.monthSelectTarget.value = String(this.viewDate().getMonth());
     }
     if (this.hasYearSelectTarget) {
-      this.yearSelectTarget.value = String(this.viewDate().getFullYear());
+      const select = this.yearSelectTarget;
+      const year = this.viewDate().getFullYear();
+      select.value = String(year);
+      if (select.selectedIndex === -1 && select.options.length) {
+        // view year outside the option range — clamp to the nearest end
+        // instead of leaving the select blank
+        const years = [...select.options].map((o) => Number(o.value));
+        select.value = String(year < Math.min(...years) ? Math.min(...years) : Math.max(...years));
+      }
     }
   }
 
@@ -218,15 +348,22 @@ export default class extends Controller {
     let cells = week.map((day) => this.renderDay(day)).join("");
     if (this.weekNumbersValue) {
       const weekNumber = this.isoWeekNumber(week[0]);
-      cells = `<td class="pk-calendar-weeknumber" role="presentation">${weekNumber}</td>` + cells;
+      cells = `<td class="pk-calendar-weeknumber" role="rowheader">${weekNumber}</td>` + cells;
     }
-    return `<tr class="pk-calendar-week">${cells}</tr>`;
+    return `<tr class="pk-calendar-week" role="row">${cells}</tr>`;
   }
 
   renderDay(day) {
     const today = new Date();
     const iso = this.isoDate(day);
-    const data = { day: iso, dayDate: day.getDate(), state: this.dayState(day) };
+    const data = {
+      day: iso,
+      dayDate: day.getDate(),
+      // full human-readable date for the button's accessible name — a bare
+      // day number ("14") is meaningless to a screen reader
+      dayLabel: day.toLocaleDateString("en-US", { weekday: "long", month: "long", day: "numeric", year: "numeric" }),
+      state: this.dayState(day),
+    };
 
     if (this.isDateDisabled(day)) {
       return renderTemplate(this.disabledDateTemplateTarget.innerHTML, data);
@@ -404,8 +541,10 @@ export default class extends Controller {
       PPPP: `${dayOfWeek}, ${monthName} ${day}${daySuffix}, ${year}`,
     };
 
+    // Longest tokens first: MMMM must precede MM or the alternation eats
+    // "MMMM" as two "MM"s and renders the month number twice.
     const formattedDate = format.replace(
-      /yyyy|MM|dd|HH|mm|ss|EEEE|MMMM|do|PPPP/g,
+      /yyyy|MMMM|MM|dd|HH|mm|ss|EEEE|PPPP|do/g,
       (matched) => map[matched],
     );
     return formattedDate;

data/app/components/phlex_kit/calendar/calendar_days.rb

@@ -1,8 +1,11 @@
 module PhlexKit
   # <template>s for the five day states (disabled / selected / today / current
   # month / other month). The controller picks one per day and interpolates
-  # {{day}} / {{dayDate}} / {{state}} — state carries the extra range/booked
-  # classes (range-start / range-end / in-range / booked). See calendar.rb.
+  # {{day}} / {{dayDate}} / {{dayLabel}} / {{state}} — state carries the extra
+  # range/booked classes (range-start / range-end / in-range / booked), and
+  # dayLabel is the full human-readable date used as the button's accessible
+  # name. Per the APG date-grid pattern the <td> is the gridcell (and carries
+  # aria-selected); the <button> inside is a plain button. See calendar.rb.
   class CalendarDays < BaseComponent
     def initialize(**attrs)
       @attrs = attrs
@@ -25,25 +28,24 @@ module PhlexKit
           name: "day",
           class: "pk-calendar-day disabled {{state}}",
           disabled: true,
-          role: "gridcell",
           tabindex: "-1",
           type: "button",
-          aria_disabled: "true"
+          aria_disabled: "true",
+          aria_label: "{{dayLabel}}"
         ) { "{{dayDate}}" }
       end
     end
 
     def render_selected_date_template
-      date_template("selectedDateTemplate") do
+      date_template("selectedDateTemplate", aria_selected: "true") do
         button(
           data_day: "{{day}}",
           data_action: "click->phlex-kit--calendar#selectDay",
           name: "day",
           class: "pk-calendar-day selected {{state}}",
-          role: "gridcell",
           tabindex: "0",
           type: "button",
-          aria_selected: "true"
+          aria_label: "{{dayLabel}}"
         ) { "{{dayDate}}" }
       end
     end
@@ -55,9 +57,9 @@ module PhlexKit
           data_action: "click->phlex-kit--calendar#selectDay",
           name: "day",
           class: "pk-calendar-day today {{state}}",
-          role: "gridcell",
           tabindex: "-1",
-          type: "button"
+          type: "button",
+          aria_label: "{{dayLabel}}"
         ) { "{{dayDate}}" }
       end
     end
@@ -69,9 +71,9 @@ module PhlexKit
           data_action: "click->phlex-kit--calendar#selectDay",
           name: "day",
           class: "pk-calendar-day {{state}}",
-          role: "gridcell",
           tabindex: "-1",
-          type: "button"
+          type: "button",
+          aria_label: "{{dayLabel}}"
         ) { "{{dayDate}}" }
       end
     end
@@ -83,16 +85,16 @@ module PhlexKit
           data_action: "click->phlex-kit--calendar#selectDay",
           name: "day",
           class: "pk-calendar-day other {{state}}",
-          role: "gridcell",
           tabindex: "-1",
-          type: "button"
+          type: "button",
+          aria_label: "{{dayLabel}}"
         ) { "{{dayDate}}" }
       end
     end
 
-    def date_template(target, &block)
+    def date_template(target, **td_attrs, &block)
       template(data: { phlex_kit__calendar_target: target }) do
-        td(class: "pk-calendar-cell", role: "presentation", &block)
+        td(class: "pk-calendar-cell", role: "gridcell", **td_attrs, &block)
       end
     end
   end

data/app/components/phlex_kit/calendar/calendar_input_controller.js

@@ -5,6 +5,12 @@ import { Controller } from "@hotwired/stimulus"
 // Connects to data-controller="phlex-kit--calendar-input"
 export default class extends Controller {
   setValue(value) {
+    if (this.element.value === value) return
     this.element.value = value
+    // Programmatic .value assignment fires nothing — dispatch input/change so
+    // form frameworks, validators and Stimulus actions bound to the field see
+    // the calendar's write.
+    this.element.dispatchEvent(new Event("input", { bubbles: true }))
+    this.element.dispatchEvent(new Event("change", { bubbles: true }))
   }
 }

data/app/components/phlex_kit/calendar/calendar_next.rb

@@ -11,7 +11,11 @@ module PhlexKit
         name: "next-month",
         class: "pk-calendar-next",
         aria: { label: "Go to next month" },
-        data: { action: "click->phlex-kit--calendar#nextMonth" }
+        data: {
+          action: "click->phlex-kit--calendar#nextMonth",
+          # target so the controller can disable it at the max-date/to-year bound
+          phlex_kit__calendar_target: "nextButton"
+        }
       }, @attrs)) do
         icon
       end

data/app/components/phlex_kit/calendar/calendar_prev.rb

@@ -11,7 +11,11 @@ module PhlexKit
         name: "previous-month",
         class: "pk-calendar-prev",
         aria: { label: "Go to previous month" },
-        data: { action: "click->phlex-kit--calendar#prevMonth" }
+        data: {
+          action: "click->phlex-kit--calendar#prevMonth",
+          # target so the controller can disable it at the min-date/from-year bound
+          phlex_kit__calendar_target: "prevButton"
+        }
       }, @attrs)) do
         icon
       end

data/app/components/phlex_kit/calendar/calendar_weekdays.rb

@@ -12,7 +12,7 @@ module PhlexKit
     def view_template
       template(data: { phlex_kit__calendar_target: "weekdaysTemplate" }) do
         thead(**@attrs) do
-          tr(class: "pk-calendar-weekdays-row") do
+          tr(class: "pk-calendar-weekdays-row", role: "row") do
             th(scope: "col", class: "pk-calendar-weekday pk-calendar-weeknumber-head", aria: { label: "Week number" }) { "#" } if @week_numbers
             DAYS.each { |day| render_day(day) }
           end

data/app/components/phlex_kit/carousel/carousel.rb

@@ -23,7 +23,7 @@ module PhlexKit
         data: {
           controller: "phlex-kit--carousel",
           phlex_kit__carousel_options_value: JSON.generate(default_options.merge(@options)),
-          action: "keydown.right->phlex-kit--carousel#scrollNext:prevent keydown.left->phlex-kit--carousel#scrollPrev:prevent"
+          action: keyboard_action
         }
       }, @attrs), &)
     end
@@ -33,5 +33,15 @@ module PhlexKit
     def default_options
       { axis: (@orientation == :horizontal) ? "x" : "y" }
     end
+
+    # Arrow keys follow the scroll axis: left/right for horizontal, up/down
+    # for vertical.
+    def keyboard_action
+      if @orientation == :vertical
+        "keydown.down->phlex-kit--carousel#scrollNext:prevent keydown.up->phlex-kit--carousel#scrollPrev:prevent"
+      else
+        "keydown.right->phlex-kit--carousel#scrollNext:prevent keydown.left->phlex-kit--carousel#scrollPrev:prevent"
+      end
+    end
   end
 end

data/app/components/phlex_kit/carousel/carousel_controller.js

@@ -37,6 +37,12 @@ export default class extends Controller {
     this._onPointerUp = this._onPointerUp.bind(this);
     this._onClickCapture = this._onClickCapture.bind(this);
     window.addEventListener("resize", this._onResize);
+    // window resize misses container-only resizes (flex/grid reflow,
+    // sidebar toggles) — observe the viewport itself.
+    if (typeof ResizeObserver !== "undefined") {
+      this._resizeObserver = new ResizeObserver(() => this._applyTransform());
+      this._resizeObserver.observe(this.viewportTarget);
+    }
     this.viewportTarget.addEventListener("pointerdown", this._onPointerDown);
     this.viewportTarget.addEventListener("click", this._onClickCapture, true);
     this._update();
@@ -44,8 +50,19 @@ export default class extends Controller {
 
   disconnect() {
     window.removeEventListener("resize", this._onResize);
+    this._resizeObserver?.disconnect();
+    this._resizeObserver = null;
     this.viewportTarget.removeEventListener("pointerdown", this._onPointerDown);
     this.viewportTarget.removeEventListener("click", this._onClickCapture, true);
+    // a disconnect mid-drag must drop the move/up listeners and drag state
+    this.viewportTarget.removeEventListener("pointermove", this._onPointerMove);
+    this.viewportTarget.removeEventListener("pointerup", this._onPointerUp);
+    this.viewportTarget.removeEventListener("pointercancel", this._onPointerUp);
+    if (this.drag) {
+      this.drag = null;
+      if (this.track) this.track.style.transition = "";
+      this.viewportTarget.classList.remove("dragging");
+    }
   }
 
   scrollNext() {
@@ -170,9 +187,19 @@ export default class extends Controller {
     const slide = this.slides[index];
     const first = this.slides[0];
     if (!slide || !first) return 0;
-    return this.options.axis === "y"
+    const raw = this.options.axis === "y"
       ? slide.offsetTop - first.offsetTop
       : slide.offsetLeft - first.offsetLeft;
+    // Never scroll past the content edge: with multi-up layouts the last
+    // slides' offsets overshoot the max scrollable offset (track − viewport).
+    return Math.min(Math.max(0, raw), this._maxOffset());
+  }
+
+  _maxOffset() {
+    const vertical = this.options.axis === "y";
+    const trackSize = vertical ? this.track.scrollHeight : this.track.scrollWidth;
+    const viewportSize = vertical ? this.viewportTarget.clientHeight : this.viewportTarget.clientWidth;
+    return Math.max(0, trackSize - viewportSize);
   }
 
   _slideSize() {