phlex_kit 0.11.0 → 0.13.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: caadd4e868a63939f22013699b89f9b1557dfa9569022301602c0f1cb07020f0
-  data.tar.gz: fa3ba42e9566f171e1fdee7ddcbfc475397bf404152031adbca2fd0cacbbda61
+  metadata.gz: 4e3d6272f0ef818c51cc952c6a2021a1f2b6a036afdab70b617f05c64ada4144
+  data.tar.gz: aa43b4e8826c3dfe52d96440987195815e836de43a795f9628dfce1cbc3bcbd8
 SHA512:
-  metadata.gz: 76304ba104026fe236758b3fa93014b516ec84e65e6baefd307853da30bb7dc9d38d1f6fff0d2c7639ede3ee9116642beed8a615c24963ea3e0462c0ca89656a
-  data.tar.gz: 0c8d0dfd56d4e4b873b35149dd7c362010c97a02a4642de0b72d80606301be27dea505849753aa8754e081c38e49484b3358524267d3df497a12b8c5d9e9ccd0
+  metadata.gz: b655fda7c0a0b013e006b2586b5b2eec5714106a7877f4b012ed6567af45fedd0320cb8cec8360fc05288924af71e809ce56ce911d2dbb72d7fceb52adf938c2
+  data.tar.gz: 90070ed31d24e9f46f311345a19eaa2ef79b760a9de08cb28c174ee6126e68aa6cd4122fbe8f915d61aaf800801d1dd781b81e86fc7e4aa90595e54be8631435

data/app/components/phlex_kit/alert_dialog/alert_dialog.css

@@ -22,7 +22,9 @@
   gap: 1rem;
   width: calc(100% - 2rem);
   max-width: 32rem;
-  max-height: 100vh;
+  /* Breathing room like dialog.css's max-height — 100vh touched the screen
+     edges and overflowed behind mobile browser chrome (dvh tracks it). */
+  max-height: calc(100dvh - 2rem);
   overflow-y: auto;
   border: 1px solid var(--pk-border);
   border-radius: var(--pk-radius);

data/app/components/phlex_kit/alert_dialog/alert_dialog_content.rb

@@ -20,9 +20,20 @@ module PhlexKit
         # mousedown on the overlay is prevented so a stray click can't move
         # focus out of the trap. tabindex="-1" on the panel is the focus
         # fallback when the dialog has no focusable children.
-        div(data: { controller: "phlex-kit--alert-dialog" }) do
+        # data-pk-overlay-clone is a common marker read across clone-based
+        # overlay families (see #topmost in alert_dialog_controller.js) so
+        # Escape resolves to whichever overlay is actually topmost, even when
+        # a different overlay type (e.g. a Sheet) is nested/stacked on top.
+        div(data: { controller: "phlex-kit--alert-dialog", pk_overlay_clone: "" }) do
           div(class: "pk-alert-dialog-overlay", "aria-hidden": "true", data: { action: "mousedown->phlex-kit--alert-dialog#overlayMousedown" })
-          div(**mix({ role: "alertdialog", "aria-modal": "true", tabindex: "-1", class: [ "pk-alert-dialog-panel", fetch_option(SIZES, @size, :size) ].compact.join(" ") }, @attrs), &block)
+          panel_attrs = { class: [ "pk-alert-dialog-panel", fetch_option(SIZES, @size, :size) ].compact.join(" ") }
+          # Defaults only when the caller didn't supply their own — `mix`
+          # would fuse role="alertdialog dialog" / aria-modal="true false" /
+          # tabindex="-1 0" instead of overriding.
+          panel_attrs[:role] = "alertdialog" unless attr_set?(:role)
+          panel_attrs[:"aria-modal"] = "true" unless aria_key_set?(:modal)
+          panel_attrs[:tabindex] = "-1" unless attr_set?(:tabindex)
+          div(**mix(panel_attrs, @attrs), &block)
         end
       end
     end

