feat(sidebar): provide a proxy for the files sidebar

Additionally to registering sidebar tabs this also provides
a public interface to access the sidebar itself.
Which can be used to retrieve or set the currently active tab,
allows to open or close it and getting the open state.

We can then use this proxy to later add fallbacks for different
Nextcloud versions once we modernized the files sidebar,
so apps can stick with this interface regardless of the Nextcloud
version and implementation used underneath.

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

Author: susnux

lib/sidebar/Sidebar.ts

@@ -0,0 +1,91 @@
+/*
+ * SPDX-FileCopyrightText: 2025 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+import { INode } from '../node/index.ts'
+import { getSidebarTabs, ISidebarTab, registerSidebarTab } from './SidebarTab.ts'
+
+export interface ISidebar {
+	/**
+	 * If the files sidebar can currently be accessed.
+	 * Registering tabs also works if the sidebar is currently not available.
+	 */
+	readonly available: boolean
+
+	/**
+	 * The current open state of the sidebar
+	 */
+	readonly open: boolean
+
+	/**
+	 * Open or close the sidebar
+	 *
+	 * @param open - The new open state
+	 */
+	setOpen(open: boolean): void
+
+	/**
+	 * Register a new sidebar tab
+	 *
+	 * @param tab - The sidebar tab to register
+	 */
+	registerTab(tab: ISidebarTab): void
+
+	/**
+	 * Get all registered sidebar tabs.
+	 * If a node is passed only the enabled tabs are retrieved.
+	 */
+	getTabs(node?: INode): ISidebarTab[]
+}
+
+/**
+ * This is just a proxy allowing an arbitrary `@nextcloud/files` library version to access the defined interface of the sidebar.
+ * By proxying this instead of providing the implementation here we ensure that if apps use different versions of the library,
+ * we do not end up with version conflicts between them.
+ *
+ * If we add new properties they just will be available in new library versions.
+ * If we decide to do a breaking change we can either add compatibility wrappers in the implementation in the files app.
+ */
+class SidebarProxy implements ISidebar {
+
+	get available(): boolean {
+		return !!window.OCA?.Files?.Sidebar
+	}
+
+	get open(): boolean {
+		return !!window.OCA?.Files?.Sidebar?.state.file
+	}
+
+	setOpen(open: boolean): void {
+		if (open) {
+			window.OCA?.Files?.Sidebar?.open()
+		} else {
+			window.OCA?.Files?.Sidebar?.close()
+		}
+	}
+
+	setActiveTab(tabId: string): void {
+		window.OCA?.Files?.Sidebar?.setActiveTab(tabId)
+	}
+
+	registerTab(tab: ISidebarTab): void {
+		registerSidebarTab(tab)
+	}
+
+	getTabs(node?: INode): ISidebarTab[] {
+		const tabs = getSidebarTabs()
+		if (node) {
+			return tabs.filter((tab) => tab.enabled(node))
+		}
+		return tabs
+	}
+
+}
+
+/**
+ * Get a reference to the files sidebar.
+ */
+export function getSidebar(): ISidebar {
+	return new SidebarProxy()
+}

lib/sidebar/SidebarTab.ts

