feat(macOS): Improved file provider switch user experience

Signed-off-by: Iva Horn <iva.horn@nextcloud.com>

Author: i2h3

doc/test-cases/regression/macos-file-provider/TC-0007-file-provider-mode-switching.md

@@ -0,0 +1,38 @@
+<!--
+  - SPDX-FileCopyrightText: 2026 Nextcloud GmbH and Nextcloud contributors
+  - SPDX-License-Identifier: GPL-2.0-or-later
+-->
+
+# TC-0007: Switching the app-level File Provider mode
+
+- **Platform:** macOS
+- **Related Issues:** None yet
+
+## Description
+
+The File Provider integration and classic sync folders (FinderSync extension) cannot run at the same time on macOS: as soon as any file provider domain exists, the system deactivates the FinderSync extension. The client therefore offers one app-level File Provider switch in the General settings. Enabling it discards all classic sync folder connections (local files are kept); disabling it removes all file provider domains without recreating classic folders. Both directions require explicit confirmation.
+
+## Preconditions
+
+- A client build with the file provider module (`Nextcloud-vfs-…`) on macOS 14 or later.
+- At least one configured account with one or more classic sync folders containing synced files.
+
+## Test Steps
+
+| Step | Action | Expected Result |
+|------|--------|-----------------|
+| 1 | Open Settings → General | A "Use macOS File Provider Integration" switch is shown with an explanatory text; it is off |
+| 2 | Open the account's settings page | The "Classic sync" panel with the folder list is shown; no File Provider panel exists |
+| 3 | Turn the File Provider switch on | A confirmation dialog appears, listing the affected accounts and their classic sync folder connections, stating that files stay on disk |
+| 4 | Click "Cancel" | Nothing changes: switch stays off, classic folders keep syncing |
+| 5 | Turn the switch on again and click "Enable File Provider" | The switch is disabled while setting up; afterwards every account appears in Finder under "Locations", all classic sync folder connections are removed, the local folders and their files remain on disk, FinderSync badges disappear, and the "Classic sync" panel is hidden in every account's settings |
+| 6 | Turn the switch off | A confirmation dialog explains that files leave Finder "Locations", unsynced items are preserved, and classic sync folders are not recreated automatically |
+| 7 | Click "Disable File Provider" | All file provider domains are removed; no classic folders are created; the "Classic sync" panel (with the "Add Folder Sync Connection" button) reappears in the account settings |
+| 8 | Add a new folder sync connection and restart the client | The classic folder syncs again and FinderSync badges work |
+
+## Expected Results
+
+- Classic sync folders and File Provider are never active at the same time.
+- No local files are deleted by either switch direction.
+- A deployment updating with both configured (or a client killed mid-switch) shows a "Choose how to sync your files" dialog at startup offering "Keep File Provider", "Keep classic sync folders" and "Decide later"; "Decide later" keeps both working, shows a warning banner in the affected account settings, and asks again on the next launch.
+- New accounts added while the mode is on automatically get a file provider domain; the account wizard skips the sync options step. With the mode off, the wizard offers classic folder setup only.

resources.qrc

@@ -80,7 +80,6 @@
         <file>src/gui/wizard/qml/WizardComboBox.qml</file>
         <file>src/gui/wizard/qml/WizardDialogFrame.qml</file>
         <file>src/gui/wizard/qml/WizardTextField.qml</file>
-        <file>src/gui/macOS/ui/FileProviderSettings.qml</file>
         <file>src/gui/macOS/ui/FileProviderFileDelegate.qml</file>
         <file>src/gui/integration/FileActionsWindow.qml</file>
         <file>src/gui/GovernanceLabelsDialog.qml</file>

src/gui/accountsettings.cpp

@@ -196,16 +196,14 @@ AccountSettings::AccountSettings(AccountState *accountState, QWidget *parent)
     connect(connectionSettingsButton, &QPushButton::clicked, this, &AccountSettings::showConnectionSettingsDialog);
 
     _ui->verticalLayout_2->removeWidget(_ui->accountStatusPanel);
-    _ui->verticalLayout_2->removeWidget(_ui->fileProviderPanel);
     _ui->verticalLayout_2->removeWidget(_ui->syncFoldersPanel);
     _ui->verticalLayout_2->removeWidget(_ui->connectionSettingsPanel);
     _ui->verticalLayout_2->removeWidget(_ui->accountActionsPanel);
     _ui->connectionSettingsPanel->hide();
