From f8e079f8a390e1e2bd96f79e6cf11ec1e6cc4eef Mon Sep 17 00:00:00 2001
From: Ferdinand Thiessen <opensource@fthiessen.de>
Date: Wed, 25 Jun 2025 23:56:40 +0200
Subject: [PATCH 1/3] feat(NcFilePicker): add picker component to select local
 files

This can be used e.g. to upload files, for example in the forms app but
also for the files or photos app.

Signed-off-by: Ferdinand Thiessen <opensource@fthiessen.de>
---
 l10n/messages.pot                            |  21 ++
 src/components/NcFilePicker/NcFilePicker.vue | 288 +++++++++++++++++++
 src/components/NcFilePicker/index.ts         |   6 +
 src/components/index.js                      |   1 +
 4 files changed, 316 insertions(+)
 create mode 100644 src/components/NcFilePicker/NcFilePicker.vue
 create mode 100644 src/components/NcFilePicker/index.ts

diff --git a/l10n/messages.pot b/l10n/messages.pot
index 81b3424211..6d8eceed9c 100644
--- a/l10n/messages.pot
+++ b/l10n/messages.pot
@@ -327,6 +327,15 @@ msgstr ""
 msgid "Pick an emoji"
 msgstr ""
 
+msgid "Pick file"
+msgstr ""
+
+msgid "Pick files"
+msgstr ""
+
+msgid "Pick folder"
+msgstr ""
+
 msgid "Please select a time zone:"
 msgstr ""
 
@@ -459,6 +468,18 @@ msgstr ""
 msgid "Undo changes"
 msgstr ""
 
+msgid "Upload file"
+msgstr ""
+
+msgid "Upload files"
+msgstr ""
+
+msgid "Upload folder"
+msgstr ""
+
+msgid "Uploading …"
+msgstr ""
+
 msgid "User status: {status}"
 msgstr ""
 
