RubyGems - phlex_kit - Versions diffs - 0.5.1 → 0.6.1 - Mend

phlex_kit 0.5.1 → 0.6.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (128) hide show

checksums.yaml CHANGED Viewed

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a8140f5bead7563457fe7da7998915db03b3011c72bf82163236b75aff4ce15d
-  data.tar.gz: '08fe9d1bd2e68091e4586e10823a98d5d7226dd57fff7d8050cf073511f483d8'
+  metadata.gz: 74f3d49a1a6adfab950d193db75d0cce12c02308c10fe69566d7a62ea0a835e3
+  data.tar.gz: 0b673ba98ab594e4f2783a32c83b792e849605cd43fb1033d2bd258dece4c789
 SHA512:
-  metadata.gz: 250d307d76eacb729f7672be2a8e00cc7e0057b3fca3079e544f518eec8417615843a1e2ef2d2043d99cde927993d6383f5269cae06e164f6d68d9e4a4705c10
-  data.tar.gz: 5fb5b1a04c2483fb63c9ef761ba05fd3ebd01ef45f05a0be2bee40b979ae4da240d610d0ae555a6470dcd11be74d08475d488ed5861b9fba7472bcd5efe764c7
+  metadata.gz: d0e680e98ac74f15fa085a2828e7aa86041d67fa58ec82dd07d9f2912bc06c063ef58b5fcdcba5c44b037cc7b4070b01869b891da449ad8bcbb9ce4eb62facf4
+  data.tar.gz: ddea978e8b26eaf08dcb373df2c59bec15405f0c043ca349c8c6f6e1c20194f75712281d526f70bc0fc234fcb2aeb41a79f42386182494a6a597af3bb9868fe3

data/README.md CHANGED Viewed

