npm - @stimulus-plumbers/controllers - Versions diffs - 0.2.0 - Mend

@stimulus-plumbers/controllers 0.2.0

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 (30) hide show

package/LICENSE +21 -0
package/README.md +144 -0
package/dist/stimulus-plumbers-controllers.es.js +1459 -0
package/dist/stimulus-plumbers-controllers.umd.js +1 -0
package/package.json +57 -0
package/src/aria.js +173 -0
package/src/controllers/auto_resize_controller.js +17 -0
package/src/controllers/calendar_month_controller.js +100 -0
package/src/controllers/calendar_month_observer_controller.js +24 -0
package/src/controllers/datepicker_controller.js +101 -0
package/src/controllers/dismisser_controller.js +10 -0
package/src/controllers/flipper_controller.js +33 -0
package/src/controllers/form-field_controller.js +77 -0
package/src/controllers/modal_controller.js +104 -0
package/src/controllers/panner_controller.js +10 -0
package/src/controllers/password_reveal_controller.js +9 -0
package/src/controllers/popover_controller.js +76 -0
package/src/controllers/visibility_controller.js +32 -0
package/src/focus.js +128 -0
package/src/index.js +23 -0
package/src/keyboard.js +92 -0
package/src/plumbers/calendar.js +399 -0
package/src/plumbers/content_loader.js +134 -0
package/src/plumbers/dismisser.js +82 -0
package/src/plumbers/flipper.js +272 -0
package/src/plumbers/index.js +10 -0
package/src/plumbers/plumber/index.js +110 -0
package/src/plumbers/plumber/support.js +101 -0
package/src/plumbers/shifter.js +164 -0
package/src/plumbers/visibility.js +136 -0

package/dist/stimulus-plumbers-controllers.umd.js ADDED Viewed

@@ -0,0 +1 @@

package/package.json ADDED Viewed

