CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-rails--activestorage

JavaScript library for direct file uploads to cloud storage services in Rails applications

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview
Eval results
Files

utilities.mddocs/

Utilities

Helper function for DOM event dispatching with cross-browser compatibility.

Capabilities

Event Dispatching

Custom DOM event creation and dispatching with cross-browser compatibility. This is the only utility function exported from the main package.

/**
 * Dispatches custom DOM events with proper browser compatibility
 * Temporarily enables elements during dispatch to ensure event delivery
 * @param element - Target element for the event
 * @param type - Event type name
 * @param eventInit - Event configuration options
 * @returns The dispatched Event object
 */
function dispatchEvent(
  element: Element, 
  type: string, 
  eventInit?: {
    bubbles?: boolean;
    cancelable?: boolean;
    detail?: any;
  }
): Event;

Usage Examples:

import { dispatchEvent } from "@rails/activestorage";

// Basic event dispatch
const button = document.querySelector("button");
dispatchEvent(button, "custom:click");

// Event with custom data
dispatchEvent(button, "upload:progress", {
  bubbles: true,
  cancelable: true,
  detail: {
    progress: 75,
    filename: "document.pdf",
    uploadId: 123
  }
});

// Listen for the custom event
button.addEventListener("upload:progress", (event) => {
  const { progress, filename } = event.detail;
  console.log(`${filename}: ${progress}%`);
});

Cross-Browser Compatibility

The dispatchEvent function handles browser differences and provides consistent behavior across different environments.

Implementation Details:

// Handles differences between:
// - Modern browsers: new CustomEvent()
// - Older browsers: document.createEvent() + initEvent()
// - Element state: temporarily enables disabled elements

function dispatchEvent(element, type, eventInit = {}) {
  const { disabled } = element;
  const { bubbles, cancelable, detail } = eventInit;
  
  // Use older event creation for maximum compatibility
  const event = document.createEvent("Event");
  event.initEvent(type, bubbles || true, cancelable || true);
  event.detail = detail || {};
  
  try {
    // Temporarily enable element to ensure event fires
    element.disabled = false;
    element.dispatchEvent(event);
  } finally {
    // Restore original disabled state
    element.disabled = disabled;
  }
  
  return event;
}

Event Options:

  • bubbles (default: true) - Whether the event bubbles up through the DOM
  • cancelable (default: true) - Whether the event can be cancelled
  • detail - Custom data object attached to the event

Temporary Element Enabling:

The function temporarily enables disabled elements during event dispatch to ensure events are properly delivered. This is particularly important for form elements that may be disabled during upload processing but still need to receive and dispatch events.

Usage in Active Storage:

The dispatchEvent function is used internally by Active Storage controllers to dispatch upload lifecycle events:

// Used by DirectUploadController
this.dispatch("start"); // Becomes dispatchEvent(this.input, "direct-upload:start", {...})
this.dispatch("progress", { progress: 75 }); // Becomes dispatchEvent(this.input, "direct-upload:progress", {...})
this.dispatch("error", { error: "Upload failed" }); // Becomes dispatchEvent(this.input, "direct-upload:error", {...})

This ensures consistent event handling across all browsers and provides a reliable way for applications to track upload progress and handle errors.

Install with Tessl CLI

npx tessl i tessl/npm-rails--activestorage

docs

direct-upload.md

form-integration.md

index.md

upload-controllers.md

utilities.md

tile.json