@stimulus-plumbers/controllers 0.2.0

package/src/controllers/modal_controller.js

@@ -0,0 +1,104 @@
+import { Controller } from '@hotwired/stimulus';
+import { FocusTrap } from '../focus';
+import { announce } from '../aria';
+import { attachDismisser } from '../plumbers';
+
+/**
+ * Modal Dialog Controller
+ * Implements WAI-ARIA Dialog (Modal) pattern
+ * Supports both native <dialog> elements and custom implementations
+ */
+export default class ModalController extends Controller {
+  static targets = ['modal', 'overlay'];
+
+  connect() {
+    if (!this.hasModalTarget) {
+      console.error('ModalController requires a modal target. Add data-modal-target="modal" to your element.');
+      return;
+    }
+
+    this.isNativeDialog = this.modalTarget instanceof HTMLDialogElement;
+
+    if (this.isNativeDialog) {
+      this.modalTarget.addEventListener('cancel', this.close);
+      this.modalTarget.addEventListener('click', this.handleBackdropClick);
+    } else {
+      this.focusTrap = new FocusTrap(this.modalTarget, {
+        escapeDeactivates: true,
+      });
+
+      attachDismisser(this, { element: this.modalTarget });
+    }
+  }
+
+  dismissed = () => {
+    this.close();
+  };
+
+  disconnect() {
+    if (this.isNativeDialog) {
+      this.modalTarget.removeEventListener('cancel', this.close);
+      this.modalTarget.removeEventListener('click', this.handleBackdropClick);
+    }
+  }
+
+  open(event) {
+    if (event) event.preventDefault();
+    if (!this.hasModalTarget) return;
+
+    if (this.isNativeDialog) {
+      this.previouslyFocused = document.activeElement;
+      this.modalTarget.showModal();
+    } else {
+      const targetToShow = this.hasOverlayTarget ? this.overlayTarget : this.modalTarget;
+      targetToShow.hidden = false;
+
+      document.body.style.overflow = 'hidden';
+
+      if (this.focusTrap) {
+        this.focusTrap.activate();
+      }
+    }
+
+    announce('Modal opened');
+  }
+
+  close(event) {
+    if (event) event.preventDefault();
+    if (!this.hasModalTarget) return;
+
+    if (this.isNativeDialog) {
+      this.modalTarget.close();
+
+      if (this.previouslyFocused && this.previouslyFocused.isConnected) {
+        setTimeout(() => {
+          this.previouslyFocused.focus();
+        }, 0);
+      }
+    } else {
+      const targetToHide = this.hasOverlayTarget ? this.overlayTarget : this.modalTarget;
+      targetToHide.hidden = true;
+
+      document.body.style.overflow = '';
+
+      if (this.focusTrap) {
+        this.focusTrap.deactivate();
+      }
+    }
+
+    announce('Modal closed');
+  }
+
+  handleBackdropClick = (event) => {
+    const rect = this.modalTarget.getBoundingClientRect();
+    const isOutsideDialog =
+      event.clientY < rect.top ||
+      event.clientY > rect.bottom ||
+      event.clientX < rect.left ||
+      event.clientX > rect.right;
+
+    if (isOutsideDialog) {
+      this.close();
+    }
+  };
+}

package/src/controllers/panner_controller.js

@@ -0,0 +1,10 @@
+import { Controller } from '@hotwired/stimulus';
+import { attachShifter } from '../plumbers';
+
+export default class extends Controller {
+  static targets = ['content'];
+
+  connect() {
+    attachShifter(this, { element: this.hasContentTarget ? this.contentTarget : null });
+  }
+}

package/src/controllers/password_reveal_controller.js

@@ -0,0 +1,9 @@
+import { Controller } from '@hotwired/stimulus';
+
+export default class extends Controller {
+  static targets = ['input'];
+
+  toggle() {
+    this.inputTarget.type = this.inputTarget.type === 'password' ? 'text' : 'password';
+  }
+}

package/src/controllers/popover_controller.js

