phlex_kit 0.8.0 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f17bf0029690be129f5e5d77449b9ebb5632d22151ed3508789683b135a7e03f
-  data.tar.gz: 2145e97971f4fba1e283d979f454562839a76bae767c29755d3e9ff01639e306
+  metadata.gz: f52a630c21854a2d2823951ef321a7749ff01adf9d5f60b0c3483aa635407aaa
+  data.tar.gz: c0a594263a95f57bf56b20955054369cc251d58fb6ecbc2bd22b45aa3b4dd278
 SHA512:
-  metadata.gz: 67b7a4e80b51796f3bfc1177be569bf13d064e01b491c5be427baf7275ca87f4fd45d243dfd5f3bdf49fd48735b00fe084ea17e93d48cca62d5b28401c33ca0e
-  data.tar.gz: fd0c992227463320e3869ac7917b8ac63c7bbbd5bc468388de7ef00cbec003e0f333c37dde32711c8fed263bb95abbdde2b9bef1789990e8070f4b2b6fc16d29
+  metadata.gz: 5c1b054a1ce8c3c1f01e4530dccdda7e23b013e2e0b3ccd966959d9419b784c462a2da725c9eefbb78b2d71675edc2d553de42745675c768c5621b31c0a41685
+  data.tar.gz: ee5a88c2c3615582fd51ca3b75d9574aba7dfedadca8e1fe2879370e052b311f2904a6ca3469ceba6fd256392becec583d3ae14c0ccb8df6c6196ab2b7cddd17

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_content.rb

@@ -1,10 +1,19 @@
 module PhlexKit
   class AccordionContent < BaseComponent
-    def initialize(**attrs) = (@attrs = attrs)
+    # Pass `open: true` alongside AccordionItem(open: true) so the content is
+    # readable without JS — the closed-state hidden + height:0 otherwise makes
+    # a server-rendered open item unreachable pre-hydration.
+    def initialize(open: false, **attrs)
+      @open = open
+      @attrs = attrs
+    end
+
     def view_template(&)
       # role="region" + aria-labelledby → trigger id (wired by the controller
       # in connect(), which also assigns the ids), per the APG accordion pattern.
-      div(**mix({ class: "pk-accordion-content", role: "region", data: { phlex_kit__accordion_target: "content", state: "closed" }, style: "height: 0px;", hidden: true }, @attrs), &)
+      base = { class: "pk-accordion-content", role: "region", data: { phlex_kit__accordion_target: "content", state: @open ? "open" : "closed" } }
+      base.merge!(style: "height: 0px;", hidden: true) unless @open
+      div(**mix(base, @attrs), &)
     end
   end
 end

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

