phlex_kit 0.9.1 → 0.11.0

data/app/components/phlex_kit/toast/toast_region.rb

@@ -41,11 +41,22 @@ module PhlexKit
       @duration = duration
       @gap = gap
       @offset = offset
+      # theme:/rich_colors: are Sonner API surface the kit deliberately does
+      # not implement (tokens are :root-scoped; there is no status palette) —
+      # fail loud rather than silently no-op (audit round 6).
       @theme = theme.to_sym
-      @rich_colors = rich_colors
+      unless @theme == :system
+        raise ArgumentError, "ToastRegion theme: only :system is supported — toasts follow the page theme (:root[data-theme])"
+      end
+      if rich_colors
+        raise ArgumentError, "ToastRegion rich_colors: is not supported — the kit has no status color palette (toasts follow --pk-* tokens)"
+      end
       @close_button = close_button
       @hotkey = hotkey
-      @dir = dir
+      @dir = dir.to_sym
+      unless %i[ltr rtl auto].include?(@dir)
+        raise ArgumentError, "ToastRegion dir: must be :ltr, :rtl or :auto"
+      end
       @flash = flash
       # Base id for the <ol> stack; the wrapper takes "#{id}-region". Defaults
       # keep the historical "pk-toaster"/"pk-toaster-region" pair — pass a
@@ -105,10 +116,12 @@ module PhlexKit
     end
 
     def region_attrs
-      {
+      base = {
         id: "#{@id}-region",
         role: "region",
         class: "pk-toast-region",
+        # offset: viewport-edge padding, consumed by toast.css.
+        style: "--pk-toast-offset: #{@offset.is_a?(Numeric) ? "#{@offset}px" : @offset};",
         # No aria-live here: each toast item is its own live region
         # (role="status"/"alert"); a live wrapper would double-announce.
         aria: { label: "Notifications" },
@@ -122,14 +135,11 @@ module PhlexKit
           phlex_kit__toaster_max_value: @max.to_s,
           phlex_kit__toaster_duration_value: @duration.to_s,
           phlex_kit__toaster_gap_value: @gap.to_s,
-          phlex_kit__toaster_offset_value: @offset.to_s,
-          phlex_kit__toaster_theme_value: @theme.to_s,
-          phlex_kit__toaster_rich_colors_value: @rich_colors.to_s,
-          phlex_kit__toaster_close_button_value: @close_button.to_s,
-          phlex_kit__toaster_hotkey_value: Array(@hotkey).join("+"),
-          phlex_kit__toaster_dir_value: @dir.to_s
+          phlex_kit__toaster_hotkey_value: Array(@hotkey).join("+")
         }
       }
+      base[:dir] = @dir.to_s unless @dir == :ltr
+      base
     end
   end
 end

data/app/components/phlex_kit/toast/toaster_controller.js

@@ -34,12 +34,10 @@ export default class extends Controller {
     max: { type: Number, default: 3 },
     duration: { type: Number, default: 4000 },
     gap: { type: Number, default: 14 },
-    offset: { type: Number, default: 24 },
-    theme: { type: String, default: "system" },
-    richColors: { type: Boolean, default: false },
-    closeButton: { type: Boolean, default: false },
+    // offset is a CSS custom property (--pk-toast-offset) and dir a real
+    // dir attribute, both stamped by ToastRegion; theme/richColors are
+    // unsupported (region raises) — none of them are controller state.
     hotkey: { type: String, default: "alt+t" },
-    dir: { type: String, default: "ltr" },
   }
 
   // State the target callbacks touch lives here, NOT in connect(): Stimulus
