fernandes-ui 0.1.0

data/app/helpers/ui/spinner_behavior.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module UI
+  # SpinnerBehavior
+  #
+  # Shared behavior for Spinner component across ERB, ViewComponent, and Phlex implementations.
+  # This module provides consistent size variants and HTML attribute generation.
+  module SpinnerBehavior
+    # Returns HTML attributes for the spinner element
+    def spinner_html_attributes
+      {
+        class: spinner_classes,
+        role: "status",
+        "aria-label": "Loading",
+        data: { slot: "spinner" }
+      }
+    end
+
+    # Returns combined CSS classes for the spinner
+    def spinner_classes
+      classes_value = respond_to?(:classes, true) ? classes : @classes
+      TailwindMerge::Merger.new.merge([
+        spinner_base_classes,
+        spinner_size_classes,
+        classes_value
+      ].compact.join(" "))
+    end
+
+    private
+
+    # Base classes applied to all spinners
+    def spinner_base_classes
+      "animate-spin"
+    end
+
+    # Size-specific classes based on @size
+    def spinner_size_classes
+      case @size.to_s
+      when "sm"
+        "size-3"
+      when "lg"
+        "size-6"
+      when "xl"
+        "size-8"
+      else # default
+        "size-4"
+      end
+    end
+  end
+end

data/app/helpers/ui/textarea_behavior.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module UI
+  # TextareaBehavior
+  #
+  # Shared behavior for Textarea component across ERB, ViewComponent, and Phlex implementations.
+  # This module provides consistent styling and HTML attribute generation for textarea elements.
+  module TextareaBehavior
+    # Returns HTML attributes for the textarea element
+    def textarea_html_attributes
+      {
+        class: textarea_classes,
+        placeholder: @placeholder,
+        name: @name,
+        rows: @rows
+      }.compact
+    end
+
+    # Returns combined CSS classes for the textarea
+    def textarea_classes
+      classes_value = respond_to?(:classes, true) ? classes : @classes
+      TailwindMerge::Merger.new.merge([
+        textarea_base_classes,
+        classes_value
+
+      ].compact.join(" "))
+    end
+
+    private
+
+    # Base classes applied to all textareas (from shadcn/ui)
+    def textarea_base_classes
+      "border-input placeholder:text-muted-foreground focus-visible:border-ring focus-visible:ring-ring/50 aria-invalid:ring-destructive/20 dark:aria-invalid:ring-destructive/40 aria-invalid:border-destructive dark:bg-input/30 flex field-sizing-content min-h-16 w-full rounded-md border bg-transparent px-3 py-2 text-base shadow-xs transition-[color,box-shadow] outline-none focus-visible:ring-[3px] disabled:cursor-not-allowed disabled:opacity-50 md:text-sm"
+    end
+  end
+end

data/app/javascript/ui/common.js

@@ -0,0 +1,24 @@
+/**
+ * UI Engine - Common Logic
+ *
+ * This file contains all shared logic for the UI engine.
+ * Used by both importmap and bundler setups.
+ */
+
+/**
+ * Register all UI engine controllers into a provided Stimulus application
+ * Useful for bundler setups where you want to use your own Stimulus instance
+ * @param {Application} application - The Stimulus application to register controllers into
+ * @param {Object} controllers - Object with controller name/class pairs
+ */
+export function registerControllersInto(application, controllers) {
+  // Register each controller
+  for (const [name, controller] of Object.entries(controllers)) {
+    try {
+      application.register(name, controller)
+      console.log(`Registered Stimulus controller: ${name}`)
+    } catch (error) {
+      console.error(`Failed to register controller ${name}:`, error)
+    }
+  }
+}

data/app/javascript/ui/controllers/accordion_controller.js