-    _ui->verticalLayout_2->insertWidget(0, _ui->fileProviderPanel);
-    _ui->verticalLayout_2->insertWidget(1, _ui->syncFoldersPanel);
-    _ui->verticalLayout_2->insertWidget(2, _encryptionPanel);
-    _ui->verticalLayout_2->insertWidget(3, _ui->accountStatusPanel);
-    _ui->verticalLayout_2->insertWidget(4, _ui->accountActionsPanel);
+    _ui->verticalLayout_2->insertWidget(0, _ui->syncFoldersPanel);
+    _ui->verticalLayout_2->insertWidget(1, _encryptionPanel);
+    _ui->verticalLayout_2->insertWidget(2, _ui->accountStatusPanel);
+    _ui->verticalLayout_2->insertWidget(3, _ui->accountActionsPanel);
 
     _model->setAccountState(_accountState);
     _model->setParent(this);
@@ -215,9 +213,6 @@ AccountSettings::AccountSettings(AccountState *accountState, QWidget *parent)
     _ui->syncFoldersPanelContents->setAutoFillBackground(false);
     _ui->syncFoldersPanelContents->setAttribute(Qt::WA_StyledBackground, false);
     _ui->syncFoldersPanelContents->setContentsMargins(0, 0, 0, 0);
-    _ui->fileProviderPanelContents->setAutoFillBackground(false);
-    _ui->fileProviderPanelContents->setAttribute(Qt::WA_StyledBackground, false);
-    _ui->fileProviderPanelContents->setContentsMargins(0, 0, 0, 0);
     _ui->connectionSettingsPanelContents->setAutoFillBackground(false);
     _ui->connectionSettingsPanelContents->setAttribute(Qt::WA_StyledBackground, false);
     _ui->connectionSettingsPanelContents->setContentsMargins(0, 0, 0, 0);
@@ -244,30 +239,20 @@ AccountSettings::AccountSettings(AccountState *accountState, QWidget *parent)
     new ToolTipUpdater(_ui->_folderList);
 
 #if defined(BUILD_FILE_PROVIDER_MODULE)
-    if (Mac::FileProvider::available()) {
-        const auto fileProviderPanelContents = _ui->fileProviderPanelContents;
-        const auto fpSettingsLayout = new QVBoxLayout(fileProviderPanelContents);
-        const auto fpAccountUserIdAtHost = _accountState->account()->userIdAtHostWithPort();
-        const auto fpSettingsController = Mac::FileProviderSettingsController::instance();
-        const auto fpSettingsWidget = fpSettingsController->settingsViewWidget(fpAccountUserIdAtHost, fileProviderPanelContents,
-                                                                               QQuickWidget::SizeRootObjectToView);
-        fpSettingsLayout->setContentsMargins(0, 0, 0, 0);
-        fpSettingsLayout->setSpacing(0);
-
-        fpSettingsWidget->setSizePolicy(QSizePolicy::Expanding, QSizePolicy::Expanding);
-        if (const auto fpSettingsWidgetLayout = fpSettingsWidget->layout()) {
-            fpSettingsWidgetLayout->setContentsMargins(0, 0, 0, 0);
-        }
-        fpSettingsLayout->addWidget(fpSettingsWidget, 1);
-        fileProviderPanelContents->setLayout(fpSettingsLayout);
-    } else {
-        // macOS 13 Ventura: the file provider feature is unsupported there.
-        // This branch can be removed once Ventura is no longer supported.
-        _ui->fileProviderPanel->setVisible(false);
-    }
-#else
-    _ui->fileProviderPanel->setVisible(false);
+    // The File Provider integration is an app-level mode, toggled in the General
+    // settings. While it is enabled, classic sync folders are unavailable: hide the
+    // "Classic sync" panel, except when the account still has classic folders
+    // configured (a conflict the banner asks the user to resolve).
+    const auto fpSettingsController = Mac::FileProviderSettingsController::instance();
+    connect(fpSettingsController, &Mac::FileProviderSettingsController::fileProviderModeEnabledChanged,
+            this, &AccountSettings::updateSyncFoldersPanelVisibility);
+    connect(FolderMan::instance(), &FolderMan::folderListChanged,
+            this, &AccountSettings::updateSyncFoldersPanelVisibility);
+    connect(_ui->fileProviderConflictResolveButton, &QPushButton::clicked, this, [fpSettingsController] {
+        fpSettingsController->performStartupReconciliation();
+    });
 #endif
