docs: add sidebar tab example to README

Signed-off-by: Ferdinand Thiessen <opensource@fthiessen.de>

Author: susnux

README.md

@@ -53,6 +53,120 @@ const myEntry: Entry = {
 addNewFileMenuEntry(myEntry)
 ```
 
+#### Register a sidebar tab
+
+It is possible to provide your own sidebar tabs for the files app.
+For this you need to create a [custom web component](https://developer.mozilla.org/en-US/docs/Web/API/Web_components),
+which can either be done without any framework by using vanilla JavaScript but is also [possible with Vue](https://vuejs.org/guide/extras/web-components#building-custom-elements-with-vue).
+
+This example will make use of the Vue framework for building a sidebar tab as this is the official UI framework for Nextcloud apps.
+
+The sidebar tab consists of two parts:
+1. The web component which will be rendered within the sidebar.
+2. A definition object that provides all information needed by the files app.
+
+##### SidebarTab definition object
+
+This object provides the requires information such as:
+- The order (to ensure a consistent tabs order)
+- The display name for the tab navigation
+- An icon, to be used in the tab navigation
+- A callback to check if the sidebar tab is enabled for the current node shown in the sidebar.
+- The web component tag name
+
+The registration must happen in an `initScript`.
+
+```ts
+import type { ISidebarTab } from '@nextcloud/files'
+
+import { getSidebar } from '@nextcloud/files'
+import { t } from '@nextcloud/l10n'
+
+const MyTab: ISidebarTab = {
+	// unique ID of the tab
+	id: 'my_app',
+	// The display name in the menu
+	displayName: t('my_app', 'Sharing'),
+	// Pass an SVG (string) to be used as the tab menu entry icon
+	iconSvgInline: '<svg>...</svg>',
+	// Lower values mean a more prominent position
+	order: 50,
+	// the tag name of the web component
+	tagName: 'my_app-files_sidebar_tab',
+	enabled({ node, folder, view }) {
+		// you can disable this tab for some cased based on:
+		// - node: The node the sidebar was opened for
+		// - folder: The folder currently shown in the files app
+		// - view: The currently active files view
+		return true
+	},
+
+	// OPTIONAL
+	async register() {
+		// This is called when the tab is about to be activated the first time.
+		// So this can be used to do some initialization or even to define the web component.
+	}
+}
+
+// the you need to register it in the sidebar
+getSidebar()
+	.registerTab(MyTab)
+```
+
+##### SidebarTab web component
+
+The web component needs to have those properties:
+- node of type `INode`
+- folder of type `IFolder`
+- view of type `IView`
+
+And should have at least one method:
+- `setActive(active: boolean)`
+
+When using Vue you need to first create the Vue component:
+
+```vue
+<script setup lang="ts">
+import type { IFolder, INode, IView } from '@nextcloud/files'
+
+defineProps<{
+	node: INode
+	folder: IFolder
+	view: IView
+}>()
+
+defineExpose({ setActive })
+
+function setActive(active: boolean) {
+	console.debug('Tab was set active', { active })
+}
+</script>
+
+<template>
+	<div>
+		<div>Showing node: {{ node.source }}</div>
+		<div>... in folder: {{ folder.source }}</div>
+		<div>... with view: {{ view.id }}</div>
+	</div>
+</template>
+```
+
+Which then can be wrapped in a web component and registered.
+
+```ts
+import { defineAsyncComponent, defineCustomElement } from 'vue'
+
+const tab: ISidebarTab = {
+	// ...
+	onInit() {
+		const MySidebarTab = defineAsyncComponent(() => import('./views/MySidebarTab.vue'))
+		// make sure to disable the shadow root to allow theming with Nextcloud provided global styles.
+		const MySidebarTabWebComponent = defineCustomElement(MySidebarTab, { shadowRoot: false })
+		customElements.define('my_app-files_sidebar_tab', MySidebarTabWebComponent)
+	}
+}
+```
+
 ### WebDAV
 The `getClient` exported function returns a webDAV client that's a wrapper around [webdav's webDAV client](https://www.npmjs.com/package/webdav).
 All its methods are available here.