UI Plugin API (#4256)

* Add page registration
* Add example plugin
* First version of proper react plugins
* Make reference react plugin
* Add patching functions
* Add tools link poc
* NavItem poc
* Add loading hook for lazily loaded components
* Add documentation

ui/v2.5/src/docs/en/Manual/UIPluginApi.md

@@ -0,0 +1,131 @@
+# UI Plugin API
+
+The `PluginApi` object is a global object in the `window` object.
+
+`PluginApi` is considered experimental and is subject to change without notice. This documentation covers only the plugin-specific API. It does not necessarily cover the core UI API. Information on these methods should be referenced in the UI source code.
+
+An example using various aspects of `PluginApi` may be found in the source code under `pkg/plugin/examples/react-component`.
+
+## Properties
+
+### `React`
+
+An instance of the React library.
+
+### `GQL`
+
+This namespace contains the generated graphql client interface. This is a low-level interface. In many cases, `StashService` should be used instead.
+
+### `libraries`
+
+`libraries` provides access to the following UI libraries:
+- `ReactRouterDOM`
+- `Bootstrap`
+- `Apollo`
+- `Intl`
+- `FontAwesomeRegular`
+- `FontAwesomeSolid`
+
+### `register`
+
+This namespace contains methods used to register page routes and components.
+
+#### `PluginApi.register.route`
+
+Registers a route in the React Router.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `path` | `string` | The path to register. This should generally use the `/plugin/` prefix. |
+| `component` | `React.FC` | A React function component that will be rendered when the route is loaded. |
+
+Returns `void`.
+
+#### `PluginApi.register.component`
+
+Registers a component to be used by plugins. The component will be available in the `components` namespace.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `name` | `string` | The name of the component to register. This should be unique and should ideally be prefixed with `plugin-`. |
+| `component` | `React.FC` | A React function component. |
+
+Returns `void`.
+
+### `components`
+
+This namespace contains all of the components available to plugins. These include a selection of core components and components registered using `PluginApi.register.component`.
+
+### `utils`
+
+This namespace provides access to the `NavUtils` and `StashService` namespaces. It also provides access to the `loadComponents` method.
+
+#### `PluginApi.utils.loadComponents`
+
+Due to code splitting, some components may not be loaded and available when a plugin page is rendered. `loadComponents` loads all of the components that a plugin page may require.
+
+In general, `PluginApi.hooks.useLoadComponents` hook should be used instead.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `components` | `Promise[]` | The list of components to load. These values should come from the `PluginApi.loadableComponents` namespace. |
+
+Returns a `Promise<void>` that resolves when all of the components have been loaded.
+
+### `hooks`
+
+This namespace provides access to the following core utility hooks:
+- `useSpriteInfo`
+
+It also provides plugin-specific hooks.
+
+#### `PluginApi.hooks.useLoadComponents`
+
+This is a hook used to load components, using the `PluginApi.utils.loadComponents` method.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `components` | `Promise[]` | The list of components to load. These values should come from the `PluginApi.loadableComponents` namespace. |
+
+Returns a `boolean` which will be `true` if the components are loading.
+
+### `loadableComponents`
+
+This namespace contains all of the components that may need to be loaded using the `loadComponents` method. Components are added to this namespace as needed. Please make a development request if a required component is not in this namespace.
+
+### `patch`
+
+This namespace provides methods to patch components to change their behaviour.
+
+#### `PluginApi.patch.before`
+
+Registers a before function. A before function is called prior to calling a component's render function. It accepts the same parameters as the component's render function, and is expected to return a list of new arguments that will be passed to the render.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `component` | `string` | The name of the component to patch. |
+| `fn` | `Function` | The before function. It accepts the same arguments as the component render function and is expected to return a list of arguments to pass to the render function. |
+
+Returns `void`.
+
+#### `PluginApi.patch.instead`
+
+Registers a replacement function for a component. The provided function will be called with the arguments passed to the original render function, plus the original render function as the last argument. An error will be thrown if the component already has a replacement function registered.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `component` | `string` | The name of the component to patch. |
+| `fn` | `Function` | The replacement function. It accepts the same arguments as the original render function, plus the original render function, and is expected to return the replacement component. |
+
+Returns `void`.
+
+#### `PluginApi.patch.after`
+
+Registers an after function. An after function is called after the render function of the component. It accepts the arguments passed to the original render function, plus the result of the original render function. It is expected to return the rendered component.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `component` | `string` | The name of the component to patch. |
+| `fn` | `Function` | The after function. It accepts the same arguments as the original render function, plus the result of the original render function, and is expected to return the rendered component. |
+
+Returns `void`.