diff --git a/src/components/NcFilePicker/NcFilePicker.vue b/src/components/NcFilePicker/NcFilePicker.vue
new file mode 100644
index 0000000000..666ac83141
--- /dev/null
+++ b/src/components/NcFilePicker/NcFilePicker.vue
@@ -0,0 +1,288 @@
+<!--
+  - SPDX-FileCopyrightText: 2025 Nextcloud GmbH and Nextcloud contributors
+  - SPDX-License-Identifier: AGPL-3.0-or-later
+-->
+
+<script setup lang="ts">
+import type { Slot } from 'vue'
+
+import { computed, nextTick, useTemplateRef } from 'vue'
+import IconFolderUpload from 'vue-material-design-icons/FolderUpload.vue'
+import IconPlus from 'vue-material-design-icons/Plus.vue'
+import IconUpload from 'vue-material-design-icons/Upload.vue'
+import NcActionButton from '../NcActionButton/NcActionButton.vue'
+import NcActionCaption from '../NcActionCaption/NcActionCaption.vue'
+import NcActions from '../NcActions/NcActions.vue'
+import NcLoadingIcon from '../NcLoadingIcon/NcLoadingIcon.vue'
+import { t } from '../../l10n.js'
+
+const props = withDefaults(defineProps<{
+	/**
+	 * File types to accept
+	 */
+	accept?: string[]
+
+	/**
+	 * Optional menu caption to be shown above the actions
+	 */
+	actionCaption?: string
+
+	/**
+	 * Allow picking a directory
+	 */
+	directory?: boolean
+
+	/**
+	 * Disable picking files and only allow picking a directory
+	 */
+	directoryOnly?: boolean
+
+	/**
+	 * Disabled state of the picker
+	 */
+	disabled?: boolean
+
+	/**
+	 * If set then the label is only used for accessibility but not shown visually
+	 */
+	iconOnly?: boolean
+
+	/**
+	 * Label of the picker
+	 *
+	 * @default 'Pick file' or 'Pick files' depending on `multiple`
+	 */
+	label?: string
+
+	/**
+	 * If set then the picker will be set into a loading state.
+	 * This means the picker is disabled, a loading spinner is shown and the label is adjusted.
+	 */
+	loading?: boolean
+
+	/**
+	 * Can the user pick multiple files.
+	 * This is ignored when picking folder (by browser limitations).
+	 */
+	multiple?: boolean
+
+	/**
+	 * The variant of the button
+	 */
+	variant?: 'primary' | 'secondary' | 'tertiary'
+}>(), {
+	accept: undefined,
+	actionCaption: '',
+	label: undefined,
+	variant: 'primary',
+})
+
+const emit = defineEmits<{
+	pick: [files: File[]]
+}>()
+
+defineSlots<{
+	/**
+	 * Custom NcAction* to be shown within the picker menu
+	 */
+	actions?: Slot
+
+	/**
+	 * Optional custom icon for the picker menu
+	 */
+	icon?: Slot
+
+	/**
+	 * Optional content to be shown in the picker.
+	 * This can be used e.g. for a progress bar or similar.
+	 */
+	default?: Slot
+}>()
+
+defineExpose({
+	reset,
+})
+
+const formElement = useTemplateRef('form')
+const inputElement = useTemplateRef('input')
+
+/**
+ * The current label to be used as menu name and accessible name of the picker.
+ */
+const currentLabel = computed(() => {
+	if (props.loading) {
+		return t('Uploading …')
+	} else if (props.label) {
+		return props.label
+	} else if (props.directoryOnly) {
+		return t('Pick folder')
+	}
+	return props.multiple ? t('Pick files') : t('Pick file')
+})
+
+/**
+ * Check whether the current browser supports uploading directories
+ * Hint: This does not check if the current connection supports this, as some browsers require a secure context!
+ */
+const canUploadFolders = computed(() => {
+	return (props.directory || props.directoryOnly) && 'webkitdirectory' in HTMLInputElement.prototype
+})
+
+/**
+ * Trigger file picker
+ *
+ * @param uploadFolders - Whether to upload folders or files
+ */
+function triggerPickFiles(uploadFolders: boolean) {
+	// Without reset selecting the same file doesn't trigger the change event
+	reset()
+
+	// Only if the browser supports picking folders and the user selected "pick folder" we set the file input to directory picking.
+	if (canUploadFolders.value) {
+		inputElement.value!.webkitdirectory = uploadFolders
+	}
+
+	// Wait for the reset and the `webkitdirectory` to be dispatched in DOM
+	nextTick(() => inputElement.value!.click())
+}
+
+/**
+ * Handle picking some local files
+ */
+function onPick() {
+	const files = inputElement.value?.files ? Array.from(inputElement.value.files) : []
+	emit('pick', files)
+}
+
+/**
+ * Reset the picker state of the currently selected files.
+ */
+function reset() {
+	formElement.value!.reset()
+}
+</script>
+
+<template>
+	<form
+		ref="form"
+		:class="$style.filePicker">
+		<NcActions
+			:aria-label="currentLabel"
+			:disabled="disabled || loading"
+			:menu-name="iconOnly ? undefined : currentLabel"
+			:force-name="!iconOnly"
+			:variant>
+			<template #icon>
+				<slot v-if="!loading" name="icon">
+					<IconPlus :size="20" />
+				</slot>
+				<NcLoadingIcon v-else />
+			</template>
+
+			<NcActionCaption v-if="actionCaption" :name="actionCaption" />
+
+			<NcActionButton
+				v-if="!directoryOnly"
+				close-after-click
+				@click="triggerPickFiles(false)">
+				<template #icon>
+					<IconUpload :size="20" />
+				</template>
+				<!-- If this is not the only action in the NcActions this is a menu entry and we need a generic name - otherwise this will be a single button where we need to apply the label -->
+				{{ canUploadFolders || $slots.actions ? (multiple ? t('Upload files') : t('Upload file')) : currentLabel }}
+			</NcActionButton>
+
+			<NcActionButton
+				v-if="canUploadFolders"
+				close-after-click
+				@click="triggerPickFiles(true)">
+				<template #icon>
+					<IconFolderUpload style="color: var(--color-primary-element)" :size="20" />
+				</template>
+				<!-- If this is not the only action in the NcActions this is a menu entry and we need a generic name - otherwise this will be a single button where we need to apply the label -->
+				{{ !directoryOnly || $slots.actions ? t('Upload folder') : currentLabel }}
+			</NcActionButton>
+
+			<!-- App defined upload actions -->
+			<slot name="actions" />
+		</NcActions>
+
+		<!-- Hidden files picker input - also hidden for accessibility as otherwise such users also loose the ability to pick files -->
+		<input
+			ref="input"
+			:accept="accept?.join(', ')"
+			aria-hidden="true"
+			class="hidden-visually"
+			:multiple
+			type="file"
+			@change="onPick">
+
+		<slot />
+	</form>
+</template>
+
+<style module>
+.filePicker {
+	display: inline-flex;
+	align-items: center;
+	height: var(--default-clickable-area);
+}
+</style>
+
+<docs>
+This component allows to pick local files (or directories) which can be used to upload them to Nextcloud or directly process them in the browser.
+
+### Exposed methods
+
+- `function reset(): void`
+  This method allows to reset the internal state of the file picker to clear the current selection
+
+### Example
+
+```vue
+<template>
+	<div>
+		<div class="wrapper">
+			<NcFilePicker ref="picker"
+				directory
+				@pick="selectedFiles = $event" />
+
+			<NcButton variant="tertiary"
+				@click="clearPicker">
+				Clear
+			</NcButton>
+		</div>
+
+		<h3>Selected files:</h3>
+		<ul>
+			<li v-for="file in selectedFiles" key="file.name">
+				{{ file.webkitRelativePath || file.name }}
+			</li>
+		</ul>
+	</div>
+</template>
+<script>
+	export default {
+		data() {
+			return {
+				selectedFiles: [],
+			}
+		},
+		methods: {
+			/**
+			 * This will clear the selected files from the picker.
+			 */
+			clearPicker() {
+				this.$refs.picker.reset()
+			},
+		},
+	}
+</script>
+<style scoped>
+.wrapper {
+	display: flex;
+	gap: 10px;
+}
+</style>
+```
+</docs>
diff --git a/src/components/NcFilePicker/index.ts b/src/components/NcFilePicker/index.ts
new file mode 100644
index 0000000000..499dbee535
--- /dev/null
+++ b/src/components/NcFilePicker/index.ts
@@ -0,0 +1,6 @@
+/**
+ * SPDX-FileCopyrightText: 2025 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+export { default } from './NcFilePicker.vue'
diff --git a/src/components/index.js b/src/components/index.js
index f70c97ec0f..ac73d7fc67 100644
--- a/src/components/index.js
+++ b/src/components/index.js
@@ -58,6 +58,7 @@ export { default as NcDialogButton } from './NcDialogButton/index.js'
 export { default as NcEllipsisedOption } from './NcEllipsisedOption/index.js'
 export { default as NcEmojiPicker } from './NcEmojiPicker/index.js'
 export { default as NcEmptyContent } from './NcEmptyContent/index.js'
+export { default as NcFilePicker } from './NcFilePicker/index.ts'
 export { default as NcFormBox } from './NcFormBox/index.ts'
 export { default as NcFormBoxButton } from './NcFormBoxButton/index.ts'
 export { default as NcFormBoxCopyButton } from './NcFormBoxCopyButton/index.ts'

From 8d1c31ae2ce13f56c4290e945a9a87a3c31a098b Mon Sep 17 00:00:00 2001
From: Ferdinand Thiessen <opensource@fthiessen.de>
Date: Wed, 21 Jan 2026 13:08:08 +0100
Subject: [PATCH 2/3] refactor: use `actions` prop instead of slot

Signed-off-by: Ferdinand Thiessen <opensource@fthiessen.de>
---
 src/components/NcFilePicker/NcFilePicker.vue | 65 ++++++++++++++++----
 src/components/NcFilePicker/index.ts         |  7 ++-
 2 files changed, 60 insertions(+), 12 deletions(-)

diff --git a/src/components/NcFilePicker/NcFilePicker.vue b/src/components/NcFilePicker/NcFilePicker.vue
index 666ac83141..3bf1a0dfef 100644
--- a/src/components/NcFilePicker/NcFilePicker.vue
+++ b/src/components/NcFilePicker/NcFilePicker.vue
@@ -13,9 +13,36 @@ import IconUpload from 'vue-material-design-icons/Upload.vue'
 import NcActionButton from '../NcActionButton/NcActionButton.vue'
 import NcActionCaption from '../NcActionCaption/NcActionCaption.vue'
 import NcActions from '../NcActions/NcActions.vue'
+import NcIconSvgWrapper from '../NcIconSvgWrapper/NcIconSvgWrapper.vue'
 import NcLoadingIcon from '../NcLoadingIcon/NcLoadingIcon.vue'
 import { t } from '../../l10n.js'
 
+export interface FilePickerItem {
+	/**
+	 * SVG icon (as string) for the action
+	 */
+	iconSvg: string
+	/**
+	 * Label of the action
+	 */
+	label: string
+	/**
+	 * Callback when the action is clicked
+	 */
+	onClick: () => void
+}
+
+export interface FilePickerItemGroup {
+	/**
+	 * Caption for the action group
+	 */
+	caption: string
+	/**
+	 * Actions within this group
+	 */
+	actions: FilePickerItem[]
+}
+
 const props = withDefaults(defineProps<{
 	/**
 	 * File types to accept
@@ -27,6 +54,11 @@ const props = withDefaults(defineProps<{
 	 */
 	actionCaption?: string
 
+	/**
+	 * Additional actions to be shown within the picker menu
+	 */
+	actions?: FilePickerItem[] | FilePickerItemGroup[]
+
 	/**
 	 * Allow picking a directory
 	 */
@@ -71,6 +103,7 @@ const props = withDefaults(defineProps<{
 	 */
 	variant?: 'primary' | 'secondary' | 'tertiary'
 }>(), {
+	actions: () => [],
 	accept: undefined,
 	actionCaption: '',
 	label: undefined,
@@ -82,11 +115,6 @@ const emit = defineEmits<{
 }>()
 
 defineSlots<{
-	/**
-	 * Custom NcAction* to be shown within the picker menu
-	 */
-	actions?: Slot
-
 	/**
 	 * Optional custom icon for the picker menu
 	 */
@@ -169,8 +197,8 @@ function reset() {
 		<NcActions
 			:aria-label="currentLabel"
 			:disabled="disabled || loading"
-			:menu-name="iconOnly ? undefined : currentLabel"
-			:force-name="!iconOnly"
+			:menuName="iconOnly ? undefined : currentLabel"
+			:forceName="!iconOnly"
 			:variant>
 			<template #icon>
 				<slot v-if="!loading" name="icon">
@@ -183,7 +211,7 @@ function reset() {
 
 			<NcActionButton
 				v-if="!directoryOnly"
-				close-after-click
+				closeAfterClick
 				@click="triggerPickFiles(false)">
 				<template #icon>
 					<IconUpload :size="20" />
@@ -194,7 +222,7 @@ function reset() {
 
 			<NcActionButton
 				v-if="canUploadFolders"
-				close-after-click
+				closeAfterClick
 				@click="triggerPickFiles(true)">
 				<template #icon>
 					<IconFolderUpload style="color: var(--color-primary-element)" :size="20" />
@@ -203,8 +231,23 @@ function reset() {
 				{{ !directoryOnly || $slots.actions ? t('Upload folder') : currentLabel }}
 			</NcActionButton>
 
-			<!-- App defined upload actions -->
-			<slot name="actions" />
+			<template v-for="group of actions">
+				<NcActionCaption
+					v-if="(group as FilePickerItemGroup).caption"
+					:key="(group as FilePickerItemGroup).caption"
+					:name="(group as FilePickerItemGroup).caption" />
+
+				<NcActionButton
+					v-for="action of (group as FilePickerItemGroup).actions ?? [group as FilePickerItem]"
+					:key="action.label"
+					closeAfterClick
+					@click="action.onClick">
+					<template #icon>
+						<NcIconSvgWrapper :svg="action.iconSvg" />
+					</template>
+					{{ action.label }}
+				</NcActionButton>
+			</template>
 		</NcActions>
 
 		<!-- Hidden files picker input - also hidden for accessibility as otherwise such users also loose the ability to pick files -->
diff --git a/src/components/NcFilePicker/index.ts b/src/components/NcFilePicker/index.ts
index 499dbee535..378c1ea178 100644
--- a/src/components/NcFilePicker/index.ts
+++ b/src/components/NcFilePicker/index.ts
@@ -1,6 +1,11 @@
-/**
+/*!
  * SPDX-FileCopyrightText: 2025 Nextcloud GmbH and Nextcloud contributors
  * SPDX-License-Identifier: AGPL-3.0-or-later
  */
 
+export type {
+	FilePickerItem,
+	FilePickerItemGroup,
+} from './NcFilePicker.vue'
+
 export { default } from './NcFilePicker.vue'

From ddff6fdfdaae0457a2e4b660b39d7b16de1c4363 Mon Sep 17 00:00:00 2001
From: Ferdinand Thiessen <opensource@fthiessen.de>
Date: Tue, 10 Feb 2026 13:27:28 +0100
Subject: [PATCH 3/3] chore: adjust for Vue 2

Signed-off-by: Ferdinand Thiessen <opensource@fthiessen.de>
---
 src/components/NcFilePicker/NcFilePicker.vue | 57 ++++++++------------
 1 file changed, 22 insertions(+), 35 deletions(-)

diff --git a/src/components/NcFilePicker/NcFilePicker.vue b/src/components/NcFilePicker/NcFilePicker.vue
index 3bf1a0dfef..16224027b4 100644
--- a/src/components/NcFilePicker/NcFilePicker.vue
+++ b/src/components/NcFilePicker/NcFilePicker.vue
@@ -4,9 +4,7 @@
 -->
 
 <script setup lang="ts">
-import type { Slot } from 'vue'
-
-import { computed, nextTick, useTemplateRef } from 'vue'
+import { computed, nextTick, ref } from 'vue'
 import IconFolderUpload from 'vue-material-design-icons/FolderUpload.vue'
 import IconPlus from 'vue-material-design-icons/Plus.vue'
 import IconUpload from 'vue-material-design-icons/Upload.vue'
@@ -111,28 +109,15 @@ const props = withDefaults(defineProps<{
 })
 
 const emit = defineEmits<{
-	pick: [files: File[]]
-}>()
-
-defineSlots<{
-	/**
-	 * Optional custom icon for the picker menu
-	 */
-	icon?: Slot
-
-	/**
-	 * Optional content to be shown in the picker.
-	 * This can be used e.g. for a progress bar or similar.
-	 */
-	default?: Slot
+	(event: 'pick', files: File[]): void
 }>()
 
 defineExpose({
 	reset,
 })
 
-const formElement = useTemplateRef('form')
-const inputElement = useTemplateRef('input')
+const formElement = ref<HTMLFormElement | null>(null)
+const inputElement = ref<HTMLInputElement | null>(null)
 
 /**
  * The current label to be used as menu name and accessible name of the picker.
@@ -192,15 +177,16 @@ function reset() {
 
 <template>
 	<form
-		ref="form"
+		ref="formElement"
 		:class="$style.filePicker">
 		<NcActions
 			:aria-label="currentLabel"
 			:disabled="disabled || loading"
-			:menuName="iconOnly ? undefined : currentLabel"
-			:forceName="!iconOnly"
-			:variant>
+			:menu-name="iconOnly ? undefined : currentLabel"
+			:force-name="!iconOnly"
+			:variant="variant">
 			<template #icon>
+				<!-- @slot Optional custom icon for the picker menu -->
 				<slot v-if="!loading" name="icon">
 					<IconPlus :size="20" />
 				</slot>
@@ -211,36 +197,36 @@ function reset() {
 
 			<NcActionButton
 				v-if="!directoryOnly"
-				closeAfterClick
+				close-after-click
 				@click="triggerPickFiles(false)">
 				<template #icon>
 					<IconUpload :size="20" />
 				</template>
+				{{ (canUploadFolders || !!$slots.actions) ? (multiple ? t('Upload files') : t('Upload file')) : currentLabel }}
 				<!-- If this is not the only action in the NcActions this is a menu entry and we need a generic name - otherwise this will be a single button where we need to apply the label -->
-				{{ canUploadFolders || $slots.actions ? (multiple ? t('Upload files') : t('Upload file')) : currentLabel }}
 			</NcActionButton>
 
 			<NcActionButton
 				v-if="canUploadFolders"
-				closeAfterClick
+				close-after-click
 				@click="triggerPickFiles(true)">
 				<template #icon>
 					<IconFolderUpload style="color: var(--color-primary-element)" :size="20" />
 				</template>
+				{{ (!directoryOnly || !!$slots.actions) ? t('Upload folder') : currentLabel }}
 				<!-- If this is not the only action in the NcActions this is a menu entry and we need a generic name - otherwise this will be a single button where we need to apply the label -->
-				{{ !directoryOnly || $slots.actions ? t('Upload folder') : currentLabel }}
 			</NcActionButton>
 
 			<template v-for="group of actions">
 				<NcActionCaption
-					v-if="(group as FilePickerItemGroup).caption"
-					:key="(group as FilePickerItemGroup).caption"
-					:name="(group as FilePickerItemGroup).caption" />
+					v-if="group.caption"
+					:key="group.caption"
+					:name="group.caption" />
 
 				<NcActionButton
-					v-for="action of (group as FilePickerItemGroup).actions ?? [group as FilePickerItem]"
+					v-for="action of group.actions ?? [group]"
 					:key="action.label"
-					closeAfterClick
+					close-after-click
 					@click="action.onClick">
 					<template #icon>
 						<NcIconSvgWrapper :svg="action.iconSvg" />
@@ -252,14 +238,15 @@ function reset() {
 
 		<!-- Hidden files picker input - also hidden for accessibility as otherwise such users also loose the ability to pick files -->
 		<input
-			ref="input"
+			ref="inputElement"
 			:accept="accept?.join(', ')"
 			aria-hidden="true"
 			class="hidden-visually"
-			:multiple
+			:multiple="multiple"
 			type="file"
 			@change="onPick">
 
+		<!-- @slot Optional content to be shown in the picker. This can be used e.g. for a progress bar or similar. -->
 		<slot />
 	</form>
 </template>
@@ -298,7 +285,7 @@ This component allows to pick local files (or directories) which can be used to
 
 		<h3>Selected files:</h3>
 		<ul>
-			<li v-for="file in selectedFiles" key="file.name">
+			<li v-for="file in selectedFiles" :key="file.name">
 				{{ file.webkitRelativePath || file.name }}
 			</li>
 		</ul>