phlex_kit 0.8.1 → 0.9.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6b7f736afc68bb09cd4706468a8a92b9b4d6085844e0e6813b12181c5b28a9fc
-  data.tar.gz: 480e8e1bc05eb96f3d05a409664737207d76a384cd2ea82d6c401c4298c42c45
+  metadata.gz: 805728288b072fe1663456e789ee106d9ca8398c53b1761255cd0167fd031677
+  data.tar.gz: 1a18b9d368989240e0f16f794ece1a7f8ca1cc9e5dd551ba38dcd002236a5f0e
 SHA512:
-  metadata.gz: 62a50bb438b7c8814f8f32e91619b24f9ba41a3a668991c384b56bcc9fa3f317c9967dc12411a52372476e59b35ad3ef0675f11ad94a0f640d2619d25f02d8e9
-  data.tar.gz: 385f3b984cde9d92cd1e3e21dd78c95583e327f7a57a914183c64504029bf72cb515f29eb155311cd8ecb3cbb2cda053af205e31a161ddb2031333e0ad5f9013
+  metadata.gz: 5b75e4ed5be4c81705389b3e3c9573986e581d04a5a97c8834c58af9f6fdd6977f02599e1aa4708454cf19ee684fd39a76439d26ec165cd47f839aa668f99d13
+  data.tar.gz: 262df1a9e8f8ecb796844c8135b706ffc953baacdb7ac863024041eb7ac28a428dd1d0379fa9cd6779e26b0ea6069a244a7ed7b94d6f4f2c3cf72cf433f9095a

data/app/assets/stylesheets/phlex_kit/_tokens.css

@@ -140,6 +140,13 @@
   --pk-chart-3: #2563eb;
   --pk-chart-4: #1d4ed8;
   --pk-chart-5: #1e40af;
+  /* Shadow/overlay base colors — bare colors; each rule applies its own alpha
+     via color-mix(in srgb, var(--pk-*) N%, transparent). shadcn/ui keeps
+     shadows black in both modes (tailwind's default shadow color), so these
+     are identical in every theme block; restated in the light blocks per the
+     cascade-trap convention anyway. */
+  --pk-shadow-color: #000000;
+  --pk-overlay: #000000;
   --pk-radius: 0.625rem;
   --pk-font-sans: ui-sans-serif, system-ui, -apple-system, sans-serif;
   --pk-font-serif: ui-serif, Georgia, Cambria, "Times New Roman", Times, serif;
@@ -163,6 +170,8 @@
   --pk-green: #16a34a;
   --pk-amber: #d97706;
   --pk-red: #e40014;
+  --pk-shadow-color: #000000;
+  --pk-overlay: #000000;
   color-scheme: light;
 }
 
@@ -183,6 +192,8 @@
     --pk-green: #16a34a;
     --pk-amber: #d97706;
     --pk-red: #e40014;
+    --pk-shadow-color: #000000;
+    --pk-overlay: #000000;
     color-scheme: light;
   }
 }

data/app/components/phlex_kit/accordion/accordion.css

@@ -5,8 +5,8 @@
 .pk-accordion-heading { margin: 0; display: flex; font-size: inherit; font-weight: inherit; line-height: inherit; }
 .pk-accordion-trigger {
   width: 100%; display: flex; flex: 1; align-items: center; justify-content: space-between;
-  padding-block: 1rem; font-size: .875rem; font-weight: 500; text-align: left;
-  background: none; border: 0; cursor: pointer; color: inherit; transition: all .15s ease;
+  padding-block: 1rem; font-size: .875rem; font-weight: 500; text-align: start;
+  background: none; border: 0; cursor: pointer; color: inherit; transition: color .15s ease, background-color .15s ease, text-decoration-color .15s ease;
 }
 .pk-accordion-trigger:hover { text-decoration: underline; }
 .pk-accordion-trigger-label { flex: 1; }

