tessl/npm-uppy--dashboard

Universal UI plugin for Uppy file uploader providing comprehensive dashboard interface with drag-and-drop, file previews, metadata editing, and progress tracking.

—

Pending

Overview

Eval results

Files

Modal Management

Name: tessl/npm-uppy--dashboard
Author: tessl

Control dashboard visibility and interaction modes for overlay-style file selection interfaces.

Capabilities

Open Modal

Open the dashboard modal interface with optional animation and focus management.

/**
 * Open the dashboard modal interface
 * Handles focus management, scroll prevention, and animations
 * @returns Promise that resolves when modal is fully opened
 */
openModal(): Promise<void>;

Usage Examples:

import Dashboard from "@uppy/dashboard";

const dashboard = uppy.getPlugin("Dashboard") as Dashboard;

// Open modal programmatically
await dashboard.openModal();
console.log("Modal is now open");

// Open modal with user interaction
document.getElementById("upload-btn").addEventListener("click", async () => {
  await dashboard.openModal();
});

Behavior:

Saves current scroll position and active element for restoration
Applies uppy-Dashboard-isFixed class to body if disablePageScrollWhenModalOpen is true
Handles animation if animateOpenClose is enabled
Updates browser history if browserBackButtonClose is enabled
Sets up keyboard event listeners for ESC and TAB keys
Emits dashboard:modal-open event

Close Modal

Close the dashboard modal with optional manual close flag and cleanup.

/**
 * Close the dashboard modal with optional manual close flag
 * @param opts - Optional configuration for close behavior
 * @param opts.manualClose - Whether modal is being closed manually (default: true)
 * @returns Promise that resolves when modal is fully closed, or void if already closing
 */
closeModal(opts?: { manualClose: boolean }): void | Promise<void>;

Usage Examples:

// Close modal programmatically (manual close)
await dashboard.closeModal();

// Close modal automatically (non-manual close)
await dashboard.closeModal({ manualClose: false });

// Close modal on upload completion
uppy.on("complete", () => {
  if (dashboard.opts.closeAfterFinish) {
    dashboard.closeModal();
  }
});

Behavior:

Returns early if modal is already hidden or closing
Removes uppy-Dashboard-isFixed class from body if applicable
Handles close animation if animateOpenClose is enabled
Restores focus to previously active element
Manages browser history cleanup if browserBackButtonClose is enabled
Removes keyboard event listeners
Emits dashboard:modal-closed event

Check Modal State

Check if the dashboard modal is currently open.

/**
 * Check if modal is currently open
 * @returns True if modal is open, false if hidden
 */
isModalOpen(): boolean;

Usage Examples:

// Check modal state
if (dashboard.isModalOpen()) {
  console.log("Modal is currently open");
} else {
  console.log("Modal is hidden");
}

// Conditional operations based on modal state
function handleFileSelection(files: File[]) {
  if (!dashboard.isModalOpen()) {
    await dashboard.openModal();
  }
  dashboard.addFiles(files);
}

// Toggle modal state
function toggleModal() {
  if (dashboard.isModalOpen()) {
    dashboard.closeModal();
  } else {
    dashboard.openModal();
  }
}

Modal Configuration

Configuration options specific to modal behavior.

/**
 * Modal-specific configuration options
 */
interface DashboardModalOptions {
  /** Indicates modal mode (default: false) */
  inline?: false;
  /** Enable open/close animations (default: true) */
  animateOpenClose?: boolean;
  /** Close modal with browser back button (default: false) */
  browserBackButtonClose?: boolean;
  /** Auto-close modal after upload completion (default: false) */
  closeAfterFinish?: boolean;
  /** Close modal when clicking outside (default: false) */
  closeModalOnClickOutside?: boolean;
  /** Disable page scroll when modal open (default: true) */
  disablePageScrollWhenModalOpen?: boolean;
}

Configuration Examples:

// Modal with animations and browser back button support
uppy.use(Dashboard, {
  inline: false,
  animateOpenClose: true,
  browserBackButtonClose: true,
  closeModalOnClickOutside: true,
  closeAfterFinish: true
});

// Simple modal without animations
uppy.use(Dashboard, {
  inline: false,
  animateOpenClose: false,
  disablePageScrollWhenModalOpen: false
});

Modal Events

Events emitted during modal lifecycle for integration and customization.

/**
 * Modal-related events
 */
interface DashboardModalEvents {
  /** Emitted when modal opens */
  "dashboard:modal-open": () => void;
  /** Emitted when modal closes */
  "dashboard:modal-closed": () => void;
}

Event Usage Examples:

// Listen for modal events
uppy.on("dashboard:modal-open", () => {
  console.log("Dashboard modal opened");
  // Track analytics, update UI state, etc.
});

uppy.on("dashboard:modal-closed", () => {
  console.log("Dashboard modal closed");
  // Cleanup, save state, etc.
});

// Conditional behavior based on modal events
uppy.on("dashboard:modal-open", () => {
  // Pause other UI animations
  document.body.classList.add("modal-active");
});

uppy.on("dashboard:modal-closed", () => {
  // Resume other UI animations
  document.body.classList.remove("modal-active");
});

Trigger Configuration

Configure elements that can trigger modal opening.

/**
 * Trigger configuration for modal opening
 */
interface DashboardTriggerConfig {
  /** Element/selector to trigger modal opening */
  trigger?: string | Element | null;
}

Trigger Examples:

// Single element trigger
uppy.use(Dashboard, {
  trigger: "#upload-button"
});

// Multiple element triggers (CSS selector)
uppy.use(Dashboard, {
  trigger: ".upload-trigger"
});

// DOM element trigger
const uploadBtn = document.getElementById("upload-btn");
uppy.use(Dashboard, {
  trigger: uploadBtn
});

// No automatic trigger (manual control only)
uppy.use(Dashboard, {
  trigger: null
});

Modal vs Inline Mode

Key differences between modal and inline dashboard modes.

/**
 * Modal mode characteristics:
 * - Overlay display above page content
 * - Focus management and keyboard trapping
 * - Browser history integration option
 * - Page scroll prevention option
 * - Click-outside-to-close option
 * - Animation support for open/close
 */
interface ModalModeFeatures {
  overlay: boolean;
  focusManagement: boolean;
  historyIntegration: boolean;
  scrollPrevention: boolean;
  clickOutsideClose: boolean;
  animations: boolean;
}

/**
 * Inline mode characteristics:
 * - Embedded in page content
 * - No focus trapping (normal tab flow)
 * - No browser history changes
 * - Fixed dimensions (width/height)
 * - Always visible when mounted
 * - No open/close animations
 */
interface InlineModeFeatures {
  embedded: boolean;
  normalTabFlow: boolean;
  fixedDimensions: boolean;
  alwaysVisible: boolean;
}

Mode Selection Examples:

// Modal mode for overlay file selection
uppy.use(Dashboard, {
  inline: false,
  target: "body",
  trigger: "#upload-button",
  animateOpenClose: true
});

// Inline mode for embedded file management
uppy.use(Dashboard, {
  inline: true,
  target: "#file-upload-area",
  width: "100%",
  height: 400
});

Install with Tessl CLI