@stimulus-plumbers/controllers 0.2.0

package/src/plumbers/flipper.js

@@ -0,0 +1,272 @@
+import Plumber from './plumber';
+import { defineRect, viewportRect, directionMap } from './plumber/support';
+import { connectTriggerToTarget } from '../aria';
+
+const defaultOptions = {
+  anchor: null,
+  events: ['click'],
+  placement: 'bottom',
+  alignment: 'start',
+  onFlipped: 'flipped',
+  ariaRole: null,
+  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
+   */
+  constructor(controller, options = {}) {
+    super(controller, options);
+
+    const { anchor, events, placement, alignment, onFlipped, ariaRole, respectMotion } = Object.assign(
+      {},
+      defaultOptions,
+      options
+    );
+    this.anchor = anchor;
+    this.events = events;
+    this.placement = placement;
+    this.alignment = alignment;
+    this.onFlipped = onFlipped;
+    this.ariaRole = ariaRole;
+    this.respectMotion = respectMotion;
+    this.prefersReducedMotion = window.matchMedia('(prefers-reduced-motion: reduce)').matches;
+
+    if (this.anchor && this.element) {
+      connectTriggerToTarget({
+        trigger: this.anchor,
+        target: this.element,
+        role: this.ariaRole,
+      });
+    }
+
+    this.enhance();
+    this.observe();
+  }
+
+  /**
+   * 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;
+
+    this.dispatch('flip');
+    const positionStyle = window.getComputedStyle(this.element);
+    if (positionStyle['position'] != 'absolute') this.element.style['position'] = 'absolute';
+
+    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)) {
+      this.element.style[key] = value;
+    }
+
+    await this.awaitCallback(this.onFlipped, { target: this.element, placement });
+    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]];
+    let flipped = {};
+    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`;
+      flipped['left'] = `${alignmentRect['left'] + window.scrollX}px`;
+    }
+    if (!Object.keys(flipped).length) {
+      flipped['top'] = '';
+      flipped['left'] = '';
+    }
+    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,
+      }),
+      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,
+      }),
+      bottom: defineRect({
+        x: outer.x,
+        y: inner.y + inner.height,
+        width: outer.width,
+        height: outer.height - (inner.y + inner.height),
+      }),
+    };
+  }
+
+  /**
+   * 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':
+        return defineRect({
+          x: reference.x,
+          y: anchor.y - reference.height,
+          width: reference.width,
+          height: reference.height,
+        });
+      case 'bottom':
+        return defineRect({
+          x: reference.x,
+          y: anchor.y + anchor.height,
+          width: reference.width,
+          height: reference.height,
+        });
+      case 'left':
+        return defineRect({
+          x: anchor.x - reference.width,
+          y: reference.y,
+          width: reference.width,
+          height: reference.height,
+        });
+      case 'right':
+        return defineRect({
+          x: anchor.x + anchor.width,
+          y: reference.y,
+          width: reference.width,
+          height: reference.height,
+        });
+      default:
+        throw `Unable place at the quadrum, ${direction}`;
+    }
+  }
+
+  /**
+   * 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':
+      case 'bottom': {
+        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,
+        });
+      }
+      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,
+        });
+      }
+      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),
+    });
+  }
+}
+
+/**
+ * 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

@@ -0,0 +1,10 @@
+/**
+ * Plumbers - Core utilities for Stimulus controllers
+ */
+
+export { initCalendar } from './calendar';
+export { attachContentLoader } from './content_loader';
+export { attachDismisser } from './dismisser';
+export { attachFlipper } from './flipper';
+export { attachShifter } from './shifter';
+export { attachVisibility } from './visibility';

package/src/plumbers/plumber/index.js

@@ -0,0 +1,110 @@
+import { isWithinViewport, visibilityConfig } from './support';
+
+const defaultOptions = {
+  element: null,
+  visible: null,
+  dispatch: true,
+  prefix: '',
+};
+
+export default class Plumber {
+  /**
+   * Creates a new Plumber instance.
+   * @param {Object} controller - Stimulus controller instance
+   * @param {Object} options - Configuration options
+   * @param {HTMLElement} [options.element] - Target element (defaults to controller.element)
+   * @param {boolean|string} [options.visible=true] - Visibility check configuration
+   * @param {boolean} [options.dispatch=true] - Enable event dispatching
+   * @param {string} [options.prefix] - Event prefix (defaults to controller.identifier)
+   */
+  constructor(controller, options = {}) {
+    this.controller = controller;
+
+    const config = Object.assign({}, defaultOptions, options);
+    const { element, visible, dispatch, prefix } = config;
+    this.element = element || controller.element;
+    this.visibleOnly = typeof visible === 'boolean' ? visible : visibilityConfig.visibleOnly;
+    this.visibleCallback = typeof visible === 'string' ? visible : null;
+    this.notify = !!dispatch;
+    this.prefix = typeof prefix === 'string' && prefix ? prefix : controller.identifier;
+  }
+
+  /**
+   * Checks if the element is visible in viewport.
+   * @returns {boolean} True if element is visible
+   */
+  get visible() {
+    if (!(this.element instanceof HTMLElement)) return false;
+    if (!this.visibleOnly) return true;
+
+    return isWithinViewport(this.element) && this.isVisible(this.element);
+  }
+
+  /**
+   * Determines if a target element is visible.
+   * @param {HTMLElement} target - Element to check
+   * @returns {boolean} True if element is visible
+   */
+  isVisible(target) {
+    if (this.visibleCallback) {
+      const callback = this.findCallback(this.visibleCallback);
+      if (typeof callback == 'function') return callback(target);
+    }
+
+    if (!(target instanceof HTMLElement)) return false;
+    return !target.hasAttribute('hidden');
+  }
+
+  /**
+   * Dispatches a custom event from the controller.
+   * @param {string} name - Event name
+   * @param {Object} [options] - Event options
+   * @param {HTMLElement} [options.target] - Event target element
+   * @param {string} [options.prefix] - Event prefix
+   * @param {*} [options.detail] - Event detail data
+   * @returns {boolean|undefined} Dispatch result
+   */
+  dispatch(name, { target = null, prefix = null, detail = null } = {}) {
+    if (!this.notify) return;
+
+    return this.controller.dispatch(name, {
+      target: target || this.element,
+      prefix: prefix || this.prefix,
+      detail: detail,
+    });
+  }
+
+  /**
+   * Finds and binds a callback function by name from controller or plumber.
+   * @param {string} name - Callback name or dot-notation path
+   * @returns {Function|undefined} Bound callback function
+   */
+  findCallback(name) {
+    if (typeof name !== 'string') return;
+
+    const context = this;
+    const controllerCallback = name.split('.').reduce((acc, key) => acc && acc[key], context.controller);
+    if (typeof controllerCallback === 'function') {
+      return controllerCallback.bind(context.controller);
+    }
+    const callback = name.split('.').reduce((acc, key) => acc && acc[key], context);
+    if (typeof callback === 'function') {
+      return callback.bind(context);
+    }
+  }
+
+  /**
+   * Executes a callback function and awaits if it returns a Promise.
+   * @param {string|Function} callback - Callback name or function
+   * @param {...*} args - Arguments to pass to callback
+   * @returns {Promise<*>} Result of callback execution
+   */
+  async awaitCallback(callback, ...args) {
+    if (typeof callback === 'string') callback = this.findCallback(callback);
+    if (typeof callback === 'function') {
+      const result = callback(...args);
+      if (result instanceof Promise) return await result;
+      else return result;
+    }
+  }
+}

package/src/plumbers/plumber/support.js

@@ -0,0 +1,101 @@
+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;
+  }
+}