@@ -0,0 +1,57 @@
+{
+  "name": "@stimulus-plumbers/controllers",
+  "version": "0.2.0",
+  "description": "Stimulus controllers following WCAG standards",
+  "type": "module",
+  "main": "dist/index.js",
+  "module": "dist/index.esm.js",
+  "files": [
+    "dist",
+    "src"
+  ],
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build",
+    "preview": "vite preview",
+    "test": "vitest run",
+    "test:ui": "vitest --ui",
+    "test:coverage": "vitest --coverage",
+    "lint": "eslint src",
+    "format:write": "prettier --write \"src/**/*.js\"",
+    "format:check": "prettier --check \"src/**/*.js\""
+  },
+  "keywords": [
+    "accessibility",
+    "a11y",
+    "stimulus",
+    "hotwire",
+    "aria"
+  ],
+  "author": "Ryan Chang",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ryanchang/stimulus-plumbers.git",
+    "directory": "stimulus"
+  },
+  "peerDependencies": {
+    "@hotwired/stimulus": "^3.0.0 || ^2.0.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@hotwired/stimulus": "^3.2.2",
+    "@testing-library/dom": "^10.4.0",
+    "@vitest/coverage-v8": "^4.0.18",
+    "@vitest/ui": "^4.1.4",
+    "axe-core": "^4.10.2",
+    "eslint": "^10.2.0",
+    "globals": "^17.4.0",
+    "jsdom": "^29.0.0",
+    "prettier": "^3.3.3",
+    "vite": "^8.0.4",
+    "vitest": "^4.1.4"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/src/aria.js ADDED Viewed

@@ -0,0 +1,173 @@
+/**
+ * Get or create a live region for screen reader announcements
+ */
+const getLiveRegion = (politeness, atomic, relevant) => {
+  let region = document.querySelector(`[data-live-region="${politeness}"]`);
+  if (!region) {
+    region = document.createElement('div');
+    region.className = 'sr-only';
+    region.dataset.liveRegion = politeness;
+    region.setAttribute('aria-live', politeness);
+    region.setAttribute('aria-atomic', atomic.toString());
+    region.setAttribute('aria-relevant', relevant);
+    document.body.appendChild(region);
+  }
+  return region;
+};
+/**
+ * Announce a message to screen readers using an aria-live region
+ */
+export function announce(message, options = {}) {
+  const { politeness = 'polite', atomic = true, relevant = 'additions text' } = options;
+  const region = getLiveRegion(politeness, atomic, relevant);
+  region.textContent = '';
+  setTimeout(() => {
+    region.textContent = message;
+  }, 100);
+}
+/**
+ * Generate a unique ID for ARIA relationships
+ */
+export const generateId = (prefix = 'a11y') => `${prefix}-${Math.random().toString(36).substr(2, 9)}`;
+/**
+ * Ensure element has an ID, generate one if needed
+ */
+export const ensureId = (element, prefix = 'element') => element.id || (element.id = generateId(prefix));
+/**
+ * Generic function to set ARIA state attributes
+ */
+export const setAriaState = (element, attribute, value) => {
+  element.setAttribute(attribute, value.toString());
+};
+/**
+ * Update aria-expanded state
+ */
+export const setExpanded = (element, expanded) => setAriaState(element, 'aria-expanded', expanded);
+/**
+ * Update aria-pressed state
+ */
+export const setPressed = (element, pressed) => setAriaState(element, 'aria-pressed', pressed);
+/**
+ * Update aria-checked state
+ */
+export const setChecked = (element, checked) => setAriaState(element, 'aria-checked', checked);
+/**
+ * Update aria-disabled state and manage tabindex
+ */
+export function setDisabled(element, disabled) {
+  setAriaState(element, 'aria-disabled', disabled);
+  disabled ? element.setAttribute('tabindex', '-1') : element.removeAttribute('tabindex');
+}
+/**
+ * Maps ARIA roles to their appropriate aria-haspopup values
+ */
+export const ARIA_HASPOPUP_VALUES = {
+  menu: 'menu',
+  listbox: 'listbox',
+  tree: 'tree',
+  grid: 'grid',
+  dialog: 'dialog',
+};
+/**
+ * Apply attributes to element if they should be set
+ */
+const applyAttributes = (element, attributes, result) => {
+  Object.entries(attributes).forEach(([attr, value]) => {
+    element.setAttribute(attr, value);
+    result[attr] = value;
+  });
+};
+/**
+ * Check if attribute should be set based on override and existing value
+ */
+const shouldSet = (element, attribute, override) => override || !element.hasAttribute(attribute);
+/**
+ * Connects a trigger element to a target element with ARIA relationships
+ * @param {Object} options - Configuration options
+ * @param {HTMLElement} options.trigger - Trigger/anchor element (e.g., button)
+ * @param {HTMLElement} options.target - Target/reference element (e.g., menu, dialog)
+ * @param {string} [options.role] - ARIA role for the target element
+ * @param {boolean} [options.override=false] - Override existing attributes
+ * @returns {Object} Object containing set attributes with trigger and target subobjects
+ */
+export function connectTriggerToTarget({ trigger, target, role = null, override = false }) {
+  const result = { trigger: {}, target: {} };
+  if (!trigger || !target) return result;
+  const triggerAttrs = {};
+  const targetAttrs = {};
+  // Set target role
+  if (role && shouldSet(target, 'role', override)) {
+    targetAttrs.role = role;
+  }
+  // Set trigger attributes if target has an ID
+  if (target.id) {
+    if (shouldSet(trigger, 'aria-controls', override)) {
+      triggerAttrs['aria-controls'] = target.id;
+    }
+    if (role === 'tooltip' && shouldSet(trigger, 'aria-describedby', override)) {
+      triggerAttrs['aria-describedby'] = target.id;
+    }
+  }
+  // Set aria-haspopup based on role
+  if (role && shouldSet(trigger, 'aria-haspopup', override)) {
+    const haspopup = ARIA_HASPOPUP_VALUES[role] || 'true';
+    if (haspopup) triggerAttrs['aria-haspopup'] = haspopup;
+  }
+  applyAttributes(target, targetAttrs, result.target);
+  applyAttributes(trigger, triggerAttrs, result.trigger);
+  return result;
+}
+/**
+ * Remove attributes from element if they exist
+ */
+const removeAttributes = (element, attributes) => {
+  attributes.forEach((attr) => {
+    if (element.hasAttribute(attr)) {
+      element.removeAttribute(attr);
+    }
+  });
+};
+/**
+ * Disconnects a trigger element from a target element by removing ARIA relationships
+ * @param {Object} options - Configuration options
+ * @param {HTMLElement} options.trigger - Trigger element
+ * @param {HTMLElement} options.target - Target element
+ * @param {string[]} [options.attributes] - Specific attributes to remove (default: all)
+ */
+export function disconnectTriggerFromTarget({ trigger, target, attributes = null }) {
+  if (!trigger || !target) return;
+  const defaultAttrs = ['aria-controls', 'aria-haspopup', 'aria-describedby'];
+  const attrsToRemove = attributes || defaultAttrs;
+  removeAttributes(trigger, attrsToRemove);
+  if (!attributes || attributes.includes('role')) {
+    removeAttributes(target, ['role']);
+  }
+}

package/src/controllers/auto_resize_controller.js ADDED Viewed

@@ -0,0 +1,17 @@
+import { Controller } from '@hotwired/stimulus';
+export default class extends Controller {
+  connect() {
+    this.resize();
+    this.element.addEventListener('input', this.resize.bind(this));
+  }
+  disconnect() {
+    this.element.removeEventListener('input', this.resize.bind(this));
+  }
+  resize() {
+    this.element.style.height = 'auto';
+    this.element.style.height = `${this.element.scrollHeight}px`;
+  }
+}

package/src/controllers/calendar_month_controller.js ADDED Viewed

@@ -0,0 +1,100 @@
+import { Controller } from '@hotwired/stimulus';
+import { initCalendar } from '../plumbers';
+export default class extends Controller {
+  static targets = ['daysOfWeek', 'daysOfMonth'];
+  static classes = ['dayOfWeek', 'dayOfMonth'];
+  static values = {
+    locales: { type: Array, default: ['default'] },
+    weekdayFormat: { type: String, default: 'short' },
+    dayFormat: { type: String, default: 'numeric' },
+    daysOfOtherMonth: { type: Boolean, default: false },
+  };
+  initialize() {
+    initCalendar(this);
+  }
+  connect() {
+    this.draw();
+  }
+  navigated() {
+    this.draw();
+  }
+  draw() {
+    this.drawDaysOfWeek();
+    this.drawDaysOfMonth();
+  }
+  createDayElement(day, { selectable = false, disabled = false } = {}) {
+    const element = document.createElement(selectable ? 'button' : 'div');
+    element.tabIndex = -1;
+    if (day) element.textContent = day;
+    else element.setAttribute('aria-hidden', 'true');
+    if (disabled) {
+      if (element instanceof HTMLButtonElement) element.disabled = true;
+      else element.setAttribute('aria-disabled', 'true');
+    }
+    return element;
+  }
+  drawDaysOfWeek() {
+    if (!this.hasDaysOfWeekTarget) return;
+    const formatter = new Intl.DateTimeFormat(this.localesValue, {
+      weekday: this.weekdayFormatValue,
+    });
+    const daysOfWeek = [];
+    for (const date of this.calendar.daysOfWeek) {
+      const dayElement = this.createDayElement(formatter.format(date.date));
+      dayElement.setAttribute('role', 'columnheader');
+      dayElement.title = date.long;
+      if (this.hasDayOfWeekClass) dayElement.classList.add(...this.dayOfWeekClasses);
+      daysOfWeek.push(dayElement);
+    }
+    const row = document.createElement('div');
+    row.setAttribute('role', 'row');
+    row.replaceChildren(...daysOfWeek);
+    this.daysOfWeekTarget.replaceChildren(row);
+  }
+  drawDaysOfMonth() {
+    if (!this.hasDaysOfMonthTarget) return;
+    const t = this.calendar.today;
+    const today = new Date(t.getFullYear(), t.getMonth(), t.getDate()).getTime();
+    const daysOfMonth = [];
+    for (const date of this.calendar.daysOfMonth) {
+      const dayDisabled =
+        !date.current || this.calendar.isDisabled(date.date) || !this.calendar.isWithinRange(date.date);
+      const dayText = date.current || this.daysOfOtherMonthValue ? date.value : '';
+      const dayElement = this.createDayElement(dayText, {
+        selectable: date.current,
+        disabled: dayDisabled,
+      });
+      if (today === date.date.getTime()) dayElement.setAttribute('aria-current', 'date');
+      if (this.hasDayOfMonthClass) dayElement.classList.add(...this.dayOfMonthClasses);
+      const time = document.createElement('time');
+      time.dateTime = date.iso;
+      dayElement.appendChild(time);
+      daysOfMonth.push(dayElement);
+    }
+    const rows = [];
+    for (let i = 0; i < daysOfMonth.length; i += 7) {
+      const row = document.createElement('div');
+      row.setAttribute('role', 'row');
+      for (const day of daysOfMonth.slice(i, i + 7)) {
+        day.setAttribute('role', 'gridcell');
+        row.appendChild(day);
+      }
+      rows.push(row);
+    }
+    this.daysOfMonthTarget.replaceChildren(...rows);
+  }
+}

package/src/controllers/calendar_month_observer_controller.js ADDED Viewed

@@ -0,0 +1,24 @@
+import { Controller } from '@hotwired/stimulus';
+import { tryParseDate } from '../plumbers/plumber/support';
+export default class extends Controller {
+  select(event) {
+    if (!(event.target instanceof HTMLElement)) return;
+    event.preventDefault();
+    const input = event.target instanceof HTMLTimeElement ? event.target.parentElement : event.target;
+    if (input.disabled || input.getAttribute('aria-disabled') === 'true') return;
+    this.dispatch('select', { target: input });
+    const time = event.target instanceof HTMLTimeElement ? event.target : event.target.querySelector('time');
+    if (!time) return console.error(`unable to locate time element within ${input}`);
+    const date = tryParseDate(time.dateTime);
+    if (!date) return console.error(`unable to parse ${time.dateTime} found within the time element`);
+    this.dispatch('selected', {
+      target: input,
+      detail: { epoch: date.getTime(), iso: date.toISOString() },
+    });
+  }
+}

package/src/controllers/datepicker_controller.js ADDED Viewed

@@ -0,0 +1,101 @@
+import { Controller } from '@hotwired/stimulus';
+import { tryParseDate } from '../plumbers/plumber/support';
+export default class extends Controller {
+  static targets = ['previous', 'next', 'day', 'month', 'year', 'input', 'display'];
+  static outlets = ['calendar-month'];
+  static values = {
+    locales: { type: Array, default: ['default'] },
+    dayFormat: { type: String, default: 'numeric' },
+    monthFormat: { type: String, default: 'long' },
+    yearFormat: { type: String, default: 'numeric' },
+  };
+  initialize() {
+    this.previous = this.previous.bind(this);
+    this.next = this.next.bind(this);
+  }
+  async calendarMonthOutletConnected() {
+    if (this.hasInputTarget && this.inputTarget.value) {
+      const date = tryParseDate(this.inputTarget.value);
+      if (date) {
+        await this.calendarMonthOutlet.calendar.navigate(date);
+      }
+    }
+    this.draw();
+  }
+  selected(event) {
+    if (this.hasInputTarget) {
+      this.inputTarget.value = event.detail.iso;
+    }
+    if (this.hasDisplayTarget) {
+      this.displayTarget.value = this.formatDate(new Date(event.detail.iso));
+    }
+  }
+  formatDate(date) {
+    return new Intl.DateTimeFormat(this.localesValue, {
+      day: this.dayFormatValue,
+      month: this.monthFormatValue,
+      year: this.yearFormatValue,
+    }).format(date);
+  }
+  previousTargetConnected(target) {
+    target.addEventListener('click', this.previous);
+  }
+  previousTargetDisconnected(target) {
+    target.removeEventListener('click', this.previous);
+  }
+  async previous() {
+    await this.calendarMonthOutlet.calendar.step('month', -1);
+    this.draw();
+  }
+  nextTargetConnected(target) {
+    target.addEventListener('click', this.next);
+  }
+  nextTargetDisconnected(target) {
+    target.removeEventListener('click', this.next);
+  }
+  async next() {
+    await this.calendarMonthOutlet.calendar.step('month', 1);
+    this.draw();
+  }
+  draw() {
+    this.drawDay();
+    this.drawMonth();
+    this.drawYear();
+  }
+  drawDay() {
+    if (!this.hasDayTarget || !this.hasCalendarMonthOutlet) return;
+    const { year, month, day } = this.calendarMonthOutlet.calendar;
+    const formatter = new Intl.DateTimeFormat(this.localesValue, { day: this.dayFormatValue });
+    this.dayTarget.textContent = formatter.format(new Date(year, month, day));
+  }
+  drawMonth() {
+    if (!this.hasMonthTarget || !this.hasCalendarMonthOutlet) return;
+    const { year, month } = this.calendarMonthOutlet.calendar;
+    const formatter = new Intl.DateTimeFormat(this.localesValue, { month: this.monthFormatValue });
+    this.monthTarget.textContent = formatter.format(new Date(year, month));
+  }
+  drawYear() {
+    if (!this.hasYearTarget || !this.hasCalendarMonthOutlet) return;
+    const { year } = this.calendarMonthOutlet.calendar;
+    const formatter = new Intl.DateTimeFormat(this.localesValue, { year: this.yearFormatValue });
+    this.yearTarget.textContent = formatter.format(new Date(year, 0));
+  }
+}

package/src/controllers/dismisser_controller.js ADDED Viewed

@@ -0,0 +1,10 @@
+import { Controller } from '@hotwired/stimulus';
+import { attachDismisser } from '../plumbers';
+export default class extends Controller {
+  static targets = ['trigger'];
+  connect() {
+    attachDismisser(this, { trigger: this.hasTriggerTarget ? this.triggerTarget : null });
+  }
+}

package/src/controllers/flipper_controller.js ADDED Viewed

@@ -0,0 +1,33 @@
+import { Controller } from '@hotwired/stimulus';
+import { attachFlipper } from '../plumbers';
+export default class FlipperController extends Controller {
+  static targets = ['anchor', 'reference'];
+  static values = {
+    placement: { type: String, default: 'bottom' },
+    alignment: { type: String, default: 'start' },
+    role: { type: String, default: 'tooltip' },
+  };
+  connect() {
+    if (!this.hasReferenceTarget) {
+      console.error(
+        'FlipperController requires a reference target. Add data-flipper-target="reference" to your element.'
+      );
+      return;
+    }
+    if (!this.hasAnchorTarget) {
+      console.error('FlipperController requires an anchor target. Add data-flipper-target="anchor" to your element.');
+      return;
+    }
+    attachFlipper(this, {
+      element: this.referenceTarget,
+      anchor: this.anchorTarget,
+      placement: this.placementValue,
+      alignment: this.alignmentValue,
+      ariaRole: this.roleValue,
+    });
+  }
+}

package/src/controllers/form-field_controller.js ADDED Viewed

@@ -0,0 +1,77 @@
+import { Controller } from '@hotwired/stimulus';
+import { attachDismisser, attachVisibility } from '../plumbers';
+export default class extends Controller {
+  static targets = ['dropdown', 'trigger', 'input'];
+  static values = {
+    inputPath: { type: String, default: 'detail.value' },
+  };
+  initialize() {
+    this.update = this.update.bind(this);
+    this.expand = this.expand.bind(this);
+    this.collapse = this.collapse.bind(this);
+  }
+  connect() {
+    attachDismisser(this, { events: ['click', 'focus'] });
+  }
+  triggerTargetConnected(target) {
+    target.addEventListener('click', this.expand);
+    target.addEventListener('focus', this.expand);
+  }
+  triggerTargetDisconnected(target) {
+    target.removeEventListener('click', this.expand);
+    target.removeEventListener('focus', this.expand);
+  }
+  dropdownTargetConnected(target) {
+    attachVisibility(this, { element: target, visibility: 'dropdownVisibility' });
+  }
+  async update(event) {
+    const value = this.inputPathValue.split('.').reduce((acc, key) => acc && acc[key], event);
+    if (this.hasInputTarget) this.updateField(this.inputTarget, value);
+    await this.collapse();
+  }
+  updateField(element, value) {
+    const attr = this.fieldAttribute(element);
+    const from = element[attr];
+    this.dispatch('update', { target: element, from, to: value });
+    element[attr] = value;
+    this.dispatch('updated', { target: element, from, to: value });
+  }
+  fieldAttribute(element) {
+    switch (element.constructor) {
+      case HTMLInputElement:
+      case HTMLTextAreaElement:
+      case HTMLButtonElement: {
+        return 'value';
+      }
+      default: {
+        return 'textContent';
+      }
+    }
+  }
+  async expand(_event) {
+    if (!this.hasDropdownTarget || this.dropdownVisibility.visible) return;
+    await this.dropdownVisibility.show();
+  }
+  async collapse(_event) {
+    if (!this.hasDropdownTarget || !this.dropdownVisibility.visible) return;
+    await this.dropdownVisibility.hide();
+  }
+  async dismissed() {
+    await this.collapse();
+  }
+}