+    updateSyncFoldersPanelVisibility();
 
     const auto mouseCursorChanger = new MouseCursorChanger(this);
     mouseCursorChanger->folderList = _ui->_folderList;
@@ -940,6 +925,13 @@ void AccountSettings::slotFolderWizardAccepted()
             QStringList() << QLatin1String("/"));
         folderMan->scheduleAllFolders();
         emit folderChanged();
+    } else {
+        // addFolder can refuse (e.g. classic sync folders are unavailable while the
+        // File Provider integration is enabled). Don't leave the user believing the
+        // wizard succeeded.
+        QMessageBox::warning(this, tr("Folder creation failed"),
+            tr("<p>Could not add the folder sync connection for <i>%1</i>.</p>")
+                .arg(Utility::escape(QDir::toNativeSeparators(definition.localPath))));
     }
 }
 
@@ -1957,6 +1949,39 @@ void AccountSettings::setEncryptionPanelVisible(bool visible)
     }
 }
 
+void AccountSettings::updateSyncFoldersPanelVisibility()
+{
+#if defined(BUILD_FILE_PROVIDER_MODULE)
+    const auto fpModeOn = Mac::FileProvider::available()
+        && Mac::FileProviderSettingsController::instance()->fileProviderModeEnabled();
+
+    auto hasClassicFolders = false;
+    const auto folderMap = FolderMan::instance()->map();
+
+    for (const auto folder : folderMap) {
+        if (folder->accountState() == _accountState) {
+            hasClassicFolders = true;
+            break;
+        }
+    }
+
+    // Hide the classic sync settings while File Provider mode is on — except when this
+    // account still has classic folders configured (mixed state): those must stay
+    // visible, together with the banner asking the user to resolve the conflict.
+    _ui->syncFoldersPanel->setVisible(!fpModeOn || hasClassicFolders);
+    _ui->fileProviderConflictBanner->setVisible(fpModeOn && hasClassicFolders);
+
+    if (fpModeOn && hasClassicFolders && _ui->fileProviderConflictBannerIcon->pixmap().isNull()) {
+        const auto iconSize = style()->pixelMetric(QStyle::PM_SmallIconSize, nullptr, this);
+        const auto warningIcon = Theme::createColorAwareIcon(QStringLiteral(":/client/theme/black/warning.svg"));
+        _ui->fileProviderConflictBannerIcon->setPixmap(warningIcon.pixmap(iconSize, iconSize));
+    }
+#else
+    _ui->syncFoldersPanel->setVisible(true);
+    _ui->fileProviderConflictBanner->setVisible(false);
+#endif
+}
+
 void AccountSettings::setEncryptionMessageIcon(const QIcon &icon)
 {
     if (icon.isNull()) {

src/gui/accountsettings.h

@@ -141,6 +141,7 @@ private slots:
     void checkClientSideEncryptionState();
     void removeActionFromEncryptionMessage(const QString &actionId);
     void setEncryptionPanelVisible(bool visible);
+    void updateSyncFoldersPanelVisibility();
 
 private:
     bool event(QEvent *) override;

src/gui/accountsettings.ui

@@ -133,46 +133,6 @@
      </layout>
     </widget>
    </item>
-   <item>
-    <widget class="QFrame" name="fileProviderPanel">
-     <property name="sizePolicy">
-      <sizepolicy hsizetype="Preferred" vsizetype="Minimum">
-       <horstretch>0</horstretch>
-       <verstretch>0</verstretch>
-      </sizepolicy>
-     </property>
-     <property name="frameShape">
-      <enum>QFrame::Shape::NoFrame</enum>
-     </property>
-     <layout class="QVBoxLayout" name="fileProviderPanelLayout">
-      <property name="sizeConstraint">
-       <enum>QLayout::SizeConstraint::SetDefaultConstraint</enum>
-      </property>
-      <item>
-       <widget class="QLabel" name="fileProviderPanelTitle">
-        <property name="font">
-         <font>
-          <bold>true</bold>
-         </font>
-        </property>
-        <property name="text">
-         <string>File Provider</string>
-        </property>
-       </widget>
-      </item>
-      <item>
-       <widget class="QWidget" name="fileProviderPanelContents" native="true">
-        <property name="sizePolicy">
-         <sizepolicy hsizetype="Preferred" vsizetype="Preferred">
-          <horstretch>0</horstretch>
-          <verstretch>0</verstretch>
-         </sizepolicy>
-        </property>
-       </widget>
-      </item>
-     </layout>
-    </widget>
-   </item>
    <item>
     <widget class="QFrame" name="syncFoldersPanel">
      <property name="sizePolicy">
@@ -206,6 +166,60 @@
         </property>
        </widget>
       </item>
+      <item>
+       <widget class="QWidget" name="fileProviderConflictBanner" native="true">
+        <property name="visible">
+         <bool>false</bool>
+        </property>
+        <layout class="QHBoxLayout" name="fileProviderConflictBannerLayout">
+         <item>
+          <widget class="QLabel" name="fileProviderConflictBannerIcon">
+           <property name="sizePolicy">
+            <sizepolicy hsizetype="Fixed" vsizetype="Fixed">
+             <horstretch>0</horstretch>
+             <verstretch>0</verstretch>
+            </sizepolicy>
+           </property>
+           <property name="text">
+            <string/>
+           </property>
+           <property name="alignment">
+            <set>Qt::AlignmentFlag::AlignHCenter|Qt::AlignmentFlag::AlignTop</set>
+           </property>
+          </widget>
+         </item>
+         <item>
+          <widget class="QLabel" name="fileProviderConflictBannerLabel">
+           <property name="sizePolicy">
+            <sizepolicy hsizetype="MinimumExpanding" vsizetype="Preferred">
+             <horstretch>0</horstretch>
+             <verstretch>0</verstretch>
+            </sizepolicy>
+           </property>
+           <property name="text">
+            <string>File Provider is enabled, but this account still has classic sync folders. The Finder integration stays unavailable until this is resolved.</string>
+           </property>
+           <property name="wordWrap">
+            <bool>true</bool>
+           </property>
+          </widget>
+         </item>
+         <item>
+          <widget class="QPushButton" name="fileProviderConflictResolveButton">
+           <property name="sizePolicy">
+            <sizepolicy hsizetype="Maximum" vsizetype="Fixed">
+             <horstretch>0</horstretch>
+             <verstretch>0</verstretch>
+            </sizepolicy>
+           </property>
+           <property name="text">
+            <string>Resolve…</string>
+           </property>
+          </widget>
+         </item>
+        </layout>
+       </widget>
+      </item>
       <item>
        <widget class="QWidget" name="syncFoldersPanelContents" native="true">
         <property name="sizePolicy">

src/gui/application.cpp

@@ -515,14 +515,22 @@ Application::Application(int &argc, char **argv)
 
 #if defined(BUILD_FILE_PROVIDER_MODULE)
     Mac::FileProvider::instance();
+
+    // Instantiating the settings controller runs its startup migrations: initialising
+    // the app-level File Provider mode flag, and — on macOS 13 Ventura, where the file
+    // provider feature is unsupported — gracefully tearing down any pre-existing VFS
+    // domains.
+    Mac::FileProviderSettingsController::instance();
+
     if (Mac::FileProvider::available()) {
         Mac::FileProvider::instance()->configureXPC();
-    } else {
-        // macOS 13 Ventura: instantiating the settings controller triggers the
-        // one-time cleanup that gracefully tears down any pre-existing VFS
-        // domains. The check (and this branch) can be removed once Ventura is
-        // no longer supported.
-        Mac::FileProviderSettingsController::instance();
+
+        // Deferred so that the event loop is running: reconciles the file provider
+        // domains with the app-level mode and, if both File Provider mode and classic
+        // sync folders are configured, asks the user which one to keep.
+        QTimer::singleShot(0, this, [] {
+            Mac::FileProviderSettingsController::instance()->performStartupReconciliation();
+        });
     }
 #endif
 

src/gui/folderman.cpp

@@ -1392,6 +1392,15 @@ void FolderMan::slotFolderSyncFinished(const SyncResult &)
 
 Folder *FolderMan::addFolder(AccountState *accountState, const FolderDefinition &folderDefinition)
 {
+#ifdef BUILD_FILE_PROVIDER_MODULE
+    // Classic sync folders and the File Provider integration are mutually exclusive:
+    // the FinderSync extension cannot run while the File Provider extension is active.
+    if (ConfigFile().macFileProviderModeEnabled()) {
+        qCWarning(lcFolderMan) << "Refusing to add classic sync folder: File Provider mode is enabled.";
+        return nullptr;
+    }
+#endif
+
     // Choose a db filename
     auto definition = folderDefinition;
     definition.journalPath = definition.defaultJournalPath(accountState->account());