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

Panel Management

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

Manage visibility and state of plugin panels within the dashboard interface.

Capabilities

Show Panel

Display a specific plugin panel by its identifier.

/**
 * Show specific plugin panel by ID
 * Only shows panels for acquirer-type plugins
 * @param id - Plugin identifier to show panel for
 */
showPanel(id: string): void;

Usage Examples:

import Dashboard from "@uppy/dashboard";

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

// Show Google Drive panel
dashboard.showPanel("GoogleDrive");

// Show Webcam panel  
dashboard.showPanel("Webcam");

// Show panel after plugin registration
uppy.use(GoogleDrive, { /* options */ });
dashboard.showPanel("GoogleDrive");

Behavior:

Finds target plugin with matching ID and type 'acquirer'
Sets the plugin as activePickerPanel in dashboard state
Sets activeOverlayType to 'PickerPanel'
Emits dashboard:show-panel event with plugin ID

Hide All Panels

Hide all currently open panels and reset dashboard to default state.

/**
 * Hide all currently open panels
 * Resets dashboard to default view state
 */
hideAllPanels(): void;

Usage Examples:

// Hide all panels programmatically
dashboard.hideAllPanels();

// Hide panels after file selection
uppy.on("file-added", () => {
  dashboard.hideAllPanels();
});

// Hide panels when modal closes
uppy.on("dashboard:modal-closed", () => {
  dashboard.hideAllPanels();
});

// Custom panel management
function resetDashboardState() {
  dashboard.hideAllPanels();
  // Additional cleanup logic
}

Behavior:

Sets activePickerPanel to undefined
Sets showAddFilesPanel to false
Sets activeOverlayType to null
Sets fileCardFor to null
Sets showFileEditor to false
Emits dashboard:close-panel event with previous panel ID
Optimizes state updates to avoid unnecessary re-renders

Panel State Management

Dashboard state properties related to panel management.

/**
 * Panel-related state properties
 */
interface DashboardPanelState {
  /** Currently active picker panel */
  activePickerPanel: Target | undefined;
  /** Visibility of add files panel */
  showAddFilesPanel: boolean;
  /** Type of active overlay */
  activeOverlayType: string | null;
  /** File ID for file card display */
  fileCardFor: string | null;
  /** File editor visibility */
  showFileEditor: boolean;
}

/**
 * Plugin target interface for panel management
 */
interface Target {
  /** Plugin identifier */
  id: string;
  /** Plugin display name */
  name: string;
  /** Plugin type ('acquirer', 'progressindicator', 'editor') */
  type: string;
}

Panel Events

Events emitted during panel lifecycle for integration and customization.

/**
 * Panel-related events
 */
interface DashboardPanelEvents {
  /** Emitted when a panel is shown */
  "dashboard:show-panel": (id: string) => void;
  /** Emitted when a panel is closed */
  "dashboard:close-panel": (id: string | undefined) => void;
}

Event Usage Examples:

// Listen for panel events
uppy.on("dashboard:show-panel", (pluginId) => {
  console.log(`Panel opened for plugin: ${pluginId}`);
  // Track analytics, update breadcrumbs, etc.
});

uppy.on("dashboard:close-panel", (pluginId) => {
  console.log(`Panel closed for plugin: ${pluginId}`);
  // Cleanup, restore previous state, etc.
});

// Conditional behavior based on panel events
uppy.on("dashboard:show-panel", (pluginId) => {
  if (pluginId === "GoogleDrive") {
    // Show Google Drive specific UI hints
    showGoogleDriveHelp();
  }
});

Overlay Types

Different overlay types that can be active in the dashboard.

/**
 * Available overlay types for dashboard state
 */
type DashboardOverlayType = 
  | 'PickerPanel'    // Plugin picker panel (e.g., Google Drive)
  | 'AddFiles'       // Add files selection panel
  | 'FileCard'       // Individual file metadata panel
  | 'FileEditor'     // File editor panel (e.g., image editor)
  | null;            // No overlay active

Overlay Management Examples:

