Create `onUnmount` in `UIPlugin` for plugins that require clean up (#3093)

- Create and call `onUnmount` in `UIPlugin` for plugins that require clean up
- Update webcam `stop` to clean up when already recording
- Update "Writing plugins" docs
- Move `onMount` and `onUnmount` from `BasePlugin` into `UIPlugin`
- Update types

packages/@uppy/core/src/BasePlugin.js

@@ -75,9 +75,6 @@ module.exports = class BasePlugin {
     throw new Error('Extend the render method to add your plugin to a DOM element')
   }
 
-  // eslint-disable-next-line class-methods-use-this
-  onMount () {}
-
   // eslint-disable-next-line class-methods-use-this
   update () {}
 

packages/@uppy/core/src/UIPlugin.js

@@ -134,7 +134,14 @@ class UIPlugin extends BasePlugin {
     if (this.isTargetDOMEl) {
       this.el?.remove()
     }
+    this.onUnmount()
   }
+
+  // eslint-disable-next-line class-methods-use-this
+  onMount () {}
+
+  // eslint-disable-next-line class-methods-use-this
+  onUnmount () {}
 }
 
 module.exports = UIPlugin

packages/@uppy/core/types/index.d.ts

@@ -122,6 +122,10 @@ export class UIPlugin<TOptions extends PluginOptions = DefaultPluginOptions> ext
   addTarget<TPlugin extends UIPlugin>(plugin: TPlugin): void
 
   unmount(): void
+
+  onMount(): void
+
+  onUnmount(): void
 }
 
 export type PluginTarget =

packages/@uppy/dashboard/src/index.js