@@ -0,0 +1,159 @@
+import { Controller } from "@hotwired/stimulus"
+import { syncExpandedState } from "../utils/state-manager.js"
+
+// Accordion controller for collapsible content sections
+// Implements WAI-ARIA APG Accordion Pattern keyboard navigation
+// https://www.w3.org/WAI/ARIA/apg/patterns/accordion/
+export default class extends Controller {
+  static targets = ["item", "trigger", "content"]
+  static values = {
+    type: { type: String, default: "single" }, // "single" or "multiple"
+    collapsible: { type: Boolean, default: false }
+  }
+
+  connect() {
+    this.setupItems()
+    this.setupKeyboardNavigation()
+  }
+
+  disconnect() {
+    this.removeKeyboardNavigation()
+  }
+
+  setupKeyboardNavigation() {
+    this.handleKeydown = this.handleKeydown.bind(this)
+    this.element.addEventListener("keydown", this.handleKeydown)
+  }
+
+  removeKeyboardNavigation() {
+    this.element.removeEventListener("keydown", this.handleKeydown)
+  }
+
+  handleKeydown(event) {
+    const trigger = event.target.closest("[data-ui--accordion-target='trigger']")
+    if (!trigger) return
+
+    const currentIndex = this.triggerTargets.indexOf(trigger)
+    if (currentIndex === -1) return
+
+    let targetIndex = -1
+    let shouldPreventDefault = true
+
+    switch (event.key) {
+      case "ArrowDown":
+        // Move focus to next trigger, wrap to first if at end
+        targetIndex = (currentIndex + 1) % this.triggerTargets.length
+        break
+
+      case "ArrowUp":
+        // Move focus to previous trigger, wrap to last if at start
+        targetIndex = currentIndex - 1
+        if (targetIndex < 0) {
+          targetIndex = this.triggerTargets.length - 1
+        }
+        break
+
+      case "Home":
+        // Move focus to first trigger
+        targetIndex = 0
+        break
+
+      case "End":
+        // Move focus to last trigger
+        targetIndex = this.triggerTargets.length - 1
+        break
+
+      case "Enter":
+      case " ":
+        // Toggle current accordion item
+        this.toggle({ currentTarget: trigger })
+        break
+
+      default:
+        shouldPreventDefault = false
+    }
+
+    if (shouldPreventDefault) {
+      event.preventDefault()
+    }
+
+    if (targetIndex !== -1 && this.triggerTargets[targetIndex]) {
+      this.triggerTargets[targetIndex].focus()
+    }
+  }
+
+  setupItems() {
+    this.itemTargets.forEach((item, index) => {
+      const content = this.contentTargets[index]
+
+      if (content) {
+        const isOpen = item.dataset.state === "open"
+        content.style.height = isOpen ? `${content.scrollHeight}px` : '0px'
+
+        if (!isOpen) {
+          content.setAttribute('hidden', '')
+        }
+      }
+    })
+  }
+
+  toggle(event) {
+    const trigger = event.currentTarget
+    const index = this.triggerTargets.indexOf(trigger)
+    const item = this.itemTargets[index]
+    const content = this.contentTargets[index]
+
+    const isOpen = item.dataset.state === "open"
+    const shouldOpen = !isOpen
+
+    // For "single" type, close all other items when opening a new one
+    if (this.typeValue === "single" && shouldOpen) {
+      this.itemTargets.forEach((otherItem, otherIndex) => {
+        if (otherIndex !== index) {
+          this.updateItemState(
+            otherItem,
+            this.triggerTargets[otherIndex],
+            this.contentTargets[otherIndex],
+            false
+          )
+        }
+      })
+    }
+
+    this.updateItemState(item, trigger, content, shouldOpen)
+  }
+
+  updateItemState(item, trigger, content, isOpen) {
+    const state = isOpen ? "open" : "closed"
+
+    // Update item data-state
+    item.dataset.state = state
+
+    // Update trigger using utility
+    syncExpandedState(trigger, null, isOpen)
+
+    // Update content state
+    content.dataset.state = state
+
+    // Update h3 wrapper state if it exists
+    const h3 = trigger.parentElement
+    if (h3 && h3.tagName === 'H3') {
+      h3.dataset.state = state
+    }
+
+    if (isOpen) {
+      // Opening: remove hidden and set height
+      content.removeAttribute('hidden')
+      content.style.height = `${content.scrollHeight}px`
+    } else {
+      // Closing: animate to 0, then add hidden after transition
+      content.style.height = '0px'
+
+      content.addEventListener('transitionend', () => {
+        if (content.dataset.state === 'closed') {
+          content.setAttribute('hidden', '')
+        }
+      }, { once: true })
+    }
+  }
+}

data/app/javascript/ui/controllers/alert_dialog_controller.js