@@ -0,0 +1,76 @@
+import { Controller } from '@hotwired/stimulus';
+import { attachContentLoader, attachVisibility } from '../plumbers';
+
+export default class extends Controller {
+  static targets = ['content', 'template', 'loader', 'activator'];
+  static classes = ['hidden'];
+  static values = {
+    url: String,
+    loadedAt: String,
+    reload: { type: String, default: 'never' },
+    staleAfter: { type: Number, default: 3600 },
+  };
+
+  connect() {
+    attachContentLoader(this, {
+      element: this.hasContentTarget ? this.contentTarget : null,
+      url: this.hasUrlValue ? this.urlValue : null,
+    });
+
+    if (this.hasContentTarget) {
+      attachVisibility(this, {
+        element: this.contentTarget,
+        activator: this.hasActivatorTarget ? this.activatorTarget : null,
+      });
+    }
+    if (this.hasLoaderTarget)
+      attachVisibility(this, { element: this.loaderTarget, visibility: 'contentLoaderVisibility' });
+  }
+
+  async show() {
+    await this.visibility.show();
+  }
+
+  async hide() {
+    await this.visibility.hide();
+  }
+
+  async shown() {
+    await this.load();
+  }
+
+  contentLoad() {
+    if (this.hasContentTarget && this.contentTarget.tagName.toLowerCase() === 'turbo-frame') {
+      if (this.hasUrlValue) this.contentTarget.setAttribute('src', this.urlValue);
+      return false;
+    }
+    return true;
+  }
+
+  async contentLoading() {
+    if (this.hasLoaderTarget) await this.contentLoaderVisibility.show();
+  }
+
+  async contentLoaded({ content }) {
+    if (this.hasContentTarget) {
+      this.contentTarget.replaceChildren(this.getContentNode(content));
+    }
+    if (this.hasLoaderTarget) await this.contentLoaderVisibility.hide();
+  }
+
+  getContentNode(content) {
+    if (typeof content === 'string') {
+      const template = document.createElement('template');
+      template.innerHTML = content;
+      return document.importNode(template.content, true);
+    }
+    return document.importNode(content, true);
+  }
+
+  contentLoader() {
+    if (!this.hasTemplateTarget) return;
+    if (this.templateTarget instanceof HTMLTemplateElement) return this.templateTarget.content;
+
+    return this.templateTarget.innerHTML;
+  }
+}

package/src/controllers/visibility_controller.js

@@ -0,0 +1,32 @@
+import { Controller } from '@hotwired/stimulus';
+import { attachDismisser, attachVisibility, attachShifter } from '../plumbers';
+
+export default class extends Controller {
+  static targets = ['content'];
+
+  connect() {
+    attachDismisser(this);
+  }
+
+  contentTargetConnected(target) {
+    attachShifter(this, { element: target });
+    attachVisibility(this, { element: target });
+  }
+
+  async dismissed() {
+    if (!this.hasContentTarget) return;
+
+    await this.visibility.hide();
+  }
+
+  async toggle() {
+    if (!this.hasContentTarget) return;
+
+    if (this.visibility.visible) {
+      await this.visibility.hide();
+    } else {
+      await this.visibility.show();
+      this.shift(this.contentTarget);
+    }
+  }
+}

package/src/focus.js

@@ -0,0 +1,128 @@
+/**
+ * Query selector for all focusable elements
+ */
+export const FOCUSABLE_SELECTOR = [
+  'a[href]',
+  'area[href]',
+  'button:not([disabled])',
+  'input:not([disabled])',
+  'select:not([disabled])',
+  'textarea:not([disabled])',
+  '[tabindex]:not([tabindex="-1"])',
+  'audio[controls]',
+  'video[controls]',
+  '[contenteditable]:not([contenteditable="false"])',
+].join(',');
+
+/**
+ * Get all focusable elements within a container
+ */
+export function getFocusableElements(container) {
+  return Array.from(container.querySelectorAll(FOCUSABLE_SELECTOR)).filter((el) => isVisible(el));
+}
+
+/**
+ * Check if an element is visible
+ */
+export function isVisible(element) {
+  return !!(element.offsetWidth || element.offsetHeight || element.getClientRects().length);
+}
+
+/**
+ * Focus the first focusable element in a container
+ */
+export function focusFirst(container) {
+  const elements = getFocusableElements(container);
+  if (elements.length > 0) {
+    elements[0].focus();
+    return true;
+  }
+  return false;
+}
+
+/**
+ * Create a focus trap within a container
+ */
+export class FocusTrap {
+  constructor(container, options = {}) {
+    this.container = container;
+    this.previouslyFocused = null;
+    this.options = options;
+    this.isActive = false;
+  }
+
+  activate() {
+    if (this.isActive) return;
+
+    this.previouslyFocused = document.activeElement;
+    this.isActive = true;
+
+    // Focus initial element or first focusable
+    if (this.options.initialFocus) {
+      this.options.initialFocus.focus();
+    } else {
+      focusFirst(this.container);
+    }
+
+    // Add event listeners
+    this.container.addEventListener('keydown', this.handleKeyDown);
+  }
+
+  deactivate() {
+    if (!this.isActive) return;
+
+    this.isActive = false;
+    this.container.removeEventListener('keydown', this.handleKeyDown);
+
+    // Return focus to previously focused element
+    const returnElement = this.options.returnFocus || this.previouslyFocused;
+    if (returnElement && isVisible(returnElement)) {
+      returnElement.focus();
+    }
+  }
+
+  handleKeyDown = (event) => {
+    if (event.key === 'Escape' && this.options.escapeDeactivates) {
+      event.preventDefault();
+      this.deactivate();
+      return;
+    }
+
+    if (event.key !== 'Tab') return;
+
+    const focusableElements = getFocusableElements(this.container);
+    if (focusableElements.length === 0) return;
+
+    const firstElement = focusableElements[0];
+    const lastElement = focusableElements[focusableElements.length - 1];
+
+    // Trap focus within container
+    if (event.shiftKey && document.activeElement === firstElement) {
+      event.preventDefault();
+      lastElement.focus();
+    } else if (!event.shiftKey && document.activeElement === lastElement) {
+      event.preventDefault();
+      firstElement.focus();
+    }
+  };
+}
+
+/**
+ * Save and restore focus utility
+ */
+export class FocusRestoration {
+  constructor() {
+    this.savedElement = null;
+  }
+
+  save() {
+    this.savedElement = document.activeElement;
+  }
+
+  restore() {
+    if (this.savedElement && isVisible(this.savedElement)) {
+      this.savedElement.focus();
+      this.savedElement = null;
+    }
+  }
+}