@@ -0,0 +1,163 @@
+/*
+ * SPDX-FileCopyrightText: 2025 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+import { IFolder, INode } from '../node/index.ts'
+import logger from '../utils/logger.ts'
+
+interface SidebarUpdateContext {
+	/**
+	 * The currently selected node for which the sidebar is shown.
+	 */
+	node: INode
+
+	/**
+	 * The parent of the current selected node.
+	 * This is not necessarily the real parent folder of the node in means of the real filesystem tree,
+	 * but rather the parent folder in the current view of the files app.
+	 */
+	parent: IFolder
+}
+
+/**
+ * Implementation of a custom sidebar tab within the files app.
+ */
+export interface ISidebarTab {
+	/**
+	 * Unique id of the sidebar tab.
+	 * This has to conform to the HTML id attribute specification.
+	 */
+	id: string
+
+	/**
+	 * The localized name of the sidebar tab.
+	 */
+	displayName: string
+
+	/**
+	 * The icon, as SVG, of the sidebar tab.
+	 */
+	iconSvg: string
+
+	/**
+	 * The order of this tab.
+	 * Use a low number to make this tab ordered in front.
+	 */
+	order: number
+
+	/**
+	 * Callback to check if the sidebar tab should be shown for the selected node.
+	 *
+	 * @param node - The currently selected node
+	 */
+	enabled: (node: INode) => boolean
+
+	/**
+	 * Called by the files app if this tab has become the active tab or was deactivated.
+	 *
+	 * @param active - The new active state of this tab
+	 */
+	setActive: (active: boolean) => void | Promise<void>
+
+	/**
+	 * The lifecylce method for mounting the sidebar tab onto the sidebar.
+	 *
+	 * @param el - The element to mount the sidebar tab to
+	 * @param context - The current sidebar context
+	 */
+	mount: (el: HTMLElement, context: SidebarUpdateContext) => void | Promise<void>
+
+	/**
+	 * The lifecycle method for updating the sidebar tab.
+	 * This is called if the currently selected node changes.
+	 *
+	 * @param context - The current sidebar context
+	 */
+	update: (context: SidebarUpdateContext) => void | Promise<void>
+
+	/**
+	 * The lifecycle method for unmounting the sidebar tab.
+	 * This is called if the sidebar is unmounted from the files app and thus the sidebar tab needs to do its cleanup and unmounting.
+	 */
+	unmount: () => void | Promise<void>
+
+	/**
+	 * Called when the bottom of the sidebar was reached during scrolling.
+	 */
+	onScrollBottomReached?: () => void | Promise<void>
+}
+
+/**
+ * Register a new sidebar tab for the files app.
+ *
+ * @param tab - The sidebar tab to register
+ * @throws If the provided tab is not a valid sidebar tab and thus cannot be registered.
+ */
+export function registerSidebarTab(tab: ISidebarTab): void {
+	validateSidebarTab(tab)
+
+	window._nc_files_sidebar_tabs ??= new Map<string, ISidebarTab>()
+	if (window._nc_files_sidebar_tabs.has(tab.id)) {
+		logger.warn(`Sidebar tab with id "${tab.id}" already registered. Skipping.`)
+		return
+	}
+	window._nc_files_sidebar_tabs.set(tab.id, tab)
+	logger.debug(`New sidebar tab with id "${tab.id}" registered.`)
+}
+
+/**
+ * Get all currently registered sidebar tabs.
+ */
+export function getSidebarTabs(): ISidebarTab[] {
+	if (window._nc_files_sidebar_tabs) {
+		return [...window._nc_files_sidebar_tabs.values()]
+	}
+	return []
+}
+
+/**
+ * Check if a given sidebar tab objects implements all necessary fields.
+ *
+ * @param tab - The sidebar tab to validate
+ */
+function validateSidebarTab(tab: ISidebarTab): void {
+	if (typeof tab !== 'object') {
+		throw new Error('Sidebar tab is not an object')
+	}
+
+	if (!tab.id || (typeof tab.id !== 'string') || tab.id !== CSS.escape(tab.id)) {
+		throw new Error('Sidebar tabs need to have an id conforming to the HTML id attribute specifications')
+	}
+
+	if (!tab.displayName || typeof tab.displayName !== 'string') {
+		throw new Error('Sidebar tabs need to have a name set')
+	}
+
+	if (typeof tab.iconSvg !== 'string' || !tab.iconSvg.match(/^<svg.+<\/svg>$/i)) {
+		throw new Error('Sidebar tabs need to have an valid SVG icon')
+	}
+
+	if (typeof tab.order !== 'number') {
+		throw new Error('Sidebar tabs need to have a numeric order set')
+	}
+
+	if (typeof tab.enabled !== 'function') {
+		throw new Error('Sidebar tabs need to have an "enabled" method')
+	}
+
+	if (typeof tab.setActive !== 'function') {
+		throw new Error('Sidebar tabs need to have a "setActive" method')
+	}
+
+	if (typeof tab.mount !== 'function'
+		|| typeof tab.update !== 'function'
+		|| typeof tab.unmount !== 'function'
+	) {
+		throw new Error('Sidebar tab is missing a required lifecycle method')
+	}
+
+	if (tab.onScrollBottomReached && typeof tab.onScrollBottomReached !== 'function') {
+		throw new Error('"onScrollBottomReached" of the sidebar tab needs to be a function')
+	}
+}