data/app/components/phlex_kit/accordion/accordion_controller.js

@@ -83,13 +83,19 @@ export default class extends Controller {
     if (this.hasIconTarget) this.rotate()
   }
 
+  // Honor prefers-reduced-motion: collapse the grow/shrink to a jump-cut
+  // (duration 0 keeps the finished-promise bookkeeping intact).
+  get effectiveDuration() {
+    return matchMedia("(prefers-reduced-motion: reduce)").matches ? 0 : this.animationDurationValue
+  }
+
   reveal() {
     const c = this.contentTarget
     c.removeAttribute("hidden")
     c.dataset.state = "open"
     const h = c.scrollHeight
     const a = c.animate([{ height: c.style.height || "0px" }, { height: `${h}px` }],
-      { duration: this.animationDurationValue, easing: "ease-in-out" })
+      { duration: this.effectiveDuration, easing: "ease-in-out" })
     c.style.height = `${h}px`
     // Settle at auto, not the frozen pixel height — with overflow hidden a
     // later content growth (or a resize that rewraps text) silently clipped.
@@ -101,7 +107,7 @@ export default class extends Controller {
     c.dataset.state = "closed"
     const from = c.scrollHeight
     const a = c.animate([{ height: `${from}px` }, { height: "0px" }],
-      { duration: this.animationDurationValue, easing: "ease-in-out" })
+      { duration: this.effectiveDuration, easing: "ease-in-out" })
     c.style.height = "0px"
     a.finished.then(() => { if (c.dataset.state === "closed") c.setAttribute("hidden", "") }).catch(() => {})
   }

data/app/components/phlex_kit/alert/alert.css

@@ -14,13 +14,13 @@
   padding: .5rem .625rem;
   font-size: .875rem;
   line-height: 1.25rem;
-  text-align: left;
+  text-align: start;
   background: var(--pk-surface);
   color: var(--pk-text);
 }
 .pk-alert:has(> .pk-alert-action) {
   position: relative;
-  padding-right: 4.5rem;
+  padding-inline-end: 4.5rem;
 }
 .pk-alert:has(> svg) {
   grid-template-columns: auto 1fr;
@@ -66,5 +66,5 @@
 .pk-alert-action {
   position: absolute;
   top: .5rem;
-  right: .5rem;
+  inset-inline-end: .5rem;
 }

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

@@ -8,7 +8,7 @@
   position: fixed;
   inset: 0;
   z-index: 50;
-  background: rgb(0 0 0 / .1);
+  background: color-mix(in srgb, var(--pk-overlay) 10%, transparent);
   backdrop-filter: blur(4px);
 }
 .pk-alert-dialog-panel {
@@ -30,7 +30,7 @@
   color: var(--pk-text);
   --pk-dialog-spacing: 1.5rem;
   padding: var(--pk-dialog-spacing);
-  box-shadow: 0 10px 40px rgba(0, 0, 0, .5);
+  box-shadow: 0 10px 40px color-mix(in srgb, var(--pk-shadow-color) 50%, transparent);
 }
 .pk-alert-dialog-panel.sm { max-width: 24rem; --pk-dialog-spacing: 1rem; gap: .75rem; }
 .pk-alert-dialog-panel.sm .pk-alert-dialog-title { font-size: 1rem; }
@@ -77,5 +77,5 @@
   background: color-mix(in oklab, var(--pk-surface-2) 50%, transparent);
 }
 @supports not (backdrop-filter: blur(1px)) {
-  .pk-alert-dialog-overlay { background: rgb(0 0 0 / .5); }
+  .pk-alert-dialog-overlay { background: color-mix(in srgb, var(--pk-overlay) 50%, transparent); }
 }

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

@@ -1,7 +1,9 @@
 module PhlexKit
   # The modal body, held in a <template> and cloned into <body> on open. The
   # cloned div carries its own `phlex-kit--alert-dialog` controller so Cancel
