maquina-components 0.5.0 → 0.5.1

data/app/javascript/controllers/breadcrumb_controller.js

@@ -4,10 +4,15 @@ export default class extends Controller {
   static targets = ["item", "ellipsis", "ellipsisSeparator"]
   static values = { collapseAfter: { type: Number, default: 0 } }
 
+  // True when CSS anchor positioning (breadcrumbs.css) places the popover
+  static supportsAnchorPositioning =
+    typeof CSS !== "undefined" &&
+    CSS.supports("anchor-name: --a") &&
+    CSS.supports("position-area: block-end")
+
   connect() {
     this._dropdown = null
-    this._clickOutsideHandler = this._closeDropdown.bind(this)
-    this._escapeHandler = this._handleEscape.bind(this)
+    this._popoverToggleHandler = this._handlePopoverToggle.bind(this)
     this._teardownHandler = this._teardown.bind(this)
 
     document.addEventListener("turbo:before-cache", this._teardownHandler)
@@ -29,7 +34,6 @@ export default class extends Controller {
       this._ellipsisTrigger = trigger
       this._toggleHandler = this._toggleDropdown.bind(this)
       trigger.addEventListener('click', this._toggleHandler)
-      trigger.style.cursor = 'pointer'
     }
   }
 
@@ -133,7 +137,7 @@ export default class extends Controller {
   _toggleDropdown(event) {
     event.stopPropagation()
 
-    if (this._dropdown && this._dropdown.dataset.state === "open") {
+    if (this._dropdown && this._dropdown.matches(":popover-open")) {
       this._closeDropdown()
     } else {
       this._openDropdown()
@@ -144,47 +148,55 @@ export default class extends Controller {
     if (!this._hiddenLinks || this._hiddenLinks.length === 0) return
 
     if (!this._dropdown) {
+      // popover="auto" gives top-layer rendering, light dismiss, and
+      // Escape-to-close natively — no document listeners needed
       this._dropdown = document.createElement('div')
       this._dropdown.setAttribute('role', 'menu')
+      this._dropdown.setAttribute('popover', 'auto')
       this._dropdown.dataset.dropdownMenuPart = 'content'
-      this._dropdown.style.position = 'fixed'
-      this._dropdown.style.zIndex = '50'
-      document.body.appendChild(this._dropdown)
+      this._dropdown.dataset.breadcrumbPart = 'dropdown'
+      this._dropdown.addEventListener('beforetoggle', this._popoverToggleHandler)
+      // Next to the trigger so CSS anchor positioning can resolve it
+      this._ellipsisTrigger.insertAdjacentElement('afterend', this._dropdown)
     }
 
     this._buildDropdownContent()
     this._positionDropdown()
-    this._dropdown.dataset.state = 'open'
-
-    if (this._ellipsisTrigger) {
-      this._ellipsisTrigger.dataset.state = 'open'
-    }
-
-    // Defer listeners so the current click doesn't immediately close
-    requestAnimationFrame(() => {
-      document.addEventListener('click', this._clickOutsideHandler)
-      document.addEventListener('keydown', this._escapeHandler)
-    })
+    this._dropdown.showPopover()
   }
 
   _closeDropdown() {
-    if (this._dropdown) {
-      this._dropdown.dataset.state = 'closed'
+    if (this._dropdown && this._dropdown.matches(":popover-open")) {
+      this._dropdown.hidePopover()
     }
+  }
+
+  // Mirrors the native popover state onto the data attributes the CSS
+  // animations and the trigger styling key on
+  _handlePopoverToggle(event) {
+    const open = event.newState === 'open'
+
+    this._dropdown.dataset.state = open ? 'open' : 'closed'
+
     if (this._ellipsisTrigger) {
-      delete this._ellipsisTrigger.dataset.state
+      if (open) {
+        this._ellipsisTrigger.dataset.state = 'open'
+      } else {
+        delete this._ellipsisTrigger.dataset.state
+      }
     }
-
-    document.removeEventListener('click', this._clickOutsideHandler)
-    document.removeEventListener('keydown', this._escapeHandler)
   }
 
   _removeDropdown() {
     this._closeDropdown()
     if (this._dropdown) {
+      this._dropdown.removeEventListener('beforetoggle', this._popoverToggleHandler)
       this._dropdown.remove()
       this._dropdown = null
     }
+    if (this._ellipsisTrigger) {
+      delete this._ellipsisTrigger.dataset.state
+    }
   }
 
   _buildDropdownContent() {
@@ -203,19 +215,16 @@ export default class extends Controller {
   }
 
   _positionDropdown() {
+    // Modern browsers position the popover declaratively via anchor CSS
+    if (this.constructor.supportsAnchorPositioning) return
     if (!this._dropdown || !this._ellipsisTrigger) return
 
     const rect = this._ellipsisTrigger.getBoundingClientRect()
+    this._dropdown.style.position = 'fixed'
     this._dropdown.style.top = `${rect.bottom + 4}px`
     this._dropdown.style.left = `${rect.left}px`
   }
 
-  _handleEscape(event) {
-    if (event.key === 'Escape') {
-      this._closeDropdown()
-    }
-  }
-
   _teardown() {
     this._removeDropdown()
     this._hiddenLinks = null

data/app/javascript/controllers/combobox_controller.js

@@ -72,7 +72,16 @@ export default class extends Controller {
     }
   }
 
+  // True when CSS anchor positioning (combobox.css) places the popover
+  static supportsAnchorPositioning =
+    typeof CSS !== "undefined" &&
+    CSS.supports("anchor-name: --a") &&
+    CSS.supports("position-area: block-end")
+
   positionPopover() {
+    // Modern browsers position the popover declaratively via anchor CSS
+    if (this.constructor.supportsAnchorPositioning) return
+
     if (!this.hasTriggerTarget || !this.hasContentTarget) return
 
     const trigger = this.triggerTarget

data/app/javascript/controllers/drawer_controller.js

@@ -20,7 +20,7 @@ export default class extends Controller {
     keyboardShortcut: { type: String, default: "d" }
   }
 
-  static targets = ["drawer", "container", "backdrop"]
+  static targets = ["drawer", "container", "backdrop", "panel"]
 
   initialize() {
     const cookieValue = this.getCookie(this.cookieNameValue)
@@ -96,6 +96,12 @@ export default class extends Controller {
     this.toggle()
   }
 
+  closeOnEscape(event) {
+    if (this.openValue) {
+      this.close()
+    }
+  }
+
   // ============================================================================
   // State Management
   // ============================================================================
@@ -107,6 +113,25 @@ export default class extends Controller {
     this.updateState()
     this.persistState()
     this.dispatchStateChange()
+
+    // Only manage focus on user-driven changes, not the initial sync
+    if (old_value !== undefined) {
+      this.manageFocus(new_value)
+    }
+  }
+
+  manageFocus(isOpen) {
+    if (!this.hasPanelTarget) return
+
+    if (isOpen) {
+      this._previouslyFocused = document.activeElement
+      this.panelTarget.focus()
+    } else {
+      if (this._previouslyFocused?.isConnected) {
+        this._previouslyFocused.focus()
+      }
+      this._previouslyFocused = null
+    }
   }
 
   updateState() {
@@ -132,6 +157,17 @@ export default class extends Controller {
       }
     }
 
+    if (this.hasPanelTarget) {
+      // The closed panel stays in the DOM: hide it from AT and block focus
+      if (isOpen) {
+        this.panelTarget.removeAttribute("aria-hidden")
+        this.panelTarget.removeAttribute("inert")
+      } else {
+        this.panelTarget.setAttribute("aria-hidden", "true")
+        this.panelTarget.setAttribute("inert", "")
+      }
+    }
+
     if (isOpen) {
       this.lockScroll()
     } else {
@@ -200,19 +236,17 @@ export default class extends Controller {
   // Scroll Lock
   // ============================================================================
 
+  // Styling lives in drawer.css (body[data-maquina-scroll-locked]); the
+  // controller only records the scroll offset and flips the attribute
   lockScroll() {
     this.scrollPosition = window.pageYOffset
-    document.body.style.overflow = "hidden"
-    document.body.style.position = "fixed"
-    document.body.style.top = `-${this.scrollPosition}px`
-    document.body.style.width = "100%"
+    document.body.style.setProperty("--maquina-scroll-lock-top", `-${this.scrollPosition}px`)
+    document.body.setAttribute("data-maquina-scroll-locked", "")
   }
 
   unlockScroll() {
-    document.body.style.overflow = ""
-    document.body.style.position = ""
-    document.body.style.top = ""
-    document.body.style.width = ""
+    document.body.removeAttribute("data-maquina-scroll-locked")
+    document.body.style.removeProperty("--maquina-scroll-lock-top")
     if (this.scrollPosition !== undefined) {
       window.scrollTo(0, this.scrollPosition)
     }

data/app/javascript/controllers/drawer_trigger_controller.js

@@ -3,11 +3,12 @@ import { Controller } from "@hotwired/stimulus";
 /**
  * Drawer Trigger Controller
  *
- * Triggers drawer toggle via Stimulus outlets.
+ * Triggers drawer toggle via Stimulus outlets and mirrors the drawer's
+ * state on the trigger (aria-expanded, aria-controls).
  * Can be placed anywhere on the page - finds drawer via outlet selector.
  *
  * @example
- * <button 
+ * <button
  *   data-controller="drawer-trigger"
  *   data-action="click->drawer-trigger#triggerClick"
  *   data-drawer-trigger-drawer-outlet="[data-outlet='drawer']"
@@ -18,6 +19,24 @@ import { Controller } from "@hotwired/stimulus";
 export default class extends Controller {
   static outlets = ["drawer"]
 
+  connect() {
+    this.handleStateChanged = this.handleStateChanged.bind(this)
+    window.addEventListener("drawer:stateChanged", this.handleStateChanged)
+  }
+
+  disconnect() {
+    window.removeEventListener("drawer:stateChanged", this.handleStateChanged)
+  }
+
+  drawerOutletConnected(outlet) {
+    this.element.setAttribute("aria-haspopup", "dialog")
+    this.syncExpanded(outlet.openValue)
+
+    if (outlet.hasPanelTarget && outlet.panelTarget.id) {
+      this.element.setAttribute("aria-controls", outlet.panelTarget.id)
+    }
+  }
+
   triggerClick() {
     if (this.hasDrawerOutlet) {
       this.drawerOutlets.forEach(outlet => {
@@ -25,4 +44,15 @@ export default class extends Controller {
       })
     }
   }
-}
+
+  handleStateChanged(event) {
+    if (!this.hasDrawerOutlet) return
+    if (!this.drawerOutletElements.includes(event.target)) return
+
+    this.syncExpanded(event.detail.open)
+  }
+
+  syncExpanded(open) {
+    this.element.setAttribute("aria-expanded", open ? "true" : "false")
+  }
+}

data/app/javascript/controllers/menu_button_controller.js

@@ -1,59 +1,137 @@
 import { Controller } from "@hotwired/stimulus"
 
+/**
+ * MenuButton Controller
+ *
+ * Sidebar-flavored button that toggles a dropdown panel with:
+ * - Click to toggle
+ * - Click outside to close
+ * - Escape key to close
+ * - aria-expanded state on the trigger
+ * - Animation states via data-state
+ */
 export default class extends Controller {
   static targets = ["button", "content"]
 
+  static values = {
+    open: { type: Boolean, default: false }
+  }
+
   connect() {
-    if (!this.hasContentTarget) {
-      return
-    }
+    this.handleClickOutside = this.handleClickOutside.bind(this)
+    this.handleKeydown = this.handleKeydown.bind(this)
+    this.boundTeardown = this.teardown.bind(this)
 
-    this.clickOutside = this.clickOutside.bind(this)
-    this.isOpen = this.buttonTarget.dataset.state === "open"
+    document.addEventListener("turbo:before-cache", this.boundTeardown)
 
-    if (this.isOpen) {
-      this.addClickOutsideListener()
+    if (this.hasContentTarget) {
+      this.contentTarget.hidden = !this.openValue
     }
   }
 
   disconnect() {
-    this.removeClickOutsideListener()
+    this.removeEventListeners()
+    document.removeEventListener("turbo:before-cache", this.boundTeardown)
   }
 
-  toggle() {
-    if (!this.hasContentTarget) {
-      return
+  toggle(event) {
+    event?.preventDefault()
+
+    if (this.openValue) {
+      this.close()
+    } else {
+      this.open()
     }
+  }
+
+  open() {
+    if (this.openValue || !this.hasContentTarget) return
 
+    this.openValue = true
+    this.buttonTarget.dataset.state = "open"
+    this.buttonTarget.setAttribute("aria-expanded", "true")
+    this.contentTarget.dataset.state = "open"
     this.contentTarget.classList.remove("hidden")
+    this.contentTarget.hidden = false
 
-    this.isOpen = !this.isOpen
-    this.buttonTarget.dataset.state = this.isOpen ? "open" : "closed"
+    this.addEventListeners()
+  }
 
-    if (this.isOpen) {
-      // Add a small delay before adding the click outside listener
-      setTimeout(() => {
-        this.addClickOutsideListener()
-      }, 100)
-    } else {
-      this.removeClickOutsideListener()
+  close() {
+    if (!this.openValue || !this.hasContentTarget) return
+
+    // Start closing animation, then hide once it finishes
+    this.contentTarget.dataset.state = "closing"
+
+    const animationDuration = 100 // matches CSS animation duration
+
+    this._closeTimeout = setTimeout(() => {
+      this._closeTimeout = null
+      this.openValue = false
+      this.buttonTarget.dataset.state = "closed"
+      this.buttonTarget.setAttribute("aria-expanded", "false")
+      this.contentTarget.dataset.state = "closed"
+      this.contentTarget.hidden = true
+
+      this.removeEventListeners()
+      this.buttonTarget.focus()
+    }, animationDuration)
+  }
+
+  // Turbo Cache Teardown
+
+  teardown() {
+    if (this._closeTimeout) {
+      clearTimeout(this._closeTimeout)
+      this._closeTimeout = null
+    }
+
+    this.openValue = false
+
+    if (this.hasButtonTarget) {
+      this.buttonTarget.dataset.state = "closed"
+      this.buttonTarget.setAttribute("aria-expanded", "false")
+    }
+
+    if (this.hasContentTarget) {
+      this.contentTarget.dataset.state = "closed"
+      this.contentTarget.hidden = true
     }
+
+    this.removeEventListeners()
   }
 
-  clickOutside(event) {
-    if (!this.isOpen) return
-    if (event.target === this.element) return
+  // Event Handlers
+
+  handleClickOutside(event) {
+    if (!this.openValue) return
+    if (this.element.contains(event.target)) return
+
+    this.close()
+  }
 
-    if (!this.contentTarget.contains(event.target)) {
-      this.toggle()
+  handleKeydown(event) {
+    if (!this.openValue) return
+
+    if (event.key === "Escape") {
+      event.preventDefault()
+      this.close()
     }
   }
 
-  addClickOutsideListener() {
-    document.addEventListener('click', this.clickOutside)
+  // Event Listener Management
+
+  addEventListeners() {
+    // Delay adding click outside listener to prevent immediate close
+    setTimeout(() => {
+      document.addEventListener("click", this.handleClickOutside)
+    }, 0)
+
+    document.addEventListener("keydown", this.handleKeydown)
   }
 
-  removeClickOutsideListener() {
-    document.removeEventListener('click', this.clickOutside)
+  removeEventListeners() {
+    document.removeEventListener("click", this.handleClickOutside)
+    document.removeEventListener("keydown", this.handleKeydown)
   }
 }

data/app/javascript/controllers/sidebar_controller.js

@@ -318,19 +318,17 @@ export default class extends Controller {
   // Scroll Lock (for mobile overlay)
   // ============================================================================
 
+  // Styling lives in drawer.css (body[data-maquina-scroll-locked]); the
+  // controller only records the scroll offset and flips the attribute
   lockScroll() {
     this.scrollPosition = window.pageYOffset
-    document.body.style.overflow = "hidden"
-    document.body.style.position = "fixed"
-    document.body.style.top = `-${this.scrollPosition}px`
-    document.body.style.width = "100%"
+    document.body.style.setProperty("--maquina-scroll-lock-top", `-${this.scrollPosition}px`)
+    document.body.setAttribute("data-maquina-scroll-locked", "")
   }
 
   unlockScroll() {
-    document.body.style.overflow = ""
-    document.body.style.position = ""
-    document.body.style.top = ""
-    document.body.style.width = ""
+    document.body.removeAttribute("data-maquina-scroll-locked")
+    document.body.style.removeProperty("--maquina-scroll-lock-top")
     if (this.scrollPosition !== undefined) {
       window.scrollTo(0, this.scrollPosition)
     }

data/app/javascript/controllers/sidebar_trigger_controller.js

@@ -2,12 +2,13 @@ import { Controller } from "@hotwired/stimulus"
 
 /**
  * Sidebar Trigger Controller
- * 
- * Triggers sidebar toggle via Stimulus outlets.
+ *
+ * Triggers sidebar toggle via Stimulus outlets and mirrors the sidebar's
+ * state on the trigger (aria-expanded, aria-controls).
  * Can be placed anywhere on the page - finds sidebar via outlet selector.
- * 
+ *
  * @example
- * <button 
+ * <button
  *   data-controller="sidebar-trigger"
  *   data-action="click->sidebar-trigger#triggerClick"
  *   data-sidebar-trigger-sidebar-outlet="[data-outlet='sidebar']"
@@ -18,6 +19,23 @@ import { Controller } from "@hotwired/stimulus"
 export default class extends Controller {
   static outlets = ["sidebar"]
 
+  connect() {
+    this.handleStateChanged = this.handleStateChanged.bind(this)
+    window.addEventListener("sidebar:stateChanged", this.handleStateChanged)
+  }
+
+  disconnect() {
+    window.removeEventListener("sidebar:stateChanged", this.handleStateChanged)
+  }
+
+  sidebarOutletConnected(outlet) {
+    this.syncExpanded(outlet.openValue)
+
+    if (outlet.hasSidebarTarget && outlet.sidebarTarget.id) {
+      this.element.setAttribute("aria-controls", outlet.sidebarTarget.id)
+    }
+  }
+
   /**
    * Toggle sidebar when trigger is clicked
    * Works with multiple sidebars if multiple outlets are connected
@@ -29,4 +47,15 @@ export default class extends Controller {
       })
     }
   }
+
+  handleStateChanged(event) {
+    if (!this.hasSidebarOutlet) return
+    if (!this.sidebarOutletElements.includes(event.target)) return
+
+    this.syncExpanded(event.detail.open)
+  }
+
+  syncExpanded(open) {
+    this.element.setAttribute("aria-expanded", open ? "true" : "false")
+  }
 }

data/app/javascript/controllers/toaster_controller.js

@@ -60,6 +60,10 @@ export default class extends Controller {
         return controller.createToast({ title, variant: "error", ...options })
       },
 
+      destructive(title, options = {}) {
+        return controller.createToast({ title, variant: "error", ...options })
+      },
+
       dismiss(toastId) {
         controller.dismissToast(toastId)
       },
@@ -115,6 +119,14 @@ export default class extends Controller {
   }
 
   buildToastHtml({ id, title, description, variant, duration, dismissible, action }) {
+    // Titles/descriptions are escaped below; variant and duration are
+    // interpolated into attributes, so constrain them to safe values.
+    // :destructive is the library-wide alias for toast's error variant.
+    if (variant === "destructive") variant = "error"
+    const knownVariants = ["default", "success", "info", "warning", "error"]
+    variant = knownVariants.includes(variant) ? variant : "default"
+    duration = Number(duration) || 0
+
     const icons = {
       default: "",
       success: this.getIconSvg("circle_check"),

data/app/views/components/_alert.html.erb

@@ -1,5 +1,7 @@
 <%# locals: (variant: :default, icon: nil, css_classes: "", **html_options) %>
-<% merged_data = (html_options.delete(:data) || {}).merge(
+<%# :error is accepted as an alias of the canonical :destructive variant %>
+<% variant = :destructive if variant.to_s == "error" %>
+<% merged_data = merge_component_data(html_options,
     component: :alert,
     variant: variant,
     has_icon: icon.present? || nil

data/app/views/components/_badge.html.erb

@@ -1,5 +1,11 @@
 <%# locals: (variant: :default, size: :md, css_classes: "", **html_options) %>
-<% merged_data = (html_options.delete(:data) || {}).merge(
+<%
+  # Library-wide vocabulary aliases: :default is the canonical middle
+  # size (badge's own is :md), :destructive the canonical danger variant
+  size = :md if size.to_s == "default"
+  variant = :destructive if variant.to_s == "error"
+%>
+<% merged_data = merge_component_data(html_options,
     component: :badge,
     variant: variant,
     size: size

data/app/views/components/_breadcrumbs.html.erb

@@ -1,5 +1,5 @@
 <%# locals: (css_classes: "", responsive: false, collapse_after: 0, **html_options) %>
-<% merged_data = (html_options.delete(:data) || {}).merge(
+<% merged_data = merge_component_data(html_options,
     component: :breadcrumbs
   )
 

data/app/views/components/_calendar.html.erb

@@ -55,7 +55,7 @@
     abbr_day_names.rotate(1) :
     abbr_day_names
 
-  merged_data = (html_options.delete(:data) || {}).merge(
+  merged_data = merge_component_data(html_options,
     controller: "calendar",
     component: "calendar",
     "calendar-mode-value": mode,

data/app/views/components/_card.html.erb

@@ -1,5 +1,5 @@
 <%# locals: (css_classes: "", **html_options) %>
-<% merged_data = (html_options.delete(:data) || {}).merge(component: :card) %>
+<% merged_data = merge_component_data(html_options, component: :card) %>
 
 <%= content_tag :div, class: css_classes.presence, data: merged_data, **html_options do %>
   <%= yield %>

data/app/views/components/_combobox.html.erb

@@ -1,6 +1,7 @@
 <%# locals: (id: nil, name: nil, value: nil, placeholder: "Select...", css_classes: "", **html_options) %>
-<% combobox_id = id || "combobox-#{SecureRandom.hex(4)}" %>
-<% merged_data = (html_options.delete(:data) || {}).merge(
+<%# Deterministic fallback id: random ids break idiomorph matching across Turbo morphs %>
+<% combobox_id = id || "combobox-#{name.to_s.parameterize.presence || "default"}" %>
+<% merged_data = merge_component_data(html_options,
     component: :combobox,
     controller: "combobox",
     combobox_value_value: value,

data/app/views/components/_date_picker.html.erb

@@ -1,7 +1,8 @@
 <%# locals: (selected: nil, selected_end: nil, mode: :single, min_date: nil, max_date: nil, disabled_dates: [], show_outside_days: true, week_starts_on: :sunday, placeholder: nil, input_name: nil, input_name_end: nil, id: nil, disabled: false, required: false, css_classes: "", **html_options) %>
 <%
-  # Generate unique ID for popover targeting
-  component_id = id || "date-picker-#{SecureRandom.hex(4)}"
+  # Deterministic ID for popover targeting: random ids break idiomorph
+  # matching across Turbo morphs
+  component_id = id || "date-picker-#{input_name.to_s.parameterize.presence || "default"}"
   popover_id = "#{component_id}-popover"
 
   # Parse selected dates for display
@@ -28,7 +29,7 @@
 
   default_placeholder = mode == :range ? "Select date range" : "Select date"
 
-  merged_data = (html_options.delete(:data) || {}).merge(
+  merged_data = merge_component_data(html_options,
     controller: "date-picker",
     component: "date-picker",
     "date-picker-mode-value": mode,