phlex_kit 0.9.1 → 0.11.0

data/app/components/phlex_kit/context_menu/context_menu_sub_trigger.rb

@@ -9,7 +9,9 @@ module PhlexKit
         # -1: roving focus reaches it via arrows (focus-within opens the sub);
         # tabindex 0 made it a stray tab stop inside the menu.
         tabindex: "-1",
-        aria: { haspopup: "menu" },
+        # expanded starts false and is mirrored live by the controller's
+        # syncSub (the reveal itself is pure CSS :hover/:focus-within).
+        aria: { haspopup: "menu", expanded: "false" },
         data: { phlex_kit__context_menu_target: "menuItem" }
       }, @attrs)) do
         block&.call

data/app/components/phlex_kit/data_table/data_table.css

@@ -23,16 +23,6 @@
 /* "Columns" dropdown rows. */
 .pk-data-table-column-toggle { position: relative; }
 .pk-data-table-column-toggle-icon { width: 1rem; height: 1rem; margin-inline-start: .25rem; }
-.pk-data-table-column-option {
-  display: flex;
-  align-items: center;
-  gap: .5rem;
-  border-radius: calc(var(--pk-radius) - 4px);
-  padding: .375rem .5rem;
-  font-size: .875rem;
-  cursor: pointer;
-}
-.pk-data-table-column-option:hover { background: var(--pk-accent); }
 
 /* Sortable header link. */
 .pk-data-table-sort-head { color: var(--pk-text); white-space: nowrap; }

data/app/components/phlex_kit/data_table/data_table_column_toggle.rb