-  # (#dismiss) can remove it. Holds Header + Footer. See alert_dialog.rb.
+  # (#dismiss) can remove it. Holds Header + Footer. Caller **attrs land on the
+  # visible panel (the role="alertdialog" div), not the inert <template>.
+  # See alert_dialog.rb.
   class AlertDialogContent < BaseComponent
     # size => panel modifier; :sm is shadcn's compact variant.
     SIZES = { default: nil, sm: "sm" }.freeze
@@ -12,13 +14,15 @@ module PhlexKit
     end
 
     def view_template(&block)
-      template(**mix({ data: { phlex_kit__alert_dialog_target: "content" } }, @attrs)) do
-        # keydown on the clone root: focus is trapped inside the panel, so
-        # Escape/Tab always bubble here; tabindex="-1" on the panel is the
-        # focus fallback when the dialog has no focusable children.
-        div(data: { controller: "phlex-kit--alert-dialog", action: "keydown->phlex-kit--alert-dialog#keydown" }) do
-          div(class: "pk-alert-dialog-overlay", "aria-hidden": "true")
-          div(role: "alertdialog", "aria-modal": "true", tabindex: "-1", class: [ "pk-alert-dialog-panel", fetch_option(SIZES, @size, :size) ].compact.join(" "), &block)
+      template(data: { phlex_kit__alert_dialog_target: "content" }) do
+        # The clone's controller listens for keydown on `document` while open
+        # (an element-scoped listener dies the moment focus escapes to <body>);
+        # 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
+          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)
         end
       end
     end

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

@@ -6,10 +6,14 @@ import { Controller } from "@hotwired/stimulus";
 // clone's lifetime (mirroring sheet_content_controller): scroll lock, initial
 // focus (the Cancel action when present — APG wants the least destructive
 // control), Tab focus trap, Escape-to-dismiss, focus restore to the opener,
-// and aria-labelledby/-describedby wiring to Title/Description. connect and
-// disconnect exactly bracket the clone, so removal by any path restores state.
+// background inert, and aria-labelledby/-describedby wiring to
+// Title/Description. Escape/Tab are handled by a document-level keydown
+// listener (an element-scoped one dies the moment focus escapes to <body>);
+// the overlay's mousedown guard keeps focus from leaving the trap. connect and
+// disconnect exactly bracket the clone, so removal by any path (Cancel,
+// Escape, turbo:before-cache) restores state.
 const FOCUSABLE =