data/app/components/phlex_kit/alert_dialog/alert_dialog_controller.js

@@ -29,7 +29,17 @@ export default class extends Controller {
     this.previousOverflow = document.body.style.overflow;
     document.body.style.overflow = "hidden";
     this.onKeydown = (event) => this.keydown(event);
-    this.beforeCache = () => this.element.remove();
+    // Turbo snapshots synchronously right after dispatching this event —
+    // BEFORE Stimulus disconnect() runs (it fires via MutationObserver, too
+    // late). Restore inert + scroll lock here so the snapshot never captures
+    // a fully-inerted, scroll-locked page; disconnect()'s later restore
+    // becomes a harmless no-op (#restoreInert clears `this.inerted`, and
+    // reassigning the same overflow value is idempotent).
+    this.beforeCache = () => {
+      this.#restoreInert();
+      document.body.style.overflow = this.previousOverflow;
+      this.element.remove();
+    };
     document.addEventListener("keydown", this.onKeydown);
     document.addEventListener("turbo:before-cache", this.beforeCache);
     this.#inertOthers();
@@ -40,7 +50,16 @@ export default class extends Controller {
   }
 
   disconnect() {
-    if (this.hasContentTarget) return;
+    if (this.hasContentTarget) {
+      // The source element (holding the template) can disconnect while a
+      // clone it spawned is still live in <body> — e.g. Turbo replacing this
+      // region out from under an open dialog. Remove the orphan rather than
+      // leaving a modal nothing can dismiss. Idempotent: if the clone
+      // already removed itself (Cancel, Escape, its own before-cache),
+      // this.clone is disconnected and the isConnected check no-ops.
+      if (this.clone?.isConnected) this.clone.remove();
+      return;
+    }
     document.removeEventListener("keydown", this.onKeydown);
     document.removeEventListener("turbo:before-cache", this.beforeCache);
     this.#restoreInert();
@@ -76,6 +95,12 @@ export default class extends Controller {
     // handle the keyboard, or one Escape would close every layer at once.
     if (!this.#topmost()) return;
     if (event.key === "Escape") {
+      // A native <dialog> nested inside this panel (e.g. a Dialog opened
+      // from within AlertDialogContent) owns its own Escape handling; this
+      // document-level listener still sees the keydown since it bubbles all
+      // the way up — ignore it so one Escape doesn't also dismiss the alert
+      // dialog underneath (mirrors sheet_content_controller's guard).
+      if (event.target.closest("dialog[open]")) return;
       event.preventDefault();
       this.dismiss();
       return;
@@ -104,12 +129,15 @@ export default class extends Controller {
     }
   }
 
-  // Clones are appended as direct <body> children whose direct child is the
-  // [role="alertdialog"] panel (source elements only hold a <template>, whose
-  // content never matches querySelector). The last such clone is the topmost.
+  // Clones are appended as direct <body> children. Other clone-based overlay
+  // families (sheet/drawer content) stamp the same [data-pk-overlay-clone]
+  // marker on their own clone root, so this checks z-stacking across overlay
+  // TYPES, not just other alert dialogs — a sheet opened from inside an
+  // alert dialog (or vice versa) is a later sibling and must absorb Escape
+  // first; only the last overlay clone overall may act on it.
   #topmost() {
-    const clones = document.body.querySelectorAll(':scope > [data-controller~="phlex-kit--alert-dialog"] > [role="alertdialog"]');
-    return clones.length > 0 && clones[clones.length - 1].parentElement === this.element;
+    const clones = document.body.querySelectorAll(":scope > [data-pk-overlay-clone]");
+    return clones.length > 0 && clones[clones.length - 1] === this.element;
   }
 
   #panel() {

data/app/components/phlex_kit/attachment/attachment.css

@@ -118,6 +118,21 @@
   -webkit-text-fill-color: transparent;
   animation: pk-shimmer 2s linear infinite;
 }
+/* Same two fallback arms as _tokens.css's .pk-shimmer (:49-54): never let the
+   filename disappear under reduced motion or without relative color syntax
+   (Safari <16.4 / Chrome <119). */
+@media (prefers-reduced-motion: reduce) {
+  .pk-attachment[data-state="uploading"] .pk-attachment-title,
+  .pk-attachment[data-state="processing"] .pk-attachment-title {
+    animation: none; background-image: none; -webkit-text-fill-color: currentColor;
+  }
+}
+@supports not (color: oklch(from white l c h)) {
+  .pk-attachment[data-state="uploading"] .pk-attachment-title,
+  .pk-attachment[data-state="processing"] .pk-attachment-title {
+    animation: none; background-image: none; -webkit-text-fill-color: currentColor;
+  }
+}
 .pk-attachment[data-state="error"] { border-color: color-mix(in oklab, var(--pk-red) 40%, transparent); }
 .pk-attachment[data-state="error"] .pk-attachment-media { color: var(--pk-red); background: color-mix(in oklab, var(--pk-red) 12%, transparent); }
 .pk-attachment[data-state="error"] .pk-attachment-description { color: var(--pk-red); }

data/app/components/phlex_kit/attachment/attachment_trigger.rb

@@ -11,6 +11,9 @@ module PhlexKit
       unless AS_TAGS.include?(@as)
         raise ArgumentError, "unknown AttachmentTrigger as: #{@as.inspect} (use one of #{AS_TAGS.join(", ")})"
       end
+      if @as == :a && href.nil?
+        raise ArgumentError, "AttachmentTrigger requires href: when as: :a"
+      end
       @href = href
       @attrs = attrs
     end

data/app/components/phlex_kit/breadcrumb/breadcrumb.css

@@ -3,6 +3,7 @@
   display: flex; flex-wrap: wrap; align-items: center;
   gap: .375rem; word-break: break-word;
   font-size: .875rem; color: var(--pk-muted);
+  list-style: none; margin: 0; padding: 0;
 }
 .pk-breadcrumb-item { display: inline-flex; align-items: center; gap: .25rem; }
 .pk-breadcrumb-link { color: inherit; text-decoration: none; transition: color .15s ease; }

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

@@ -144,9 +144,11 @@ export default class extends Controller {
     const end = this.parseDate(this.rangeEndValue);
 
     if (!start || (start && end)) {
-      // begin a fresh range
+      // begin a fresh range. undefined (not null) clears the value: Stimulus
+      // removes the attribute for undefined, while null goes through
+      // setAttribute and serializes as the literal string "null".
       this.rangeStartValue = this.isoDate(candidate);
-      this.rangeEndValue = null;
+      this.rangeEndValue = undefined;
     } else if (candidate < start) {
       this.rangeStartValue = this.isoDate(candidate);
     } else {
@@ -182,9 +184,10 @@ export default class extends Controller {
       return;
     }
 
-    // update the viewDateValue to the selected date's month (this re-renders)
+    // update the viewDateValue to the selected date's month
     const newViewDate = new Date(selectedDate);
     newViewDate.setDate(2); // avoid month-length/timezone edges
+    this._viewRendered = true;
     this.viewDateValue = this.isoDate(newViewDate);
 
     this.updateCalendar();
@@ -197,6 +200,13 @@ export default class extends Controller {
   }
 
   viewDateValueChanged(value, prevValue) {
+    // Month-cross paths render synchronously right after writing
+    // viewDateValue (focus must land in the NEW grid); this async echo
+    // (MutationObserver) would render the same view a second time.
+    if (this._viewRendered) {
+      this._viewRendered = false;
+      return;
+    }
     this.updateCalendar();
   }
 
@@ -243,7 +253,10 @@ export default class extends Controller {
     return this.isoDate(date);
   }
 
-  updateCalendar() {
+  // `focusDay` overrides the day to refocus after re-render: on a keyboard
+  // month cross the target day lives in the NEW grid, not the pre-render
+  // activeElement, so onKeydown passes it explicitly.
+  updateCalendar(focusDay = null) {
     if (this.hasTitleTarget) {
       this.titleTarget.textContent = this.monthAndYear();
     }
@@ -251,9 +264,11 @@ export default class extends Controller {
     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;
+    const focusedDay =
+      focusDay ||
+      (this.calendarTarget.contains(document.activeElement)
+        ? document.activeElement.dataset?.day
+        : null);
     this.calendarTarget.innerHTML = this.calendarHTML();
     this.ensureGridTabStop(focusedDay);
   }
@@ -282,7 +297,11 @@ export default class extends Controller {
   // 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 };
+    // In RTL the day grid mirrors: the physical LEFT arrow advances one day.
+    // The week steps (Up/Down) and the PageUp/Down/Home/End jumps are
+    // unaffected. Runtime dir check is reliable after a dynamic flip.
+    const rtl = getComputedStyle(this.element).direction === "rtl";
+    const STEPS = { ArrowLeft: rtl ? 1 : -1, ArrowRight: rtl ? -1 : 1, ArrowUp: -7, ArrowDown: 7 };
     const day = e.target.closest?.("[data-day]");
     if (!day) return;
 
@@ -319,7 +338,16 @@ export default class extends Controller {
     }
 
     if (target.getMonth() !== this.viewDate().getMonth() || target.getFullYear() !== this.viewDate().getFullYear()) {
-      this.viewDateValue = iso; // re-renders the grid on the target month
+      // Crossing a month re-renders the grid on the target month. Stimulus
+      // value-changed callbacks fire via MutationObserver (async), so the grid
+      // is NOT re-rendered synchronously after this assignment — querying it
+      // below would hit the OLD month, and the target day (outside it) would be
+      // missing → early return, stranding focus on <body>. Drive the re-render
+      // ourselves and hand it the target day so ensureGridTabStop focuses it.
+      this._viewRendered = true;
+      this.viewDateValue = iso;
+      this.updateCalendar(iso);
+      return;
     }
     const next = this.calendarTarget.querySelector(`[data-day="${iso}"]:not([disabled])`);
     if (!next) return;

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

@@ -10,6 +10,11 @@ const DEFAULT_OPTIONS = {
 const DRAG_DISTANCE_THRESHOLD = 0.25;
 const DRAG_VELOCITY_THRESHOLD = 0.5;
 
+// Subpixel slop when comparing the current offset to the max scrollable
+// offset — layout rounding can leave a fraction of a px short of the true
+// max, which would otherwise read as "can still scroll".
+const OFFSET_EPSILON = 0.5;
+
 // Ported from ruby_ui's carousel controller with the embla-carousel dependency
 // removed: a minimal translate-based engine (scrollNext/scrollPrev, loop, x/y
 // axis from the options value) moves the track directly, so only
@@ -36,6 +41,7 @@ export default class extends Controller {
     this._onPointerMove = this._onPointerMove.bind(this);
     this._onPointerUp = this._onPointerUp.bind(this);
     this._onClickCapture = this._onClickCapture.bind(this);
+    this._onDragStart = this._onDragStart.bind(this);
     window.addEventListener("resize", this._onResize);
     // window resize misses container-only resizes (flex/grid reflow,
     // sidebar toggles) — observe the viewport itself.
@@ -45,6 +51,10 @@ export default class extends Controller {
     }
     this.viewportTarget.addEventListener("pointerdown", this._onPointerDown);
     this.viewportTarget.addEventListener("click", this._onClickCapture, true);
+    // Firefox starts a native image drag on pointerdown-over-<img>, which
+    // cancels the pointer sequence mid-swipe; -webkit-user-drag (CSS) is
+    // WebKit-only, so suppress it here for every browser.
+    this.viewportTarget.addEventListener("dragstart", this._onDragStart);
     this._update();
   }
 
@@ -54,6 +64,7 @@ export default class extends Controller {
     this._resizeObserver = null;
     this.viewportTarget.removeEventListener("pointerdown", this._onPointerDown);
     this.viewportTarget.removeEventListener("click", this._onClickCapture, true);
+    this.viewportTarget.removeEventListener("dragstart", this._onDragStart);
     // 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);
@@ -66,6 +77,14 @@ export default class extends Controller {
   }
 
   scrollNext() {
+    // Non-loop multi-up: the track can hit its max scrollable offset before
+    // the index reaches the last slide (_offsetOf clamps). Once there, index
+    // still has room to climb but there's nothing left to reveal — bail so
+    // neither clicks (button already disables via _update) nor ArrowRight
+    // (keyNext, which routes here) produce dead no-op advances.
+    if (!this.options.loop && this._offsetOf(this.index) >= this._maxOffset() - OFFSET_EPSILON) {
+      return;
+    }
     this._goTo(this.index + 1);
   }
 
@@ -105,8 +124,13 @@ export default class extends Controller {
 
   _update() {
     this._applyTransform();
-    const last = this.slides.length - 1;
-    const canNext = this.options.loop ? this.slides.length > 1 : this.index < last;
+    const canNext = this.options.loop
+      ? this.slides.length > 1
+      // Offset-based, not index-based: with multi-up layouts the track
+      // reaches its max scrollable offset (_maxOffset) before this.index
+      // reaches the last slide, and _offsetOf clamps to that max — an
+      // index-based check left Next enabled for several dead clicks.
+      : this._offsetOf(this.index) < this._maxOffset() - OFFSET_EPSILON;
     const canPrev = this.options.loop ? this.slides.length > 1 : this.index > 0;
     this.nextButtonTargets.forEach((button) => (button.disabled = !canNext));
     this.prevButtonTargets.forEach((button) => (button.disabled = !canPrev));
@@ -189,6 +213,16 @@ export default class extends Controller {
     e.stopPropagation();
   }
 
+  // Firefox-only: a pointer drag that starts on an <img> slide fires a
+  // native HTML5 dragstart, which cancels the in-flight pointer sequence
+  // (pointercancel) and aborts the swipe. Chrome/Safari never fire it here
+  // because carousel.css already sets -webkit-user-drag: none.
+  _onDragStart(e) {
+    if (e.target.closest("img")) {
+      e.preventDefault();
+    }
+  }
+
   // --- geometry ---
 
   _pointerPos(e) {

data/app/components/phlex_kit/chart/chart.rb

@@ -21,15 +21,17 @@ module PhlexKit
     def view_template(&)
       base = {
         class: "pk-chart",
-        # Canvas content is invisible to AT — announce it as an image with at
-        # least a generic name; pass aria: { label: "…" } (or block fallback
-        # content) to describe the actual data.
-        role: "img",
         data: {
           controller: "phlex-kit--chart",
           phlex_kit__chart_options_value: JSON.generate(@options)
         }
       }
+      # Defaults only when the caller didn't supply their own — `mix` would
+      # fuse role="img figure" instead of overriding.
+      # Canvas content is invisible to AT — announce it as an image with at
+      # least a generic name; pass aria: { label: "…" } (or block fallback
+      # content) to describe the actual data.
+      base[:role] = "img" unless attr_set?(:role)
       base[:aria] = { label: "Chart" } unless aria_labelled?
       canvas(**mix(base, @attrs), &)
     end

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

@@ -26,7 +26,7 @@ export default class extends Controller {
   }
 
   disconnect() {
-    this.themeObserver?.disconnect()
+    this.disconnectThemeObservers()
     this.chart?.destroy()
     if (!this.chart) {
       this.dispatch("disconnect", { detail: { canvas: this.element } })
@@ -44,9 +44,14 @@ export default class extends Controller {
   }
 
   // Kit tokens are plain color values (hex / color-mix results), not the hsl
-  // triplets ruby_ui reads — return them as-is.
+  // triplets ruby_ui reads — return them as-is. Resolved from this.element,
+  // not document.documentElement: a .pk-dark island (_tokens.css:123-129)
+  // sets the --pk-* custom properties at the SUBTREE root, and per-element
+  // getComputedStyle correctly picks up the nearest ancestor's values —
+  // reading from the document root would ignore the island and always
+  // return the page-level theme.
   getThemeColor(name) {
-    return getComputedStyle(document.documentElement).getPropertyValue(`--${name}`).trim()
+    return getComputedStyle(this.element).getPropertyValue(`--${name}`).trim()
   }
 
   // shadcn-style series colors: dataset N takes --pk-chart-(N%5 + 1). Line/area
@@ -80,6 +85,13 @@ export default class extends Controller {
 
   setDefaultColorsForChart() {
     const Chart = this.chartLibrary()
+    // Chart.defaults is a library-wide singleton (chart.js has no per-instance
+    // defaults object), so it can only ever reflect ONE theme — the
+    // documented caveat. It's resolved from the document root, not
+    // this.element: a chart inside a .pk-dark island still gets per-dataset
+    // colors from the island (getThemeColor/seriesColor, above), just not
+    // these library-global defaults (grid/tooltip/legend chrome).
+    //
     // 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
@@ -122,20 +134,37 @@ export default class extends Controller {
   // unrelated class flip is the expensive path.
   initThemeObserver() {
     this._themeKey = this.currentThemeKey()
-    this.themeObserver = new MutationObserver(() => {
+    const onMutate = () => {
       const key = this.currentThemeKey()
       if (key === this._themeKey) return
       this._themeKey = key
       this.refreshChart()
-    })
+    }
+    this.themeObserver = new MutationObserver(onMutate)
     this.themeObserver.observe(document.documentElement, { attributeFilter: ["data-theme", "class"] })
+
+    // A .pk-dark island (_tokens.css:123-129) re-themes a subtree without
+    // touching the document root, so the root-only observer above misses it.
+    // Watch the nearest island ancestor too, if this chart lives inside one.
+    const island = this.element.closest(".pk-dark")
+    if (island && island !== document.documentElement) {
+      this.islandObserver = new MutationObserver(onMutate)
+      this.islandObserver.observe(island, { attributeFilter: ["data-theme", "class"] })
+    }
+  }
+
+  disconnectThemeObservers() {
+    this.themeObserver?.disconnect()
+    this.islandObserver?.disconnect()
   }
 
   // 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.
+  // every light/dark pair. Resolved from this.element (island-aware, see
+  // getThemeColor) so a mutation on an ancestor .pk-dark island is detected
+  // even though the document root never changes. One style resolve per
+  // mutation vs a full chart rebuild.
   currentThemeKey() {
-    const styles = getComputedStyle(document.documentElement)
+    const styles = getComputedStyle(this.element)
     return `${styles.getPropertyValue("--pk-bg")}|${styles.getPropertyValue("--pk-text")}`
   }
 

data/app/components/phlex_kit/checkbox/checkbox.rb

@@ -8,11 +8,25 @@ module PhlexKit
   # `name:`/`value:`/`checked:`/`**on(...)` pass through via `mix`. Styled by
   # `.pk-checkbox` (checkbox.css).
   class Checkbox < BaseComponent
-    def initialize(**attrs)
+    # include_hidden mirrors Rails' check_box (and PhlexKit::Switch): an
+    # unchecked box posts nothing, so a paired hidden field carries the
+    # unchecked value. Emitted only when a `name:` is present — and never for
+    # array-style names ("ids[]"), where an unchecked "0" would inject a
+    # bogus element into the collection param (use a single blank hidden for
+    # the whole collection instead, as Rails' collection helpers do).
+    def initialize(include_hidden: true, unchecked_value: "0", **attrs)
+      @include_hidden = include_hidden
+      @unchecked_value = unchecked_value
       @attrs = attrs
     end
 
     def view_template
+      if @include_hidden && @attrs[:name] && !@attrs[:name].to_s.end_with?("[]")
+        # Disabled in lockstep with the checkbox (Rails' check_box idiom) —
+        # a disabled checkbox must not still post its unchecked value.
+        input(type: "hidden", name: @attrs[:name], value: @unchecked_value,
+          disabled: @attrs[:disabled] ? true : nil)
+      end
       input(**mix({
         type: :checkbox,
         class: "pk-checkbox",

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

@@ -12,7 +12,11 @@ module PhlexKit
       # 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.
-      base = { class: "pk-codeblock", tabindex: "0", role: "region", data: { syntax: @syntax } }
+      # Defaults only when the caller didn't supply their own — `mix` would
+      # fuse tabindex="0 -1" / role="region article" instead of overriding.
+      base = { class: "pk-codeblock", data: { syntax: @syntax } }
+      base[:tabindex] = "0" unless attr_set?(:tabindex)
+      base[:role] = "region" unless attr_set?(:role)
       # A region landmark without a name is an axe violation — default one
       # from the syntax; a caller aria: { label: } replaces it (never fused).
       unless aria_labelled?

data/app/components/phlex_kit/combobox/combobox.css

@@ -107,7 +107,7 @@
   padding: .25rem 0;
   border-bottom: 1px solid var(--pk-border);
 }
-.pk-combobox-group::before {
+.pk-combobox-group[data-label]::before {
   content: attr(data-label);
   padding: .375rem .5rem;
   font-size: .75rem;

data/app/components/phlex_kit/combobox/combobox_controller.js

@@ -50,6 +50,10 @@ export default class extends Controller {
     // a restored page doesn't announce an open listbox over a closed combobox.
     this.setExpanded(false)
     this.clearActiveDescendant()
+    // Mirrors select_controller.js's connect(): a Turbo snapshot also
+    // serializes the keyboard-highlighted item's aria-current even though
+    // the popover itself does not survive the restore.
+    this.itemTargets.forEach((item) => item.removeAttribute("aria-current"))
     this.generateItemIds()
     this.updateTriggerContent()
   }
@@ -208,7 +212,19 @@ export default class extends Controller {
     remove.textContent = "×"
     remove.addEventListener("click", (e) => {
       e.stopPropagation() // don't reopen the popover via the trigger's click action
+      // Removing a focused chip drops focus with it (the remove button is
+      // torn out of the DOM by the renderBadges() rebuild below) — hand
+      // focus to the badge input instead of stranding it on <body>.
+      const wasFocused = document.activeElement === remove
       this.uncheck(input)
+      // badgeInput sits inside the trigger wrapper, so focusing it bubbles a
+      // focusin the trigger's own focusin->openPopover action would otherwise
+      // reopen — same guard closePopover() uses for its own focus restore.
+      if (wasFocused && this.hasBadgeInputTarget) {
+        this.refocusing = true
+        this.badgeInputTarget.focus()
+        this.refocusing = false
+      }
     })
 
     badge.append(remove)
@@ -235,6 +251,10 @@ export default class extends Controller {
   }
 
   clearAll(e) {
+    // The clear button hides itself once nothing is checked (updateTriggerContent
+    // below) — if it held focus, hand focus to the badge input rather than
+    // stranding it on a now-hidden element.
+    const wasFocused = this.hasClearButtonTarget && document.activeElement === this.clearButtonTarget
     if (e) {
       e.preventDefault()
       e.stopPropagation() // the button sits inside the trigger's click-to-open area
@@ -246,6 +266,11 @@ export default class extends Controller {
     })
     if (this.hasToggleAllTarget) this.toggleAllTarget.checked = false
     this.updateTriggerContent()
+    if (wasFocused && this.hasBadgeInputTarget) {
+      this.refocusing = true
+      this.badgeInputTarget.focus()
+      this.refocusing = false
+    }
   }
 
   togglePopover(event) {
@@ -303,6 +328,11 @@ export default class extends Controller {
     // aria-activedescendant holds an element id; on close it must be removed,
     // not left pointing at a hidden option.
     this.clearActiveDescendant()
+    // Also drop the highlight itself — otherwise a closed combobox still
+    // exposes an aria-current="true" option that Enter would go on to
+    // activate (APG: Enter on a closed combobox must be a no-op).
+    this.selectedItemIndex = null
+    this.itemTargets.forEach(item => item.ariaCurrent = "false")
     if (this.hasPopoverTarget && this.popoverTarget.matches(":popover-open")) this.popoverTarget.hidePopover()
     this.updateTriggerContent() // reflect the selection into an input trigger
 
@@ -324,6 +354,10 @@ export default class extends Controller {
     if (!this.isOpen()) return
     if (this.element.contains(event.target)) return
 
+    // Kit-wide dismiss contract: the combobox is POPOVER-family (shadcn
+    // builds it on Popover light-dismiss), so the dismissing outside click
+    // deliberately clicks through — no preventDefault. Only the MENU
+    // overlays (dropdown/context/menubar/select) swallow theirs.
     this.closePopover()
   }
 
@@ -349,6 +383,12 @@ export default class extends Controller {
     this.applyFilter(field.value.toLowerCase())
   }
 
+  // Strips combining diacritical marks after an NFD decomposition, so "é"
+  // (query or candidate) matches "e" instead of never comparing equal.
+  normalizeDiacritics(s) {
+    return s.normalize("NFD").replace(/[̀-ͯ]/g, "")
+  }
+
   applyFilter(filterTerm) {
     if (this.hasToggleAllTarget) {
       if (filterTerm) this.toggleAllTarget.parentElement.classList.add("pk-hidden")
@@ -363,10 +403,12 @@ export default class extends Controller {
     // aria-current="true" stayed the Enter target while invisible.
     this.itemTargets.forEach(item => item.ariaCurrent = "false")
 
+    const normalizedFilterTerm = this.normalizeDiacritics(filterTerm)
+
     this.inputTargets.forEach((input) => {
-      const text = this.inputContent(input).toLowerCase()
+      const text = this.normalizeDiacritics(this.inputContent(input).toLowerCase())
 
-      if (text.indexOf(filterTerm) > -1) {
+      if (text.indexOf(normalizedFilterTerm) > -1) {
         input.parentElement.classList.remove("pk-hidden")
         resultCount++
       } else {
@@ -395,6 +437,12 @@ export default class extends Controller {
   keyDownPressed(e) {
     if (e) e.preventDefault()
 
+    // APG: ArrowDown on a closed combobox opens it and highlights the first
+    // option, rather than walking aria-current through invisible options.
+    // openPopover() resets selectedItemIndex to null, so the branch below
+    // still lands on 0.
+    if (!this.isOpen()) this.openPopover()
+
     if (this.selectedItemIndex !== null) {
       this.selectedItemIndex++
     } else {
@@ -407,6 +455,11 @@ export default class extends Controller {
   keyUpPressed(e) {
     if (e) e.preventDefault()
 
+    // Same as keyDownPressed: ArrowUp on a closed combobox opens it and
+    // highlights the last option (wrapSelectedInputIndex turns -1 into the
+    // final index).
+    if (!this.isOpen()) this.openPopover()
+
     if (this.selectedItemIndex !== null) {
       this.selectedItemIndex--
     } else {
@@ -439,6 +492,12 @@ export default class extends Controller {
   }
 
   keyEnterPressed(event) {
+    // APG: Enter on a CLOSED combobox is a no-op — it must not activate
+    // whatever option happened to keep aria-current="true" from before the
+    // popover closed. Bail before preventDefault so a closed field keeps
+    // Enter's ordinary default behaviour.
+    if (!this.isOpen()) return
+
     event.preventDefault()
     const option = this.itemTargets.find(item => item.ariaCurrent === "true")