@@ -27,7 +27,10 @@ module PhlexKit
               # invalid ARIA. The change event bubbles from the hidden checkbox
               # to this row, where our toggle action picks it up.
               render DropdownMenuCheckboxItem.new(
-                checked: true,
+                # visible: false starts the menu row unchecked for a column
+                # the host server-renders hidden (pk-hidden on its cells) —
+                # checked: true hardcoded meant the two could never agree.
+                checked: col.fetch(:visible, true),
                 data: {
                   column_key: col[:key].to_s,
                   action: "change->phlex-kit--data-table-column-visibility#toggle"

data/app/components/phlex_kit/data_table/data_table_controller.js

@@ -20,7 +20,11 @@ export default class extends Controller {
   toggleAll(event) {
     const checked = event.target.checked;
     this.rowCheckboxTargets.forEach((cb) => {
+      if (cb.checked === checked) return;
       cb.checked = checked;
+      // Programmatic .checked flips fire no event — hosts (and the
+      // form-field wiring on PhlexKit::Checkbox) must still hear select-all.
+      cb.dispatchEvent(new Event("change", { bubbles: true }));
     });
     this.updateState();
   }

data/app/components/phlex_kit/date_picker/date_picker.rb

@@ -31,6 +31,12 @@ module PhlexKit
       # until the first interaction.
       @value = value || format_selected_date
       @placeholder = placeholder
+      # An id smuggled through input_attrs would MERGE with the generated one
+      # (mix fuses duplicate string attrs), breaking label[for] and the
+      # calendar outlet selector — the top-level id: kwarg is the one path.
+      if input_attrs.key?(:id) || input_attrs.key?("id")
+        raise ArgumentError, "DatePicker: pass id: as the top-level kwarg, not input_attrs[:id]"
+      end
       @input_attrs = input_attrs
       @calendar_attrs = calendar_attrs
       @trigger_attrs = trigger_attrs

data/app/components/phlex_kit/dialog/dialog.css

@@ -11,10 +11,12 @@
   --pk-dialog-spacing: 1rem;
   position: fixed; z-index: 50; width: 100%;
   max-width: min(24rem, calc(100% - 2rem));
-  max-height: 100vh;
+  /* Breathing room like the horizontal inset — 100vh touched the screen
+     edges and overflowed behind mobile browser chrome (dvh tracks it). */
+  max-height: calc(100dvh - 2rem);
   overflow-y: auto; gap: 1rem;
   border: 1px solid color-mix(in oklab, var(--pk-text) 10%, transparent);
-  border-radius: .75rem; background: var(--pk-surface); color: var(--pk-text);
+  border-radius: calc(var(--pk-radius) + 2px); background: var(--pk-surface); color: var(--pk-text);
   padding: var(--pk-dialog-spacing);
   font-size: .875rem;
   box-shadow: 0 10px 30px color-mix(in srgb, var(--pk-shadow-color) 35%, transparent);
@@ -35,7 +37,7 @@
   margin: 0 calc(-1 * var(--pk-dialog-spacing)) calc(-1 * var(--pk-dialog-spacing));
   padding: var(--pk-dialog-spacing);
   border-top: 1px solid var(--pk-border);
-  border-radius: 0 0 .75rem .75rem;
+  border-radius: 0 0 calc(var(--pk-radius) + 2px) calc(var(--pk-radius) + 2px);
   background: color-mix(in oklab, var(--pk-surface-2) 50%, transparent);
 }
 .pk-dialog-title { font-size: 1rem; font-weight: 500; line-height: 1; }

data/app/components/phlex_kit/dialog/dialog_close.rb

@@ -7,7 +7,7 @@ module PhlexKit
     end
 
     def view_template(&)
-      span(**mix({ style: "display: contents", data: { action: "click->phlex-kit--dialog#dismiss" } }, @attrs), &)
+      span(**mix({ style: "display: contents;", data: { action: "click->phlex-kit--dialog#dismiss" } }, @attrs), &)
     end
   end
 end

data/app/components/phlex_kit/dialog/dialog_content.rb

@@ -21,7 +21,7 @@ module PhlexKit
       aria = {}
       aria[:labelledby] = @labelledby if @labelledby
       aria[:describedby] = @describedby if @describedby
-      dialog(**mix({ class: cls, aria: aria, data: { phlex_kit__dialog_target: "dialog", action: "click->phlex-kit--dialog#backdropClick" } }, @attrs)) do
+      dialog(**mix({ class: cls, aria: aria, data: { phlex_kit__dialog_target: "dialog", action: "pointerdown->phlex-kit--dialog#backdropPointerdown click->phlex-kit--dialog#backdropClick" } }, @attrs)) do
         yield
         if @show_close_button
           button(type: "button", class: "pk-overlay-close", data: { action: "click->phlex-kit--dialog#dismiss" }) do

data/app/components/phlex_kit/dialog/dialog_controller.js

@@ -10,6 +10,9 @@ export default class extends Controller {
 
   connect() {
     this.dialogTarget.addEventListener("close", this.handleClose)
+    // Turbo snapshots at turbo:before-cache, BEFORE disconnect — close now or
+    // the cached page restores a non-modal <dialog open> with scroll locked.
+    document.addEventListener("turbo:before-cache", this.beforeCache)
     this.#wireAria("aria-labelledby", ".pk-dialog-title")
     this.#wireAria("aria-describedby", ".pk-dialog-description")
     if (this.openValue) this.open()
@@ -24,8 +27,14 @@ export default class extends Controller {
   }
   disconnect() {
     this.dialogTarget.removeEventListener("close", this.handleClose)
+    document.removeEventListener("turbo:before-cache", this.beforeCache)
     if (this.dialogTarget.open) this.handleClose()
   }
+  beforeCache = () => {
+    if (!this.dialogTarget.open) return
+    this.dialogTarget.close()
+    this.handleClose() // the close event is a queued task — too late for the snapshot
+  }
   open(e) {
     e?.preventDefault()
     this.dialogTarget.showModal()
@@ -35,15 +44,26 @@ export default class extends Controller {
     document.body.style.overflow = "hidden"
   }
   dismiss() { this.dialogTarget.close() }
+  // Only a press that STARTED on the backdrop may dismiss: a drag-select
+  // beginning inside the panel and released over the backdrop fires the
+  // click on <dialog> with outside coordinates — that must not close it
+  // (Radix guards on pointerdown origin the same way).
+  backdropPointerdown(e) {
+    this.pressStartedOutside = e.target === this.dialogTarget && !this.#insideBox(e)
+  }
   // Only a click on the ::backdrop dismisses. e.target is the <dialog> for
   // backdrop clicks, but ALSO for clicks on the dialog's own padding/flex
   // gaps — disambiguate by testing the click point against the dialog's box.
   backdropClick(e) {
     if (e.target !== this.dialogTarget) return
     if (e.detail === 0) return // synthetic/keyboard click — no coordinates
+    if (!this.pressStartedOutside) return
+    this.pressStartedOutside = false
+    if (!this.#insideBox(e)) this.dismiss()
+  }
+  #insideBox(e) {
     const r = this.dialogTarget.getBoundingClientRect()
-    const inside = e.clientX >= r.left && e.clientX <= r.right && e.clientY >= r.top && e.clientY <= r.bottom
-    if (!inside) this.dismiss()
+    return e.clientX >= r.left && e.clientX <= r.right && e.clientY >= r.top && e.clientY <= r.bottom
   }
   handleClose = () => { document.body.style.overflow = this.previousOverflow ?? "" }
 }

data/app/components/phlex_kit/drawer/drawer.css

@@ -27,7 +27,7 @@
   bottom: 0;
   max-height: 85vh;
   border-top: 1px solid var(--pk-border);
-  border-radius: .75rem .75rem 0 0;
+  border-radius: calc(var(--pk-radius) + 2px) calc(var(--pk-radius) + 2px) 0 0;
   animation: pk-drawer-up .3s ease;
 }
 .pk-drawer.top {
@@ -35,7 +35,7 @@
   top: 0;
   max-height: 85vh;
   border-bottom: 1px solid var(--pk-border);
-  border-radius: 0 0 .75rem .75rem;
+  border-radius: 0 0 calc(var(--pk-radius) + 2px) calc(var(--pk-radius) + 2px);
   animation: pk-drawer-down .3s ease;
 }
 .pk-drawer.left,
@@ -48,13 +48,13 @@
 .pk-drawer.left {
   left: 0;
   border-right: 1px solid var(--pk-border);
-  border-radius: 0 .75rem .75rem 0;
+  border-radius: 0 calc(var(--pk-radius) + 2px) calc(var(--pk-radius) + 2px) 0;
   animation: pk-drawer-from-left .3s ease;
 }
 .pk-drawer.right {
   right: 0;
   border-left: 1px solid var(--pk-border);
-  border-radius: .75rem 0 0 .75rem;
+  border-radius: calc(var(--pk-radius) + 2px) 0 0 calc(var(--pk-radius) + 2px);
   animation: pk-drawer-from-right .3s ease;
 }
 @keyframes pk-drawer-up { from { transform: translateY(100%); } to { transform: translateY(0); } }

data/app/components/phlex_kit/dropdown_menu/dropdown_menu.css

@@ -20,14 +20,17 @@
   position-try-fallbacks: flip-block;
 }
 .pk-dropdown-menu-content-up { position-area: block-start span-inline-end; margin: 0 0 4px; }
+/* Gap margins are logical to match the logical position-area — physical
+   margins landed on the wrong side in RTL (and flip-inline flips logical
+   margins along with the placement). */
 .pk-dropdown-menu-content-right {
   position-area: inline-end span-block-end;
-  margin: 0 0 0 4px;
+  margin: 0; margin-inline-start: 4px;
   position-try-fallbacks: flip-inline;
 }
 .pk-dropdown-menu-content-left {
   position-area: inline-start span-block-end;
-  margin: 0 4px 0 0;
+  margin: 0; margin-inline-end: 4px;
   position-try-fallbacks: flip-inline;
 }
 .pk-dropdown-menu-viewport {

data/app/components/phlex_kit/dropdown_menu/dropdown_menu_controller.js

@@ -16,20 +16,47 @@ export default class extends Controller {
 
   connect() {
     this.boundHandleKeydown = this.#handleKeydown.bind(this);
+    // Outstanding syncSub rAF handles — cancelled on disconnect so a queued
+    // frame never touches a torn-down menu (menubar's pattern).
+    this.subFrames = new Set();
     // The visible control is the caller's button/link inside the trigger
     // wrapper — that's what AT reads, so the popup wiring belongs on it.
     this.invoker = this.triggerTarget.querySelector("button, a, [tabindex]") || this.triggerTarget;
     this.invoker.setAttribute("aria-haspopup", "menu");
     this.invoker.setAttribute("aria-expanded", "false");
+    // Associate trigger and menu for AT (the dialog controller wires its
+    // ids the same way).
+    if (!this.contentTarget.id) this.contentTarget.id = `pk-dropdown-menu-${Math.random().toString(36).slice(2, 8)}`;
+    this.invoker.setAttribute("aria-controls", this.contentTarget.id);
+    // Turbo snapshots BEFORE disconnect — an open menu (reflected in the
+    // open value) would be resurrected from the page cache on restore.
+    this.boundBeforeCache = () => this.close();
+    document.addEventListener("turbo:before-cache", this.boundBeforeCache);
     // `open:` on the Ruby side renders the value — start open (same
     // kwarg -> value -> connect flow as Collapsible).
     if (this.openValue) this.#open();
   }
 
   disconnect() {
+    document.removeEventListener("turbo:before-cache", this.boundBeforeCache);
+    this.subFrames.forEach((id) => cancelAnimationFrame(id));
+    this.subFrames.clear();
     this.#removeEventListeners();
   }
 
+  // Mirrors the CSS-driven submenu state (:hover / :focus-within) onto the
+  // sub trigger's aria-expanded. rAF: on mouseleave/focusout the pseudo-class
+  // state isn't settled until the event finishes dispatching.
+  syncSub(e) {
+    const sub = e.currentTarget;
+    const id = requestAnimationFrame(() => {
+      this.subFrames.delete(id);
+      sub.querySelector(":scope > [aria-haspopup]")
+        ?.setAttribute("aria-expanded", sub.matches(":hover, :focus-within"));
+    });
+    this.subFrames.add(id);
+  }
+
   onClickOutside(event) {
     // Gate on the live :popover-open state, not the stored flag — a stale
     // flag is how a close on an already-closed panel becomes an open.

data/app/components/phlex_kit/dropdown_menu/dropdown_menu_sub.rb

@@ -5,7 +5,9 @@ module PhlexKit
   class DropdownMenuSub < BaseComponent
     def initialize(**attrs) = (@attrs = attrs)
     def view_template(&)
-      div(**mix({ class: "pk-dropdown-menu-sub" }, @attrs), &)
+      # syncSub mirrors the CSS-driven reveal state onto the sub trigger's
+      # aria-expanded (same wiring as MenubarSub).
+      div(**mix({ class: "pk-dropdown-menu-sub", data: { action: "mouseenter->phlex-kit--dropdown-menu#syncSub mouseleave->phlex-kit--dropdown-menu#syncSub focusin->phlex-kit--dropdown-menu#syncSub focusout->phlex-kit--dropdown-menu#syncSub" } }, @attrs), &)
     end
   end
 end

data/app/components/phlex_kit/dropdown_menu/dropdown_menu_sub_trigger.rb

@@ -10,7 +10,9 @@ module PhlexKit
         # -1: roving focus reaches it via arrows (focus-within opens the sub);
         # tabindex 0 made it a stray tab stop inside the menu.
         tabindex: "-1",
-        aria: { haspopup: "menu" },
+        # expanded starts false and is mirrored live by the controller's
+        # syncSub (the reveal itself is pure CSS :hover/:focus-within).
+        aria: { haspopup: "menu", expanded: "false" },
         data: { phlex_kit__dropdown_menu_target: "menuItem" }
       }, @attrs)) do
         block&.call

data/app/components/phlex_kit/empty/empty.css

@@ -5,7 +5,7 @@
 .pk-empty {
   display: flex; width: 100%; min-width: 0; flex: 1; flex-direction: column;
   align-items: center; justify-content: center; gap: 1rem;
-  border: 0 dashed var(--pk-border); border-radius: .75rem;
+  border: 0 dashed var(--pk-border); border-radius: calc(var(--pk-radius) + 2px);
   padding: 1.5rem; text-align: center; text-wrap: balance;
 }
 .pk-empty.outline { border-width: 1px; }

data/app/components/phlex_kit/field/field.css

@@ -146,7 +146,8 @@
   display: flex;
   flex-direction: column;
   gap: .25rem;
-  margin: 0 0 0 1rem;
+  margin: 0;
+  margin-inline-start: 1rem;
   padding: 0;
   list-style: disc;
 }

data/app/components/phlex_kit/field/field_separator.rb

@@ -6,7 +6,7 @@ module PhlexKit
     def initialize(**attrs) = (@attrs = attrs)
 
     def view_template(&block)
-      div(**mix({ class: "pk-field-separator", data: { content: block ? "true" : "false" } }, @attrs)) do
+      div(**mix({ class: "pk-field-separator" }, @attrs)) do
         render Separator.new(class: "pk-field-separator-line")
         span(class: "pk-field-separator-content", &block) if block
       end

data/app/components/phlex_kit/form_field/form_field_controller.js

@@ -9,13 +9,31 @@ import { Controller } from "@hotwired/stimulus";
 // back to the browser's validationMessage.
 // Connects to data-controller="phlex-kit--form-field"
 export default class extends Controller {
-  static targets = ["input", "error"];
+  static targets = ["input", "error", "hint"];
   static values = { shouldValidate: false };
 
   connect() {
+    // Hints are static description text — wire them onto every control's
+    // aria-describedby up front (errors join/leave dynamically via
+    // #describeBy, which preserves foreign tokens like these).
+    this.hintTargets.forEach((hint) => {
+      if (!hint.id) return;
+      this.inputTargets.forEach((input) => {
+        const tokens = (input.getAttribute("aria-describedby") || "").split(/\s+/).filter(Boolean);
+        if (!tokens.includes(hint.id)) tokens.push(hint.id);
+        input.setAttribute("aria-describedby", tokens.join(" "));
+      });
+    });
     if (this.hasErrorTarget) {
       if (this.errorTarget.textContent.trim()) {
         this.shouldValidateValue = true;
+        // A server-rendered error is already visible — give the control(s)
+        // the same aria wiring onInvalid applies, instead of leaving
+        // aria-invalid/aria-describedby unset until the first input/change.
+        this.inputTargets.forEach((input) => {
+          input.setAttribute("aria-invalid", "true");
+          this.#describeBy(input, true);
+        });
       } else {
         this.errorTarget.classList.add("pk-hidden");
       }
@@ -30,6 +48,16 @@ export default class extends Controller {
     if (!this.hasErrorTarget) return;
     error.preventDefault();
 
+    // preventDefault also cancels the browser's focus-first-invalid — restore
+    // it for the first invalid control of the submit pass (all invalid events
+    // fire in the same task, so the microtask reset scopes "first" correctly).
+    if (!this._focusedInvalid) {
+      this._focusedInvalid = true;
+      queueMicrotask(() => { this._focusedInvalid = false; });
+      error.target.focus({ preventScroll: true });
+      error.target.scrollIntoView({ block: "nearest" });
+    }
+
     this.shouldValidateValue = true;
     this.#setErrorMessage(error);
   }

data/app/components/phlex_kit/form_field/form_field_hint.rb

@@ -2,12 +2,16 @@ module PhlexKit
   # Muted helper text under a PhlexKit::FormField control. Hidden when empty.
   # See form_field.rb.
   class FormFieldHint < BaseComponent
-    def initialize(**attrs)
+    # A default id (like FormFieldError) so the controller can wire the hint
+    # into every control's aria-describedby — without it SR users never heard
+    # the hint text. id: is a named kwarg to avoid mix id-fusion.
+    def initialize(id: nil, **attrs)
+      @id = id || "pk-form-field-hint-#{SecureRandom.hex(4)}"
       @attrs = attrs
     end
 
     def view_template(&block)
-      p(**mix({ class: "pk-form-field-hint" }, @attrs), &block)
+      p(**mix({ id: @id, class: "pk-form-field-hint", data: { phlex_kit__form_field_target: "hint" } }, @attrs), &block)
     end
   end
 end

data/app/components/phlex_kit/hover_card/hover_card.css

@@ -22,12 +22,14 @@
   box-shadow: 0 8px 24px color-mix(in srgb, var(--pk-shadow-color) 30%, transparent); outline: none;
 }
 .pk-hover-card-content.top { position-area: block-start span-inline-end; margin: 0 0 .25rem; }
+/* Gap margins are logical to match the logical position-area (and tooltip's
+   pattern) — physical margins landed on the wrong side in RTL. */
 .pk-hover-card-content.left {
-  position-area: inline-start; margin: 0 .25rem 0 0;
+  position-area: inline-start; margin: 0; margin-inline-end: .25rem;
   position-try-fallbacks: flip-inline;
 }
 .pk-hover-card-content.right {
-  position-area: inline-end; margin: 0 0 0 .25rem;
+  position-area: inline-end; margin: 0; margin-inline-start: .25rem;
   position-try-fallbacks: flip-inline;
 }
 /* Hiding must survive author display values (a host class like

data/app/components/phlex_kit/icon/icon.css

@@ -0,0 +1,9 @@
+/* Co-located with icon.rb — PhlexKit::Icon. The .pk-icon class was emitted
+   with no rule anywhere (audit round 6): the bare SVG inherited the UA's
+   inline/baseline layout (descender gap under icons) and could be squashed
+   inside height-constrained flex scroll panes. */
+.pk-icon {
+  display: inline-block;
+  vertical-align: middle;
+  flex: none;
+}

data/app/components/phlex_kit/icon/icon.rb

@@ -20,7 +20,13 @@ module PhlexKit
 
     def view_template
       icon = Icons.fetch(@name, library: @library || PhlexKit.config.icon_library)
-      svg(**mix(base_attrs(icon), @attrs)) do |s|
+      base = base_attrs(icon)
+      # `mix` merges duplicate string attrs ("16 24") — drop a generated attr
+      # whenever the caller supplies their own copy, so theirs wins.
+      %i[width height viewbox aria-hidden].each do |key|
+        base.delete(key) if @attrs.key?(key) || @attrs.key?(key.to_s)
+      end
+      svg(**mix(base, @attrs)) do |s|
         icon[:elements].each { |tag, attrs| s.public_send(tag, **attrs) }
       end
     end

data/app/components/phlex_kit/input_group/input_group.css

@@ -59,7 +59,6 @@
   justify-content: center;
   gap: .5rem;
   flex: none;
-  cursor: text;
   user-select: none;
   padding-block: .375rem;
   color: var(--pk-muted);

data/app/components/phlex_kit/input_otp/input_otp.css

@@ -18,12 +18,12 @@
 }
 .pk-input-otp-slot:not(:first-child) { margin-inline-start: -1px; }
 .pk-input-otp-group .pk-input-otp-slot:first-child {
-  border-top-left-radius: var(--pk-radius);
-  border-bottom-left-radius: var(--pk-radius);
+  border-start-start-radius: var(--pk-radius);
+  border-end-start-radius: var(--pk-radius);
 }
 .pk-input-otp-group .pk-input-otp-slot:last-child {
-  border-top-right-radius: var(--pk-radius);
-  border-bottom-right-radius: var(--pk-radius);
+  border-start-end-radius: var(--pk-radius);
+  border-end-end-radius: var(--pk-radius);
 }
 .pk-input-otp-slot:focus {
   position: relative;

data/app/components/phlex_kit/marker/marker.rb

@@ -6,11 +6,24 @@ module PhlexKit
   # underline and brighten on hover. `.pk-marker*` (marker.css).
   class Marker < BaseComponent
     VARIANTS = { default: nil, border: "border", separator: "separator" }.freeze
+    # The elements this component knows how to render (href: forces <a>);
+    # unknown values used to fall through silently to <div> — fail loud instead.
+    AS_TAGS = %i[div button].freeze
 
-    def initialize(variant: :default, href: nil, as: :div, **attrs)
+    # type: is a named kwarg (not a mix default) because `mix` would *fuse* a
+    # caller type: "submit" with the generated "button" into an invalid
+    # two-token value the browser resolves back to submit.
+    def initialize(variant: :default, href: nil, as: :div, type: :button, **attrs)
       @variant = variant.to_sym
       @href = href
       @as = as.to_sym
+      unless AS_TAGS.include?(@as)
+        raise ArgumentError, "unknown Marker as: #{@as.inspect} (use one of #{AS_TAGS.join(", ")})"
+      end
+      if @href && @as != :div
+        raise ArgumentError, "Marker href: renders an <a> — it can't combine with as: #{@as.inspect}"
+      end
+      @type = type
       @attrs = attrs
     end
 
@@ -19,7 +32,7 @@ module PhlexKit
       if @href
         a(**mix({ class: classes, href: @href }, @attrs), &)
       elsif @as == :button
-        button(**mix({ class: classes, type: "button" }, @attrs), &)
+        button(**mix({ class: classes, type: @type }, @attrs), &)
       else
         div(**mix({ class: classes }, @attrs), &)
       end

data/app/components/phlex_kit/masked_input/masked_input_controller.js

@@ -11,21 +11,42 @@ export default class extends Controller {
     if (!this.mask) return
     // Skip IME composition updates — masking mid-composition mangles the text.
     this.onInput = (e) => { if (!e.isComposing) this.apply() }
+    // Some browsers (Safari) fire the final input event with isComposing still
+    // true, so IME-committed text would never be masked — catch the commit here.
+    this.onCompositionEnd = () => this.apply()
     this.element.addEventListener("input", this.onInput)
+    this.element.addEventListener("compositionend", this.onCompositionEnd)
     // A server-prefilled value renders unmasked — format it once up front.
     if (this.element.value) this.apply()
   }
-  disconnect() { if (this.onInput) this.element.removeEventListener("input", this.onInput) }
+  disconnect() {
+    if (this.onInput) this.element.removeEventListener("input", this.onInput)
+    if (this.onCompositionEnd) this.element.removeEventListener("compositionend", this.onCompositionEnd)
+  }
   apply() {
     const el = this.element
     // The whole value is rewritten below, which throws the caret to the end —
-    // remember how many maskable chars sit before it and re-seat it after
-    // the same count in the masked output (mid-field edits keep their place).
+    // re-seat it after the same number of TOKEN-filled (user) characters.
+    // Counting is done in token space, not "any alphanumeric" space: mask
+    // literals can themselves be alphanumeric (the "1" in "+1 (###) ###-####"),
+    // and counting them as user input reordered every subsequent keystroke.
     const caret = el.selectionStart ?? el.value.length
-    const rawBefore = el.value.slice(0, caret).replace(/[^0-9A-Za-z]/g, "").length
+    const filledBefore = this.maskFill(this.maskable(el.value.slice(0, caret))).tokenPos.length
+
+    const { out, tokenPos } = this.maskFill(this.maskable(el.value))
+    el.value = out
+
+    if (document.activeElement === el) {
+      const pos = filledBefore === 0 ? 0 : tokenPos[filledBefore - 1] + 1
+      el.setSelectionRange(pos, pos)
+    }
+  }
 
-    const raw = el.value.replace(/[^0-9A-Za-z]/g, "")
+  // Fill the mask from `raw`, returning the output and the output indices
+  // that were filled from user input (vs emitted as mask literals).
+  maskFill(raw) {
     let out = "", i = 0
+    const tokenPos = []
     for (const t of this.mask) {
       if (i >= raw.length) break
       if (t === "#" || t === "A" || t === "*") {
@@ -34,18 +55,17 @@ export default class extends Controller {
         const re = t === "#" ? /\d/ : t === "A" ? /[A-Za-z]/ : /[0-9A-Za-z]/
         while (i < raw.length && !re.test(raw[i])) i++
         if (i >= raw.length) break
+        tokenPos.push(out.length)
         out += raw[i++]
       } else { out += t; if (raw[i] === t) i++ }
     }
-    el.value = out
-
-    if (document.activeElement === el) {
-      let pos = 0, seen = 0
-      while (pos < out.length && seen < rawBefore) {
-        if (/[0-9A-Za-z]/.test(out[pos])) seen++
-        pos++
-      }
-      el.setSelectionRange(pos, pos)
-    }
+    return { out, tokenPos }
+  }
+  // Transliterate full-width digits (０-９, U+FF10–FF19 — common IME numeric
+  // output) to ASCII before the charset filter would silently drop them.
+  maskable(value) {
+    return value
+      .replace(/[０-９]/g, (d) => String.fromCharCode(d.charCodeAt(0) - 0xFEE0))
+      .replace(/[^0-9A-Za-z]/g, "")
   }
 }

data/app/components/phlex_kit/menubar/menubar.rb

@@ -16,7 +16,9 @@ module PhlexKit
         role: "menubar",
         data: {
           controller: "phlex-kit--menubar",
-          action: "click@window->phlex-kit--menubar#onClickOutside keydown->phlex-kit--menubar#onKeydown"
+          # focusout: tabbing out of the bar closes the open [popover=manual]
+          # panel (which no focus trap holds open).
+          action: "click@window->phlex-kit--menubar#onClickOutside keydown->phlex-kit--menubar#onKeydown focusout->phlex-kit--menubar#onFocusout"
         }
       }, @attrs), &)
     end