phlex_kit 0.8.0 → 0.9.0

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

@@ -5,7 +5,10 @@ module PhlexKit
   # Trigger + Content (+ Item / Label / Separator). Tailwind → vanilla
   # `.pk-dropdown-menu*` (dropdown_menu.css).
   class DropdownMenu < BaseComponent
-    def initialize(**attrs)
+    # `open: true` renders the menu open on connect (matching Collapsible's
+    # kwarg -> Stimulus value -> connect flow).
+    def initialize(open: false, **attrs)
+      @open = open
       @attrs = attrs
     end
 
@@ -14,6 +17,7 @@ module PhlexKit
         class: "pk-dropdown-menu",
         data: {
           controller: "phlex-kit--dropdown-menu",
+          phlex_kit__dropdown_menu_open_value: @open,
           action: "click@window->phlex-kit--dropdown-menu#onClickOutside"
         }
       }, @attrs), &block)

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

@@ -14,9 +14,13 @@ module PhlexKit
     def view_template(&block)
       label(**mix({
         class: "pk-dropdown-menu-item pk-dropdown-menu-checkbox-item",
-        role: "menuitemcheckbox"
+        role: "menuitemcheckbox",
+        tabindex: "-1",
+        aria: { checked: @checked ? "true" : "false" },
+        data: { phlex_kit__dropdown_menu_target: "menuItem" }
       }, @attrs)) do
-        input(type: :checkbox, class: "pk-dropdown-menu-item-input", name: @name, value: @value, checked: @checked)
+        input(type: :checkbox, class: "pk-dropdown-menu-item-input", name: @name, value: @value, checked: @checked,
+              tabindex: "-1", data: { action: "change->phlex-kit--dropdown-menu#syncChecked" })
         span(class: "pk-dropdown-menu-item-indicator", aria: { hidden: "true" }) { check_icon }
         yield if block
       end

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

@@ -14,7 +14,9 @@ module PhlexKit
 
     def view_template(&block)
       div(class: wrapper_classes, popover: "manual", data: { phlex_kit__dropdown_menu_target: "content" }) do
-        div(**mix({ class: "pk-dropdown-menu-viewport" }, @attrs), &block)
+        # role="menu" on the items' direct parent — the rows render
+        # role="menuitem", which is invalid ARIA without a menu ancestor.
+        div(**mix({ class: "pk-dropdown-menu-viewport", role: "menu" }, @attrs), &block)
       end
     end
 

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

@@ -4,14 +4,26 @@ import { Controller } from "@hotwired/stimulus";
 // @floating-ui/dom dependency: the panel is a native [popover=manual] in the
 // top layer, anchor-positioned with viewport-edge flipping by
 // dropdown_menu.css (manual so this controller keeps owning click-outside,
