@stimulus-plumbers/controllers 0.2.9 → 0.3.0

package/src/plumbers/flipper.js

@@ -1,6 +1,6 @@
-import Plumber from './plumber';
-import { defineRect, viewportRect, directionMap } from './plumber/support';
-import { connectTriggerToTarget } from '../aria';
+import WindowObserver from './plumber/window_observer';
+import { defineRect, viewportRect, directionMap } from './plumber/geometry';
+import { connectTriggerToTarget } from '../accessibility/aria';
 
 const defaultOptions = {
   anchor: null,
@@ -12,19 +12,7 @@ const defaultOptions = {
   respectMotion: true,
 };
 
-export class Flipper extends Plumber {
-  /**
-   * Creates a new Flipper plumber instance for smart positioning relative to an anchor.
-   * @param {Object} controller - Stimulus controller instance
-   * @param {Object} [options] - Configuration options
-   * @param {HTMLElement} [options.anchor] - Anchor element for positioning
-   * @param {string[]} [options.events=['click']] - Events triggering flip calculation
-   * @param {string} [options.placement='bottom'] - Initial placement direction ('top', 'bottom', 'left', 'right')
-   * @param {string} [options.alignment='start'] - Alignment ('start', 'center', 'end')
-   * @param {string} [options.onFlipped='flipped'] - Callback name when flipped
-   * @param {string} [options.ariaRole=null] - ARIA role to set on element
-   * @param {boolean} [options.respectMotion=true] - Respect prefers-reduced-motion preference
-   */
+export class Flipper extends WindowObserver {
   constructor(controller, options = {}) {
     super(controller, options);
 
@@ -43,22 +31,13 @@ export class Flipper extends Plumber {
     this.prefersReducedMotion = window.matchMedia('(prefers-reduced-motion: reduce)').matches;
 
     if (this.anchor && this.element) {
-      connectTriggerToTarget({
-        trigger: this.anchor,
-        target: this.element,
-        role: this.ariaRole,
-      });
+      connectTriggerToTarget({ trigger: this.anchor, target: this.element, role: this.ariaRole });
     }
 
     this.enhance();
-    this.observe();
+    this.observe(this.flip);
   }
 
-  /**
-   * Attempts to place element in configured direction, flipping to opposite direction if needed.
-   * For example, if placement is 'bottom' but no space below anchor, flips to 'top'.
-   * @returns {Promise<void>}
-   */
   flip = async () => {
     if (!this.visible) return;
 
@@ -68,7 +47,6 @@ export class Flipper extends Plumber {
 
     const placement = this.flippedRect(this.anchor.getBoundingClientRect(), this.element.getBoundingClientRect());
 
-    // Disable transitions for users who prefer reduced motion
     this.element.style.transition = this.respectMotion && this.prefersReducedMotion ? 'none' : '';
 
     for (const [key, value] of Object.entries(placement)) {
@@ -79,12 +57,6 @@ export class Flipper extends Plumber {
     this.dispatch('flipped', { detail: { placement } });
   };
 
-  /**
-   * Determines the best position that fits within viewport boundaries.
-   * @param {DOMRect} anchorRect - Anchor element's bounding rect
-   * @param {DOMRect} referenceRect - Reference element's bounding rect
-   * @returns {Object} Position object with top and left styles
-   */
   flippedRect(anchorRect, referenceRect) {
     const candidateRects = this.quadrumRect(anchorRect, viewportRect());
     const candidates = [this.placement, directionMap[this.placement]];
@@ -92,7 +64,6 @@ export class Flipper extends Plumber {
     while (!Object.keys(flipped).length && candidates.length > 0) {
       const candidate = candidates.shift();
       if (!this.biggerRectThan(candidateRects[candidate], referenceRect)) continue;
-
       const placementRect = this.quadrumPlacement(anchorRect, candidate, referenceRect);
       const alignmentRect = this.quadrumAlignment(anchorRect, candidate, placementRect);
       flipped['top'] = `${alignmentRect['top'] + window.scrollY}px`;
@@ -105,32 +76,16 @@ export class Flipper extends Plumber {
     return flipped;
   }
 
-  /**
-   * Calculates available space in each direction around the inner rect within outer rect.
-   * @param {Object} inner - Inner rect object
-   * @param {Object} outer - Outer rect object
-   * @returns {Object} Rect objects for each direction (left, right, top, bottom)
-   */
   quadrumRect(inner, outer) {
     return {
-      left: defineRect({
-        x: outer.x,
-        y: outer.y,
-        width: inner.x - outer.x,
-        height: outer.height,
-      }),
+      left: defineRect({ x: outer.x, y: outer.y, width: inner.x - outer.x, height: outer.height }),
       right: defineRect({
         x: inner.x + inner.width,
         y: outer.y,
         width: outer.width - (inner.x + inner.width),
         height: outer.height,
       }),
-      top: defineRect({
-        x: outer.x,
-        y: outer.y,
-        width: outer.width,
-        height: inner.y - outer.y,
-      }),
+      top: defineRect({ x: outer.x, y: outer.y, width: outer.width, height: inner.y - outer.y }),
       bottom: defineRect({
         x: outer.x,
         y: inner.y + inner.height,
@@ -140,14 +95,6 @@ export class Flipper extends Plumber {
     };
   }
 
-  /**
-   * Calculates placement rect for reference element in given direction from anchor.
-   * @param {Object} anchor - Anchor rect object
-   * @param {string} direction - Direction ('top', 'bottom', 'left', 'right')
-   * @param {Object} reference - Reference rect object
-   * @returns {Object} Placed rect object
-   * @throws {string} If direction is invalid
-   */
   quadrumPlacement(anchor, direction, reference) {
     switch (direction) {
       case 'top':
@@ -183,14 +130,6 @@ export class Flipper extends Plumber {
     }
   }
 
-  /**
-   * Applies alignment adjustment to placed rect based on configuration.
-   * @param {Object} anchor - Anchor rect object
-   * @param {string} direction - Direction ('top', 'bottom', 'left', 'right')
-   * @param {Object} reference - Reference rect object
-   * @returns {Object} Aligned rect object
-   * @throws {string} If direction is invalid
-   */
   quadrumAlignment(anchor, direction, reference) {
     switch (direction) {
       case 'top':
@@ -198,75 +137,28 @@ export class Flipper extends Plumber {
         let alignment = anchor.x;
         if (this.alignment === 'center') alignment = anchor.x + anchor.width / 2 - reference.width / 2;
         else if (this.alignment === 'end') alignment = anchor.x + anchor.width - reference.width;
-        return defineRect({
-          x: alignment,
-          y: reference.y,
-          width: reference.width,
-          height: reference.height,
-        });
+        return defineRect({ x: alignment, y: reference.y, width: reference.width, height: reference.height });
       }
       case 'left':
       case 'right': {
         let alignment = anchor.y;
         if (this.alignment === 'center') alignment = anchor.y + anchor.height / 2 - reference.height / 2;
         else if (this.alignment === 'end') alignment = anchor.y + anchor.height - reference.height;
-        return defineRect({
-          x: reference.x,
-          y: alignment,
-          width: reference.width,
-          height: reference.height,
-        });
+        return defineRect({ x: reference.x, y: alignment, width: reference.width, height: reference.height });
       }
       default:
         throw `Unable align at the quadrum, ${direction}`;
     }
   }
 
-  /**
-   * Checks if the big rect can contain the small rect dimensions.
-   * @param {Object} big - Larger rect object
-   * @param {Object} small - Smaller rect object
-   * @returns {boolean} True if big rect can contain small rect
-   */
   biggerRectThan(big, small) {
     return big.height >= small.height && big.width >= small.width;
   }
 
-  /**
-   * Starts observing configured events for flipping.
-   */
-  observe() {
-    this.events.forEach((event) => {
-      window.addEventListener(event, this.flip, true);
-    });
-  }
-
-  /**
-   * Stops observing events for flipping.
-   */
-  unobserve() {
-    this.events.forEach((event) => {
-      window.removeEventListener(event, this.flip, true);
-    });
-  }
-
   enhance() {
-    const context = this;
-    const superDisconnect = context.controller.disconnect.bind(context.controller);
-    Object.assign(this.controller, {
-      disconnect: () => {
-        context.unobserve();
-        superDisconnect();
-      },
-      flip: context.flip.bind(context),
-    });
+    super.enhance();
+    this.controller.flip = this.flip;
   }
 }
 
-/**
- * Factory function to create and attach a Flipper plumber to a controller.
- * @param {Object} controller - Stimulus controller instance
- * @param {Object} [options] - Configuration options
- * @returns {Flipper} Flipper plumber instance
- */
 export const attachFlipper = (controller, options) => new Flipper(controller, options);

package/src/plumbers/index.js

@@ -3,7 +3,6 @@
  */
 
 export { initCalendar } from './calendar';
-export { initComboboxDropdown } from './combobox_dropdown';
 export { attachContentLoader } from './content_loader';
 export { attachDismisser } from './dismisser';
 export { attachFlipper } from './flipper';

package/src/plumbers/plumber/config.js

@@ -0,0 +1,6 @@
+export const visibilityConfig = {
+  get visibleOnly() {
+    return true;
+  },
+  hiddenClass: null,
+};

package/src/plumbers/plumber/date.js

@@ -0,0 +1,14 @@
+export function isValidDate(value) {
+  return value instanceof Date && !isNaN(value);
+}
+
+export function tryParseDate(...values) {
+  if (values.length === 0) throw 'Missing values to parse as date';
+  if (values.length === 1) {
+    const parsed = new Date(values[0]);
+    if (values[0] && isValidDate(parsed)) return parsed;
+  } else {
+    const parsed = new Date(...values);
+    if (isValidDate(parsed)) return parsed;
+  }
+}

package/src/plumbers/plumber/geometry.js

@@ -0,0 +1,36 @@
+export const directionMap = {
+  get top() {
+    return 'bottom';
+  },
+  get bottom() {
+    return 'top';
+  },
+  get left() {
+    return 'right';
+  },
+  get right() {
+    return 'left';
+  },
+};
+
+export function defineRect({ x, y, width, height }) {
+  return { x, y, width, height, left: x, right: x + width, top: y, bottom: y + height };
+}
+
+export function viewportRect() {
+  return defineRect({
+    x: 0,
+    y: 0,
+    width: window.innerWidth || document.documentElement.clientWidth,
+    height: window.innerHeight || document.documentElement.clientHeight,
+  });
+}
+
+export function isWithinViewport(target) {
+  if (!(target instanceof HTMLElement)) return false;
+  const outer = viewportRect();
+  const inner = target.getBoundingClientRect();
+  const vertical = inner.top <= outer.height && inner.top + inner.height > 0;
+  const horizontal = inner.left <= outer.width && inner.left + inner.width > 0;
+  return vertical && horizontal;
+}

package/src/plumbers/plumber/index.js

@@ -1,4 +1,5 @@
-import { isWithinViewport, visibilityConfig } from './support';
+import { isWithinViewport } from './geometry';
+import { visibilityConfig } from './config';
 
 const defaultOptions = {
   element: null,

package/src/plumbers/plumber/window_observer.js

@@ -0,0 +1,22 @@
+import Plumber from './index';
+
+export default class WindowObserver extends Plumber {
+  observe(handler) {
+    this._handler = handler;
+    this.events.forEach((e) => window.addEventListener(e, handler, true));
+  }
+
+  unobserve() {
+    if (!this._handler) return;
+    this.events.forEach((e) => window.removeEventListener(e, this._handler, true));
+  }
+
+  enhance() {
+    const context = this;
+    const superDisconnect = this.controller.disconnect?.bind(this.controller) || (() => {});
+    this.controller.disconnect = () => {
+      context.unobserve();
+      superDisconnect();
+    };
+  }
+}

package/src/plumbers/shifter.js

@@ -1,5 +1,5 @@
-import Plumber from './plumber';
-import { viewportRect, directionMap, defineRect } from './plumber/support';
+import WindowObserver from './plumber/window_observer';
+import { viewportRect, directionMap, defineRect } from './plumber/geometry';
 
 const defaultOptions = {
   events: ['resize'],
@@ -8,16 +8,7 @@ const defaultOptions = {
   respectMotion: true,
 };
 
-export class Shifter extends Plumber {
-  /**
-   * Creates a new Shifter plumber instance for viewport boundary shifting.
-   * @param {Object} controller - Stimulus controller instance
-   * @param {Object} [options] - Configuration options
-   * @param {string[]} [options.events=['resize']] - Events triggering shift calculation
-   * @param {string[]} [options.boundaries=['top','left','right']] - Boundaries to check (valid values: 'top', 'bottom', 'left', 'right')
-   * @param {string} [options.onShifted='shifted'] - Callback name when shifted
-   * @param {boolean} [options.respectMotion=true] - Respect prefers-reduced-motion preference
-   */
+export class Shifter extends WindowObserver {
   constructor(controller, options = {}) {
     super(controller, options);
 
@@ -29,13 +20,9 @@ export class Shifter extends Plumber {
     this.prefersReducedMotion = window.matchMedia('(prefers-reduced-motion: reduce)').matches;
 
     this.enhance();
-    this.observe();
+    this.observe(this.shift);
   }
 
-  /**
-   * Calculates and applies transform to shift element within viewport boundaries.
-   * @returns {Promise<void>}
-   */
   shift = async () => {
     if (!this.visible) return;
 
@@ -44,21 +31,13 @@ export class Shifter extends Plumber {
     const translateX = overflow['left'] || overflow['right'] || 0;
     const translateY = overflow['top'] || overflow['bottom'] || 0;
 
-    // Disable transitions for users who prefer reduced motion
     this.element.style.transition = this.respectMotion && this.prefersReducedMotion ? 'none' : '';
-
     this.element.style.transform = `translate(${translateX}px, ${translateY}px)`;
 
     await this.awaitCallback(this.onShifted, overflow);
     this.dispatch('shifted', { detail: overflow });
   };
 
-  /**
-   * Calculates overflow distances for each boundary direction.
-   * @param {DOMRect} targetRect - Target element's bounding rect
-   * @param {Object} translations - Current transform translations
-   * @returns {Object} Overflow distances by direction
-   */
   overflowRect(targetRect, translations) {
     const overflow = {};
     const viewport = viewportRect();
@@ -81,14 +60,6 @@ export class Shifter extends Plumber {
     return overflow;
   }
 
-  /**
-   * Calculates distance from inner rect to outer boundary in given direction.
-   * @param {Object} inner - Inner rect object
-   * @param {string} direction - Direction ('top', 'bottom', 'left', 'right')
-   * @param {Object} outer - Outer rect object
-   * @returns {number} Distance to boundary (negative if overflowing)
-   * @throws {string} If direction is invalid
-   */
   directionDistance(inner, direction, outer) {
     switch (direction) {
       case 'top':
@@ -102,63 +73,20 @@ export class Shifter extends Plumber {
     }
   }
 
-  /**
-   * Extracts current translate values from element's transform style.
-   * @param {HTMLElement} target - Target element
-   * @returns {Object} Translation object with x and y values
-   */
   elementTranslations(target) {
     const style = window.getComputedStyle(target);
     const matrix = style['transform'] || style['webkitTransform'] || style['mozTransform'];
-
-    if (matrix === 'none' || typeof matrix === 'undefined') {
-      return { x: 0, y: 0 };
-    }
-
+    if (matrix === 'none' || typeof matrix === 'undefined') return { x: 0, y: 0 };
     const matrixType = matrix.includes('3d') ? '3d' : '2d';
     const matrixValues = matrix.match(/matrix.*\((.+)\)/)[1].split(', ');
-
-    if (matrixType === '2d') {
-      return { x: Number(matrixValues[4]), y: Number(matrixValues[5]) };
-    }
+    if (matrixType === '2d') return { x: Number(matrixValues[4]), y: Number(matrixValues[5]) };
     return { x: 0, y: 0 };
   }
 
-  /**
-   * Starts observing configured events for shifting.
-   */
-  observe() {
-    this.events.forEach((event) => {
-      window.addEventListener(event, this.shift, true);
-    });
-  }
-
-  /**
-   * Stops observing events for shifting.
-   */
-  unobserve() {
-    this.events.forEach((event) => {
-      window.removeEventListener(event, this.shift, true);
-    });
-  }
-
   enhance() {
-    const context = this;
-    const superDisconnect = context.controller.disconnect.bind(context.controller);
-    Object.assign(this.controller, {
-      disconnect: () => {
-        context.unobserve();
-        superDisconnect();
-      },
-      shift: context.shift.bind(context),
-    });
+    super.enhance();
+    this.controller.shift = this.shift;
   }
 }
 
-/**
- * Factory function to create and attach a Shifter plumber to a controller.
- * @param {Object} controller - Stimulus controller instance
- * @param {Object} [options] - Configuration options
- * @returns {Shifter} Shifter plumber instance
- */
 export const attachShifter = (controller, options) => new Shifter(controller, options);

package/src/plumbers/visibility.js

@@ -1,5 +1,5 @@
 import Plumber from './plumber';
-import { visibilityConfig } from './plumber/support';
+import { visibilityConfig } from './plumber/config';
 
 const defaultOptions = {
   visibility: 'visibility',

package/src/requestor.js

@@ -0,0 +1,24 @@
+export class Requestor {
+  constructor() {
+    this._abortController = null;
+    this._timer = null;
+  }
+
+  schedule(fn, delay) {
+    clearTimeout(this._timer);
+    this._timer = setTimeout(fn, delay);
+  }
+
+  async request(url, options = {}) {
+    this._abortController?.abort();
+    this._abortController = new AbortController();
+    const res = await fetch(url, { ...options, signal: this._abortController.signal });
+    if (!res.ok) throw new Error(`${res.status}`);
+    return res;
+  }
+
+  cancel() {
+    clearTimeout(this._timer);
+    this._abortController?.abort();
+  }
+}

package/src/researcher.js

@@ -0,0 +1,39 @@
+export function fuzzyMatcher(needle, haystack) {
+  let ni = 0;
+  for (let i = 0; i < haystack.length && ni < needle.length; i++) {
+    if (haystack[i] === needle[ni]) ni++;
+  }
+  return ni === needle.length;
+}
+
+function matchContains(needle, haystack) {
+  return haystack.includes(needle);
+}
+
+function matchPrefix(needle, haystack) {
+  return haystack.startsWith(needle);
+}
+
+function getStrategy(strategy) {
+  if (strategy === 'contains') return matchContains;
+  if (strategy === 'prefix') return matchPrefix;
+  return fuzzyMatcher;
+}
+
+function extractDOMValue(el, field) {
+  if (field === 'textContent') return el.textContent?.trim().toLowerCase() ?? '';
+  return (el.getAttribute(field) ?? '').toLowerCase();
+}
+
+export function filterOptions(listbox, query, options = {}) {
+  const { strategy = 'fuzzy', matcher, fields = ['textContent'] } = options;
+  const matchFn = typeof matcher === 'function' ? matcher : getStrategy(strategy);
+  const needle = query.toLowerCase();
+  let visible = 0;
+  listbox.querySelectorAll('[role="option"]').forEach((opt) => {
+    const match = fields.some((field) => matchFn(needle, extractDOMValue(opt, field)));
+    opt.hidden = !match;
+    if (match) visible++;
+  });
+  return visible;
+}

package/src/plumbers/combobox_dropdown.js

@@ -1,60 +0,0 @@
-import Plumber from './plumber';
-
-export class ComboboxDropdown extends Plumber {
-  constructor(controller, options = {}) {
-    super(controller, options);
-    this.debounceTimer = null;
-    this.abortController = null;
-  }
-
-  fuzzyFilter(listbox, query) {
-    const needle = query.toLowerCase();
-    let visible = 0;
-    listbox.querySelectorAll('[role="option"]').forEach((opt) => {
-      const match = this.fuzzyMatch(needle, opt.textContent.trim().toLowerCase());
-      opt.hidden = !match;
-      if (match) visible++;
-    });
-    return visible;
-  }
-
-  fuzzyMatch(needle, haystack) {
-    let ni = 0;
-    for (let i = 0; i < haystack.length && ni < needle.length; i++) {
-      if (haystack[i] === needle[ni]) ni++;
-    }
-    return ni === needle.length;
-  }
-
-  scheduleFetch(query, delay, callback) {
-    clearTimeout(this.debounceTimer);
-    this.debounceTimer = setTimeout(() => this.fetch(query, callback), delay);
-  }
-
-  async fetch(query, { url, field, onLoading, onLoaded, onError }) {
-    this.abortController?.abort();
-    this.abortController = new AbortController();
-    onLoading?.(true);
-    const fetchUrl = new URL(url, window.location.href);
-    fetchUrl.searchParams.set(field, query);
-    try {
-      const res = await fetch(fetchUrl, {
-        signal: this.abortController.signal,
-        headers: { Accept: 'text/html', 'X-Requested-With': 'XMLHttpRequest' },
-      });
-      if (!res.ok) throw new Error(`${res.status}`);
-      onLoaded?.(await res.text());
-    } catch (err) {
-      if (err.name !== 'AbortError') onError?.(err);
-    } finally {
-      onLoading?.(false);
-    }
-  }
-
-  cancel() {
-    clearTimeout(this.debounceTimer);
-    this.abortController?.abort();
-  }
-}
-
-export const initComboboxDropdown = (controller, options) => new ComboboxDropdown(controller, options);