@@ -206,6 +206,7 @@ module.exports = class Dashboard extends UIPlugin {
   }
 
   hideAllPanels = () => {
+    const state = this.getPluginState()
     const update = {
       activePickerPanel: false,
       showAddFilesPanel: false,
@@ -214,11 +215,10 @@ module.exports = class Dashboard extends UIPlugin {
       showFileEditor: false,
     }
 
-    const current = this.getPluginState()
-    if (current.activePickerPanel === update.activePickerPanel
-        && current.showAddFilesPanel === update.showAddFilesPanel
-        && current.showFileEditor === update.showFileEditor
-        && current.activeOverlayType === update.activeOverlayType) {
+    if (state.activePickerPanel === update.activePickerPanel
+        && state.showAddFilesPanel === update.showAddFilesPanel
+        && state.showFileEditor === update.showFileEditor
+        && state.activeOverlayType === update.activeOverlayType) {
       // avoid doing a state update if nothing changed
       return
     }

packages/@uppy/webcam/src/index.js

@@ -1,6 +1,5 @@
 const { h } = require('preact')
 const { UIPlugin } = require('@uppy/core')
-const Translator = require('@uppy/utils/lib/Translator')
 const getFileTypeExtension = require('@uppy/utils/lib/getFileTypeExtension')
 const mimeTypes = require('@uppy/utils/lib/mimeTypes')
 const canvasToBlob = require('@uppy/utils/lib/canvasToBlob')
@@ -393,19 +392,34 @@ module.exports = class Webcam extends UIPlugin {
     }
   }
 
-  stop () {
+  async stop () {
     if (this.stream) {
-      this.stream.getAudioTracks().forEach((track) => {
-        track.stop()
-      })
-      this.stream.getVideoTracks().forEach((track) => {
-        track.stop()
+      const audioTracks = this.stream.getAudioTracks()
+      const videoTracks = this.stream.getVideoTracks()
+
+      audioTracks.concat(videoTracks).forEach((track) => track.stop())
+    }
+
+    if (this.recorder) {
+      await new Promise((resolve) => {
+        this.recorder.addEventListener('stop', resolve, { once: true })
+        this.recorder.stop()
+
+        if (this.opts.showRecordingLength) {
+          clearInterval(this.recordingLengthTimer)
+        }
       })
     }
+
+    this.recordingChunks = null
+    this.recorder = null
     this.webcamActive = false
     this.stream = null
+
     this.setPluginState({
       recordedVideo: null,
+      isRecording: false,
+      recordingLengthSeconds: 0,
     })
   }
 
@@ -624,10 +638,11 @@ module.exports = class Webcam extends UIPlugin {
   }
 
   uninstall () {
-    if (this.stream) {
-      this.stop()
-    }
-
+    this.stop()
     this.unmount()
   }
+
+  onUnmount () {
+    this.stop()
+  }
 }

website/src/docs/writing-plugins.md

@@ -17,14 +17,18 @@ See a [full example of a plugin](#Example-of-a-custom-plugin) below.
 
 ## Creating A Plugin
 
-Plugins are classes that extend from Uppy's `Plugin` class. Each plugin has an `id` and a `type`. `id`s are used to uniquely identify plugins. A `type` can be anything—some plugins use `type`s to determine whether to do something to some other plugin. For example, when targeting plugins at the built-in `Dashboard` plugin, the Dashboard uses the `type` to figure out where to mount different UI elements. `'acquirer'`-type plugins are mounted into the tab bar, while `'progressindicator'`-type plugins are mounted into the progress bar area.
+Uppy has two classes to create plugins with. `BasePlugin` for plugins that don't require an user interface, and `UIPlugin` for onces that do.
+Each plugin has an `id` and a `type`. `id`s are used to uniquely identify plugins.
+A `type` can be anything—some plugins use `type`s to determine whether to do something to some other plugin.
+For example, when targeting plugins at the built-in `Dashboard` plugin, the Dashboard uses the `type` to figure out where to mount different UI elements.
+`'acquirer'`-type plugins are mounted into the tab bar, while `'progressindicator'`-type plugins are mounted into the progress bar area.
 
 The plugin constructor receives the Uppy instance in the first parameter, and any options passed to `uppy.use()` in the second parameter.
 
 ```js
-import { UIPlugin } from '@uppy/core'
+import { BasePlugin } from '@uppy/core'
 
-export default class MyPlugin extends UIPlugin {
+export default class MyPlugin extends BasePlugin {
   constructor (uppy, opts) {
     super(uppy, opts)
     this.id = opts.id || 'MyPlugin'
@@ -39,7 +43,9 @@ Plugins can implement methods in order to execute certain tasks. The most import
 
 All of the below methods are optional! Only implement the methods you need.
 
-### `install()`
+### `BasePlugin`
+
+#### `install()`
 
 Called when the plugin is `.use`d. Do any setup work here, like attaching events or adding [upload hooks](#Upload-Hooks).
 
@@ -53,7 +59,7 @@ export default class MyPlugin extends UIPlugin {
 }
 ```
 
-### `uninstall()`
+#### `uninstall()`
 
 Called when the plugin is removed, or the Uppy instance is closed. This should undo all of the work done in the `install()` method.
 
@@ -67,10 +73,41 @@ export default class MyPlugin extends UIPlugin {
 }
 ```
 
-### `update(state)`
+#### `afterUpdate()`
+
+Called after every state update with a debounce, after everything has mounted.
+
+#### `addTarget()`
+
+Use this to add your plugin to another plugin's target. This is what `@uppy/dashboard` uses to add other plugins to its UI.
+
+### `UIPlugin`
+
+`UIPlugin` extends the `BasePlugin` class so it will also contain all the above methods.
+
+#### `mount(target)`
+
+Mount this plugin to the `target` element. `target` can be a CSS query selector, a DOM element, or another Plugin. If `target` is a Plugin, the source (current) plugin will register with the target plugin, and the latter can decide how and where to render the source plugin.
+
+This method can be overridden to support for different render engines.
+
+#### `render()`
+
+Render this plugin's UI. Uppy uses [Preact](https://preactjs.com) as its view engine, so `render()` should return a Preact element.
+`render` is automatically called by Uppy on each state change.
+
+#### `onMount()`
+
+Called after Preact has rendered the components of the plugin. Can be used to perform additional side-effects.
+
+#### `update(state)`
 
 Called on each state update. You will rarely need to use this, it is mostly handy if you want to build a UI plugin using something other than Preact.
 
+#### `onUnmount()`
+
+Called after the elements have been removed from the DOM. Can be used to perform additional (clean up) side-effects.
+
 ## Upload Hooks
 
 When creating an upload, Uppy runs files through an upload pipeline. The pipeline consists of three parts, each of which can be hooked into: Preprocessing, Uploading, and Postprocessing. Preprocessors can be used to configure uploader plugins, encrypt files, resize images, etc., before uploading them. Uploaders do the actual uploading work, such as creating an XMLHttpRequest object and sending the file. Postprocessors do their work after files have been uploaded completely. This could be anything from waiting for a file to propagate across a CDN, to sending another request to relate some metadata to the file.
@@ -82,7 +119,7 @@ Additionally, upload hooks can fire events to signal progress.
 When adding hooks, make sure to bind the hook `fn` beforehand! Otherwise, it will be impossible to remove. For example:
 
 ```js
-class MyPlugin extends UIPlugin {
+class MyPlugin extends BasePlugin {
   constructor (uppy, opts) {
     super(uppy, opts)
     this.id = opts.id || 'MyPlugin'
@@ -164,35 +201,11 @@ When `mode` is `'determinate'`, also add the `value` property:
 
  `err` is an `Error` object. `fileID` can optionally which file fails to inform the user.
 
-## UI Plugins
-
-UI Plugins can be used to show a user interface. Uppy plugins use [preact](https://preactjs.com) v8.2.9 for rendering. preact is a very small React-like library that works really well with Uppy's state architecture. Uppy implements preact rendering in the `mount(target)` and `update()` plugin methods, so if you want to write a custom UI plugin using some other library, you can override those methods.
-
-> **Only** `preact@8.2.9` can be used for Uppy plugins. In Uppy 2.0, the restriction will be changed to a newer range of preact versions. For now, specify the dependency with a fixed version number:
-> ```json
-> "dependencies": {
->   "preact": "8.2.9"
-> }
-> ```
-
-Plugins can implement certain methods to do so, that will be called by Uppy when necessary:
-
-### `mount(target)`
-
-Mount this plugin to the `target` element. `target` can be a CSS query selector, a DOM element, or another Plugin. If `target` is a Plugin, the source (current) plugin will register with the target plugin, and the latter can decide how and where to render the source plugin.
-
-This method can be overridden to support for different render engines.
-
-### `render()`
-
-Render this plugin's UI. Uppy uses [Preact](https://preactjs.com) as its view engine, so `render()` should return a Preact element.
-`render` is automatically called by Uppy on each state change.
-
-Note that we are looking into ways to make Uppy's render engine agnostic, so that plugins can choose their own favourite library—whether it's Preact, Choo, jQuery, or anything else. This means that the `render()` API may change in the future, but we will detail exactly what you need to do on the [blog](https://uppy.io/blog) if and when that happens.
 
 ### JSX
 
-Since Uppy uses Preact and not React, the default Babel configuration for JSX elements does not work. You have to import the Preact `h` function and tell Babel to use it by adding a `/** @jsx h */` comment at the top of the file.
+Since Uppy uses Preact and not React, the default Babel configuration for JSX elements does not work.
+You have to import the Preact `h` function and tell Babel to use it by adding a `/** @jsx h */` comment at the top of the file.
 
 See the Preact [Getting Started Guide](https://preactjs.com/guide/getting-started) for more on Babel and JSX.