restore library sidebar state on startup

persist and restore both selected item and scroll position across
sessions for seamless startup experience.

selection restoration:
- stores feature iconname (non-translated) and child data
- uses QAbstractItemModel::match for robust child lookup
- handles playlists, crates, and feature roots
- config keys: [Library] LastSelectedFeature, LastSelectedChild

scroll restoration:
- saves scroll position on every change
- restores after tree expansion completes
- config key: [Library] SidebarScrollPosition

prevents jarring position changes on startup while maintaining
natural sidebar behavior during runtime

Author: Milkii Brewster

src/library/library.cpp

@@ -79,6 +79,9 @@ Library::Library(
           m_pAnalysisFeature(nullptr) {
     qRegisterMetaType<LibraryRemovalType>("LibraryRemovalType");
 
+    // provide config to sidebar model for selection persistence
+    m_pSidebarModel->setConfig(m_pConfig);
+
     m_pKeyNotation.reset(
             new ControlObject(mixxx::library::prefs::kKeyNotationConfigKey));
 
@@ -349,6 +352,7 @@ void Library::bindSidebarWidget(WLibrarySidebar* pSidebarWidget) {
 
     // Setup the sources view
     pSidebarWidget->setModel(m_pSidebarModel);
+    pSidebarWidget->setup(m_pConfig);
     connect(m_pSidebarModel,
             &SidebarModel::selectIndex,
             pSidebarWidget,

src/library/sidebarmodel.cpp

@@ -2,6 +2,7 @@
 
 #include <QTimer>
 #include <QUrl>
+#include <functional>
 
 #include "library/libraryfeature.h"
 #include "library/treeitem.h"
@@ -94,9 +95,20 @@ void SidebarModel::setDefaultSelection(unsigned int index) {
 }
 
 void SidebarModel::activateDefaultSelection() {
+    // try to restore previously selected item
+    QModelIndex savedIndex = restoreSavedSelection();
+    if (savedIndex.isValid()) {
+        // disable auto-scrolling - sidebar will restore saved scroll position
+        emit selectIndex(savedIndex, false /* scrollTo */);
+        // reuse clicked() method to activate the restored selection
+        clicked(savedIndex);
+        return;
+    }
+
+    // fallback to default selection if restoration failed
     if (m_iDefaultSelectedIndex <
             static_cast<unsigned int>(m_sFeatures.size())) {
-        emit selectIndex(getDefaultSelection(), true /* scrollTo */);
+        emit selectIndex(getDefaultSelection(), false /* scrollTo */);
         // Selecting an index does not activate it.
         m_sFeatures[m_iDefaultSelectedIndex]->activate();
     }
@@ -354,6 +366,9 @@ void SidebarModel::clicked(const QModelIndex& index) {
     // this event.
     stopPressedUntilClickedTimer();
     if (index.isValid()) {
+        // save the selection for restoration on restart
+        saveCurrentSelection(index);
+
         if (index.internalPointer() == this) {
             m_sFeatures[index.row()]->activate();
         } else {
@@ -520,7 +535,16 @@ QModelIndex SidebarModel::translateIndex(
 void SidebarModel::slotDataChanged(const QModelIndex& topLeft, const QModelIndex& bottomRight) {
     // qDebug() << "slotDataChanged topLeft:" << topLeft << "bottomRight:" << bottomRight;
     QModelIndex topLeftTranslated = translateSourceIndex(topLeft);
-    QModelIndex bottomRightTranslated = translateSourceIndex(bottomRight);
+    QModelIndex bottomRightTranslated;
+
+    // if bottomRight is invalid in the source, keep it invalid in the translation
+    if (bottomRight.isValid()) {
+        bottomRightTranslated = translateSourceIndex(bottomRight);
+    } else {
+        // per Qt convention, invalid bottomRight means same as topLeft
+        bottomRightTranslated = topLeftTranslated;
+    }
+
     emit dataChanged(topLeftTranslated, bottomRightTranslated);
 }
 
@@ -610,3 +634,131 @@ void SidebarModel::slotFeatureSelect(LibraryFeature* pFeature,
     }
     emit selectIndex(ind, scrollTo);
 }
+
+void SidebarModel::saveCurrentSelection(const QModelIndex& index) {
+    if (!m_pConfig || !index.isValid()) {
+        return;
+    }
+
+    QString featureName;
+    QString childName;
+
+    if (index.internalPointer() == this) {
+        // root feature selected
+        if (index.row() >= 0 && index.row() < m_sFeatures.size()) {
+            featureName = m_sFeatures[index.row()]->iconName();
+        }
+    } else {
+        // child item selected
+        TreeItem* pTreeItem = static_cast<TreeItem*>(index.internalPointer());
+        if (pTreeItem) {
+            LibraryFeature* pFeature = pTreeItem->feature();
+            if (pFeature) {
+                featureName = pFeature->iconName();
+                childName = pTreeItem->getData().toString();
+            }
+        }
+    }
+
+    if (!featureName.isEmpty()) {
+        m_pConfig->setValue(
+                ConfigKey(QStringLiteral("[Library]"), QStringLiteral("LastSelectedFeature")),
+                featureName);
+        m_pConfig->setValue(
+                ConfigKey(QStringLiteral("[Library]"), QStringLiteral("LastSelectedChild")),
+                childName);
+    }
+}
+
+QModelIndex SidebarModel::restoreSavedSelection() {
+    if (!m_pConfig || m_sFeatures.isEmpty()) {
+        return QModelIndex();
+    }
+
+    const QString savedFeatureName = m_pConfig->getValueString(
+            ConfigKey(QStringLiteral("[Library]"), QStringLiteral("LastSelectedFeature")));
+
+    if (savedFeatureName.isEmpty()) {
+        return QModelIndex();
+    }
+
+    int featureRow = -1;
+    // find the feature by icon name (non-translated, programmatic identifier)
+    for (int i = 0; i < m_sFeatures.size(); ++i) {
+        if (m_sFeatures[i]->iconName() == savedFeatureName) {
+            featureRow = i;
+            break;
+        }
+    }
+
+    const QString savedChildName = m_pConfig->getValueString(
+            ConfigKey(QStringLiteral("[Library]"), QStringLiteral("LastSelectedChild")));
+    // if no child data, return the feature root.
+    // returns invalid index if feature was not found.
+    if (savedChildName.isEmpty()) {
+        return index(featureRow, 0);
+    }
+
+    // feature not found, can't search for child
+    if (featureRow < 0) {
+        return {};
+    }
+
+    // search for matching child by data using QAbstractItemModel::match()
+    QAbstractItemModel* pChildModel = m_sFeatures[featureRow]->sidebarModel();
+    if (pChildModel && pChildModel->rowCount() > 0) {
+        // the model items' data type may be int (playlist, crate) or
+        // QString (Missing, Quick Links).
+        // get the model's data type, then create the appropriate QVariant.
+        // note: assumes the model uses only one data type!
+        const QVariant dataVar = pChildModel->data(
+                pChildModel->index(0, 0), TreeItemModel::kDataRole);
+        auto dataType = dataVar.metaType();
+        QVariant childData;
+        switch (dataType.id()) {
+        case QMetaType::QString: {
+            childData = QVariant::fromValue(savedChildName);
+            break;
+        }
+        case QMetaType::Int: {
+            bool convertedToInt = false;
+            int intValue = savedChildName.toInt(&convertedToInt);
+            if (convertedToInt) {
+                childData = QVariant::fromValue(intValue);
+            } else {
+                qWarning() << "SidebarModel::restoreSavedSelection: could not "
+                              "convert stored child data to int";
+            }
+            break;
+        }
+        default:
+            qWarning() << "SidebarModel::restoreSavedSelection: "
+                          "model uses unexpected data type"
+                       << dataType.name();
+            qWarning() << "select feature root";
+        }
+
+        if (!childData.isValid()) {
+            return {};
+        }
+
+        const QModelIndexList matches = pChildModel->match(
+                pChildModel->index(0, 0),
+                TreeItemModel::kDataRole,
+                childData,
+                1, // stop at first match
+                Qt::MatchExactly | Qt::MatchRecursive);
+
+        if (!matches.isEmpty() && matches.first().isValid()) {
+            // translate child model index to sidebar model index
+            const QModelIndex childIndex = matches.first();
+            TreeItem* pTreeItem = static_cast<TreeItem*>(childIndex.internalPointer());
+            if (pTreeItem) {
+                return createIndex(childIndex.row(), childIndex.column(), pTreeItem);
+            }
+        }
+    }
+
+    // child not found, return feature root or invalid index if feature was not found.
+    return index(featureRow, 0);
+}

src/library/sidebarmodel.h

@@ -3,8 +3,11 @@
 #include <QAbstractItemModel>
 #include <QList>
 #include <QModelIndex>
+#include <QString>
 #include <QVariant>
 
+#include "preferences/usersettings.h"
+
 class LibraryFeature;
 class QTimer;
 
@@ -25,6 +28,10 @@ class SidebarModel : public QAbstractItemModel {
             QObject* parent = nullptr);
     ~SidebarModel() override = default;
 
+    void setConfig(UserSettingsPointer pConfig) {
+        m_pConfig = pConfig;
+    }
+
     void addLibraryFeature(LibraryFeature* feature);
     QModelIndex getDefaultSelection();
     void setDefaultSelection(unsigned int index);
@@ -93,10 +100,14 @@ class SidebarModel : public QAbstractItemModel {
     QModelIndex translateSourceIndex(const QModelIndex& parent);
     QModelIndex translateIndex(const QModelIndex& index, const QAbstractItemModel* model);
     void featureRenamed(LibraryFeature*);
+    void saveCurrentSelection(const QModelIndex& index);
+    QModelIndex restoreSavedSelection();
+
     unsigned int m_iDefaultSelectedIndex; /** Index of the item in the sidebar model to select at startup. */
 
     QTimer* const m_pressedUntilClickedTimer;
     QModelIndex m_pressedIndex;
+    UserSettingsPointer m_pConfig;
 
     void startPressedUntilClickedTimer(const QModelIndex& pressedIndex);
     void stopPressedUntilClickedTimer();

src/library/treeitemmodel.cpp

@@ -214,6 +214,11 @@ void TreeItemModel::triggerRepaint(const QModelIndex& index) {
 }
 
 void TreeItemModel::triggerRepaint() {
+    // don't emit dataChanged if the model is empty
+    if (rowCount() == 0) {
+        return;
+    }
+
     QModelIndex left = index(0, 0);
     QModelIndex right = index(rowCount() - 1, columnCount() - 1);
     emit dataChanged(left, right);