package/src/plumbers/shifter.js

@@ -0,0 +1,164 @@
+import Plumber from './plumber';
+import { viewportRect, directionMap, defineRect } from './plumber/support';
+
+const defaultOptions = {
+  events: ['resize'],
+  boundaries: ['top', 'left', 'right'],
+  onShifted: 'shifted',
+  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
+   */
+  constructor(controller, options = {}) {
+    super(controller, options);
+
+    const { onShifted, events, boundaries, respectMotion } = Object.assign({}, defaultOptions, options);
+    this.onShifted = onShifted;
+    this.events = events;
+    this.boundaries = boundaries;
+    this.respectMotion = respectMotion;
+    this.prefersReducedMotion = window.matchMedia('(prefers-reduced-motion: reduce)').matches;
+
+    this.enhance();
+    this.observe();
+  }
+
+  /**
+   * Calculates and applies transform to shift element within viewport boundaries.
+   * @returns {Promise<void>}
+   */
+  shift = async () => {
+    if (!this.visible) return;
+
+    this.dispatch('shift');
+    const overflow = this.overflowRect(this.element.getBoundingClientRect(), this.elementTranslations(this.element));
+    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();
+    const currentRect = defineRect({
+      x: targetRect.x - translations.x,
+      y: targetRect.y - translations.y,
+      width: targetRect.width,
+      height: targetRect.height,
+    });
+    for (const direction of this.boundaries) {
+      const distance = this.directionDistance(currentRect, direction, viewport);
+      const opposite = directionMap[direction];
+      if (distance < 0) {
+        const sufficientSpace = currentRect[opposite] + distance >= viewport[opposite];
+        if (sufficientSpace && !overflow[opposite]) overflow[direction] = distance;
+      } else {
+        overflow[direction] = '';
+      }
+    }
+    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':
+      case 'left':
+        return inner[direction] - outer[direction];
+      case 'bottom':
+      case 'right':
+        return outer[direction] - inner[direction];
+      default:
+        throw `Invalid direction to calcuate distance, ${direction}`;
+    }
+  }
+
+  /**
+   * 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 };
+    }
+
+    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]) };
+    }
+    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),
+    });
+  }
+}
+
+/**
+ * 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);