// Check current overlay state
const state = dashboard.getPluginState();
switch (state.activeOverlayType) {
  case 'PickerPanel':
    console.log(`Showing ${state.activePickerPanel?.name} panel`);
    break;
  case 'AddFiles':
    console.log("Showing add files panel");
    break;
  case 'FileCard':
    console.log(`Showing file card for ${state.fileCardFor}`);
    break;
  case 'FileEditor':
    console.log("File editor is open");
    break;
  case null:
    console.log("No overlay active");
    break;
}

Plugin Integration

How plugins integrate with panel management system.

/**
 * Plugin requirements for panel integration
 */
interface PanelCompatiblePlugin {
  /** Plugin must have unique ID */
  id: string;
  /** Plugin must have display name */
  title?: string;
  /** Plugin must be 'acquirer' type for panels */
  type: 'acquirer';
  /** Plugin can optionally provide support check */
  isSupported?: () => boolean;
  /** Plugin must provide render function */
  render: () => ComponentChild;
  /** Plugin should provide icon */
  icon?: () => ComponentChild;
}

Plugin Panel Integration Examples:

// Plugin with panel support
class CustomAcquirer extends BasePlugin {
  type = 'acquirer';
  id = 'CustomAcquirer';
  title = 'Custom Source';

  // Render method for panel content
  render() {
    return h('div', { className: 'custom-panel' }, [
      h('h3', null, 'Select from Custom Source'),
      h('button', { 
        onclick: this.selectFiles.bind(this) 
      }, 'Browse Files')
    ]);
  }

  // Optional support check
  isSupported() {
    return typeof window !== 'undefined';
  }

  selectFiles() {
    // File selection logic
    const files = getFilesFromCustomSource();
    files.forEach(file => this.uppy.addFile(file));
  }
}

// Register plugin and show its panel
uppy.use(CustomAcquirer);
const dashboard = uppy.getPlugin('Dashboard');
dashboard.showPanel('CustomAcquirer');

Automatic Panel Management

Dashboard automatically manages panels in response to various events.

/**
 * Automatic panel management triggers
 */
interface AutoPanelManagement {
  /** Hide panels when files are added */
  onFileAdded: () => void;
  /** Hide panels when modal closes */
  onModalClosed: () => void;
  /** Show appropriate panels for plugin types */
  onPluginAdded: (plugin: UnknownPlugin) => void;
  /** Remove panels when plugins are removed */
  onPluginRemoved: (plugin: UnknownPlugin) => void;
}

Automatic Behavior:

Panels are automatically hidden when files are added to maintain clean UI
Modal closure triggers panel cleanup
Compatible plugins are automatically mounted when added to Uppy
Panel targets are removed when plugins are uninstalled

Panel Navigation

Best practices for panel navigation and user experience.

/**
 * Panel navigation patterns
 */
interface PanelNavigation {
  /** Show specific panel */
  showPanel(id: string): void;
  /** Return to main dashboard view */
  hideAllPanels(): void;
  /** Navigate between panels */
  switchPanel(fromId: string, toId: string): void;
}

Navigation Examples:

// Sequential panel navigation
function navigateToNextPanel(currentPanelId: string) {
  const availablePanels = ['GoogleDrive', 'Dropbox', 'Instagram'];
  const currentIndex = availablePanels.indexOf(currentPanelId);
  const nextIndex = (currentIndex + 1) % availablePanels.length;
  
  dashboard.showPanel(availablePanels[nextIndex]);
}

// Breadcrumb navigation
function showBreadcrumb(panelId: string) {
  const breadcrumb = document.getElementById('panel-breadcrumb');
  breadcrumb.innerHTML = `Dashboard > ${panelId}`;
  
  breadcrumb.onclick = () => {
    dashboard.hideAllPanels();
    breadcrumb.innerHTML = 'Dashboard';
  };
}

// Panel history tracking
const panelHistory: string[] = [];

uppy.on('dashboard:show-panel', (id) => {
  panelHistory.push(id);
});

function goBackToPanel() {
  panelHistory.pop(); // Remove current
  const previousPanel = panelHistory.pop();
  if (previousPanel) {
    dashboard.showPanel(previousPanel);
  } else {
    dashboard.hideAllPanels();
  }
}

Install with Tessl CLI