phlex_kit 0.8.1 → 0.9.1

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

@@ -9,6 +9,9 @@ module PhlexKit
     def view_template
       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

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) {
@@ -162,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();
@@ -193,6 +246,7 @@ 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)
@@ -221,9 +275,10 @@ export default class extends Controller {
     if (focused) stop.focus({ preventScroll: true });
   }
 
-  // Arrow keys move by day/week, 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).
+  // 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]");
@@ -233,6 +288,13 @@ export default class extends Controller {
     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);
@@ -260,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));
+      }
     }
   }
 
@@ -278,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);

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() {

data/app/components/phlex_kit/chart/chart_controller.js

@@ -80,15 +80,22 @@ export default class extends Controller {
 
   setDefaultColorsForChart() {
     const Chart = this.chartLibrary()
-    Chart.defaults.color = this.getThemeColor("pk-muted") // font color
-    Chart.defaults.borderColor = this.getThemeColor("pk-border") // border color
-    Chart.defaults.backgroundColor = this.getThemeColor("pk-bg") // background color
+    // One computed-style resolve for all nine tokens (this runs on every
+    // connect; assigning identical values to Chart.defaults is free — charts
+    // read defaults at construction — so the style resolves are the only cost
+    // worth trimming).
+    const styles = getComputedStyle(document.documentElement)
+    const token = (name) => styles.getPropertyValue(`--${name}`).trim()
+
+    Chart.defaults.color = token("pk-muted") // font color
+    Chart.defaults.borderColor = token("pk-border") // border color
+    Chart.defaults.backgroundColor = token("pk-bg") // background color
 
     // tooltip colors
-    Chart.defaults.plugins.tooltip.backgroundColor = this.getThemeColor("pk-surface")
-    Chart.defaults.plugins.tooltip.borderColor = this.getThemeColor("pk-border")
-    Chart.defaults.plugins.tooltip.titleColor = this.getThemeColor("pk-text")
-    Chart.defaults.plugins.tooltip.bodyColor = this.getThemeColor("pk-muted")
+    Chart.defaults.plugins.tooltip.backgroundColor = token("pk-surface")
+    Chart.defaults.plugins.tooltip.borderColor = token("pk-border")
+    Chart.defaults.plugins.tooltip.titleColor = token("pk-text")
+    Chart.defaults.plugins.tooltip.bodyColor = token("pk-muted")
     Chart.defaults.plugins.tooltip.borderWidth = 1
 
     // legend
@@ -99,7 +106,7 @@ export default class extends Controller {
     Chart.defaults.plugins.legend.labels.borderRadius = 2
 
     // shadcn look: hairline grid, no axis borders, muted ticks
-    Chart.defaults.scale.grid = { ...Chart.defaults.scale.grid, color: this.getThemeColor("pk-border"), drawTicks: false }
+    Chart.defaults.scale.grid = { ...Chart.defaults.scale.grid, color: token("pk-border"), drawTicks: false }
     Chart.defaults.scale.border = { ...Chart.defaults.scale.border, display: false }
   }
 
@@ -108,14 +115,30 @@ export default class extends Controller {
     this.initChart()
   }
 
-  // The kit themes via <html data-theme="...">, not a class — watch that.
+  // The kit themes via <html data-theme="...">, not a class — but a class can
+  // re-theme too (.pk-dark, custom theme classes), so watch both. ANY root
+  // class mutation fires the observer though, so only rebuild when the
+  // resolved token values actually changed — rebuilding every chart on an
+  // unrelated class flip is the expensive path.
   initThemeObserver() {
+    this._themeKey = this.currentThemeKey()
     this.themeObserver = new MutationObserver(() => {
+      const key = this.currentThemeKey()
+      if (key === this._themeKey) return
+      this._themeKey = key
       this.refreshChart()
     })
     this.themeObserver.observe(document.documentElement, { attributeFilter: ["data-theme", "class"] })
   }
 
+  // Cheap fingerprint of the resolved theme: two tokens that differ between
+  // every light/dark pair. One style resolve per mutation vs a full chart
+  // rebuild.
+  currentThemeKey() {
+    const styles = getComputedStyle(document.documentElement)
+    return `${styles.getPropertyValue("--pk-bg")}|${styles.getPropertyValue("--pk-text")}`
+  }
+
   mergeOptionsWithDefaults() {
     return {
       ...this.optionsValue,

data/app/components/phlex_kit/checkbox/checkbox.css

@@ -16,7 +16,8 @@
   height: 1rem;
   margin: 0;
   border: 1px solid var(--pk-input);
-  border-radius: 4px;
+  /* Tracks the radius token — 4px at the default --pk-radius (0.625rem). */
+  border-radius: calc(var(--pk-radius) - 6px);
   background: color-mix(in oklab, var(--pk-input) 30%, transparent);
   cursor: pointer;
   transition: border-color .15s ease, background-color .15s ease, box-shadow .15s ease;

data/app/components/phlex_kit/clipboard/clipboard.css

@@ -4,5 +4,5 @@
 .pk-clipboard-popover { position: absolute; bottom: calc(100% + .5rem); left: 50%; transform: translateX(-50%); z-index: 50; width: max-content; }
 .pk-clipboard-popover-inner {
   border: 1px solid var(--pk-border); border-radius: calc(var(--pk-radius) - 2px); background: var(--pk-surface);
-  color: var(--pk-text); padding: .125rem .5rem; font-size: .875rem; box-shadow: 0 8px 24px rgb(0 0 0 / .3);
+  color: var(--pk-text); padding: .125rem .5rem; font-size: .875rem; box-shadow: 0 8px 24px color-mix(in srgb, var(--pk-shadow-color) 30%, transparent);
 }

data/app/components/phlex_kit/clipboard/clipboard_controller.js

@@ -5,6 +5,13 @@ import { Controller } from "@hotwired/stimulus"
 export default class extends Controller {
   static targets = ["trigger", "source", "successPopover", "errorPopover"]
 
+  disconnect() {
+    // Don't leave the 1.5s hide timer running into a dead/recycled element
+    // (Turbo can detach and re-attach this subtree mid-flash).
+    clearTimeout(this.timer)
+    this.hideAll()
+  }
+
   copy() {
     const el = this.sourceTarget.children[0]
     if (!el) { this.show(this.errorPopoverTarget); return }

data/app/components/phlex_kit/codeblock/codeblock.rb

@@ -9,7 +9,10 @@ module PhlexKit
       @attrs = attrs
     end
     def view_template(&block)
-      div(**mix({ class: "pk-codeblock", data: { syntax: @syntax } }, @attrs)) do
+      # tabindex=0 + role=region: the block scrolls (overflow:auto), so it must
+      # be keyboard-focusable (WCAG 2.1.1 scrollable-region-focusable). Pass
+      # `aria: { label: ... }` to name the region for AT.
+      div(**mix({ class: "pk-codeblock", tabindex: "0", role: "region", data: { syntax: @syntax } }, @attrs)) do
         pre do
           if block
             code(&block)

data/app/components/phlex_kit/collapsible/collapsible_content.rb

@@ -1,8 +1,21 @@
 module PhlexKit
+  # Collapsed region of a Collapsible. Pass `open:` matching the parent
+  # Collapsible's so a closed region is hidden before JS (no flash-open, and
+  # no stuck-open region without JS); the controller toggles `.pk-hidden`
+  # from there. The default id lets the trigger's aria-controls point here.
   class CollapsibleContent < BaseComponent
-    def initialize(**attrs) = (@attrs = attrs)
+    def initialize(open: false, id: nil, **attrs)
+      @open = open
+      @id = id || "pk-collapsible-content-#{SecureRandom.hex(4)}"
+      @attrs = attrs
+    end
+
     def view_template(&)
-      div(**mix({ class: "pk-collapsible-content", data: { phlex_kit__collapsible_target: "content" } }, @attrs), &)
+      div(**mix({
+        class: @open ? "pk-collapsible-content" : "pk-collapsible-content pk-hidden",
+        id: @id,
+        data: { phlex_kit__collapsible_target: "content" }
+      }, @attrs), &)
     end
   end
 end

data/app/components/phlex_kit/collapsible/collapsible_controller.js

@@ -2,20 +2,29 @@ import { Controller } from "@hotwired/stimulus"
 
 // Connects to data-controller="phlex-kit--collapsible"
 export default class extends Controller {
-  static targets = ["content"]
+  static targets = ["trigger", "content"]
   static values = { open: { type: Boolean, default: false } }
 
-  connect() { this.openValue ? this.open() : this.close() }
+  connect() {
+    // The trigger renders aria-expanded from its own `open:` kwarg but can't
+    // know the content's id at render time — wire aria-controls here.
+    if (this.hasTriggerTarget && this.hasContentTarget && this.contentTarget.id) {
+      this.triggerTarget.setAttribute("aria-controls", this.contentTarget.id)
+    }
+    this.openValue ? this.open() : this.close()
+  }
   toggle() { this.openValue = !this.openValue }
   openValueChanged(isOpen) { isOpen ? this.open() : this.close() }
 
   open() {
     if (this.hasContentTarget) { this.contentTarget.classList.remove("pk-hidden"); this.openValue = true }
+    if (this.hasTriggerTarget) this.triggerTarget.setAttribute("aria-expanded", "true")
     this.element.dataset.state = "open";
   }
 
   close() {
     if (this.hasContentTarget) { this.contentTarget.classList.add("pk-hidden"); this.openValue = false }
+    if (this.hasTriggerTarget) this.triggerTarget.setAttribute("aria-expanded", "false")
     this.element.dataset.state = "closed";
   }
 }

data/app/components/phlex_kit/collapsible/collapsible_trigger.rb

@@ -1,8 +1,23 @@
 module PhlexKit
+  # Toggle for a Collapsible. Renders a plain wrapper carrying the click
+  # action — it deliberately has no role of its own, so nest a real focusable
+  # control (a <button>, e.g. PhlexKit::Button) inside it for keyboard
+  # operability and semantics, the same composition pattern as
+  # AttachmentTrigger. Pass `open:` matching the parent Collapsible's so
+  # aria-expanded is correct before JS; the controller keeps it in sync and
+  # wires aria-controls to the content's id in connect().
   class CollapsibleTrigger < BaseComponent
-    def initialize(**attrs) = (@attrs = attrs)
+    def initialize(open: false, **attrs)
+      @open = open
+      @attrs = attrs
+    end
+
     def view_template(&)
-      div(**mix({ class: "pk-collapsible-trigger", data: { action: "click->phlex-kit--collapsible#toggle" } }, @attrs), &)
+      div(**mix({
+        class: "pk-collapsible-trigger",
+        aria_expanded: @open ? "true" : "false",
+        data: { phlex_kit__collapsible_target: "trigger", action: "click->phlex-kit--collapsible#toggle" }
+      }, @attrs), &)
     end
   end
 end