@@ -6,7 +6,7 @@
 A [shadcn/ui](https://ui.shadcn.com)-grade component kit for
 [Phlex](https://phlex.fun) + Rails, styled with **vanilla CSS + design tokens
 instead of Tailwind**. The full [ruby_ui](https://ruby-ui.com) catalog plus
-shadcn's own additions — 70 component families, 38 Stimulus controllers —
+shadcn's own additions — 72 component families, 40 Stimulus controllers —
 with the default theme lifted verbatim from shadcn/ui's current token system.
 <picture>
@@ -21,7 +21,9 @@ switches, nav menu, command palette — at `/create` in [the docs site](#the-doc
 - **No build step.** Components are plain Ruby classes with co-located vanilla
   CSS, served precompiled-static through Propshaft. No Tailwind, no Node, no
-  PostCSS.
+  PostCSS. (Outside Rails there's no Zeitwerk to autoload them — after
+  `require "phlex_kit"`, require the component files you use, e.g.
+  `Dir[File.join(gem_dir, "app/components/phlex_kit/**/*.rb")].sort.each { require it }`.)
 - **The shadcn look, themeable.** Every component reads `--pk-*` custom
   properties. The default palette, radii, and control geometry match
   ui.shadcn.com; redefine `:root` and the whole kit re-themes live — dark,
@@ -119,8 +121,8 @@ PhlexKit.configure { |c| c.define_ui_alias = true }   # UI == PhlexKit
 The gem ships shadcn/ui's default (neutral) token set — dark by default, light
 via `<html data-theme="light">`, OS-following via `data-theme="system"`.
-Override any token in your own stylesheet; your app's CSS sorts ahead of the
-gem's, so you win:
+Override any token in your own stylesheet — the installer prepends the gem's
+`@import`, so the gem's rules come first and yours, coming later, win:
 ```css
 @import url("phlex_kit/phlex_kit.css");
@@ -137,8 +139,9 @@ The full token surface: `--pk-bg`, `--pk-surface`, `--pk-surface-2`,
 `--pk-brand`, `--pk-brand-ink`, `--pk-green`, `--pk-amber`, `--pk-red`,
 `--pk-chart-1..5`, `--pk-radius`, plus `--pk-font-sans` / `--pk-font-serif` /
 `--pk-font-mono` (system stacks by default — override them after an @font-face to adopt Geist
-like shadcn, as the docs site does). Want a fully custom palette? Drop the
-`_tokens.css` import and define them all yourself. The complete reference —
+like shadcn, as the docs site does). Want a fully custom palette? Override
+every token in your stylesheet (the `_tokens.css` import lives inside the
+gem's manifest, so you re-declare rather than remove). The complete reference —
 defaults, shadcn equivalents, the optional `--pk-sidebar-*` overrides, and
 every per-component knob (`--pk-card-spacing`, `--pk-cell-size`, …) — is in
 [docs/07-TOKENS.md](docs/07-TOKENS.md).
@@ -248,7 +251,16 @@ for another component reuses the same wiring — it's injected only once.
 The dummy Rails app is a full shadcn-style docs site: a sidebar menu with one
 page per component, every use case demoed with a Preview/Code toggle (the code
 shown is extracted from the running example source, so it can never drift).
-A one-page kitchen-sink gallery lives at /gallery:
+A one-page kitchen-sink gallery lives at /gallery, and /examples holds six
+full-page admin screens (dashboard, orders, inbox, profile, reports, settings)
+for a fictional commerce app — every visible element a kit component:
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="docs/images/examples-dashboard-dark.png">
+  <source media="(prefers-color-scheme: light)" srcset="docs/images/examples-dashboard-light.png">
+  <img alt="The /examples admin dashboard — KPI cards, a revenue chart and a live activity feed inside the kit's sidebar shell" src="docs/images/examples-dashboard-light.png">
+</picture>
 ```bash
 git clone https://github.com/MatthewKennedy/phlex_kit && cd phlex_kit
@@ -284,7 +296,8 @@ alert dialog, aspect ratio, attachment, avatar (+ group), badge, breadcrumb,
 bubble, button, button group, calendar, card, carousel, chart, checkbox,
 clipboard, codeblock, collapsible, combobox (button/input/badge-chip
 triggers), command palette, context menu, data table, date picker, dialog,
-drawer, dropdown menu, empty, form + form field, hover card, input, input
+drawer, dropdown menu, empty, field (set / group / label / description /
+error), form + form field, hover card, input, input
 group, input OTP, item, kbd, label, link, masked input, menubar, message,
 message scroller, native select, navigation menu, pagination, popover,
 marker, progress, radio button + radio group, resizable, scroll area, select,

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

@@ -1,6 +1,8 @@
 /* Co-located with accordion.rb. Theme tokens from the global stylesheet. */
 .pk-accordion { width: 100%; }
 .pk-accordion-item { border-bottom: 1px solid var(--pk-border); }
+/* APG: triggers live inside headings — the heading is a neutral wrapper. */
+.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;

data/app/components/phlex_kit/accordion/accordion.rb CHANGED Viewed

@@ -13,7 +13,7 @@ module PhlexKit
     end
     def view_template(&)
-      div(**mix({ class: "pk-accordion", data: { type: TYPES.fetch(@type) } }, @attrs), &)
+      div(**mix({ class: "pk-accordion", data: { type: fetch_option(TYPES, @type, :type) } }, @attrs), &)
     end
   end
 end

data/app/components/phlex_kit/accordion/accordion_content.rb CHANGED Viewed

@@ -2,7 +2,9 @@ module PhlexKit
   class AccordionContent < BaseComponent
     def initialize(**attrs) = (@attrs = attrs)
     def view_template(&)
-      div(**mix({ class: "pk-accordion-content", data: { phlex_kit__accordion_target: "content", state: "closed" }, style: "height: 0px;", hidden: true }, @attrs), &)
+      # 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), &)
     end
   end
 end

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

@@ -3,8 +3,10 @@ import { Controller } from "@hotwired/stimulus"
 // Connects to data-controller="phlex-kit--accordion"
 // Ported from ruby_ui's ruby-ui--accordion controller, reworked to use the native
 // Web Animations API instead of the `motion` package (no extra JS dependency).
+let uid = 0
 export default class extends Controller {
-  static targets = ["icon", "content"]
+  static targets = ["icon", "content", "trigger"]
   static values = {
     open: { type: Boolean, default: false },
     animationDuration: { type: Number, default: 150 },
@@ -12,6 +14,7 @@ export default class extends Controller {
   }
   connect() {
+    this.wireAria()
     const d = this.animationDurationValue
     this.animationDurationValue = 0
     this.openValue ? this.open() : this.close()
@@ -35,7 +38,28 @@ export default class extends Controller {
       if (ctrl && ctrl.openValue) ctrl.openValue = false
     })
   }
-  openValueChanged(isOpen) { isOpen ? this.open() : this.close() }
+  openValueChanged(isOpen) {
+    if (this.hasTriggerTarget) this.triggerTarget.setAttribute("aria-expanded", isOpen ? "true" : "false")
+    isOpen ? this.open() : this.close()
+  }
+  // Pair the trigger with its content: assign per-instance ids (render time
+  // has no shared item value, so the parts can't derive them), wire
+  // aria-controls/aria-labelledby, and propagate a disabled item onto the
+  // actual button so it drops out of the tab order.
+  wireAria() {
+    if (!this.hasTriggerTarget) return
+    const id = ++uid
+    const trigger = this.triggerTarget
+    if (!trigger.id) trigger.id = `pk-accordion-trigger-${id}`
+    if (this.hasContentTarget) {
+      const content = this.contentTarget
+      if (!content.id) content.id = `pk-accordion-panel-${id}`
+      trigger.setAttribute("aria-controls", content.id)
+      content.setAttribute("aria-labelledby", trigger.id)
+    }
+    if ("disabled" in this.element.dataset) trigger.disabled = true
+  }
   open() {
     if (!this.hasContentTarget) return

data/app/components/phlex_kit/accordion/accordion_default_trigger.rb CHANGED Viewed

@@ -1,11 +1,27 @@
 module PhlexKit
   # Convenience trigger: label on the left, chevron icon on the right.
   class AccordionDefaultTrigger < BaseComponent
-    def initialize(**attrs) = (@attrs = attrs)
+    def initialize(open: false, disabled: false, heading_level: 3, **attrs)
+      raise ArgumentError, "heading_level must be 1..6" unless (1..6).cover?(heading_level)
+      @open = open
+      @disabled = disabled
+      @heading_level = heading_level
+      @attrs = attrs
+    end
     def view_template(&block)
-      button(**mix({ type: "button", class: "pk-accordion-trigger", data: { action: "click->phlex-kit--accordion#toggle" } }, @attrs)) do
-        span(class: "pk-accordion-trigger-label", &block)
-        render PhlexKit::AccordionIcon.new
+      # APG accordion: each trigger is a button wrapped in a heading.
+      # aria-expanded reflects the render-time open state; the controller keeps
+      # it in sync and wires aria-controls to the content's id in connect().
+      base = {
+        type: "button", class: "pk-accordion-trigger",
+        aria_expanded: @open ? "true" : "false", disabled: @disabled,
+        data: { phlex_kit__accordion_target: "trigger", action: "click->phlex-kit--accordion#toggle" }
+      }
+      send(:"h#{@heading_level}", class: "pk-accordion-heading") do
+        button(**mix(base, @attrs)) do
+          span(class: "pk-accordion-trigger-label", &block)
+          render PhlexKit::AccordionIcon.new
+        end
       end
     end
   end

data/app/components/phlex_kit/accordion/accordion_trigger.rb CHANGED Viewed

@@ -1,8 +1,24 @@
 module PhlexKit
   class AccordionTrigger < BaseComponent
-    def initialize(**attrs) = (@attrs = attrs)
+    def initialize(open: false, disabled: false, heading_level: 3, **attrs)
+      raise ArgumentError, "heading_level must be 1..6" unless (1..6).cover?(heading_level)
+      @open = open
+      @disabled = disabled
+      @heading_level = heading_level
+      @attrs = attrs
+    end
     def view_template(&)
-      button(**mix({ type: "button", class: "pk-accordion-trigger", data: { action: "click->phlex-kit--accordion#toggle" } }, @attrs), &)
+      # APG accordion: each trigger is a button wrapped in a heading.
+      # aria-expanded reflects the render-time open state; the controller keeps
+      # it in sync and wires aria-controls to the content's id in connect().
+      base = {
+        type: "button", class: "pk-accordion-trigger",
+        aria_expanded: @open ? "true" : "false", disabled: @disabled,
+        data: { phlex_kit__accordion_target: "trigger", action: "click->phlex-kit--accordion#toggle" }
+      }
+      send(:"h#{@heading_level}", class: "pk-accordion-heading") do
+        button(**mix(base, @attrs), &)
+      end
     end
   end
 end

data/app/components/phlex_kit/alert/alert.rb CHANGED Viewed

@@ -35,7 +35,7 @@ module PhlexKit
     private
     def classes
-      [ "pk-alert", VARIANTS.fetch(@variant) ].compact.join(" ")
+      [ "pk-alert", fetch_option(VARIANTS, @variant, :variant) ].compact.join(" ")
     end
   end
 end

data/app/components/phlex_kit/alert_dialog/alert_dialog_cancel.rb CHANGED Viewed

@@ -7,7 +7,7 @@ module PhlexKit
     end
     def view_template(&block)
-      render PhlexKit::Button.new(variant: :outline, data: { action: "click->phlex-kit--alert-dialog#dismiss" }, **@attrs, &block)
+      render PhlexKit::Button.new(variant: :outline, **mix({ data: { action: "click->phlex-kit--alert-dialog#dismiss" } }, @attrs), &block)
     end
   end
 end

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

@@ -15,7 +15,7 @@ module PhlexKit
       template(**mix({ data: { phlex_kit__alert_dialog_target: "content" } }, @attrs)) do
         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", SIZES.fetch(@size) ].compact.join(" "), &block)
+          div(role: "alertdialog", "aria-modal": "true", class: [ "pk-alert-dialog-panel", fetch_option(SIZES, @size, :size) ].compact.join(" "), &block)
         end
       end
     end

data/app/components/phlex_kit/attachment/attachment.rb CHANGED Viewed

@@ -20,8 +20,8 @@ module PhlexKit
     def view_template(&)
       div(**mix({
-        class: [ "pk-attachment", SIZES.fetch(@size), ORIENTATIONS.fetch(@orientation) ].compact.join(" "),
-        data: { state: STATES.fetch(@state) }
+        class: [ "pk-attachment", fetch_option(SIZES, @size, :size), fetch_option(ORIENTATIONS, @orientation, :orientation) ].compact.join(" "),
+        data: { state: fetch_option(STATES, @state, :state) }
       }, @attrs), &)
     end
   end

data/app/components/phlex_kit/attachment/attachment_media.rb CHANGED Viewed

@@ -11,7 +11,7 @@ module PhlexKit
     end
     def view_template(&)
-      div(**mix({ class: [ "pk-attachment-media", VARIANTS.fetch(@variant) ].compact.join(" ") }, @attrs), &)
+      div(**mix({ class: [ "pk-attachment-media", fetch_option(VARIANTS, @variant, :variant) ].compact.join(" ") }, @attrs), &)
     end
   end
 end

data/app/components/phlex_kit/avatar/avatar.rb CHANGED Viewed

@@ -21,7 +21,7 @@ module PhlexKit
     private
     def classes
-      [ "pk-avatar", SIZES.fetch(@size) ].compact.join(" ")
+      [ "pk-avatar", fetch_option(SIZES, @size, :size) ].compact.join(" ")
     end
   end
 end

data/app/components/phlex_kit/badge/badge.rb CHANGED Viewed

@@ -50,7 +50,7 @@ module PhlexKit
     private
     def classes
-      [ "pk-badge", VARIANTS.fetch(@variant), SIZES.fetch(@size) ].compact.join(" ")
+      [ "pk-badge", fetch_option(VARIANTS, @variant, :variant), fetch_option(SIZES, @size, :size) ].compact.join(" ")
     end
   end
 end

data/app/components/phlex_kit/button/button.rb CHANGED Viewed

@@ -52,7 +52,7 @@ module PhlexKit
     private
     def classes
-      [ "pk-button", VARIANTS.fetch(@variant), SIZES.fetch(@size), ("icon" if @icon) ].compact.join(" ")
+      [ "pk-button", fetch_option(VARIANTS, @variant, :variant), fetch_option(SIZES, @size, :size), ("icon" if @icon) ].compact.join(" ")
     end
   end
 end

data/app/components/phlex_kit/button_group/button_group.rb CHANGED Viewed

@@ -13,7 +13,7 @@ module PhlexKit
     end
     def view_template(&)
-      classes = [ "pk-button-group", ORIENTATIONS.fetch(@orientation) ].compact.join(" ")
+      classes = [ "pk-button-group", fetch_option(ORIENTATIONS, @orientation, :orientation) ].compact.join(" ")
       div(**mix({ class: classes, role: "group" }, @attrs), &)
     end
   end

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

@@ -34,10 +34,10 @@ export default class extends Controller {
     maxDate: { type: String, default: null },
     disabledDates: { type: Array, default: [] },
     weekNumbers: { type: Boolean, default: false },
-    viewDate: {
-      type: String,
-      default: new Date().toISOString().slice(0, 10),
-    },
+    // Resolved lazily by viewDate() — a `new Date()` default here would be
+    // frozen at module load (stale "today" in long-lived tabs) and
+    // toISOString() is UTC (wrong day for non-UTC users near midnight).
+    viewDate: { type: String, default: "" },
     format: { type: String, default: "yyyy-MM-dd" },
   };
   static outlets = ["phlex-kit--calendar-input"];
@@ -61,14 +61,14 @@ export default class extends Controller {
     const date = this.viewDate();
     date.setDate(2);
     date.setMonth(Number(e.target.value));
-    this.viewDateValue = date.toISOString().slice(0, 10);
+    this.viewDateValue = this.isoDate(date);
   }
   setYear(e) {
     const date = this.viewDate();
     date.setDate(2);
     date.setFullYear(Number(e.target.value));
-    this.viewDateValue = date.toISOString().slice(0, 10);
+    this.viewDateValue = this.isoDate(date);
   }
   selectDay(e) {
@@ -132,9 +132,13 @@ export default class extends Controller {
     // update the viewDateValue to the selected date's month (this re-renders)
     const newViewDate = new Date(selectedDate);
     newViewDate.setDate(2); // avoid month-length/timezone edges
-    this.viewDateValue = newViewDate.toISOString().slice(0, 10);
+    this.viewDateValue = this.isoDate(newViewDate);
     this.updateCalendar();
+    // Stimulus fires valueChanged during value initialization too — a
+    // server-rendered selected_date must not dispatch a change event.
+    if (prevValue === undefined) return;
     this.pushToOutlets();
     this.dispatchChange();
   }
@@ -180,7 +184,7 @@ export default class extends Controller {
     const date = this.viewDate();
     date.setDate(2); // avoid month-length/timezone edges
     date.setMonth(date.getMonth() + adjustment);
-    return date.toISOString().slice(0, 10);
+    return this.isoDate(date);
   }
   updateCalendar() {

data/app/components/phlex_kit/card/card.rb CHANGED Viewed

@@ -27,7 +27,7 @@ module PhlexKit
     end
     def view_template(&block)
-      div(**mix({ class: [ "pk-card", SIZES.fetch(@size) ].compact.join(" ") }, @attrs), &block)
+      div(**mix({ class: [ "pk-card", fetch_option(SIZES, @size, :size) ].compact.join(" ") }, @attrs), &block)
     end
   end
 end

data/app/components/phlex_kit/carousel/carousel.rb CHANGED Viewed

@@ -17,7 +17,7 @@ module PhlexKit
     def view_template(&)
       div(**mix({
-        class: [ "pk-carousel", ORIENTATIONS.fetch(@orientation) ].join(" "),
+        class: [ "pk-carousel", fetch_option(ORIENTATIONS, @orientation, :orientation) ].join(" "),
         role: "region",
         aria: { roledescription: "carousel" },
         data: {

data/app/components/phlex_kit/clipboard/clipboard_popover.rb CHANGED Viewed

@@ -6,7 +6,7 @@ module PhlexKit
       @attrs = attrs
     end
     def view_template(&block)
-      div(class: "pk-clipboard-popover pk-hidden", data: { phlex_kit__clipboard_target: TARGETS.fetch(@type) }) do
+      div(class: "pk-clipboard-popover pk-hidden", data: { phlex_kit__clipboard_target: fetch_option(TARGETS, @type, :target) }) do
         div(**mix({ class: "pk-clipboard-popover-inner" }, @attrs), &block)
       end
     end

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

@@ -1,10 +1,13 @@
 /* Co-located with combobox.rb — UI::Combobox. ruby_ui's structure + Stimulus
-   kept; the @floating-ui/native-popover positioning replaced with plain CSS
-   (panel below the trigger), and Tailwind with vanilla CSS on the palette
-   tokens. Geometry from ruby_ui (h-9 trigger, rounded-lg panel, p-1 list,
-   px-2 py-1 label rows, group labels via ::before content(attr(label))).
+   kept; like upstream the panel is a native [popover] (manual), and CSS
+   anchor positioning replaces @floating-ui (Baseline 2026): the panel anchors
+   to the combobox wrapper (all three trigger layouts fill it), gets the
+   trigger width as a floor via anchor-size(), and flips above at the
+   viewport bottom via position-try-fallbacks. Tailwind → vanilla CSS on the
+   palette tokens. Geometry from ruby_ui (h-9 trigger, rounded-lg panel, p-1
+   list, px-2 py-1 label rows, group labels via ::before content(attr(label))).
    Theme tokens come from the global stylesheet. */
-.pk-combobox { position: relative; width: 100%; }
+.pk-combobox { width: 100%; anchor-name: --pk-combobox; anchor-scope: --pk-combobox; }
 /* Closed-state trigger (mirrors .pk-select-trigger geometry). */
 .pk-combobox-trigger {
@@ -40,14 +43,17 @@
 .pk-combobox-trigger-content { overflow: hidden; text-overflow: ellipsis; }
 .pk-combobox-trigger-icon { flex: none; width: 1rem; height: 1rem; margin-left: .5rem; opacity: .5; }
-/* Dropdown panel — opens below the trigger (no floating-ui); the controller
-   toggles .pk-hidden and matches its width to the trigger. */
+/* Dropdown panel — anchored below the combobox, flips above at the viewport
+   bottom. Width: trigger width with a 15rem floor (was JS
+   updatePopoverWidth, now pure CSS). */
 .pk-combobox-popover {
-  position: absolute;
-  top: 100%;
-  left: 0;
-  z-index: 50;
-  margin-top: .25rem;
+  position: fixed;
+  position-anchor: --pk-combobox;
+  inset: auto;
+  position-area: block-end span-inline-end;
+  margin: .25rem 0 0;
+  position-try-fallbacks: flip-block;
+  width: max(anchor-size(width), 15rem);
   border: 1px solid var(--pk-border);
   border-radius: var(--pk-radius);
   background: var(--pk-surface);
@@ -342,3 +348,6 @@
     box-shadow: 0 0 0 3px color-mix(in oklab, var(--pk-red) 20%, transparent);
   }
 }
+/* Hiding must survive author display values (a host class like
+   display:grid would beat the UA [popover] { display: none }). */
+.pk-combobox-popover:not(:popover-open) { display: none; }

data/app/components/phlex_kit/combobox/combobox.rb CHANGED Viewed

@@ -19,9 +19,10 @@ module PhlexKit
       @attrs = attrs
     end
-    def view_template(&)
+    def view_template
+      # role="combobox" lives on the interactive element (the trigger button /
+      # filter input), not this wrapper — see ComboboxTrigger and friends.
       div(**mix({
-        role: "combobox",
         class: "pk-combobox",
         data: {
           controller: "phlex-kit--combobox",
@@ -29,7 +30,22 @@ module PhlexKit
           phlex_kit__combobox_auto_highlight_value: (@auto_highlight ? "true" : nil),
           action: "turbo:morph@window->phlex-kit--combobox#updateTriggerContent click@window->phlex-kit--combobox#onClickOutside"
         }
-      }, @attrs), &)
+      }, @attrs)) do
+        live_region
+        yield
+      end
+    end
+    private
+    # Screen-reader announcement of the filtered result count — the controller
+    # writes "N results" / "No results" into it from applyFilter.
+    def live_region
+      div(
+        class: "pk-sr-only",
+        aria: { live: "polite" },
+        data: { phlex_kit__combobox_target: "liveRegion" }
+      )
     end
   end
 end

data/app/components/phlex_kit/combobox/combobox_badge_trigger.rb CHANGED Viewed

@@ -8,16 +8,19 @@ module PhlexKit
   # PhlexKit's completion of it. Keyboard actions live here because focus stays
   # in this field (see ComboboxInputTrigger). See combobox.rb.
   class ComboboxBadgeTrigger < BaseComponent
-    def initialize(placeholder: "", clear_button: false, **attrs)
+    def initialize(placeholder: "", clear_button: false, list_id: nil, **attrs)
       @placeholder = placeholder
       @clear_button = clear_button
+      @list_id = list_id
       @attrs = attrs
     end
     def view_template
+      # The ARIA combobox role sits on the field itself (the interactive
+      # element), not this wrapper. Pass `list_id:` matching the ComboboxList
+      # id to wire aria-controls statically — otherwise the controller wires it.
       div(**mix({
         class: "pk-combobox-badge-trigger",
-        aria: { haspopup: "listbox", expanded: "false" },
         data: {
           placeholder: @placeholder,
           phlex_kit__combobox_target: "trigger",
@@ -34,6 +37,8 @@ module PhlexKit
         div(class: "pk-combobox-badge-container pk-hidden", data: { phlex_kit__combobox_target: "badgeContainer" })
         input(
           type: :text,
+          role: "combobox",
+          aria: { haspopup: "listbox", expanded: "false", autocomplete: "list", controls: @list_id },
           placeholder: @placeholder,
           autocomplete: "off",
           autocorrect: "off",

data/app/components/phlex_kit/combobox/combobox_checkbox.rb CHANGED Viewed

@@ -10,6 +10,9 @@ module PhlexKit
     def view_template
       input(**mix({
         type: :checkbox,
+        # The option label is the interactive surface (ARIA option); the real
+        # input must not be a second tab stop inside it.
+        tabindex: "-1",
         class: "pk-combobox-checkbox",
         data: {
           phlex_kit__combobox_target: "input",