-  'a[href], button:not([disabled]), input:not([disabled]), select, textarea, [tabindex]:not([tabindex="-1"])';
+  'a[href], button:not([disabled]), input:not([disabled]), select:not([disabled]), textarea:not([disabled]), [tabindex]:not([tabindex="-1"])';
 
 export default class extends Controller {
   static targets = ["content"];
@@ -24,6 +28,11 @@ export default class extends Controller {
     this.opener = document.activeElement;
     this.previousOverflow = document.body.style.overflow;
     document.body.style.overflow = "hidden";
+    this.onKeydown = (event) => this.keydown(event);
+    this.beforeCache = () => this.element.remove();
+    document.addEventListener("keydown", this.onKeydown);
+    document.addEventListener("turbo:before-cache", this.beforeCache);
+    this.#inertOthers();
     this.#wireAria();
     const focusables = this.#focusables();
     const cancel = focusables.find((el) => (el.dataset.action || "").includes("#dismiss"));
@@ -32,6 +41,9 @@ export default class extends Controller {
 
   disconnect() {
     if (this.hasContentTarget) return;
+    document.removeEventListener("keydown", this.onKeydown);
+    document.removeEventListener("turbo:before-cache", this.beforeCache);
+    this.#restoreInert();
     document.body.style.overflow = this.previousOverflow;
     if (this.opener?.isConnected) this.opener.focus();
   }
@@ -48,6 +60,13 @@ export default class extends Controller {
     this.element.remove();
   }
 
+  // Overlay mousedown would move focus to <body>, killing an element-scoped
+  // trap; prevented here so focus stays inside the panel (the overlay is
+  // deliberately NOT a dismiss surface on an alert dialog).
+  overlayMousedown(event) {
+    event.preventDefault();
+  }
+
   keydown(event) {
     if (event.key === "Escape") {
       event.preventDefault();
@@ -61,6 +80,12 @@ export default class extends Controller {
       this.#panel()?.focus();
       return;
     }
+    // Focus somehow left the dialog (e.g. programmatically): pull it back in.
+    if (!this.element.contains(document.activeElement)) {
+      event.preventDefault();
+      focusables[0].focus();
+      return;
+    }
     const first = focusables[0];
     const last = focusables[focusables.length - 1];
     if (event.shiftKey && (document.activeElement === first || document.activeElement === this.#panel())) {
@@ -82,6 +107,24 @@ export default class extends Controller {
     return [...panel.querySelectorAll(FOCUSABLE)].filter((el) => el.getClientRects().length > 0);
   }
 
+  // Make everything behind the modal inert (the clone is <body>'s last child,
+  // so its siblings are the whole page). Prior inert state is saved per
+  // element and restored on disconnect.
+  #inertOthers() {
+    this.inerted = [];
+    for (const el of document.body.children) {
+      if (el === this.element) continue;
+      if (["SCRIPT", "STYLE", "LINK", "TEMPLATE"].includes(el.tagName)) continue;
+      this.inerted.push([el, el.inert]);
+      el.inert = true;
+    }
+  }
+
+  #restoreInert() {
+    for (const [el, wasInert] of this.inerted || []) el.inert = wasInert;
+    this.inerted = null;
+  }
+
   #wireAria() {
     const panel = this.#panel();
     if (!panel) return;

data/app/components/phlex_kit/aspect_ratio/aspect_ratio.rb

@@ -16,8 +16,10 @@ module PhlexKit
 
     def view_template(&block)
       # **mix on the ROOT (kit rule) — caller attrs previously landed on the
-      # inner div and could never reach the actual root element.
-      div(**mix({ class: "pk-aspect-ratio", style: "padding-bottom: #{padding_bottom}%" }, @attrs)) do
+      # inner div and could never reach the actual root element. The trailing
+      # ";" matters: mix joins duplicate string attrs with a space, so a
+      # caller style: would otherwise fuse into one invalid declaration.
+      div(**mix({ class: "pk-aspect-ratio", style: "padding-bottom: #{padding_bottom}%;" }, @attrs)) do
         div(class: "pk-aspect-ratio-inner", &block)
       end
     end

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

@@ -92,7 +92,7 @@
 .pk-attachment.vertical .pk-attachment-actions {
   position: absolute;
   top: .75rem;
-  right: .75rem;
+  inset-inline-end: .75rem;
 }
 .pk-attachment.vertical .pk-attachment-action {
   background: color-mix(in oklab, var(--pk-bg) 60%, transparent);

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

@@ -1,8 +1,12 @@
 module PhlexKit
-  # Small ghost icon button in an Attachment (remove/download). Give it an
-  # aria-label; block content is the icon (defaults to ×). See attachment.rb.
+  # Small ghost icon button in an Attachment (remove/download). Block content
+  # is the icon (defaults to ×). `label:` renders a pk-sr-only span so the
+  # icon-only button always has an accessible name (default "Remove") —
+  # override it per action, or pass `label: nil` when supplying your own
+  # aria-label. See attachment.rb.
   class AttachmentAction < BaseComponent
-    def initialize(**attrs)
+    def initialize(label: "Remove", **attrs)
+      @label = label
       @attrs = attrs
     end
 
@@ -13,6 +17,7 @@ module PhlexKit
         else
           render Icon.new(:x, size: nil)
         end
+        span(class: "pk-sr-only") { @label } if @label
       end
     end
   end

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

@@ -10,12 +10,12 @@ module PhlexKit
       @attrs = attrs
     end
 
-    def view_template
+    def view_template(&block)
       base = { class: "pk-attachment-trigger" }
       if @as == :a
-        a(**mix(base.merge(href: @href), @attrs))
+        a(**mix(base.merge(href: @href), @attrs), &block)
       else
-        button(**mix(base.merge(type: :button), @attrs))
+        button(**mix(base.merge(type: :button), @attrs), &block)
       end
     end
   end

data/app/components/phlex_kit/attachment/scroll_fade_controller.js

@@ -11,11 +11,19 @@ export default class extends Controller {
   connect() {
     this._onScroll = () => this.update()
     this.element.addEventListener("scroll", this._onScroll, { passive: true })
+    // Content changes (items added/removed, images sizing in) and container
+    // resizes shift the overflow edges — without these the masks go stale.
+    this._resizeObserver = new ResizeObserver(() => this.update())
+    this._resizeObserver.observe(this.element)
+    this._mutationObserver = new MutationObserver(() => this.update())
+    this._mutationObserver.observe(this.element, { childList: true, subtree: true })
     this.update()
   }
 
   disconnect() {
     this.element.removeEventListener("scroll", this._onScroll)
+    this._resizeObserver?.disconnect()
+    this._mutationObserver?.disconnect()
   }
 
   update() {

data/app/components/phlex_kit/avatar/avatar.css

@@ -2,9 +2,11 @@
    Group / GroupCount). Matched to shadcn/ui's current avatar (nova): the root
    is NOT overflow-clipped (a Badge hangs over the edge) — image and fallback
    round themselves, and a ::after overlay draws the hairline border, blended
-   darken (light mode) / lighten (dark mode) so it hugs any photo. The
-   controller toggles `.hidden` between image and fallback. shadcn ships
-   sm/default/lg; xs/xl are kit extras. */
+   darken (light mode) / lighten (dark mode) so it hugs any photo. The image
+   is absolutely stacked over the in-flow fallback (both can coexist without
+   squashing pre-hydration / no-JS); the controller then toggles `.pk-hidden`
+   between them as progressive enhancement. shadcn ships sm/default/lg;
+   xs/xl are kit extras. */
 .pk-avatar {
   position: relative;
   display: inline-flex;
@@ -33,7 +35,14 @@
 .pk-avatar.lg { height: 2.5rem; width: 2.5rem; font-size: 1rem; }
 .pk-avatar.xl { height: 5rem; width: 5rem; font-size: 1.875rem; }
 
+/* Stacked over the fallback: pre-hydration both render, and as flex siblings
+   they squashed into half-circles. Absolutely positioning the image lets a
+   loaded image simply cover the fallback with no JS at all; on 404 the
+   fallback stays visible underneath (and the controller removes the broken
+   image once it runs). */
 .pk-avatar-image {
+  position: absolute;
+  inset: 0;
   aspect-ratio: 1 / 1;
   height: 100%;
   width: 100%;
@@ -50,7 +59,9 @@
   background: var(--pk-surface-2);
   color: var(--pk-muted);
 }
-.pk-avatar-image.hidden, .pk-avatar-fallback.hidden { display: none; }
+/* Local restatement of the kit-wide .pk-hidden utility (_tokens.css) so the
+   controller's toggle also holds if avatar.css is consumed standalone. */
+.pk-avatar-image.pk-hidden, .pk-avatar-fallback.pk-hidden { display: none; }
 
 /* Status dot pinned to the bottom-right corner; sized by the avatar's size
    modifier, glyph hidden when there's no room (shadcn's AvatarBadge). */
@@ -84,7 +95,7 @@
 .pk-avatar-group { display: flex; }
 .pk-avatar-group .pk-avatar,
 .pk-avatar-group .pk-avatar-group-count { box-shadow: 0 0 0 2px var(--pk-bg); }
-.pk-avatar-group > :not(:first-child) { margin-left: -.5rem; }
+.pk-avatar-group > :not(:first-child) { margin-inline-start: -.5rem; }
 
 .pk-avatar-group-count {
   position: relative;

data/app/components/phlex_kit/avatar/avatar_controller.js

@@ -1,8 +1,11 @@
 import { Controller } from "@hotwired/stimulus";
 
-// Ported verbatim from ruby_ui's phlex-kit--avatar controller. Shows the image once
-// it has loaded (else the fallback). With no image target (fallback-only avatar)
-// connect() no-ops and the fallback stays visible.
+// Ported from ruby_ui's phlex-kit--avatar controller. Shows the image once it
+// has loaded (else the fallback). With no image target (fallback-only avatar)
+// connect() no-ops and the fallback stays visible. Purely progressive
+// enhancement: the CSS stacks the image over the fallback, so with no JS a
+// loaded image covers the fallback and a failed one leaves it showing. Uses
+// the kit's .pk-hidden utility (not a bare .hidden).
 export default class extends Controller {
   static targets = ["image", "fallback"];
 
@@ -19,12 +22,12 @@ export default class extends Controller {
   }
 
   showImage() {
-    this.imageTargets.forEach((image) => image.classList.remove("hidden"));
-    this.fallbackTargets.forEach((fallback) => fallback.classList.add("hidden"));
+    this.imageTargets.forEach((image) => image.classList.remove("pk-hidden"));
+    this.fallbackTargets.forEach((fallback) => fallback.classList.add("pk-hidden"));
   }
 
   showFallback() {
-    this.imageTargets.forEach((image) => image.classList.add("hidden"));
-    this.fallbackTargets.forEach((fallback) => fallback.classList.remove("hidden"));
+    this.imageTargets.forEach((image) => image.classList.add("pk-hidden"));
+    this.fallbackTargets.forEach((fallback) => fallback.classList.remove("pk-hidden"));
   }
 }

data/app/components/phlex_kit/badge/badge.css

@@ -26,8 +26,8 @@
 }
 /* shadcn forces glyphs to size-3 with `!` — override Spinner's own sizing. */
 .pk-badge > svg { width: .75rem !important; height: .75rem !important; pointer-events: none; }
-.pk-badge:has(> [data-icon="inline-start"]) { padding-left: .375rem; }
-.pk-badge:has(> [data-icon="inline-end"]) { padding-right: .375rem; }
+.pk-badge:has(> [data-icon="inline-start"]) { padding-inline-start: .375rem; }
+.pk-badge:has(> [data-icon="inline-end"]) { padding-inline-end: .375rem; }
 .pk-badge:focus-visible {
   outline: none;
   border-color: var(--pk-ring);
@@ -36,8 +36,8 @@
 
 /* Sizes (md is the base above) — kit extras. */
 .pk-badge.sm { height: 1rem; padding: 0 .375rem; font-size: .7rem; }
-.pk-badge.sm:has(> [data-icon="inline-start"]) { padding-left: .25rem; }
-.pk-badge.sm:has(> [data-icon="inline-end"]) { padding-right: .25rem; }
+.pk-badge.sm:has(> [data-icon="inline-start"]) { padding-inline-start: .25rem; }
+.pk-badge.sm:has(> [data-icon="inline-end"]) { padding-inline-end: .25rem; }
 .pk-badge.lg { height: 1.5rem; padding: .125rem .75rem; font-size: .875rem; }
 
 .pk-badge.primary { background: var(--pk-brand); color: var(--pk-brand-ink); }

data/app/components/phlex_kit/breadcrumb/breadcrumb_ellipsis.rb

@@ -2,7 +2,9 @@ module PhlexKit
   class BreadcrumbEllipsis < BaseComponent
     def initialize(**attrs) = (@attrs = attrs)
     def view_template
-      span(**mix({ class: "pk-breadcrumb-ellipsis", role: "presentation", aria: { hidden: true } }, @attrs)) do
+      # No aria-hidden on the wrapper — it would swallow the sr-only text.
+      # The Icon renders its own aria-hidden="true"; only the glyph is hidden.
+      span(**mix({ class: "pk-breadcrumb-ellipsis", role: "presentation" }, @attrs)) do
         render Icon.new(:ellipsis, size: nil)
         span(class: "pk-sr-only") { "More" }
       end

data/app/components/phlex_kit/bubble/bubble.css

@@ -18,7 +18,7 @@
   padding: .5rem .75rem; font-size: .875rem; line-height: 1.625;
 }
 .pk-bubble[data-align="end"] > .pk-bubble-content { align-self: flex-end; }
-button.pk-bubble-content { text-align: left; font: inherit; }
+button.pk-bubble-content { text-align: start; font: inherit; }
 a.pk-bubble-content { color: inherit; text-decoration: none; }
 button.pk-bubble-content, a.pk-bubble-content {
   cursor: pointer; outline: none;
@@ -69,5 +69,5 @@ button.pk-bubble-content, a.pk-bubble-content {
 .pk-bubble-reactions:has(button) { padding: 0; }
 .pk-bubble-reactions[data-side="bottom"] { bottom: 0; transform: translateY(75%); }
 .pk-bubble-reactions[data-side="top"] { top: 0; transform: translateY(-75%); }
-.pk-bubble-reactions[data-align="end"] { right: .75rem; }
-.pk-bubble-reactions[data-align="start"] { left: .75rem; }
+.pk-bubble-reactions[data-align="end"] { inset-inline-end: .75rem; }
+.pk-bubble-reactions[data-align="start"] { inset-inline-start: .75rem; }

data/app/components/phlex_kit/bubble/bubble.rb

@@ -4,10 +4,12 @@ module PhlexKit
   # trailing edge. Compose Bubble > BubbleContent (+ BubbleReactions).
   class Bubble < BaseComponent
     VARIANTS = %i[default secondary muted tinted outline ghost destructive].freeze
+    ALIGNS = %i[start end].freeze
     def initialize(variant: :default, align: :start, **attrs)
       @variant = variant.to_sym
       raise KeyError, "unknown Bubble variant #{@variant}" unless VARIANTS.include?(@variant)
       @align = align.to_sym
+      raise KeyError, "unknown Bubble align #{@align}" unless ALIGNS.include?(@align)
       @attrs = attrs
     end
     def view_template(&)

data/app/components/phlex_kit/bubble/bubble_content.rb

@@ -1,7 +1,11 @@
 module PhlexKit
   class BubbleContent < BaseComponent
+    # `as:` is dispatched dynamically — whitelist the sensible text containers
+    # so it can't reach arbitrary (including private) methods.
+    AS_TAGS = %i[div p blockquote].freeze
     def initialize(as: :div, **attrs)
-      @as = as
+      @as = as.to_sym
+      raise ArgumentError, "unknown BubbleContent as: #{@as.inspect} (use one of #{AS_TAGS.join(", ")})" unless AS_TAGS.include?(@as)
       @attrs = attrs
     end
     def view_template(&)

data/app/components/phlex_kit/bubble/bubble_reactions.rb

@@ -1,8 +1,12 @@
 module PhlexKit
   class BubbleReactions < BaseComponent
+    SIDES = %i[top bottom].freeze
+    ALIGNS = %i[start end].freeze
     def initialize(side: :bottom, align: :end, **attrs)
       @side = side.to_sym
+      raise KeyError, "unknown BubbleReactions side #{@side}" unless SIDES.include?(@side)
       @align = align.to_sym
+      raise KeyError, "unknown BubbleReactions align #{@align}" unless ALIGNS.include?(@align)
       @attrs = attrs
     end
     def view_template(&)

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",