@@ -50,6 +48,7 @@ export default class extends Controller {
     this._heights = new Map()
     this._resizeObservers = new WeakMap()
     this._expanded = false
+    this._paused = false
   }
 
   connect() {
@@ -59,8 +58,11 @@ export default class extends Controller {
     registerStreamAction()
     if (!this._listEl) return
 
-    this._onPointerEnter = () => this._setExpanded(true)
-    this._onPointerLeave = () => { if (!this.expandValue) this._setExpanded(false) }
+    // Pause/resume tracks the POINTER, not the expand transition: an
+    // expand:true region is born expanded, and tying the pause dispatch to
+    // _setExpanded's state change left auto-dismiss running under the cursor.
+    this._onPointerEnter = () => { this._setPaused(true); this._setExpanded(true) }
+    this._onPointerLeave = () => { this._setPaused(false); if (!this.expandValue) this._setExpanded(false) }
     this._onWindowToast = (e) => this._spawn(e.detail || {})
     this._onWindowDismissAll = () => this._dismissById(null)
     this._onKey = this._onKey.bind(this)
@@ -82,6 +84,10 @@ export default class extends Controller {
     this._listEl?.removeEventListener("pointerenter", this._onPointerEnter)
     this._listEl?.removeEventListener("pointerleave", this._onPointerLeave)
     document.removeEventListener("keydown", this._onKey)
+    // Drop the global API if it still closes over this controller — after
+    // region teardown it would touch a stale _listEl. A replacement region
+    // re-registers its own on connect.
+    if (window.PhlexKit?.toast === this._api) delete window.PhlexKit.toast
   }
 
   toastTargetConnected(el) {
@@ -178,13 +184,21 @@ export default class extends Controller {
     return tpl.content.firstElementChild.cloneNode(true)
   }
 
-  _setExpanded(value) {
-    if (this._expanded === value) return
-    this._expanded = value
+  _setPaused(value) {
+    if (this._paused === value) return
+    this._paused = value
     // Mirror the pause state onto the DOM so toasts spawned while the stack
     // is already hovered can arm paused (the pause event predates them).
     this._listEl?.toggleAttribute("data-pk-toasts-paused", value)
-    document.dispatchEvent(new CustomEvent(value ? "phlex-kit:toast:pause" : "phlex-kit:toast:resume"))
+    // Region-scoped, not document-global: on multi-region pages one region's
+    // hover must not pause (or worse, RESUME under the pointer) another's
+    // toasts. Toasts listen on their own list element.
+    this._listEl.dispatchEvent(new CustomEvent(value ? "phlex-kit:toast:pause" : "phlex-kit:toast:resume"))
+  }
+
+  _setExpanded(value) {
+    if (this._expanded === value) return
+    this._expanded = value
     this._reflow()
   }
 
@@ -264,7 +278,14 @@ export default class extends Controller {
     const wantCtrl = parts.includes("ctrl")
     const wantMeta = parts.includes("meta")
     const wantShift = parts.includes("shift")
-    if (e.key.toLowerCase() !== key.toLowerCase()) return
+    // Match e.code as well as e.key: with Option held, macOS reports the
+    // COMPOSED character (Option+T → "†"), so alt+ hotkeys never match on
+    // e.key alone (Sonner matches event.code for the same reason).
+    const code = (e.code || "").toLowerCase()
+    const keyMatches = e.key.toLowerCase() === key.toLowerCase()
+      || code === `key${key.toLowerCase()}`
+      || code === `digit${key.toLowerCase()}`
+    if (!keyMatches) return
     if (wantAlt !== e.altKey) return
     if (wantCtrl !== e.ctrlKey) return
     if (wantMeta !== e.metaKey) return
@@ -303,6 +324,7 @@ export default class extends Controller {
     }
 
     window.PhlexKit = window.PhlexKit || {}
+    this._api = api
     window.PhlexKit.toast = api
   }
 

data/app/components/phlex_kit/toggle_group/toggle_group.css

@@ -1,11 +1,11 @@
 /* Co-located with toggle_group.rb. Theme tokens from the global stylesheet. */
 .pk-toggle-group { display: inline-flex; width: fit-content; align-items: center; border-radius: var(--pk-radius); }
 .pk-toggle-group.vertical { flex-direction: column; align-items: stretch; }
-.pk-toggle-group.spaced { gap: .25rem; }
+/* spacing: N stamps --pk-toggle-group-gap inline (N × .25rem). */
+.pk-toggle-group.spaced { gap: var(--pk-toggle-group-gap, .25rem); }
 /* Joined (default, unspaced): square the inner corners, tighten padding. */
-.pk-toggle-group:not(.spaced) .pk-toggle-group-item { padding-inline: .5rem; }
-.pk-toggle-group:not(.spaced) .pk-toggle-group-item { border-radius: 0; }
-.pk-toggle-group:not(.spaced):not(.vertical) .pk-toggle-group-item:first-of-type { border-top-left-radius: var(--pk-radius); border-bottom-left-radius: var(--pk-radius); }
-.pk-toggle-group:not(.spaced):not(.vertical) .pk-toggle-group-item:last-of-type { border-top-right-radius: var(--pk-radius); border-bottom-right-radius: var(--pk-radius); }
-.pk-toggle-group.vertical:not(.spaced) .pk-toggle-group-item:first-of-type { border-top-left-radius: var(--pk-radius); border-top-right-radius: var(--pk-radius); }
-.pk-toggle-group.vertical:not(.spaced) .pk-toggle-group-item:last-of-type { border-bottom-left-radius: var(--pk-radius); border-bottom-right-radius: var(--pk-radius); }
+.pk-toggle-group:not(.spaced) .pk-toggle-group-item { padding-inline: .5rem; border-radius: 0; }
+.pk-toggle-group:not(.spaced):not(.vertical) .pk-toggle-group-item:first-of-type { border-start-start-radius: var(--pk-radius); border-end-start-radius: var(--pk-radius); }
+.pk-toggle-group:not(.spaced):not(.vertical) .pk-toggle-group-item:last-of-type { border-start-end-radius: var(--pk-radius); border-end-end-radius: var(--pk-radius); }
+.pk-toggle-group.vertical:not(.spaced) .pk-toggle-group-item:first-of-type { border-start-start-radius: var(--pk-radius); border-start-end-radius: var(--pk-radius); }
+.pk-toggle-group.vertical:not(.spaced) .pk-toggle-group-item:last-of-type { border-end-start-radius: var(--pk-radius); border-end-end-radius: var(--pk-radius); }

data/app/components/phlex_kit/toggle_group/toggle_group.rb

@@ -21,7 +21,7 @@ module PhlexKit
 
     def view_template(&block)
       div(**mix(group_default_attrs, @attrs)) do
-        yield(self)
+        yield(self) if block
         render_hidden_inputs
       end
     end
@@ -54,12 +54,17 @@ module PhlexKit
     end
 
     def group_default_attrs
-      { role: (@type == :single) ? "radiogroup" : "group",
+      attrs = { role: (@type == :single) ? "radiogroup" : "group",
         class: [ "pk-toggle-group", (@orientation == :vertical ? "vertical" : nil), (@spacing > 0 ? "spaced" : nil) ].compact.join(" "),
         data: { controller: "phlex-kit--toggle-group",
           phlex_kit__toggle_group_type_value: @type.to_s,
           phlex_kit__toggle_group_name_value: @name.to_s,
           orientation: @orientation.to_s, spacing: @spacing.to_s } }
+      # spacing: N gaps the items by N × .25rem (Tailwind-style scale) via the
+      # custom property toggle_group.css reads. Trailing ";" so a caller
+      # style: merges into a second valid declaration (Phlex mix gotcha).
+      attrs[:style] = "--pk-toggle-group-gap: #{@spacing * 0.25}rem;" if @spacing > 0
+      attrs
     end
   end
 end

data/app/components/phlex_kit/toggle_group/toggle_group_controller.js

@@ -17,6 +17,14 @@ export default class extends Controller {
     }
     this.rebuildInputs()
     this.updateRovingTabindex(item)
+    // Parity with Toggle: announce the selection as
+    // "phlex-kit--toggle-group:change" — single carries the one selected
+    // value (radiogroup semantics: no deselect), multiple the pressed array.
+    const values = this.itemTargets.filter((el) => this.isPressed(el)).map((el) => el.dataset.value)
+    this.dispatch("change", {
+      detail: this.typeValue === "single" ? { value: values[0] ?? null } : { value: values },
+      bubbles: true
+    })
   }
 
   navigate(event) {
@@ -37,11 +45,15 @@ export default class extends Controller {
     const next = items[nextIndex]
     this.updateRovingTabindex(next)
     next.focus()
+    // APG radio-group keyboard model: with role="radio", arrows move focus
+    // AND check the landed-on item (Home/End included).
+    if (next !== event.currentTarget) next.click()
   }
 
   reconcile() {
     if (this.typeValue === "single") {
-      const pressed = this.itemTargets.find((el) => this.isPressed(el))
+      // A disabled button can't take focus — never hand it the tab stop.
+      const pressed = this.itemTargets.find((el) => this.isPressed(el) && !el.disabled)
       const first = pressed || this.enabledItems()[0]
       this.itemTargets.forEach((el) => el.setAttribute("tabindex", el === first ? "0" : "-1"))
     } else {

data/app/components/phlex_kit/toggle_group/toggle_group_item.rb

@@ -1,6 +1,12 @@
 module PhlexKit
   class ToggleGroupItem < Toggle
     def initialize(value:, group_context:, variant: nil, size: nil, **attrs)
+      # Toggle kwargs this item renders no markup for — inheriting them
+      # silently discarded the caller's input.
+      unsupported = attrs.keys & %i[wrapper name unpressed_value]
+      if unsupported.any?
+        raise ArgumentError, "ToggleGroupItem does not support #{unsupported.join(", ")} (group items render a bare button)"
+      end
       @item_value = value.to_s
       @group_context = group_context
       pressed = group_context[:selected_values].include?(@item_value)
@@ -26,7 +32,9 @@ module PhlexKit
       if @group_context[:type] == :single
         a[:role] = "radio"
         a[:aria] = { checked: @pressed.to_s }
-        a[:tabindex] = @pressed ? "0" : "-1"
+        # A disabled button can't take focus — giving the tab stop to a
+        # pressed-but-disabled item made the whole group Tab-unreachable.
+        a[:tabindex] = (@pressed && !@disabled) ? "0" : "-1"
       else
         a[:aria] = { pressed: @pressed.to_s }
         a[:tabindex] = "0"

data/app/components/phlex_kit/tooltip/tooltip.css

@@ -64,11 +64,11 @@
 }
 .pk-tooltip-content.bottom { position-area: block-end; margin: 6px 0 0; }
 .pk-tooltip-content.left {
-  position-area: inline-start; margin: 0 6px 0 0;
+  position-area: inline-start; margin: 0; margin-inline-end: 6px;
   position-try-fallbacks: flip-inline;
 }
 .pk-tooltip-content.right {
-  position-area: inline-end; margin: 0 0 0 6px;
+  position-area: inline-end; margin: 0; margin-inline-start: 6px;
   position-try-fallbacks: flip-inline;
 }
 /* Hover reveal only on devices that actually hover (a touch tap must not
@@ -79,6 +79,9 @@
   .pk-tooltip:hover .pk-tooltip-content {
     opacity: 1;
     visibility: visible;
+    /* WCAG 1.4.13 Hoverable: the revealed bubble must accept the pointer —
+       it's a DOM child of .pk-tooltip, so hovering it keeps the reveal. */
+    pointer-events: auto;
     transition-delay: .4s, .4s;
   }
 }
@@ -87,9 +90,10 @@
 .pk-tooltip:has(:focus-visible) .pk-tooltip-content {
   opacity: 1;
   visibility: visible;
+  pointer-events: auto;
   transition-delay: 0s, 0s;
 }
 /* Escape-dismissed (WCAG 1.4.13): suppressed until pointer/focus leaves.
    transition: none so the hide is immediate regardless of hover-in delays. */
 .pk-tooltip[data-pk-dismissed]:hover .pk-tooltip-content,
-.pk-tooltip[data-pk-dismissed]:focus-within .pk-tooltip-content { opacity: 0; visibility: hidden; transition: none; }
+.pk-tooltip[data-pk-dismissed]:focus-within .pk-tooltip-content { opacity: 0; visibility: hidden; pointer-events: none; transition: none; }

data/app/components/phlex_kit/tooltip/tooltip_controller.js

@@ -11,7 +11,13 @@ export default class extends Controller {
     const trigger = this.element.querySelector(".pk-tooltip-trigger")
     if (content && trigger) {
       if (!content.id) content.id = `pk-tooltip-${Math.random().toString(36).slice(2, 8)}`
-      if (!trigger.hasAttribute("aria-describedby")) trigger.setAttribute("aria-describedby", content.id)
+      // Describe the element that actually takes focus: with focusable: false
+      // the wrapper span never receives focus, so a describedby left only on
+      // it is never announced — wire the focusable child too.
+      const focusable = trigger.querySelector("button, a[href], input, select, textarea, [tabindex]")
+      ;[trigger, focusable].forEach((el) => {
+        if (el && !el.hasAttribute("aria-describedby")) el.setAttribute("aria-describedby", content.id)
+      })
     }
 
     this._onKeydown = (e) => {

data/app/components/phlex_kit/typography/heading.rb

@@ -8,15 +8,23 @@ module PhlexKit
     # ruby_ui's level → default size mapping (h1 is big, h4 smaller); 5/6
     # extend the scale downward — HTML has h1–h6, so all six must map.
     LEVEL_SIZE = { "1" => "7", "2" => "6", "3" => "5", "4" => "4", "5" => "3", "6" => "2" }.freeze
+    # `as:` is dispatched dynamically (send) — whitelist so it can't reach
+    # arbitrary (including private) methods. Mirrors Separator/Marker.
+    AS_TAGS = %i[h1 h2 h3 h4 h5 h6 p span div].freeze
 
-    def initialize(level: nil, as: nil, size: nil, **attrs)
+    # level: defaults to 1 so `Heading.new` is identical to `Heading.new(level: 1)`
+    # (a nil default used to render h1 with the level-6 size — self-disagreeing).
+    def initialize(level: 1, as: nil, size: nil, **attrs)
       # Fail loud at construction: level 7 previously exploded at render time
       # with NoMethodError (no h7 element), and 5/6 fell through the size map.
-      unless level.nil? || LEVEL_SIZE.key?(level.to_s)
+      unless LEVEL_SIZE.key?(level.to_s)
         raise ArgumentError, "Invalid heading level: #{level.inspect} — valid: 1–6"
       end
       @level = level
-      @as = as
+      @as = as&.to_sym
+      if @as && !AS_TAGS.include?(@as)
+        raise ArgumentError, "unknown Heading as: #{@as.inspect} (use one of #{AS_TAGS.join(", ")})"
+      end
       @size = size
       @attrs = attrs
     end
@@ -28,11 +36,11 @@ module PhlexKit
     private
 
     def element
-      (@as || (@level ? "h#{@level}" : "h1")).to_sym
+      (@as || "h#{@level}").to_sym
     end
 
     def size_token
-      token = (@size || LEVEL_SIZE[@level.to_s] || "6").to_s
+      token = (@size || LEVEL_SIZE.fetch(@level.to_s)).to_s
       raise ArgumentError, "Invalid heading size: #{token.inspect}" unless SIZES.include?(token)
       token
     end

data/app/components/phlex_kit/typography/list.rb

@@ -0,0 +1,22 @@
+module PhlexKit
+  # Prose list, ported from shadcn/ui's typography "list" style (ruby_ui's
+  # TypographyList). Renders a ul (or ol via as:) with the .pk-list styling
+  # that previously shipped as an orphaned utility class. Children are plain
+  # <li>s.
+  class List < BaseComponent
+    # `as:` is dispatched dynamically (send) — whitelist like Separator.
+    AS_TAGS = %i[ul ol].freeze
+
+    def initialize(as: :ul, **attrs)
+      @as = as.to_sym
+      unless AS_TAGS.include?(@as)
+        raise ArgumentError, "unknown List as: #{@as.inspect} (use one of #{AS_TAGS.join(", ")})"
+      end
+      @attrs = attrs
+    end
+
+    def view_template(&)
+      send(@as, **mix({ class: "pk-list" }, @attrs), &)
+    end
+  end
+end

data/app/components/phlex_kit/typography/text.rb

@@ -27,9 +27,15 @@ module PhlexKit
       bold: "pk-text-bold",
       muted: "pk-text-muted"
     }.freeze
+    # `as:` is dispatched dynamically (send) — whitelist so it can't reach
+    # arbitrary (including private) methods. Mirrors Separator/Marker.
+    AS_TAGS = %i[p span div label small strong em].freeze
 
     def initialize(as: :p, size: "3", weight: :regular, **attrs)
-      @as = as
+      @as = as.to_sym
+      unless AS_TAGS.include?(@as)
+        raise ArgumentError, "unknown Text as: #{@as.inspect} (use one of #{AS_TAGS.join(", ")})"
+      end
       @size = size.to_s
       @weight = weight.to_sym
       @attrs = attrs

data/lib/phlex_kit/base_component.rb

@@ -30,5 +30,18 @@ module PhlexKit
                         "valid: #{map.keys.map(&:inspect).join(", ")}"
       end
     end
+
+    # True when the caller supplied an accessible name in @attrs — via the
+    # aria: hash or flat aria_label/aria-label(ledby) keys. Components with a
+    # generated default label must skip it then: `mix` merges duplicate string
+    # attrs ("pagination Résultats") instead of overriding.
+    def aria_labelled?
+      aria = @attrs[:aria] || @attrs["aria"]
+      if aria.is_a?(Hash)
+        return true if %i[label labelledby].any? { |k| aria[k] || aria[k.to_s] }
+      end
+      [ :aria_label, "aria_label", "aria-label",
+        :aria_labelledby, "aria_labelledby", "aria-labelledby" ].any? { |k| @attrs[k] }
+    end
   end
 end

data/lib/phlex_kit/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module PhlexKit
-  VERSION = "0.9.1"
+  VERSION = "0.11.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: phlex_kit
 version: !ruby/object:Gem::Version
-  version: 0.9.1
+  version: 0.11.0
 platform: ruby
 authors:
 - Matt Kennedy
@@ -373,6 +373,7 @@ files:
 - app/components/phlex_kit/hover_card/hover_card_content.rb
 - app/components/phlex_kit/hover_card/hover_card_controller.js
 - app/components/phlex_kit/hover_card/hover_card_trigger.rb
+- app/components/phlex_kit/icon/icon.css
 - app/components/phlex_kit/icon/icon.rb
 - app/components/phlex_kit/input/input.css
 - app/components/phlex_kit/input/input.rb
@@ -587,6 +588,7 @@ files:
 - app/components/phlex_kit/typography/heading.rb
 - app/components/phlex_kit/typography/inline_code.rb
 - app/components/phlex_kit/typography/inline_link.rb
+- app/components/phlex_kit/typography/list.rb
 - app/components/phlex_kit/typography/text.rb
 - app/components/phlex_kit/typography/typography.css
 - app/javascript/phlex_kit/controllers/index.js