package/src/index.js

@@ -0,0 +1,23 @@
+/**
+ * @stimulus-plumbers/controllers
+ *
+ * Stimulus Plumbers controllers for UI components
+ * Following WCAG 2.1+ and WAI-ARIA best practices
+ */
+
+// Export utilities (framework-agnostic)
+export * from './focus.js';
+export * from './keyboard.js';
+export * from './aria.js';
+
+// Export Stimulus controllers
+export { default as ModalController } from './controllers/modal_controller.js';
+export { default as DismisserController } from './controllers/dismisser_controller.js';
+export { default as FlipperController } from './controllers/flipper_controller.js';
+export { default as PopoverController } from './controllers/popover_controller.js';
+export { default as CalendarMonthController } from './controllers/calendar_month_controller.js';
+export { default as CalendarMonthObserverController } from './controllers/calendar_month_observer_controller.js';
+export { default as DatepickerController } from './controllers/datepicker_controller.js';
+export { default as PannerController } from './controllers/panner_controller.js';
+export { default as PasswordRevealController } from './controllers/password_reveal_controller.js';
+export { default as AutoResizeController } from './controllers/auto_resize_controller.js';

package/src/keyboard.js

@@ -0,0 +1,92 @@
+/**
+ * Keyboard interaction utilities
+ */
+
+/**
+ * Check if a key matches the expected key
+ */
+export function isKey(event, key) {
+  return event.key === key;
+}
+
+/**
+ * Check if Enter or Space was pressed (activation keys)
+ */
+export function isActivationKey(event) {
+  return event.key === 'Enter' || event.key === ' ';
+}
+
+/**
+ * Check if an arrow key was pressed
+ */
+export function isArrowKey(event) {
+  return ['ArrowUp', 'ArrowDown', 'ArrowLeft', 'ArrowRight'].includes(event.key);
+}
+
+/**
+ * Prevent default and stop propagation
+ */
+export function preventDefault(event) {
+  event.preventDefault();
+  event.stopPropagation();
+}
+
+/**
+ * Handle roving tabindex for a list of items
+ */
+export class RovingTabIndex {
+  constructor(items, initialIndex = 0) {
+    this.items = items;
+    this.currentIndex = initialIndex;
+    this.updateTabIndex();
+  }
+
+  handleKeyDown(event) {
+    let newIndex;
+
+    switch (event.key) {
+      case 'ArrowDown':
+      case 'ArrowRight':
+        event.preventDefault();
+        newIndex = (this.currentIndex + 1) % this.items.length;
+        break;
+      case 'ArrowUp':
+      case 'ArrowLeft':
+        event.preventDefault();
+        newIndex = this.currentIndex === 0 ? this.items.length - 1 : this.currentIndex - 1;
+        break;
+      case 'Home':
+        event.preventDefault();
+        newIndex = 0;
+        break;
+      case 'End':
+        event.preventDefault();
+        newIndex = this.items.length - 1;
+        break;
+      default:
+        return;
+    }
+
+    this.setCurrentIndex(newIndex);
+  }
+
+  setCurrentIndex(index) {
+    if (index >= 0 && index < this.items.length) {
+      this.currentIndex = index;
+      this.updateTabIndex();
+      this.items[index].focus();
+    }
+  }
+
+  updateTabIndex() {
+    this.items.forEach((item, index) => {
+      item.tabIndex = index === this.currentIndex ? 0 : -1;
+    });
+  }
+
+  updateItems(items) {
+    this.items = items;
+    this.currentIndex = Math.min(this.currentIndex, items.length - 1);
+    this.updateTabIndex();
+  }
+}