@@ -0,0 +1,98 @@
+import { Controller } from "@hotwired/stimulus"
+import { setState } from "../utils/state-manager.js"
+import { createEscapeKeyHandler } from "../utils/escape-key-manager.js"
+import { focusFirstElement } from "../utils/focus-trap-manager.js"
+import { lockScroll, unlockScroll } from "../utils/scroll-lock-manager.js"
+
+// Alert Dialog controller for important confirmations
+// Similar to Dialog but requires explicit action (no click-outside to close)
+export default class extends Controller {
+  static targets = ["container", "overlay", "content"]
+  static values = {
+    open: { type: Boolean, default: false },
+    closeOnEscape: { type: Boolean, default: true }
+  }
+
+  connect() {
+    // Setup escape key handler
+    this.escapeHandler = createEscapeKeyHandler(() => this.close(), {
+      enabled: this.closeOnEscapeValue
+    })
+
+    if (this.openValue) {
+      this.show()
+    }
+  }
+
+  open() {
+    this.openValue = true
+    this.show()
+  }
+
+  close() {
+    this.openValue = false
+    this.hide()
+  }
+
+  show() {
+    // Set open state on all targets
+    const targets = [
+      this.hasContainerTarget ? this.containerTarget : null,
+      this.hasOverlayTarget ? this.overlayTarget : null,
+      this.hasContentTarget ? this.contentTarget : null
+    ].filter(Boolean)
+
+    targets.forEach(target => setState(target, 'open'))
+
+    // Lock body scroll
+    lockScroll()
+
+    // Setup focus trap
+    if (this.hasContentTarget) {
+      focusFirstElement(this.contentTarget)
+    }
+
+    // Attach escape handler
+    if (this.closeOnEscapeValue) {
+      this.escapeHandler.attach()
+    }
+
+    this.element.dispatchEvent(new CustomEvent("alertdialog:open", {
+      bubbles: true,
+      detail: { open: true }
+    }))
+  }
+
+  hide() {
+    // Set closed state on all targets
+    const targets = [
+      this.hasContainerTarget ? this.containerTarget : null,
+      this.hasOverlayTarget ? this.overlayTarget : null,
+      this.hasContentTarget ? this.contentTarget : null
+    ].filter(Boolean)
+
+    targets.forEach(target => setState(target, 'closed'))
+
+    // Unlock body scroll
+    unlockScroll()
+
+    // Detach escape handler
+    this.escapeHandler.detach()
+
+    this.element.dispatchEvent(new CustomEvent("alertdialog:close", {
+      bubbles: true,
+      detail: { open: false }
+    }))
+  }
+
+  // Alert dialogs should NOT close when clicking overlay (important for destructive actions)
+  // This is intentionally different from regular Dialog
+  preventOverlayClose(event) {
+    event.stopPropagation()
+  }
+
+  disconnect() {
+    unlockScroll()
+    this.escapeHandler.detach()
+  }
+}

data/app/javascript/ui/controllers/avatar_controller.js

@@ -0,0 +1,84 @@
+import { Controller } from "@hotwired/stimulus"
+
+// Avatar controller for handling image load and fallback display
+//
+// Based on shadcn/ui Avatar: https://ui.shadcn.com/docs/components/avatar
+// Based on Radix UI Avatar: https://www.radix-ui.com/primitives/docs/components/avatar
+export default class extends Controller {
+  static targets = ["image", "fallback"]
+
+  connect() {
+    // If image target exists, listen for load/error events
+    if (this.hasImageTarget) {
+      // Bind methods for event listeners
+      this.boundOnImageLoad = this.onImageLoad.bind(this)
+      this.boundOnImageError = this.onImageError.bind(this)
+
+      this.setupImageHandlers()
+    }
+  }
+
+  setupImageHandlers() {
+    // Check if image is already loaded (from cache)
+    if (this.imageTarget.complete) {
+      // Image is already loaded (from cache)
+      if (this.imageTarget.naturalHeight > 0) {
+        // Image loaded successfully
+        this.showImage()
+        this.hideFallback()
+      } else {
+        // Image failed to load
+        this.hideImage()
+        this.showFallback()
+      }
+    } else {
+      // Image not loaded yet, add event listeners
+      this.imageTarget.addEventListener("load", this.boundOnImageLoad)
+      this.imageTarget.addEventListener("error", this.boundOnImageError)
+    }
+  }
+
+  onImageLoad() {
+    // Image loaded successfully, show image and hide fallback
+    this.showImage()
+    this.hideFallback()
+  }
+
+  onImageError() {
+    // Image failed to load, hide image and show fallback
+    this.hideImage()
+    this.showFallback()
+  }
+
+  showImage() {
+    if (this.hasImageTarget) {
+      this.imageTarget.classList.remove("hidden")
+    }
+  }
+
+  hideImage() {
+    if (this.hasImageTarget) {
+      this.imageTarget.classList.add("hidden")
+    }
+  }
+
+  hideFallback() {
+    if (this.hasFallbackTarget) {
+      this.fallbackTarget.classList.add("hidden")
+    }
+  }
+
+  showFallback() {
+    if (this.hasFallbackTarget) {
+      this.fallbackTarget.classList.remove("hidden")
+    }
+  }
+
+  disconnect() {
+    // Clean up event listeners
+    if (this.hasImageTarget && this.boundOnImageLoad) {
+      this.imageTarget.removeEventListener("load", this.boundOnImageLoad)
+      this.imageTarget.removeEventListener("error", this.boundOnImageError)
+    }
+  }
+}