-// Escape, and arrow/enter keyboard nav — all unchanged from upstream).
+// Escape, and keyboard nav). Keyboard nav moves REAL focus over the rows
+// (upstream stamped aria-selected on menuitems, which AT ignores): :focus
+// styles the highlight and :focus-within opens/closes submenus, so hidden
+// sub-rows are skipped via a visibility filter. Escape returns focus to the
+// trigger; Enter/Space activate the focused row (links, checkbox/radio
+// labels, and sub triggers alike).
 export default class extends Controller {
   static targets = ["trigger", "content", "menuItem"];
   static values = { open: { type: Boolean, default: false } };
 
   connect() {
     this.boundHandleKeydown = this.#handleKeydown.bind(this);
-    this.selectedIndex = -1;
+    // 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");
+    // `open:` on the Ruby side renders the value — start open (same
+    // kwarg -> value -> connect flow as Collapsible).
+    if (this.openValue) this.#open();
   }
 
   disconnect() {
@@ -24,6 +36,9 @@ export default class extends Controller {
     if (!this.contentTarget.matches(":popover-open")) return;
     if (this.element.contains(event.target)) return;
 
+    // Deliberate (matches Radix's modal dismiss): the outside click ONLY
+    // dismisses the menu — it is swallowed rather than also acting on
+    // whatever was under the pointer (e.g. navigating a link).
     event.preventDefault();
     this.close();
   }
@@ -34,65 +49,104 @@ export default class extends Controller {
 
   #open() {
     this.openValue = true;
-    this.#deselectAll();
     this.#addEventListeners();
     this.contentTarget.showPopover();
+    this.invoker.setAttribute("aria-expanded", "true");
   }
 
-  close() {
+  close(event) {
+    // Menu rows default to href="#"; without this an Enter/click on a
+    // non-link row scrolls to top and appends # to the URL.
+    if (event?.target?.closest?.('a[href="#"]')) event.preventDefault();
     this.openValue = false;
     this.#removeEventListeners();
     if (this.contentTarget.matches(":popover-open")) this.contentTarget.hidePopover();
+    this.invoker.setAttribute("aria-expanded", "false");
   }
 
-  #handleKeydown(e) {
-    if (this.menuItemTargets.length === 0) return;
-
-    if (e.key === "ArrowDown") {
-      e.preventDefault();
-      this.#updateSelectedItem(1);
-    } else if (e.key === "ArrowUp") {
-      e.preventDefault();
-      this.#updateSelectedItem(-1);
-    } else if (e.key === "Enter" && this.selectedIndex !== -1) {
-      e.preventDefault();
-      this.menuItemTargets[this.selectedIndex].click();
-    } else if (e.key === "Escape") {
-      this.close();
-    }
+  // Mirrors a checkbox/radio row's native input state onto the row's
+  // aria-checked (radios also reset their group's siblings).
+  syncChecked(event) {
+    const input = event.target;
+    const group = input.name
+      ? this.element.querySelectorAll(`input[name="${CSS.escape(input.name)}"]`)
+      : [input];
+    group.forEach((i) => i.closest('[role^="menuitem"]')?.setAttribute("aria-checked", i.checked));
   }
 
-  #updateSelectedItem(direction) {
-    this.menuItemTargets.forEach((item, index) => {
-      if (item.getAttribute("aria-selected") === "true") this.selectedIndex = index;
-    });
-
-    if (this.selectedIndex >= 0) {
-      this.#toggleAriaSelected(this.menuItemTargets[this.selectedIndex], false);
-    }
-
-    this.selectedIndex += direction;
-
-    if (this.selectedIndex < 0) {
-      this.selectedIndex = this.menuItemTargets.length - 1;
-    } else if (this.selectedIndex >= this.menuItemTargets.length) {
-      this.selectedIndex = 0;
+  #handleKeydown(e) {
+    const items = this.#items();
+    if (items.length === 0) return;
+    const index = items.indexOf(document.activeElement);
+
+    switch (e.key) {
+      case "ArrowDown":
+        e.preventDefault();
+        items[(index + 1) % items.length]?.focus();
+        break;
+      case "ArrowUp":
+        e.preventDefault();
+        items[index < 0 ? items.length - 1 : (index - 1 + items.length) % items.length]?.focus();
+        break;
+      case "Home":
+        e.preventDefault();
+        items[0]?.focus();
+        break;
+      case "End":
+        e.preventDefault();
+        items[items.length - 1]?.focus();
+        break;
+      case "Enter":
+      case " ":
+        // Explicit click so label rows (checkbox/radio) activate too —
+        // labels have no native keyboard activation.
+        if (index >= 0) {
+          e.preventDefault();
+          items[index].click();
+        }
+        break;
+      case "Escape":
+        e.preventDefault();
+        this.close();
+        this.invoker.focus();
+        break;
+      case "ArrowRight":
+        // On a sub trigger, enter the submenu (focus reveals it via
+        // :focus-within, making its rows visible to the roving nav).
+        // Same keyboard grammar as context_menu.
+        if (document.activeElement?.matches(".pk-dropdown-menu-sub-trigger")) {
+          e.preventDefault();
+          this.#enterSub(document.activeElement);
+        }
+        break;
+      case "ArrowLeft": {
+        // Inside a submenu, step back to its trigger (closes it on focus-out).
+        const sub = document.activeElement?.closest(".pk-dropdown-menu-sub-content");
+        if (sub) {
+          e.preventDefault();
+          sub.closest(".pk-dropdown-menu-sub")?.querySelector(".pk-dropdown-menu-sub-trigger")?.focus();
+        }
+        break;
+      }
     }
-
-    this.#toggleAriaSelected(this.menuItemTargets[this.selectedIndex], true);
   }
 
-  #toggleAriaSelected(element, isSelected) {
-    if (isSelected) {
-      element.setAttribute("aria-selected", "true");
-    } else {
-      element.removeAttribute("aria-selected");
-    }
+  #enterSub(trigger) {
+    trigger.focus();
+    const panel = trigger.closest(".pk-dropdown-menu-sub")?.querySelector(".pk-dropdown-menu-sub-content");
+    if (!panel) return;
+    const first = [...panel.querySelectorAll('[role^="menuitem"]')]
+      .find((el) => !el.closest("[data-disabled]") && el.getClientRects().length > 0);
+    first?.focus();
   }
 
-  #deselectAll() {
-    this.menuItemTargets.forEach((item) => this.#toggleAriaSelected(item, false));
-    this.selectedIndex = -1;
+  // Rows inside a closed submenu are display:none (revealed by CSS on
+  // hover/focus-within) — focus() on them silently fails and the roving
+  // navigation would jam at the submenu boundary.
+  #items() {
+    return this.menuItemTargets.filter(
+      (el) => !el.closest("[data-disabled]") && el.getClientRects().length > 0,
+    );
   }
 
   #addEventListeners() {

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

@@ -6,7 +6,9 @@ module PhlexKit
     end
 
     def view_template(&block)
-      h3(**mix({ class: "pk-dropdown-menu-label" }, @attrs), &block)
+      # div, not a heading: role="menu" only allows menuitem/group/separator
+      # children, so an <h3> is invalid ARIA there (shadcn uses a div too).
+      div(**mix({ class: "pk-dropdown-menu-label" }, @attrs), &block)
     end
   end
 end

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

@@ -13,9 +13,13 @@ module PhlexKit
     def view_template(&block)
       label(**mix({
         class: "pk-dropdown-menu-item pk-dropdown-menu-radio-item",
-        role: "menuitemradio"
+        role: "menuitemradio",
+        tabindex: "-1",
+        aria: { checked: @checked ? "true" : "false" },
+        data: { phlex_kit__dropdown_menu_target: "menuItem" }
       }, @attrs)) do
-        input(type: :radio, class: "pk-dropdown-menu-item-input", name: @name, value: @value, checked: @checked)
+        input(type: :radio, class: "pk-dropdown-menu-item-input", name: @name, value: @value, checked: @checked,
+              tabindex: "-1", data: { action: "change->phlex-kit--dropdown-menu#syncChecked" })
         span(class: "pk-dropdown-menu-item-indicator", aria: { hidden: "true" }) do
           # Deliberately NOT a PhlexKit::Icon: a filled selection dot is
           # geometry, not icon-library vocabulary — it stays identical across

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

@@ -7,8 +7,11 @@ module PhlexKit
       div(**mix({
         class: "pk-dropdown-menu-item pk-dropdown-menu-sub-trigger",
         role: "menuitem",
-        tabindex: "0",
-        aria: { haspopup: "menu" }
+        # -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" },
+        data: { phlex_kit__dropdown_menu_target: "menuItem" }
       }, @attrs)) do
         block&.call
         render Icon.new(:chevron_right, size: nil, class: "pk-dropdown-menu-sub-chevron")

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

@@ -110,7 +110,7 @@
   font-size: .875rem;
   font-weight: 400;
   line-height: 1.5;
-  text-align: left;
+  text-align: start;
 }
 .pk-field-description a { text-decoration: underline; text-underline-offset: 4px; color: inherit; }
 .pk-field-description a:hover { color: var(--pk-brand); }

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

@@ -1,8 +1,8 @@
 module PhlexKit
   # Validation message(s) for a Field, ported from shadcn/ui's FieldError.
   # Pass `errors:` an array of message strings (deduped; one renders plain,
-  # several render a list) or give a block. Renders nothing when empty —
-  # matching theirs. Distinct from FormFieldError, which is the Stimulus
+  # several render a list) or give a block — both render (block after the
+  # list) when both are given. Renders nothing when empty — matching theirs. Distinct from FormFieldError, which is the Stimulus
   # live-validation slot; server-rendered errors belong here. See field.rb.
   class FieldError < BaseComponent
     def initialize(errors: nil, **attrs)
@@ -14,15 +14,14 @@ module PhlexKit
       return if @errors.empty? && !block
 
       div(**mix({ class: "pk-field-error", role: "alert", data: { slot: "field-error" } }, @attrs)) do
-        if block
-          yield
-        elsif @errors.length == 1
+        if @errors.length == 1
           plain @errors.first
-        else
+        elsif @errors.length > 1
           ul(class: "pk-field-error-list") do
             @errors.each { |message| li { message } }
           end
         end
+        yield if block
       end
     end
   end

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

@@ -14,7 +14,7 @@ export default class extends Controller {
 
   connect() {
     if (this.hasErrorTarget) {
-      if (this.errorTarget.textContent) {
+      if (this.errorTarget.textContent.trim()) {
         this.shouldValidateValue = true;
       } else {
         this.errorTarget.classList.add("pk-hidden");
@@ -23,36 +23,68 @@ export default class extends Controller {
   }
 
   onInvalid(error) {
+    // Only suppress the native validation bubble when we can show our own
+    // message — a FormField without a FormFieldError previously ate the
+    // bubble AND crashed on the missing target, so a required-but-empty
+    // form gave zero feedback and never submitted.
+    if (!this.hasErrorTarget) return;
     error.preventDefault();
 
     this.shouldValidateValue = true;
-    this.#setErrorMessage();
+    this.#setErrorMessage(error);
   }
 
-  onInput() {
-    this.#setErrorMessage();
+  onInput(event) {
+    this.#setErrorMessage(event);
   }
 
-  onChange() {
-    this.#setErrorMessage();
+  onChange(event) {
+    this.#setErrorMessage(event);
   }
 
-  #setErrorMessage() {
-    if (!this.shouldValidateValue) return;
+  // The event's own control, when it's one of ours — radio/checkbox groups
+  // register several input targets and validity/aria-invalid must land on
+  // the control that fired, not always the first.
+  #inputFor(event) {
+    if (event && this.inputTargets.includes(event.target)) return event.target;
+    return this.inputTarget;
+  }
+
+  #setErrorMessage(event) {
+    if (!this.shouldValidateValue || !this.hasErrorTarget) return;
 
-    if (this.inputTarget.validity.valid) {
+    const input = this.#inputFor(event);
+    // aria-invalid drives the red ring for LIVE validation too (input.css
+    // only matched server-rendered attrs); aria-describedby ties the message
+    // to the control for AT.
+    if (input.validity.valid) {
+      input.removeAttribute("aria-invalid");
+      this.#describeBy(input, false);
       this.errorTarget.textContent = "";
       this.errorTarget.classList.add("pk-hidden");
     } else {
-      this.errorTarget.textContent = this.#getValidationMessage();
+      input.setAttribute("aria-invalid", "true");
+      this.#describeBy(input, true);
+      this.errorTarget.textContent = this.#getValidationMessage(input);
       this.errorTarget.classList.remove("pk-hidden");
     }
   }
 
-  #getValidationMessage() {
+  // Append/remove the error's id on the control's aria-describedby without
+  // clobbering pre-existing tokens (e.g. a hint's id).
+  #describeBy(input, present) {
+    const id = this.errorTarget.id;
+    if (!id) return;
+    const tokens = (input.getAttribute("aria-describedby") || "").split(/\s+/).filter((t) => t && t !== id);
+    if (present) tokens.push(id);
+    if (tokens.length) input.setAttribute("aria-describedby", tokens.join(" "));
+    else input.removeAttribute("aria-describedby");
+  }
+
+  #getValidationMessage(input) {
     let errorMessage;
 
-    const { validity, dataset, validationMessage } = this.inputTarget;
+    const { validity, dataset, validationMessage } = input;
 
     if (validity.tooLong) errorMessage = dataset.tooLong;
     if (validity.tooShort) errorMessage = dataset.tooShort;

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

@@ -5,13 +5,20 @@ module PhlexKit
   # with server-rendered model errors — non-empty content arms validation on
   # connect. See form_field.rb.
   class FormFieldError < BaseComponent
-    def initialize(**attrs)
+    def initialize(id: nil, **attrs)
+      # A default id (like SelectContent / CommandList) so the controller can
+      # always wire aria-describedby from the control to this message.
+      @id = id || "pk-form-field-error-#{SecureRandom.hex(4)}"
       @attrs = attrs
     end
 
     def view_template(&block)
+      # role="alert": the controller swaps this text live on invalid/input —
+      # without a live region the announcement never reaches screen readers.
       p(**mix({
+        id: @id,
         class: "pk-form-field-error",
+        role: "alert",
         data: { phlex_kit__form_field_target: "error" }
       }, @attrs), &block)
     end

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

@@ -19,7 +19,7 @@
   border: 1px solid color-mix(in oklab, var(--pk-text) 10%, transparent);
   border-radius: var(--pk-radius); background: var(--pk-surface);
   color: var(--pk-text); padding: .625rem; font-size: .875rem;
-  box-shadow: 0 8px 24px rgb(0 0 0 / .3); outline: none;
+  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; }
 .pk-hover-card-content.left {

data/app/components/phlex_kit/hover_card/hover_card_controller.js

@@ -4,6 +4,9 @@ import { Controller } from "@hotwired/stimulus"
 // with a small open/close delay. The panel is a native [popover=manual]
 // (top layer; manual because the controller owns open/close — hover
 // semantics want no light dismiss), anchor-positioned by hover_card.css.
+// Manual popovers get no built-in Escape dismiss, so a window keydown
+// listener (bound only while open, cf. tooltip_controller.js) closes the
+// card immediately — the keyboard/touch escape hatch for a hover surface.
 export default class extends Controller {
   static targets = ["trigger", "content"]
   static values = { openDelay: { type: Number, default: 200 }, closeDelay: { type: Number, default: 200 } }
@@ -12,14 +15,35 @@ export default class extends Controller {
     this.t = setTimeout(() => {
       if (!this.contentTarget.matches(":popover-open")) this.contentTarget.showPopover()
       this.contentTarget.dataset.state = "open"
+      this.#bindEscape()
     }, this.openDelayValue)
   }
   hide() {
     clearTimeout(this.t)
-    this.t = setTimeout(() => {
-      if (this.contentTarget.matches(":popover-open")) this.contentTarget.hidePopover()
-      this.contentTarget.dataset.state = "closed"
-    }, this.closeDelayValue)
+    this.t = setTimeout(() => this.#close(), this.closeDelayValue)
+  }
+  disconnect() {
+    clearTimeout(this.t)
+    this.#unbindEscape()
+  }
+
+  #close() {
+    if (this.contentTarget.matches(":popover-open")) this.contentTarget.hidePopover()
+    this.contentTarget.dataset.state = "closed"
+    this.#unbindEscape()
+  }
+  #bindEscape() {
+    if (this.onKeydown) return
+    this.onKeydown = (e) => {
+      if (e.key !== "Escape") return
+      clearTimeout(this.t)
+      this.#close()
+    }
+    window.addEventListener("keydown", this.onKeydown)
+  }
+  #unbindEscape() {
+    if (!this.onKeydown) return
+    window.removeEventListener("keydown", this.onKeydown)
+    this.onKeydown = null
   }
-  disconnect() { clearTimeout(this.t) }
 }

data/app/components/phlex_kit/input/input.css

@@ -30,7 +30,7 @@
   font: inherit;
   font-size: .875rem;
   font-weight: 500;
-  margin-right: .5rem;
+  margin-inline-end: .5rem;
 }
 .pk-input:focus-visible {
   outline: none;

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

@@ -24,7 +24,9 @@
   flex-direction: column;
   align-items: stretch;
 }
-.pk-input-group:focus-within {
+/* Ring only when the CONTROL is focused (shadcn gates on the control's
+   focus-visible) — :focus-within would also light it for addon buttons. */
+.pk-input-group:has(.pk-input:focus-visible, .pk-textarea:focus-visible) {
   border-color: var(--pk-ring);
   box-shadow: 0 0 0 3px color-mix(in oklab, var(--pk-ring) 50%, transparent);
 }
@@ -48,8 +50,8 @@
 .pk-input-group .pk-input:disabled,
 .pk-input-group .pk-textarea:disabled { background: transparent; }
 /* Tighten the control's near-side padding beside an inline addon. */
-.pk-input-group:has(> .pk-input-group-addon.start) > .pk-input { padding-left: .375rem; }
-.pk-input-group:has(> .pk-input-group-addon.end) > .pk-input { padding-right: .375rem; }
+.pk-input-group:has(> .pk-input-group-addon.start) > .pk-input { padding-inline-start: .375rem; }
+.pk-input-group:has(> .pk-input-group-addon.end) > .pk-input { padding-inline-end: .375rem; }
 
 .pk-input-group-addon {
   display: flex;
@@ -64,8 +66,8 @@
   font-size: .875rem;
   font-weight: 500;
 }
-.pk-input-group-addon.start { order: -1; padding-left: .5rem; }
-.pk-input-group-addon.end { order: 99; padding-right: .5rem; }
+.pk-input-group-addon.start { order: -1; padding-inline-start: .5rem; }
+.pk-input-group-addon.end { order: 99; padding-inline-end: .5rem; }
 .pk-input-group-addon.block-start,
 .pk-input-group-addon.block-end {
   width: 100%;
@@ -78,8 +80,8 @@
 .pk-input-group-addon.block-end.bordered { border-top: 1px solid var(--pk-border); padding-top: .5rem; }
 .pk-input-group-addon svg:not([class*="size-"]) { width: 1rem; height: 1rem; }
 .pk-input-group-addon > kbd { border-radius: calc(var(--pk-radius) - 5px); }
-.pk-input-group-addon.start:has(> .pk-button) { margin-left: -0.3rem; }
-.pk-input-group-addon.end:has(> .pk-button) { margin-right: -0.3rem; }
+.pk-input-group-addon.start:has(> .pk-button) { margin-inline-start: -0.3rem; }
+.pk-input-group-addon.end:has(> .pk-button) { margin-inline-end: -0.3rem; }
 
 .pk-button.pk-input-group-button {
   gap: .25rem;

data/app/components/phlex_kit/input_group/input_group_addon.rb

@@ -17,7 +17,11 @@ module PhlexKit
     end
 
     def view_template(&)
-      div(**mix({ class: "pk-input-group-addon #{fetch_option(ALIGNS, @align, :align)}", role: "group" }, @attrs), &)
+      # No role: shadcn puts role="group" on its addon, but an unnamed group
+      # nested inside the InputGroup's own group is noise for AT — a text or
+      # icon addon needs no role, and interactive addon children (buttons)
+      # carry their own semantics.
+      div(**mix({ class: "pk-input-group-addon #{fetch_option(ALIGNS, @align, :align)}" }, @attrs), &)
     end
   end
 end

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

@@ -16,7 +16,7 @@
   outline: none;
   transition: border-color .15s ease, box-shadow .15s ease;
 }
-.pk-input-otp-slot:not(:first-child) { margin-left: -1px; }
+.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);

data/app/components/phlex_kit/input_otp/input_otp_controller.js

@@ -10,6 +10,12 @@ export default class extends Controller {
   static values = { length: Number }
 
   connect() {
+    // Slots compose without knowing their position, so `length:` can drift
+    // from the actual slot count — flag the mismatch instead of silently
+    // truncating/underfilling codes.
+    if (this.hasLengthValue && this.lengthValue !== this.slotTargets.length) {
+      console.warn(`phlex-kit--input-otp: length is ${this.lengthValue} but ${this.slotTargets.length} slots rendered`, this.element)
+    }
     // Slots compose without knowing their position — label them here so AT
     // announces "Digit N of M" instead of anonymous edit fields.
     this.slotTargets.forEach((slot, i) => {
@@ -17,12 +23,39 @@ export default class extends Controller {
         slot.setAttribute("aria-label", `Digit ${i + 1} of ${this.slotTargets.length}`)
       }
     })
+    // A server-provided value renders on the hidden input only — distribute
+    // it into the empty slots BEFORE syncing, or syncValue would join the
+    // empty slots and wipe the value with a spurious change event.
+    if (this.hasValueTarget && this.valueTarget.value && this.slotTargets.every((slot) => !slot.value)) {
+      const chars = this.valueTarget.value.split("")
+      this.slotTargets.forEach((slot, i) => { if (chars[i] != null) slot.value = chars[i] })
+    }
     this.syncValue()
   }
 
   onInput(e) {
     const slot = e.target
-    slot.value = slot.value.replace(/\s/g, "").slice(-1)
+    let text = slot.value.replace(/\s/g, "")
+    // Typing rejects the same characters paste strips — a letter keyed into
+    // an inputmode=numeric slot must not land.
+    if (slot.getAttribute("inputmode") === "numeric") text = text.replace(/\D/g, "")
+
+    if (text.length > 1) {
+      if (e.data && e.data.length === 1) {
+        // one keystroke into an already-filled slot: keep the newest char
+        slot.value = e.data
+        this.focusSlot(this.slotTargets.indexOf(slot) + 1)
+        this.syncValue()
+      } else {
+        // OTP autofill (autocomplete="one-time-code") delivers the whole
+        // code into the focused slot — distribute it like a paste instead
+        // of discarding all but one digit.
+        this.fillFrom(slot, text)
+      }
+      return
+    }
+
+    slot.value = text
     if (slot.value) this.focusSlot(this.slotTargets.indexOf(slot) + 1)
     this.syncValue()
   }
@@ -50,10 +83,16 @@ export default class extends Controller {
     // Numeric slots reject non-digits on typing; pasted text like
     // "code: 123456" should distribute only the digits.
     if (e.target.getAttribute("inputmode") === "numeric") text = text.replace(/\D/g, "")
+    if (!text.length) return
+    this.fillFrom(e.target, text)
+  }
+
+  // Distribute a multi-character string across the slots starting at `slot`
+  // (shared by paste and autofill), then park focus after the last filled one.
+  fillFrom(slot, text) {
     const chars = text.split("")
-    if (!chars.length) return
-    const start = this.slotTargets.indexOf(e.target)
-    this.slotTargets.slice(start).forEach((slot, i) => { if (chars[i] != null) slot.value = chars[i] })
+    const start = this.slotTargets.indexOf(slot)
+    this.slotTargets.slice(start).forEach((s, i) => { if (chars[i] != null) s.value = chars[i] })
     this.focusSlot(Math.min(start + chars.length, this.slotTargets.length - 1))
     this.syncValue()
   }