@@ -15,8 +15,11 @@ export default class extends Controller {
 
   connect() {
     this.wireAria()
+    // Apply the initial state without animating (the initial valueChanged
+    // callback is skipped — it fires before connect()).
     const d = this.animationDurationValue
     this.animationDurationValue = 0
+    if (this.hasTriggerTarget) this.triggerTarget.setAttribute("aria-expanded", this.openValue ? "true" : "false")
     this.openValue ? this.open() : this.close()
     this.animationDurationValue = d
   }
@@ -34,11 +37,18 @@ export default class extends Controller {
     if (!root || root.dataset.type !== "single") return
     root.querySelectorAll('[data-controller~="phlex-kit--accordion"]').forEach((el) => {
       if (el === this.element) return
+      // Skip items of a NESTED accordion — querySelectorAll descends into
+      // item content, and opening an outer item collapsed inner ones too.
+      if (el.closest(".pk-accordion") !== root) return
       const ctrl = this.application.getControllerForElementAndIdentifier(el, "phlex-kit--accordion")
       if (ctrl && ctrl.openValue) ctrl.openValue = false
     })
   }
-  openValueChanged(isOpen) {
+  openValueChanged(isOpen, wasOpen) {
+    // Stimulus fires the initial value callback BEFORE connect() — before
+    // connect zeroes the duration — so a server-rendered open item visibly
+    // animated open on every page load. connect() applies the initial state.
+    if (wasOpen === undefined) return
     if (this.hasTriggerTarget) this.triggerTarget.setAttribute("aria-expanded", isOpen ? "true" : "false")
     isOpen ? this.open() : this.close()
   }
@@ -73,14 +83,23 @@ 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
-    c.animate([{ height: c.style.height || "0px" }, { height: `${h}px` }],
-      { duration: this.animationDurationValue, easing: "ease-in-out" })
+    const a = c.animate([{ height: c.style.height || "0px" }, { height: `${h}px` }],
+      { 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.
+    a.finished.then(() => { if (c.dataset.state === "open") c.style.height = "auto" }).catch(() => {})
   }
 
   hide() {
@@ -88,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,10 +14,15 @@ module PhlexKit
     end
 
     def view_template(&block)
-      template(**mix({ data: { phlex_kit__alert_dialog_target: "content" } }, @attrs)) do
+      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")
-          div(role: "alertdialog", "aria-modal": "true", class: [ "pk-alert-dialog-panel", fetch_option(SIZES, @size, :size) ].compact.join(" "), &block)
+          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

@@ -1,24 +1,141 @@
 import { Controller } from "@hotwired/stimulus";
 
 // Ported from ruby_ui's phlex-kit--alert-dialog controller. open() clones the
-// <template> content into <body> as a modal (the clone carries its own instance
-// of this controller); dismiss() removes it. The only change from upstream: lock
-// body scroll via inline style rather than a Tailwind `overflow-hidden` class.
+// <template> content into <body> as a modal; the clone carries its own
+// instance of this controller, which owns the full modal contract for the
+// 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,
+// 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:not([disabled]), textarea:not([disabled]), [tabindex]:not([tabindex="-1"])';
+
 export default class extends Controller {
   static targets = ["content"];
   static values = { open: { type: Boolean, default: false } };
 
   connect() {
-    if (this.openValue) this.open();
+    // The source element holds the <template>; the clone in <body> does not.
+    if (this.hasContentTarget) {
+      if (this.openValue) this.open();
+      return;
+    }
+    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"));
+    (cancel || focusables[0] || this.#panel())?.focus();
+  }
+
+  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();
   }
 
   open() {
+    // Double-open guard: Enter+click (or a double-click) on the trigger must
+    // not stack a second clone over the first.
+    if (this.clone?.isConnected) return;
     document.body.insertAdjacentHTML("beforeend", this.contentTarget.innerHTML);
-    document.body.style.overflow = "hidden";
+    this.clone = document.body.lastElementChild;
   }
 
   dismiss() {
-    document.body.style.overflow = "";
     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();
+      this.dismiss();
+      return;
+    }
+    if (event.key !== "Tab") return;
+    const focusables = this.#focusables();
+    if (focusables.length === 0) {
+      event.preventDefault();
+      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())) {
+      event.preventDefault();
+      last.focus();
+    } else if (!event.shiftKey && document.activeElement === last) {
+      event.preventDefault();
+      first.focus();
+    }
+  }
+
+  #panel() {
+    return this.element.querySelector('[role="alertdialog"]');
+  }
+
+  #focusables() {
+    const panel = this.#panel();
+    if (!panel) return [];
+    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;
+    const wire = (attr, selector) => {
+      if (panel.getAttribute(attr)) return;
+      const el = this.element.querySelector(selector);
+      if (!el) return;
+      if (!el.id) el.id = `pk-alert-dialog-${Math.random().toString(36).slice(2, 10)}`;
+      panel.setAttribute(attr, el.id);
+    };
+    wire("aria-labelledby", ".pk-alert-dialog-title");
+    wire("aria-describedby", ".pk-alert-dialog-description");
+  }
 }

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

@@ -5,16 +5,22 @@ module PhlexKit
   # `.pk-aspect-ratio*` (aspect_ratio.css).
   class AspectRatio < BaseComponent
     def initialize(aspect_ratio: "16/9", **attrs)
-      unless aspect_ratio.is_a?(String) && aspect_ratio.include?("/")
-        raise ArgumentError, %(aspect_ratio must be a "w/h" string (e.g. "16/9"))
+      # Both terms must be positive integers — "16/0" yields Infinity% and
+      # "a/b" NaN% padding, silently breaking the layout.
+      unless aspect_ratio.is_a?(String) && aspect_ratio.match?(%r{\A[1-9]\d*/[1-9]\d*\z})
+        raise ArgumentError, %(aspect_ratio must be a "w/h" string of positive integers (e.g. "16/9"))
       end
       @aspect_ratio = aspect_ratio
       @attrs = attrs
     end
 
     def view_template(&block)
-      div(class: "pk-aspect-ratio", style: "padding-bottom: #{padding_bottom}%") do
-        div(**mix({ class: "pk-aspect-ratio-inner" }, @attrs), &block)
+      # **mix on the ROOT (kit rule) — caller attrs previously landed on the
+      # 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(&)