@nextcloud/files 4.0.0-beta.9 → 4.0.0-rc.1

package/README.md

@@ -53,6 +53,123 @@ 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 tab list
+	displayName: t('my_app', 'Sharing'),
+
+	// Pass an SVG (string) to be used as the tab button 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',
+
+	// Optional callback to check if the tab should be shown
+	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, recommended to large tabs  
+	async onInit() {
+		// 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`
+- active of type `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
+	active: boolean
+}>()
+</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 { getSidebar } from '@nextcloud/files'
+import { defineAsyncComponent, defineCustomElement } from 'vue'
+
+getSidebar().registerTab({
+	// ...
+
+	tagName: `my_app-files_sidebar_tab`,
+
+	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.

package/dist/actions/fileAction.d.ts

@@ -31,7 +31,7 @@ export interface IHotkeyConfig {
      */
     alt?: true;
 }
-export interface FileActionData {
+export interface IFileAction {
     /** Unique ID */
     id: string;
     /** Translatable string displayed in the menu */
@@ -97,32 +97,13 @@ export interface FileActionData {
      */
     renderInline?: (context: ActionContextSingle) => Promise<HTMLElement | null>;
 }
-export declare class FileAction {
-    private _action;
-    constructor(action: FileActionData);
-    get id(): string;
-    get displayName(): (context: ActionContext) => string;
-    get title(): ((context: ActionContext) => string) | undefined;
-    get iconSvgInline(): (context: ActionContext) => string;
-    get enabled(): ((context: ActionContext) => boolean) | undefined;
-    get exec(): (context: ActionContextSingle) => Promise<boolean | null>;
-    get execBatch(): ((context: ActionContext) => Promise<(boolean | null)[]>) | undefined;
-    get hotkey(): IHotkeyConfig | undefined;
-    get order(): number | undefined;
-    get parent(): string | undefined;
-    get default(): TDefaultType | undefined;
-    get destructive(): boolean | undefined;
-    get inline(): ((context: ActionContextSingle) => boolean) | undefined;
-    get renderInline(): ((context: ActionContextSingle) => Promise<HTMLElement | null>) | undefined;
-    private validateAction;
-}
 /**
  * Register a new file action.
  *
  * @param action - The file list action to register
  */
-export declare function registerFileAction(action: FileAction): void;
+export declare function registerFileAction(action: IFileAction): void;
 /**
- *
+ * Get all registered file actions.
  */
-export declare function getFileActions(): FileAction[];
+export declare function getFileActions(): IFileAction[];

package/dist/actions/fileListAction.d.ts

@@ -1,5 +1,5 @@
 import { ViewActionContext } from '../types.ts';
-interface FileListActionData {
+export interface IFileListAction {
     /** Unique ID */
     id: string;
     /** Translated name of the action */
@@ -21,25 +21,13 @@ interface FileListActionData {
      */
     exec: (context: ViewActionContext) => Promise<boolean | null>;
 }
-export declare class FileListAction {
-    private _action;
-    constructor(action: FileListActionData);
-    get id(): string;
-    get displayName(): (context: ViewActionContext) => string;
-    get iconSvgInline(): ((context: ViewActionContext) => string) | undefined;
-    get order(): number;
-    get enabled(): ((context: ViewActionContext) => boolean) | undefined;
-    get exec(): (context: ViewActionContext) => Promise<boolean | null>;
-    private validateAction;
-}
 /**
  * Register a new file list action.
  *
  * @param action - The file list action to register
  */
-export declare function registerFileListAction(action: FileListAction): void;
+export declare function registerFileListAction(action: IFileListAction): void;
 /**
  * Get all currently registered file list actions.
  */
-export declare function getFileListActions(): FileListAction[];
-export {};
+export declare function getFileListActions(): IFileListAction[];

package/dist/actions/index.d.ts

@@ -1,3 +1,4 @@
-export type { FileActionData, IHotkeyConfig } from './fileAction.ts';
-export { DefaultType, FileAction, getFileActions, registerFileAction } from './fileAction.ts';
-export { FileListAction, getFileListActions, registerFileListAction } from './fileListAction.ts';
+export type { IFileAction, IHotkeyConfig } from './fileAction.ts';
+export type { IFileListAction } from './fileListAction.ts';
+export { DefaultType, getFileActions, registerFileAction } from './fileAction.ts';
+export { getFileListActions, registerFileListAction } from './fileListAction.ts';

package/dist/filters/functions.d.ts

@@ -0,0 +1,20 @@
+import { IFileListFilter } from './listFilters.ts';
+/**
+ * Register a new filter on the file list
+ *
+ * This only must be called once to register the filter,
+ * when the filter state changes you need to call `filterUpdated` on the filter instead.
+ *
+ * @param filter The filter to register on the file list
+ */
+export declare function registerFileListFilter(filter: IFileListFilter): void;
+/**
+ * Remove a registered filter from the file list
+ *
+ * @param filterId The unique ID of the filter to remove
+ */
+export declare function unregisterFileListFilter(filterId: string): void;
+/**
+ * Get all registered file list filters
+ */
+export declare function getFileListFilters(): IFileListFilter[];

package/dist/filters/index.d.ts

@@ -0,0 +1,7 @@
+/*!
+ * SPDX-FileCopyrightText: 2026 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+export type * from './listFilters.ts';
+export { getFileListFilters, registerFileListFilter, unregisterFileListFilter, } from './functions.ts';
+export { FileListFilter } from './listFilters.ts';

package/dist/{fileListFilters.d.ts → filters/listFilters.d.ts}

@@ -1,4 +1,4 @@
-import { INode } from './node/index.ts';
+import { INode } from '../node/index.ts';
 import { TypedEventTarget } from 'typescript-event-target';
 /**
  * Active filters can provide one or more "chips" to show the currently active state.
@@ -106,23 +106,4 @@ export declare class FileListFilter extends TypedEventTarget<IFileListFilterEven
     protected updateChips(chips: IFileListFilterChip[]): void;
     protected filterUpdated(): void;
 }
-/**
- * Register a new filter on the file list
- *
- * This only must be called once to register the filter,
- * when the filter state changes you need to call `filterUpdated` on the filter instead.
- *
- * @param filter The filter to register on the file list
- */
-export declare function registerFileListFilter(filter: IFileListFilter): void;
-/**
- * Remove a registered filter from the file list
- *
- * @param filterId The unique ID of the filter to remove
- */
-export declare function unregisterFileListFilter(filterId: string): void;
-/**
- * Get all registered file list filters
- */
-export declare function getFileListFilters(): IFileListFilter[];
 export {};

package/dist/headers/functions.d.ts

@@ -0,0 +1,11 @@
+import { Header } from './listHeaders.ts';
+/**
+ * Register a new file list header.
+ *
+ * @param header - The header to register
+ */
+export declare function registerFileListHeaders(header: Header): void;
+/**
+ * Get all currently registered file list headers.
+ */
+export declare function getFileListHeaders(): Header[];

package/dist/headers/index.d.ts

@@ -0,0 +1,3 @@
+export type * from './listHeaders.ts';
+export { Header } from './listHeaders.ts';
+export { getFileListHeaders, registerFileListHeaders } from './functions.ts';

package/dist/{fileListHeaders.d.ts → headers/listHeaders.d.ts}

@@ -1,5 +1,5 @@
-import { IView } from './navigation/view.ts';
-import { IFolder } from './node/folder.ts';
+import { IView } from '../navigation/view.ts';
+import { IFolder } from '../node/folder.ts';
 export interface HeaderData {
     /** Unique ID */
     id: string;
@@ -8,9 +8,9 @@ export interface HeaderData {
     /** Condition wether this header is shown or not */
     enabled?: (folder: IFolder, view: IView) => boolean;
     /** Executed when file list is initialized */
-    render: (el: HTMLElement, folder: IFolder, view: IView) => void;
+    render(el: HTMLElement, folder: IFolder, view: IView): void;
     /** Executed when root folder changed */
-    updated(folder: IFolder, view: IView): any;
+    updated(folder: IFolder, view: IView): void;
 }
 export declare class Header {
     private _header;
@@ -19,16 +19,6 @@ export declare class Header {
     get order(): number;
     get enabled(): ((folder: IFolder, view: IView) => boolean) | undefined;
     get render(): (el: HTMLElement, folder: IFolder, view: IView) => void;
-    get updated(): (folder: IFolder, view: IView) => any;
+    get updated(): (folder: IFolder, view: IView) => void;
     private validateHeader;
 }
-/**
- * Register a new file list header.
- *
- * @param header - The header to register
- */
-export declare function registerFileListHeaders(header: Header): void;
-/**
- * Get all currently registered file list headers.
- */
-export declare function getFileListHeaders(): Header[];

package/dist/index.d.ts

@@ -1,10 +1,11 @@
 export type * from './types.ts';
 export * from './actions/index.ts';
-export * from './fileListFilters.ts';
-export * from './fileListHeaders.ts';
+export * from './filters/index.ts';
+export * from './headers/index.ts';
 export * from './navigation/index.ts';
 export * from './newMenu/index.ts';
 export * from './node/index.ts';
 export * from './permissions.ts';
 export * from './sidebar/index.ts';
 export * from './utils/index.ts';
+export { getFilesRegistry } from './registry.ts';