@stimulus-plumbers/controllers 0.2.8 → 0.3.0

package/src/plumbers/index.js

@@ -3,10 +3,9 @@
  */
 
 export { initCalendar } from './calendar';
-export { initComboboxDropdown } from './combobox_dropdown';
 export { attachContentLoader } from './content_loader';
 export { attachDismisser } from './dismisser';
 export { attachFlipper } from './flipper';
-export { attachInputFormat } from './input_format';
+export { attachFormatter } from './formatter';
 export { attachShifter } from './shifter';
 export { attachVisibility } from './visibility';

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);

package/src/plumbers/input_format/index.js

@@ -1,90 +0,0 @@
-import Plumber from '../plumber';
-import { PlainInputFormatter } from './formatters/plain';
-import { CreditCardInputFormatter } from './formatters/credit_card';
-import { PhoneInputFormatter } from './formatters/phone';
-import { CurrencyInputFormatter } from './formatters/currency';
-import { DateInputFormatter } from './formatters/date';
-import { TimeInputFormatter } from './formatters/time';
-
-export { PlainInputFormatter } from './formatters/plain';
-export { CreditCardInputFormatter } from './formatters/credit_card';
-export { PhoneInputFormatter } from './formatters/phone';
-export { CurrencyInputFormatter } from './formatters/currency';
-export { DateInputFormatter } from './formatters/date';
-export { TimeInputFormatter } from './formatters/time';
-
-export const FORMATTER_TYPES = {
-  PLAIN: 'plain',
-  CREDIT_CARD: 'creditCard',
-  PHONE: 'phone',
-  CURRENCY: 'currency',
-  DATE: 'date',
-  TIME: 'time',
-};
-
-const registry = new Map([
-  [FORMATTER_TYPES.PLAIN, PlainInputFormatter],
-  [FORMATTER_TYPES.CREDIT_CARD, CreditCardInputFormatter],
-  [FORMATTER_TYPES.PHONE, PhoneInputFormatter],
-  [FORMATTER_TYPES.CURRENCY, CurrencyInputFormatter],
-  [FORMATTER_TYPES.DATE, DateInputFormatter],
-  [FORMATTER_TYPES.TIME, TimeInputFormatter],
-]);
-
-const defaultOptions = {
-  type: FORMATTER_TYPES.PLAIN,
-  options: {},
-};
-
-export class InputFormat extends Plumber {
-  /**
-   * Registers a custom input formatter for a given type identifier.
-   * @param {string} type - The type identifier (e.g. 'iban')
-   * @param {Object} formatter - Object with normalize, validate, and optionally format/mask methods
-   */
-  static register(type, formatter) {
-    registry.set(type, formatter);
-  }
-
-  /**
-   * Creates a new InputFormat plumber instance.
-   * @param {Object} controller - Stimulus controller instance
-   * @param {Object} [options] - Configuration options
-   * @param {string} [options.type='plain'] - Formatter type identifier
-   * @param {Object} [options.options={}] - Type-specific options (e.g. locale, currency)
-   */
-  constructor(controller, options = {}) {
-    super(controller, options);
-    this.type = options.type ?? defaultOptions.type;
-    this.options = options.options ?? defaultOptions.options;
-    this.enhance();
-  }
-
-  enhance() {
-    const context = this;
-    const formatter = registry.get(context.type) ?? registry.get(FORMATTER_TYPES.PLAIN);
-
-    const helpers = {
-      normalize: (raw) => formatter.normalize?.(raw, context.options) ?? (typeof raw === 'string' ? raw : ''),
-      validate: (value) => formatter.validate?.(value, context.options) ?? true,
-      format: (value) => formatter.format?.(value, context.options) ?? (typeof value === 'string' ? value : ''),
-      mask: (value) => formatter.mask?.(value, context.options) ?? null,
-      maskable: () => typeof formatter.mask === 'function',
-    };
-
-    Object.defineProperty(this.controller, 'inputFormat', {
-      get() {
-        return helpers;
-      },
-      configurable: true,
-    });
-  }
-}
-
-/**
- * Factory function to create and attach an InputFormat plumber to a controller.
- * @param {Object} controller - Stimulus controller instance
- * @param {Object} [options] - Configuration options
- * @returns {InputFormat} InputFormat plumber instance
- */
-export const attachInputFormat = (controller, options) => new InputFormat(controller, options);

package/src/plumbers/plumber/support.js

@@ -1,101 +0,0 @@
-export const visibilityConfig = {
-  get visibleOnly() {
-    return true;
-  },
-  hiddenClass: null,
-};
-
-/**
- * Maps each direction to its opposite direction.
- * Used for flipping and boundary calculations.
- */
-export const directionMap = {
-  get top() {
-    return 'bottom';
-  },
-  get bottom() {
-    return 'top';
-  },
-  get left() {
-    return 'right';
-  },
-  get right() {
-    return 'left';
-  },
-};
-
-/**
- * Creates a rect object with position and dimension properties.
- * @param {Object} params - Rectangle parameters
- * @param {number} params.x - X coordinate
- * @param {number} params.y - Y coordinate
- * @param {number} params.width - Width
- * @param {number} params.height - Height
- * @returns {Object} Rect object with x, y, width, height, left, right, top, bottom properties
- */
-export function defineRect({ x, y, width, height }) {
-  return {
-    x: x,
-    y: y,
-    width: width,
-    height: height,
-    left: x,
-    right: x + width,
-    top: y,
-    bottom: y + height,
-  };
-}
-
-/**
- * Returns the current viewport dimensions as a rect object.
- * @returns {Object} Viewport rect with dimensions and boundaries
- */
-export function viewportRect() {
-  return defineRect({
-    x: 0,
-    y: 0,
-    width: window.innerWidth || document.documentElement.clientWidth,
-    height: window.innerHeight || document.documentElement.clientHeight,
-  });
-}
-
-/**
- * Checks if an element is within the visible viewport.
- * @param {HTMLElement} target - Element to check
- * @returns {boolean} True if element is within viewport
- */
-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;
-}
-
-/**
- * Validates if a value is a valid Date object.
- * @param {*} value - Value to check
- * @returns {boolean} True if value is a valid Date
- */
-export function isValidDate(value) {
-  return value instanceof Date && !isNaN(value);
-}
-
-/**
- * Attempts to parse values into a Date object.
- * @param {...*} values - Date values to parse
- * @returns {Date|undefined} Parsed Date object or undefined if invalid
- * @throws {string} If no values provided
- */
-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;
-  }
-}