@ulu/frontend 0.1.0-beta.81 → 0.1.0-beta.83

package/js/ui/resizer.js

@@ -2,9 +2,15 @@
  * @module ui/resizer
  */
 
+// Note: Gzip Test = 1.6kb (7-28-25), which seems appropriate  
+// based on how many options/events it handles
+
 import { createEvent } from "../events/index.js";
-import { logError, log } from "../utils/class-logger.js"; // Assuming this utility exists
+import { logError, log } from "../utils/class-logger.js";
 
+/**
+ * Class for creating/controlling a container size with a handle/control
+ */
 export class Resizer {
   static defaults = {
     debug: false,
@@ -22,192 +28,405 @@ export class Resizer {
      * `null` means no horizontal resizing.
      * - Default null
      */
-    fromX: null, 
+    fromX: null,
     /**
      * @type {"top"|"bottom"|null}
      * Specifies the vertical edge from which resizing occurs.
      * - `null` means no vertical resizing.
      * - Default null
      */
-    fromY: null 
+    fromY: null,
+    /**
+     * The step in pixels for keyboard resizing with arrow keys.
+     */
+    keyboardStep: 10,
+    /**
+     * Debounce time in milliseconds for ending a keyboard resize.
+     */
+    keyboardDebounceTime: 200,
+    /**
+     * If true, the Resizer instance will automatically bind its own DOM event listeners
+     * (pointerdown, keydown) to the control element. If `false`, the user is
+     * responsible for calling `resizerInstance.onPointerdown(event)` and
+     * `resizerInstance.onKeydown(event)` from their own listeners.
+     * Default: true
+     */
+    manageEvents: true,
+    /**
+     * If true, the Resizer instance will automatically manage the `aria-label`
+     * attribute of the control element. If `false`, the user is responsible
+     * for setting this attribute.
+     * Default: false
+     */
+    manageAriaLabel: false,
+    /**
+     * If true, pointer events (mouse/touch) will enable resizing.
+     * Default: true
+     */
+    enablePointerResizing: true,
+    /**
+     * If true, keyboard events (arrow keys) will enable resizing.
+     * Default: true
+     */
+    enableKeyboardResizing: true
   };
 
-  // Declare any runtime populated private fields
-  #handlerPointerdown;
+  // Declare private fields without initial assignments
+  #handlerPointerdownInternal;
+  #handlerKeydownInternal;
+  #keyboardResizeTimeout;
+  #initialContainerDimensions;
+  #accumulatedKeyboardDeltaX;
+  #accumulatedKeyboardDeltaY;
+  #isResizingActive;
+  #pointerStartX;
+  #pointerStartY;
 
   /**
    * @param {Node} container Container to be resized
-   * @param {Node} control Resize handle element
-   * @param {Object} options Options to configure the resizer.
-   * @param {Boolean} options.debug Enable non-essential debugging logs.
-   * @param {Boolean} options.overrideMaxDimensions When script is activated by handle, remove the element's max-width/max-height and allow the resize to exceed them (default false).
-   * @param {"left"|"right"|null} [options.fromX=null] Horizontal resizing direction.
-   * @param {"top"|"bottom"|null} [options.fromY=null] Vertical resizing direction.
+   * @param {HTMLElement} control Resize handle element (should be focusable like a button)
+   * @param {Object} config Options to configure the resizer.
+   * @param {Boolean} [config.debug=false] Enable non-essential debugging logs.
+   * @param {Boolean} [config.multiplier=1] Amount to increase size by (ie. pointer movement * multiplier).
+   * @param {Boolean} [config.overrideMaxDimensions=false] When script is activated by handle, remove the element's max-width/max-height and allow the resize to exceed them.
+   * @param {"left"|"right"|null} [config.fromX=null] Horizontal resizing direction.
+   * @param {"top"|"bottom"|null} [config.fromY=null] Vertical resizing direction.
+   * @param {number} [config.keyboardStep=10] The step in pixels for keyboard resizing.
+   * @param {number} [config.keyboardDebounceTime=200] Debounce time for keyboard resize end.
+   * @param {boolean} [config.manageEvents=true] If true, the Resizer will automatically bind its own events.
+   * @param {boolean} [config.manageAriaLabel=false] If true, the Resizer will manage the control's aria-label.
+   * @param {boolean} [config.enablePointerResizing=true] If true, pointer events will enable resizing.
+   * @param {boolean} [config.enableKeyboardResizing=true] If true, keyboard events will enable resizing.
    */
-  constructor(container, control, options) {
+  constructor(container, control, config) {
     if (!control || !container) {
       logError(this, "Missing required elements: control, container");
       return;
     }
-    this.options = Object.assign({}, Resizer.defaults, options);
-    log(this, "Resolved options", this.options);
-    
+    const options = Object.assign({}, Resizer.defaults, config);
+    this.options = options;
     this.container = container;
     this.control = control;
-    this.debug = this.options.debug; // for logger
+    this.debug = options.debug;
 
-    // Validate and normalize fromX/fromY
     const validX = ["left", "right"];
     const validY = ["top", "bottom"];
-
-    const { fromX, fromY } = this.options;
+    const { fromX, fromY } = options;
 
     if (!validX.includes(fromX) && fromX !== null) {
       logError(this, `Invalid fromX: ${ fromX } (left|right|null)`);
-      return; 
+      return;
     }
     if (!validY.includes(fromY) && fromY !== null) {
       logError(this, `Invalid fromY: ${ fromY } (top|bottom|null)`);
       return;
     }
-
     if (!fromX && !fromY) {
-      logError(this, "Invalid fromX/fromY, failed to setup resizer");
+      logError(this, "Invalid fromX/fromY, failed to setup resizer (at least one of fromX or fromY must be set)");
       return;
     }
 
-    // Determine effective resizing directions based on fromX/fromY being non-null
-    this.resizeHorizontal = this.options.fromX !== null;
-    this.resizeVertical = this.options.fromY !== null;
+    this.resizeHorizontal = options.fromX !== null;
+    this.resizeVertical = options.fromY !== null;
+
+    // Bind internal listeners only if manageEvents is true AND the respective event type is enabled
+    if (options.manageEvents) {
+      this.#handlerPointerdownInternal = this.onPointerdown.bind(this);
+      this.#handlerKeydownInternal = this.onKeydown.bind(this);
+
+      if (options.enablePointerResizing) {
+        control.addEventListener("pointerdown", this.#handlerPointerdownInternal);
+      }
+      if (options.enableKeyboardResizing) {
+        control.addEventListener("keydown", this.#handlerKeydownInternal);
+      }
+    }
 
-    // Bind event handlers
-    this.#handlerPointerdown = this.#onPointerdown.bind(this);
+    this.#resetInternalState();
 
-    // Attach event listener
-    this.control.addEventListener("pointerdown", this.#handlerPointerdown);
+    if (options.manageAriaLabel) {
+      control.setAttribute("aria-label", this.getAriaLabel());
+    }
   }
 
   /**
-   * Cleans up event listeners to prevent memory leaks.
+   * Resets all internal state properties to their default/inactive values.
+   * This centralizes state cleanup and initial setup.
+   * @private
+   */
+  #resetInternalState() {
+    this.#keyboardResizeTimeout = null;
+    this.#initialContainerDimensions = { width: 0, height: 0 };
+    this.#accumulatedKeyboardDeltaX = 0;
+    this.#accumulatedKeyboardDeltaY = 0;
+    this.#isResizingActive = false;
+    this.#pointerStartX = 0;
+    this.#pointerStartY = 0;
+  }
+
+  /**
+   * Cleans up event listeners and internal state to prevent memory leaks.
    */
   destroy() {
-    this.control.removeEventListener("pointerdown", this.#handlerPointerdown);
+    const { control, options } = this;
+
+    if (options.manageEvents) {
+      if (options.enablePointerResizing) {
+        control.removeEventListener("pointerdown", this.#handlerPointerdownInternal);
+      }
+      if (options.enableKeyboardResizing) {
+        control.removeEventListener("keydown", this.#handlerKeydownInternal);
+      }
+    }
+
+    if (this.#keyboardResizeTimeout) {
+      clearTimeout(this.#keyboardResizeTimeout);
+    }
+
+    this.#resetInternalState();
+
+    if (options.manageAriaLabel) {
+      control.removeAttribute("aria-label");
+    }
+    log(this, "Resizer destroyed.");
   }
 
   /**
-   * Handles the pointerdown event on the resize control.
-   * @param {PointerEvent} e The pointerdown event.
+   * Initiates a resize operation.
+   * This sets initial dimensions and dispatches the 'resizer:start' event.
+   * @param {Object} eventDetails Additional details about the initiating event.
    * @private
    */
-  #onPointerdown(e) {
-    e.preventDefault(); // Prevent default browser drag behavior
+  #startResize(eventDetails) {
+    const { container, options } = this;
 
-    const { overrideMaxDimensions, fromX, fromY, multiplier } = this.options; // Destructure fromX, fromY
-    const doc = document.documentElement;
-    const win = document.defaultView;
-    const containerStyle = win.getComputedStyle(this.container);
-
-    // Initial pointer coordinates
-    const startX = e.clientX;
-    const startY = e.clientY;
+    if (this.#isResizingActive) {
+      if (options.overrideMaxDimensions) {
+        if (this.resizeHorizontal) {
+          container.style.maxWidth = "none";
+        }
+        if (this.resizeVertical) {
+          container.style.maxHeight = "none";
+        }
+      }
+      return;
+    }
 
-    // Initial dimensions of the container
-    const initialWidth = parseInt(containerStyle.width, 10);
-    const initialHeight = parseInt(containerStyle.height, 10);
+    const win = document.defaultView;
+    const containerStyle = win.getComputedStyle(container);
 
-    // Set pointer capture on the control element
-    this.control.setPointerCapture(e.pointerId);
+    this.#initialContainerDimensions.width = parseInt(containerStyle.width, 10);
+    this.#initialContainerDimensions.height = parseInt(containerStyle.height, 10);
 
-    // Optionally remove max-width/max-height to allow unrestricted resizing
-    if (overrideMaxDimensions) {
+    if (options.overrideMaxDimensions) {
       if (this.resizeHorizontal) {
-        this.container.style.maxWidth = "none";
+        container.style.maxWidth = "none";
       }
       if (this.resizeVertical) {
-        this.container.style.maxHeight = "none";
+        container.style.maxHeight = "none";
       }
     }
 
-    const initialInfo = {
-      event: e,
-      startX,
-      startY,
-      initialWidth,
-      initialHeight,
-      fromX, // Log fromX and fromY separately
-      fromY,
-      pointerId: e.pointerId
-    };
+    this.#isResizingActive = true;
+    this.dispatchEvent("resizer:start", eventDetails);
+    log(this, "Resize started.", {
+      initialWidth: this.#initialContainerDimensions.width,
+      initialHeight: this.#initialContainerDimensions.height,
+      ...eventDetails
+    });
+  }
 
-    this.dispatchEvent("resizer:start", initialInfo);
-    log(this, "Pointerdown initiated/captured.", initialInfo);
+  /**
+   * Ends a resize operation.
+   * Dispatches 'resizer:end' event and resets internal state.
+   * @private
+   */
+  #endResize() {
+    if (!this.#isResizingActive) return;
 
-    /**
-     * Handles the pointermove event to resize the container.
-     * @param {PointerEvent} event The pointermove event.
-     */
-    const pointermove = (event) => {
-      let newWidth = initialWidth;
-      let newHeight = initialHeight;
+    this.dispatchEvent("resizer:end");
+    this.#resetInternalState();
+    log(this, "Resize ended.");
+  }
 
-      const deltaX = event.clientX - startX;
-      const deltaY = event.clientY - startY;
+  /**
+   * Core logic for calculating and applying the new size of the container.
+   * This method is called by both pointer and keyboard event handlers.
+   *
+   * @param {number} totalDeltaX The total horizontal displacement from the start of the resize.
+   * @param {number} totalDeltaY The total vertical displacement from the start of the resize.
+   * @param {Event} originalEvent The original DOM event (PointerEvent or KeyboardEvent) that triggered the update.
+   * @private
+   */
+  #updateSize(totalDeltaX, totalDeltaY, originalEvent) {
+    let newWidth = this.#initialContainerDimensions.width;
+    let newHeight = this.#initialContainerDimensions.height;
+    const { fromX, fromY, multiplier } = this.options;
 
-      // Handle horizontal resizing
-      if (this.resizeHorizontal) {
-        if (fromX === "right") { 
-          newWidth = (initialWidth + (deltaX * multiplier));
-        } else if (fromX === "left") { 
-          newWidth = (initialWidth - (deltaX * multiplier));
-        }
-        this.container.style.width = `${ Math.max(0, newWidth) }px`; // Ensure non-negative width
+    if (this.resizeHorizontal) {
+      if (fromX === "right") {
+        newWidth = (this.#initialContainerDimensions.width + (totalDeltaX * multiplier));
+      } else if (fromX === "left") {
+        newWidth = (this.#initialContainerDimensions.width - (totalDeltaX * multiplier));
       }
+      this.container.style.width = `${ Math.max(0, newWidth) }px`;
+    }
 
-      // Handle vertical resizing
-      if (this.resizeVertical) {
-        if (fromY === "bottom") { // Use fromY directly
-          newHeight = (initialHeight + (deltaY * multiplier));
-        } else if (fromY === "top") { // Use fromY directly
-          newHeight = (initialHeight - (deltaY * multiplier));
-        }
-        this.container.style.height = `${ Math.max(0, newHeight) }px`; // Ensure non-negative height
+    if (this.resizeVertical) {
+      if (fromY === "bottom") {
+        newHeight = (this.#initialContainerDimensions.height + (totalDeltaY * multiplier));
+      } else if (fromY === "top") {
+        newHeight = (this.#initialContainerDimensions.height - (totalDeltaY * multiplier));
       }
+      this.container.style.height = `${ Math.max(0, newHeight) }px`;
+    }
+
+    const updateInfo = {
+      newWidth: newWidth,
+      newHeight: newHeight,
+      totalDeltaX: totalDeltaX,
+      totalDeltaY: totalDeltaY,
+      event: originalEvent
+    };
+
+    this.dispatchEvent("resizer:update", updateInfo);
+    log(this, "Resizing update.", updateInfo);
+  }
+
+  /**
+   * Public handler for pointerdown events. Call this method from your own event listeners
+   * if `manageEvents` is false. Its logic will only execute if `enablePointerResizing` is true.
+   * @param {PointerEvent} e The pointerdown event.
+   */
+  onPointerdown(e) {
+    if (!this.options.enablePointerResizing) {
+      log(this, "Pointer resizing disabled. Ignoring pointerdown event.");
+      return;
+    }
+
+    e.preventDefault();
+    const doc = document.documentElement;
 
-      const updateInfo = {
-        clientX: event.clientX,
-        clientY: event.clientY,
-        newWidth,
-        newHeight,
-        event
-      };
+    this.#pointerStartX = e.clientX;
+    this.#pointerStartY = e.clientY;
+
+    this.#startResize({
+      inputType: 'pointer',
+      startX: e.clientX,
+      startY: e.clientY,
+      pointerId: e.pointerId
+    });
+
+    this.control.setPointerCapture(e.pointerId);
 
-      this.dispatchEvent("resizer:update", updateInfo);
-      log(this, "Pointermove.", updateInfo);
+    const pointermove = (event) => {
+      const totalDeltaX = event.clientX - this.#pointerStartX;
+      const totalDeltaY = event.clientY - this.#pointerStartY;
+      this.#updateSize(totalDeltaX, totalDeltaY, event);
     };
 
-    /**
-     * Cleans up event listeners after the pointerup event.
-     * @param {PointerEvent} event The pointerup event.
-     */
     const cleanup = (event) => {
       doc.removeEventListener("pointermove", pointermove, false);
       doc.removeEventListener("pointerup", cleanup, { capture: true, once: true });
 
-      // Release pointer capture from the control element
-      this.control.releasePointerCapture(event.pointerId);
-      this.dispatchEvent("resizer:end");
-
-      log(this, "Pointerup cleanup complete. Pointer released.", {
-        pointerId: event.pointerId
-      });
-      
+      if (this.control.hasPointerCapture(event.pointerId)) {
+        this.control.releasePointerCapture(event.pointerId);
+      }
+      this.#endResize();
     };
 
-    // Attach global event listeners for dragging
     doc.addEventListener("pointermove", pointermove, false);
     doc.addEventListener("pointerup", cleanup, { capture: true, once: true });
   }
-  dispatchEvent(type, data) {
+
+  /**
+   * Public handler for keydown events. Call this method from your own event listeners
+   * if `manageEvents` is false. Its logic will only execute if `enableKeyboardResizing` is true.
+   * @param {KeyboardEvent} e The keydown event.
+   */
+  onKeydown(e) {
+    if (!this.options.enableKeyboardResizing) {
+      log(this, "Keyboard resizing disabled. Ignoring keydown event.");
+      return;
+    }
+
+    const { key } = e;
+    const { keyboardStep, keyboardDebounceTime } = this.options;
+
+    let stepDeltaX = 0;
+    let stepDeltaY = 0;
+    let isResizeKey = false;
+
+    if (this.resizeHorizontal) {
+      if (key === "ArrowLeft") {
+        // ArrowLeft should always move the active horizontal edge to the left
+        stepDeltaX = -keyboardStep;
+        isResizeKey = true;
+      } else if (key === "ArrowRight") {
+        // ArrowRight should always move the active horizontal edge to the right
+        stepDeltaX = keyboardStep;
+        isResizeKey = true;
+      }
+    }
+
+    if (this.resizeVertical) {
+      if (key === "ArrowUp") {
+        // ArrowUp should always move the active vertical edge up
+        stepDeltaY = -keyboardStep;
+        isResizeKey = true;
+      } else if (key === "ArrowDown") {
+        // ArrowDown should always move the active vertical edge down
+        stepDeltaY = keyboardStep;
+        isResizeKey = true;
+      }
+    }
+
+    if (isResizeKey) {
+      e.preventDefault();
+      e.stopPropagation();
+
+      if (!this.#isResizingActive || this.#keyboardResizeTimeout === null) {
+        this.#startResize({ inputType: 'keyboard', keyboardKey: key });
+      }
+
+      this.#accumulatedKeyboardDeltaX += stepDeltaX;
+      this.#accumulatedKeyboardDeltaY += stepDeltaY;
+
+      this.#updateSize(this.#accumulatedKeyboardDeltaX, this.#accumulatedKeyboardDeltaY, e);
+
+      if (this.#keyboardResizeTimeout) {
+        clearTimeout(this.#keyboardResizeTimeout);
+      }
+      this.#keyboardResizeTimeout = setTimeout(() => {
+        this.#endResize();
+        this.#keyboardResizeTimeout = null;
+      }, keyboardDebounceTime);
+    }
+  }
+
+  /**
+   * Generates an accessible label for the resize control based on its configuration.
+   * This is a convenience function that can be used by the consumer if `manageAriaLabel` is false.
+   * @returns {string} The suggested aria-label for the control.
+   */
+  getAriaLabel() {
+    const { fromY, fromX } = this.options;
+    const directions = [fromY, fromX].filter(v => v);
+
+    if (directions.length === 0) {
+      return "Resize control"; // Fallback for invalid configuration (should be caught by constructor)
+    }
+
+    // Join all directions with a space and append " edge".
+    return `Resize from ${directions.join(' ')} edge`;
+  }
+
+  /**
+   * Dispatches a custom event on the container element.
+   * @param {string} type The event type (e.g., "resizer:start", "resizer:update", "resizer:end").
+   * @param {Object} [data={}] Optional data to attach to the event's detail property.
+   */
+  dispatchEvent(type, data = {}) {
     this.container.dispatchEvent(createEvent(type, data));
   }
 }

package/js/utils/font-awesome.js

@@ -12,7 +12,7 @@ export function configureIcons() {
   updateSettings({
     iconClassClose: "fas fa-xmark",
     iconClassDragX: "fas fa-solid fa-grip-lines-vertical",
-    iconClassDragBoth: "fas fa-solid fa-grip", // Not really any good icons for this (no diagonal arrows, etc)
+    // iconClassDragBoth: "fas fa-solid fa-grip", // Not really any good icons for this (no diagonal arrows, etc)
     iconClassPrevious: "fas fa-solid fa-chevron-left",
     iconClassNext: "fas fa-solid fa-chevron-right"
   });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ulu/frontend",
-  "version": "0.1.0-beta.81",
+  "version": "0.1.0-beta.83",
   "description": "A versatile SCSS and JavaScript component library offering configurable, accessible components and flexible integration into any project, with SCSS modules suitable for modern JS frameworks.",
   "browser": "js/index.js",
   "main": "index.js",

package/types/ui/dialog.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dialog.d.ts","sourceRoot":"","sources":["../../js/ui/dialog.js"],"names":[],"mappings":"AA6DA;;GAEG;AACH,gDAEC;AAED;;;GAGG;AACH,6BAqBC;AAED;;;;GAIG;AACH,sCAHW,IAAI,0BA2Bd;AAED;;;GAGG;AACH,oCAFW,IAAI,0BAyFd;AAED;;;;GAIG;AACH,yCAHW,IAAI,OAKd;AAzND;;GAEG;AACH,8CAA+C;AAE/C;;GAEG;AACH,+CAAuF;AAEvF;;GAEG;AACH,oCAAgE;;;;;;;;;qCAlB3B,oBAAoB"}
+{"version":3,"file":"dialog.d.ts","sourceRoot":"","sources":["../../js/ui/dialog.js"],"names":[],"mappings":"AA6DA;;GAEG;AACH,gDAEC;AAED;;;GAGG;AACH,6BAqBC;AAED;;;;GAIG;AACH,sCAHW,IAAI,0BA2Bd;AAED;;;GAGG;AACH,oCAFW,IAAI,0BA6Dd;AAED;;;;GAIG;AACH,yCAHW,IAAI,OAKd;AA7LD;;GAEG;AACH,8CAA+C;AAE/C;;GAEG;AACH,+CAAuF;AAEvF;;GAEG;AACH,oCAAgE;;;;;;;;;qCAjB3B,oBAAoB"}