qtreetotablemodel.cpp

// SPDX-License-Identifier: MIT
// Copyright (c) 2026, Meld Studio, Inc.

#include "qtreetotablemodel.h"

#include <QtCore/QLoggingCategory>

using namespace Qt::Literals::StringLiterals;

Q_LOGGING_CATEGORY(lcTreeToTable, "QTreeToTableModel")

// =============================================================================
// Construction / Destruction
// =============================================================================

QTreeToTableModel::QTreeToTableModel(QObject *parent)
    : QAbstractTableModel(parent)
{
    // Keep the count property in sync with any row changes. These connections
    // fire after the model signals complete, ensuring m_items is up-to-date.
    connect(this, &QAbstractItemModel::rowsInserted, this, &QTreeToTableModel::updateCount);
    connect(this, &QAbstractItemModel::rowsRemoved, this, &QTreeToTableModel::updateCount);
    connect(this, &QAbstractItemModel::modelReset, this, &QTreeToTableModel::updateCount);
    connect(this, &QAbstractItemModel::layoutChanged, this, &QTreeToTableModel::updateCount);
}

QTreeToTableModel::~QTreeToTableModel()
{
    disconnectFromSourceModel();
}

// =============================================================================
// Source Model
// =============================================================================

QAbstractItemModel *QTreeToTableModel::sourceModel() const
{
    return m_sourceModel.data();
}

void QTreeToTableModel::setSourceModel(QAbstractItemModel *model)
{
    if (m_sourceModel == model)
        return;

    const bool rootWasValid = m_rootIndex.isValid();

    beginResetModel();

    disconnectFromSourceModel();
    m_sourceModel = model;
    // Changing the source model invalidates the root index, since it belonged
    // to the previous model.
    m_rootIndex = QPersistentModelIndex();

    if (m_sourceModel)
        connectToSourceModel();
    rebuildFlatList();

    endResetModel();

    Q_EMIT sourceModelChanged();
    if (rootWasValid)
        Q_EMIT rootIndexChanged();
}

// =============================================================================
// Root Index
// =============================================================================

QModelIndex QTreeToTableModel::rootIndex() const
{
    return m_rootIndex;
}

void QTreeToTableModel::setRootIndex(const QModelIndex &index)
{
    if (m_rootIndex == index)
        return;

    if (index.isValid() && index.model() != m_sourceModel) {
        qCWarning(lcTreeToTable) << "setRootIndex: index belongs to a different model";
        return;
    }

    beginResetModel();
    m_rootIndex = index;
    rebuildFlatList();
    endResetModel();

    Q_EMIT rootIndexChanged();
}

void QTreeToTableModel::resetRootIndex()
{
    setRootIndex(QModelIndex());
}

// =============================================================================
// Max Depth
// =============================================================================

int QTreeToTableModel::maxDepth() const
{
    return m_maxDepth;
}

void QTreeToTableModel::setMaxDepth(int depth)
{
    // Negative values are not meaningful; clamp to 0 (unlimited).
    if (depth < 0)
        depth = 0;

    if (m_maxDepth == depth)
        return;

    beginResetModel();
    m_maxDepth = depth;
    rebuildFlatList();
    endResetModel();

    Q_EMIT maxDepthChanged();
}

// =============================================================================
// Count
// =============================================================================

int QTreeToTableModel::count() const
{
    return m_count;
}

void QTreeToTableModel::updateCount()
{
    const int newCount = m_items.size();
    if (m_count != newCount) {
        m_count = newCount;
        Q_EMIT countChanged();
    }
}

// =============================================================================
// QAbstractTableModel Interface
// =============================================================================

bool QTreeToTableModel::hasChildren(const QModelIndex &parent) const
{
    // In a flat table, only the invisible root can have children.
    return !parent.isValid() && !m_items.isEmpty();
}

int QTreeToTableModel::rowCount(const QModelIndex &parent) const
{
    if (parent.isValid())
        return 0; // Flat table items have no children
    return m_items.size();
}

int QTreeToTableModel::columnCount(const QModelIndex &parent) const
{
    if (parent.isValid() || !m_sourceModel)
        return 0;
    // Ask the source model for the column count at the effective root.
    // When a rootIndex is set, its children define the columns.
    return m_sourceModel->columnCount(m_rootIndex);
}

QVariant QTreeToTableModel::data(const QModelIndex &index, int role) const
{
    if (!index.isValid())
        return {};

    const int row = index.row();
    if (row < 0 || row >= m_items.size())
        return {};

    const FlatItem &item = m_items.at(row);

    // Handle our additional roles before forwarding to source.
    switch (role) {
    case static_cast<int>(Roles::Depth):
        return item.depth;
    case static_cast<int>(Roles::SourceIndex):
        return QVariant::fromValue(item.sourceIndex);
    default:
        break;
    }

    // Forward all other roles to the source model.
    if (!item.sourceIndex.isValid())
        return {};

    // For column > 0, construct the appropriate source index at the correct
    // column since FlatItem always stores column-0 indexes.
    QModelIndex sourceIdx = item.sourceIndex;
    if (index.column() != 0)
        sourceIdx = m_sourceModel->index(sourceIdx.row(), index.column(), sourceIdx.parent());

    return m_sourceModel->data(sourceIdx, role);
}

bool QTreeToTableModel::setData(const QModelIndex &index,
                                const QVariant &value,
                                int role)
{
    if (!index.isValid())
        return false;

    const int row = index.row();
    if (row < 0 || row >= m_items.size())
        return false;

    // Our additional roles are read-only.
    if (role == static_cast<int>(Roles::Depth)
        || role == static_cast<int>(Roles::SourceIndex))
        return false;

    const FlatItem &item = m_items.at(row);
    if (!item.sourceIndex.isValid())
        return false;

    QModelIndex sourceIdx = item.sourceIndex;
    if (index.column() != 0)
        sourceIdx = m_sourceModel->index(sourceIdx.row(), index.column(), sourceIdx.parent());

    return m_sourceModel->setData(sourceIdx, value, role);
}

QVariant QTreeToTableModel::headerData(int section,
                                       Qt::Orientation orientation,
                                       int role) const
{
    if (!m_sourceModel)
        return {};
    return m_sourceModel->headerData(section, orientation, role);
}

Qt::ItemFlags QTreeToTableModel::flags(const QModelIndex &index) const
{
    if (!index.isValid())
        return Qt::NoItemFlags;

    const int row = index.row();
    if (row < 0 || row >= m_items.size())
        return Qt::NoItemFlags;

    const FlatItem &item = m_items.at(row);
    if (!item.sourceIndex.isValid())
        return Qt::NoItemFlags;

    QModelIndex sourceIdx = item.sourceIndex;
    if (index.column() != 0)
        sourceIdx = m_sourceModel->index(sourceIdx.row(), index.column(), sourceIdx.parent());

    return m_sourceModel->flags(sourceIdx);
}

QHash<int, QByteArray> QTreeToTableModel::roleNames() const
{
    QHash<int, QByteArray> roles;
    if (m_sourceModel)
        roles = m_sourceModel->roleNames();
    roles.insert(static_cast<int>(Roles::Depth), "depth");
    roles.insert(static_cast<int>(Roles::SourceIndex), "sourceIndex");
    return roles;
}

// =============================================================================
// Mapping Functions
// =============================================================================

QModelIndex QTreeToTableModel::mapToSource(const QModelIndex &proxyIndex) const
{
    if (!proxyIndex.isValid())
        return {};

    const int row = proxyIndex.row();
    if (row < 0 || row >= m_items.size())
        return {};

    const FlatItem &item = m_items.at(row);
    QModelIndex sourceIdx = item.sourceIndex;

    // Remap to the correct column if the proxy index has column > 0.
    if (proxyIndex.column() != 0 && sourceIdx.isValid())
        sourceIdx = m_sourceModel->index(sourceIdx.row(), proxyIndex.column(), sourceIdx.parent());

    return sourceIdx;
}

QModelIndex QTreeToTableModel::mapFromSource(const QModelIndex &sourceIndex) const
{
    if (!sourceIndex.isValid())
        return {};

    const int row = findFlatRow(sourceIndex);
    if (row < 0)
        return QModelIndex();

    return createIndex(row, sourceIndex.column());
}

QModelIndex QTreeToTableModel::sourceIndexForRow(int row) const
{
    if (row < 0 || row >= m_items.size())
        return {};
    return m_items.at(row).sourceIndex;
}

int QTreeToTableModel::rowForSourceIndex(const QModelIndex &sourceIndex) const
{
    return findFlatRow(sourceIndex);
}

int QTreeToTableModel::depthForRow(int row) const
{
    if (row < 0 || row >= m_items.size())
        return -1;
    return m_items.at(row).depth;
}

bool QTreeToTableModel::isSourceIndexVisible(const QModelIndex &sourceIndex) const
{
    return findFlatRow(sourceIndex) >= 0;
}

bool QTreeToTableModel::isAncestorOf(const QModelIndex &ancestor,
                                     const QModelIndex &descendant) const
{
    if (!ancestor.isValid() || !descendant.isValid())
        return false;

    // Walk up from descendant itself (not parent) looking for ancestor.
    // This means isAncestorOf(A, A) returns true, which is the correct
    // behavior for drag-and-drop: you cannot drop an item onto itself.
    QModelIndex idx = descendant;
    while (idx.isValid()) {
        if (idx == ancestor)
            return true;
        idx = idx.parent();
    }
    return false;
}

bool QTreeToTableModel::moveSourceRow(const QModelIndex &sourceIndex,
                                       const QModelIndex &destinationParent,
                                       int destinationChild)
{
    if (!m_sourceModel || !sourceIndex.isValid())
        return false;

    // Cannot move into own subtree (isAncestorOf(A,A) returns true,
    // covering self-drop as well).
    if (destinationParent.isValid() && isAncestorOf(sourceIndex, destinationParent))
        return false;

    // Normalize: -1 or out-of-range means "append as last child."
    // moveRows() expects rowCount(parent) for "after the last child."
    int destChild = destinationChild;
    if (destChild < 0 || destChild > m_sourceModel->rowCount(destinationParent))
        destChild = m_sourceModel->rowCount(destinationParent);

    // Delegate to the source model's standard moveRows() API.
    // The source model will call beginMoveRows/endMoveRows, which emit
    // rowsAboutToBeMoved/rowsMoved. Our onSourceRowsAboutToBeMoved and
    // onSourceRowsMoved handlers translate these into the correct
    // flat-table operations.
    const bool result = m_sourceModel->moveRows(sourceIndex.parent(),  // sourceParent
                                                sourceIndex.row(),     // sourceRow
                                                1,                     // count (single row; subtree moves implicitly)
                                                destinationParent,     // destinationParent
                                                destChild);            // destinationChild

    if (!result)
        qCDebug(lcTreeToTable) << "moveSourceRow: source model moveRows() returned false";

    return result;
}

void QTreeToTableModel::dump() const
{
    qCInfo(lcTreeToTable) << "=== QTreeToTableModel Dump ===";
    qCInfo(lcTreeToTable) << "Source model:" << m_sourceModel;
    qCInfo(lcTreeToTable) << "Root index valid:" << m_rootIndex.isValid();
    if (m_rootIndex.isValid())
        qCInfo(lcTreeToTable) << "Root index data:" << m_rootIndex.data();
    qCInfo(lcTreeToTable) << "Max depth:" << m_maxDepth;
    qCInfo(lcTreeToTable) << "Item count:" << m_items.size();
    qCInfo(lcTreeToTable) << "---";

    for (int i = 0; i < m_items.size(); ++i) {
        const FlatItem &item = m_items.at(i);
        QString indent(item.depth * 2, u' ');
        qCInfo(lcTreeToTable).noquote()
            << QString(u"[%1] %2depth=%3 data=%4"_s)
                   .arg(i, 3)
                   .arg(indent)
                   .arg(item.depth)
                   .arg(item.sourceIndex.data().toString());
    }

    qCInfo(lcTreeToTable) << "==============================";
}

// =============================================================================
// Connection Management
// =============================================================================

void QTreeToTableModel::connectToSourceModel()
{
    if (!m_sourceModel)
        return;

    // Connect to all relevant source model signals. We store the connections
    // so they can be cleanly disconnected when the source model changes.
    m_connections = {
        connect(m_sourceModel,
                &QAbstractItemModel::destroyed,
                this,
                &QTreeToTableModel::onSourceModelDestroyed),
        connect(m_sourceModel,
                &QAbstractItemModel::modelAboutToBeReset,
                this,
                &QTreeToTableModel::onSourceModelAboutToBeReset),
        connect(m_sourceModel,
                &QAbstractItemModel::modelReset,
                this,
                &QTreeToTableModel::onSourceModelReset),
        connect(m_sourceModel,
                &QAbstractItemModel::dataChanged,
                this,
                &QTreeToTableModel::onSourceDataChanged),
        connect(m_sourceModel,
                &QAbstractItemModel::layoutAboutToBeChanged,
                this,
                &QTreeToTableModel::onSourceLayoutAboutToBeChanged),
        connect(m_sourceModel,
                &QAbstractItemModel::layoutChanged,
                this,
                &QTreeToTableModel::onSourceLayoutChanged),
        connect(m_sourceModel,
                &QAbstractItemModel::rowsInserted,
                this,
                &QTreeToTableModel::onSourceRowsInserted),
        connect(m_sourceModel,
                &QAbstractItemModel::rowsAboutToBeRemoved,
                this,
                &QTreeToTableModel::onSourceRowsAboutToBeRemoved),
        connect(m_sourceModel,
                &QAbstractItemModel::rowsRemoved,
                this,
                &QTreeToTableModel::onSourceRowsRemoved),
        connect(m_sourceModel,
                &QAbstractItemModel::rowsAboutToBeMoved,
                this,
                &QTreeToTableModel::onSourceRowsAboutToBeMoved),
        connect(m_sourceModel,
                &QAbstractItemModel::rowsMoved,
                this,
                &QTreeToTableModel::onSourceRowsMoved),
        connect(m_sourceModel,
                &QAbstractItemModel::columnsAboutToBeInserted,
                this,
                &QTreeToTableModel::onSourceColumnsAboutToBeInserted),
        connect(m_sourceModel,
                &QAbstractItemModel::columnsInserted,
                this,
                &QTreeToTableModel::onSourceColumnsInserted),
        connect(m_sourceModel,
                &QAbstractItemModel::columnsAboutToBeRemoved,
                this,
                &QTreeToTableModel::onSourceColumnsAboutToBeRemoved),
        connect(m_sourceModel,
                &QAbstractItemModel::columnsRemoved,
                this,
                &QTreeToTableModel::onSourceColumnsRemoved),
        // Header data changes need no transformation — forward directly.
        connect(m_sourceModel,
                &QAbstractItemModel::headerDataChanged,
                this,
                &QTreeToTableModel::headerDataChanged),
    };
}

void QTreeToTableModel::disconnectFromSourceModel()
{
    for (const auto &conn : m_connections)
        disconnect(conn);
    m_connections.clear();
}

// =============================================================================
// Source Model Signal Handlers
// =============================================================================

void QTreeToTableModel::onSourceModelDestroyed()
{
    // The source model is being destroyed. Clear all state and emit a reset
    // so views know to discard everything.
    beginResetModel();
    m_sourceModel = nullptr;
    m_rootIndex = QPersistentModelIndex();
    m_items.clear();
    m_connections.clear(); // Connections are already dead, just clear the list.
    endResetModel();

    Q_EMIT sourceModelChanged();
    Q_EMIT rootIndexChanged();
}

void QTreeToTableModel::onSourceModelAboutToBeReset()
{
    // Record whether we had a valid root index before the reset. After the
    // reset, QPersistentModelIndex will be invalidated if the root item no
    // longer exists. We use this flag to detect that case and emit
    // rootIndexChanged().
    m_rootWasValidBeforeReset = m_rootIndex.isValid();
}

void QTreeToTableModel::onSourceModelReset()
{
    const bool rootInvalidated = m_rootWasValidBeforeReset && !m_rootIndex.isValid();
    m_rootWasValidBeforeReset = false;

    beginResetModel();

    if (rootInvalidated)
        m_rootIndex = QPersistentModelIndex();
    rebuildFlatList();

    endResetModel();

    // Emit after endResetModel so slots see consistent model state.
    if (rootInvalidated)
        Q_EMIT rootIndexChanged();
}

void QTreeToTableModel::onSourceDataChanged(const QModelIndex &topLeft,
                                            const QModelIndex &bottomRight,
                                            const QList<int> &roles)
{
    if (!topLeft.isValid() || !bottomRight.isValid())
        return;

    Q_ASSERT(topLeft.parent() == bottomRight.parent());

    // Map the source range to proxy rows. The source range may span multiple
    // rows under the same parent; we find the first and last proxy rows that
    // correspond to visible items in the range and emit a single dataChanged
    // covering the contiguous proxy range.
    int firstProxyRow = -1;
    int lastProxyRow = -1;

    const QModelIndex parent = topLeft.parent();
    for (int srcRow = topLeft.row(); srcRow <= bottomRight.row(); ++srcRow) {
        const QModelIndex srcIdx = m_sourceModel->index(srcRow, 0, parent);
        const int proxyRow = findFlatRow(srcIdx);
        if (proxyRow >= 0) {
            if (firstProxyRow < 0 || proxyRow < firstProxyRow)
                firstProxyRow = proxyRow;
            if (proxyRow > lastProxyRow)
                lastProxyRow = proxyRow;
        }
    }

    if (firstProxyRow >= 0 && lastProxyRow >= 0) {
        const QModelIndex proxyTopLeft = createIndex(firstProxyRow, topLeft.column());
        const QModelIndex proxyBottomRight = createIndex(lastProxyRow, bottomRight.column());
        Q_EMIT dataChanged(proxyTopLeft, proxyBottomRight, roles);
    }
}

void QTreeToTableModel::onSourceLayoutAboutToBeChanged(
    const QList<QPersistentModelIndex> & /*parents*/,
    QAbstractItemModel::LayoutChangeHint /*hint*/)
{
    Q_EMIT layoutAboutToBeChanged();

    // Save the current persistent indexes so we can remap them after the
    // layout change. For each persistent proxy index, we store the
    // corresponding source index and the old proxy row.
    const auto persistentIndexes = persistentIndexList();
    m_layoutChangePersistentIndexes.clear();
    m_layoutChangeProxyIndexes.clear();

    m_layoutChangePersistentIndexes.reserve(persistentIndexes.size());
    m_layoutChangeProxyIndexes.reserve(persistentIndexes.size());

    for (const QModelIndex &proxyIdx : persistentIndexes) {
        const int row = proxyIdx.row();
        if (row >= 0 && row < m_items.size()) {
            m_layoutChangePersistentIndexes.append(m_items.at(row).sourceIndex);
            m_layoutChangeProxyIndexes.append(proxyIdx);
        }
    }
}

void QTreeToTableModel::onSourceLayoutChanged(
    const QList<QPersistentModelIndex> & /*parents*/,
    QAbstractItemModel::LayoutChangeHint /*hint*/)
{
    // Rebuild the flat list from scratch -- the source model's ordering may
    // have changed arbitrarily.
    rebuildFlatList();

    // Remap persistent indexes: for each saved source index, find its new
    // position in the rebuilt flat list and update the persistent index.
    QModelIndexList oldIndexes;
    QModelIndexList newIndexes;

    for (int i = 0; i < m_layoutChangePersistentIndexes.size(); ++i) {
        const QPersistentModelIndex &srcIdx = m_layoutChangePersistentIndexes.at(i);
        const QModelIndex &oldProxyIdx = m_layoutChangeProxyIndexes.at(i);

        oldIndexes.append(oldProxyIdx);

        if (srcIdx.isValid()) {
            const int newRow = findFlatRow(srcIdx);
            if (newRow >= 0) {
                newIndexes.append(createIndex(newRow, oldProxyIdx.column()));
            } else {
                // Item left the flat list (e.g. pushed past maxDepth) — invalidate.
                newIndexes.append(QModelIndex());
            }
        } else {
            // Source item no longer exists — invalidate.
            newIndexes.append(QModelIndex());
        }
    }

    changePersistentIndexList(oldIndexes, newIndexes);

    m_layoutChangePersistentIndexes.clear();
    m_layoutChangeProxyIndexes.clear();

    Q_EMIT layoutChanged();
}

// -- Row insertion handling --
//
// Qt's insert protocol is a two-phase signal: rowsAboutToBeInserted fires
// before the rows exist, and rowsInserted fires after they are in place. We
// do all our work in the "inserted" handler because we need to read the
// newly-inserted items from the source model.

void QTreeToTableModel::onSourceRowsInserted(const QModelIndex &parent, int first, int last)
{
    // Note: we intentionally do not connect to rowsAboutToBeInserted because
    // we can only read the newly-inserted items after they exist in the source.
    // Ignore insertions under parents that are not visible (outside root
    // subtree or hidden by a non-visible ancestor).
    if (!isParentVisible(parent))
        return;

    // Check maxDepth: the parent's depth + 1 is the depth of children being
    // inserted. If that depth would be at or beyond maxDepth, skip.
    const int depth = calculateDepth(m_sourceModel->index(first, 0, parent));
    if (m_maxDepth > 0 && depth >= m_maxDepth)
        return;

    // Find the position in the flat list where the new items should go.
    const int insertPos = findInsertPosition(parent, first);

    // Flatten the newly-inserted rows and their subtrees.
    QList<FlatItem> newItems;
    for (int row = first; row <= last; ++row) {
        const QModelIndex childIdx = m_sourceModel->index(row, 0, parent);
        newItems.append(FlatItem(childIdx, depth));
        if (m_sourceModel->hasChildren(childIdx))
            flattenSubtree(childIdx, depth + 1, newItems);
    }

    if (newItems.isEmpty())
        return;

    beginInsertRows(QModelIndex(), insertPos, insertPos + newItems.size() - 1);
    m_items.insert(insertPos, newItems.size(), FlatItem{});
    for (int i = 0; i < newItems.size(); ++i)
        m_items[insertPos + i] = newItems[i];
    endInsertRows();

    m_lastLookupRow = -1; // Invalidate cache -- row positions have shifted.
}

// -- Row removal handling --
//
// Removal is the reverse of insertion. We do all our work in the "aboutTo"
// handler because we need to find the items in the flat list while they
// still exist in the source model (QPersistentModelIndex is still valid).

void QTreeToTableModel::onSourceRowsAboutToBeRemoved(const QModelIndex &parent,
                                                     int first,
                                                     int last)
{
    // Record whether we have a valid root index before the removal. If the
    // root item itself is being removed, QPersistentModelIndex will be
    // invalidated after the removal completes, and we detect that in
    // onSourceRowsRemoved.
    m_rootWasValid = m_rootIndex.isValid();

    // If the root index is among the items being removed, don't try to remove
    // items from the flat list now -- we'll handle the full reset in
    // onSourceRowsRemoved once the persistent index is actually invalidated.
    if (m_rootWasValid) {
        for (int row = first; row <= last; ++row) {
            const QModelIndex idx = m_sourceModel->index(row, 0, parent);
            if (idx == m_rootIndex)
                return;
        }
    }

    if (!isParentVisible(parent))
        return;

    removeFlatRange(parent, first, last);
}

void QTreeToTableModel::onSourceRowsRemoved(const QModelIndex &parent, int first, int last)
{
    Q_UNUSED(parent)
    Q_UNUSED(first)
    Q_UNUSED(last)

    // If the root index was valid before removal but is now invalid, the root
    // item was removed from the source model. Reset to show the entire tree.
    if (m_rootWasValid && !m_rootIndex.isValid()) {
        beginResetModel();
        m_rootIndex = QPersistentModelIndex();
        rebuildFlatList();
        endResetModel();
        Q_EMIT rootIndexChanged();
    }

    m_rootWasValid = false;
    m_lastLookupRow = -1; // Invalidate lookup cache after removal.
}

// -- Move handling --
//
// Move operations are the most complex signal to handle because we want to
// preserve them as moves in the flat table (rather than emitting separate
// remove + insert signals) to allow views to animate the operation.
//
// The move is a two-phase operation:
// 1. aboutToBeMoved: Items are still at their old positions. We calculate
//    the flat list range, destination position, and depth delta. We save
//    copies of the moved items in m_pendingMove.
// 2. moved: Items have been relocated in the source model. We use the
//    captured state to emit beginMoveRows/endMoveRows or fall back to
//    remove+insert if the move is a no-op in flat space.
//
// There are four visibility cases:
// - Both visible: Emit move (preferred) or remove+insert fallback.
// - Source visible, dest not: Emit remove (items leave the visible area).
// - Source not visible, dest visible: Emit insert (items enter visible area).
// - Neither visible: No-op.

void QTreeToTableModel::onSourceRowsAboutToBeMoved(const QModelIndex &sourceParent,
                                                   int sourceFirst,
                                                   int sourceLast,
                                                   const QModelIndex &destParent,
                                                   int destRow)
{
    const bool sourceVisible = isParentVisible(sourceParent);
    const bool destVisible = isParentVisible(destParent);

    // Reset pending move state for this operation.
    m_pendingMove = PendingMove{};

    if (!sourceVisible && !destVisible)
        return; // Neither end is visible, nothing to do.

    if (sourceVisible && destVisible) {
        // Both source and destination are visible. Find the flat list range
        // of the items being moved, including their entire subtrees.
        int flatSourceFirst = -1;
        int flatSourceLast = -1;

        for (int row = sourceFirst; row <= sourceLast; ++row) {
            const QModelIndex childIdx = m_sourceModel->index(row, 0, sourceParent);
            const int flatRow = findFlatRow(childIdx);
            if (flatRow >= 0) {
                const int depth = m_items.at(flatRow).depth;
                const int subtreeCount = countSubtreeItems(flatRow, depth);

                if (flatSourceFirst < 0 || flatRow < flatSourceFirst)
                    flatSourceFirst = flatRow;
                if (flatRow + subtreeCount - 1 > flatSourceLast)
                    flatSourceLast = flatRow + subtreeCount - 1;
            }
        }

        if (flatSourceFirst < 0 || flatSourceLast < flatSourceFirst)
            return; // Items not found in flat list (e.g. hidden by maxDepth).

        // Calculate the destination position in the flat list.
        int flatDestRow = findInsertPosition(destParent, destRow);

        // Determine the old and new depths. Moving between parents can change
        // the depth of all items in the subtree.
        const int oldDepth = m_items.at(flatSourceFirst).depth;

        int newDepth;
        if (!destParent.isValid() && !m_rootIndex.isValid()) {
            // Moving to the invisible root (top level) with no root index set.
            newDepth = 0;
        } else if (destParent == m_rootIndex) {
            // Moving to the root index's children (depth 0 relative to root).
            newDepth = 0;
        } else {
            // Moving under a visible parent -- depth is parent's depth + 1.
            const int parentFlatRow = findFlatRow(destParent);
            if (parentFlatRow >= 0)
                newDepth = m_items.at(parentFlatRow).depth + 1;
            else
                newDepth = oldDepth; // Fallback: keep original depth.
        }

        // If maxDepth limits prevent the destination from being visible,
        // treat this as a visible-to-invisible move (just remove).
        if (m_maxDepth > 0 && newDepth >= m_maxDepth) {
            beginRemoveRows(QModelIndex(), flatSourceFirst, flatSourceLast);
            m_items.remove(flatSourceFirst, flatSourceLast - flatSourceFirst + 1);
            endRemoveRows();
            m_lastLookupRow = -1;
            return;
        }

        // When maxDepth is active and depth changes, descendants may cross
        // the maxDepth boundary in either direction: moving deeper can push
        // visible descendants beyond the limit, and moving shallower can
        // reveal previously-hidden descendants. Fall back to remove + re-
        // flatten (handled in onSourceRowsMoved) to ensure correct filtering.
        if (m_maxDepth > 0 && newDepth != oldDepth) {
            removeFlatRange(sourceParent, sourceFirst, sourceLast);
            return;
        }

        // Save copies of the moved items for use in onSourceRowsMoved.
        QList<FlatItem> movedItems;
        for (int i = flatSourceFirst; i <= flatSourceLast; ++i)
            movedItems.append(m_items.at(i));

        m_pendingMove.active = true;
        m_pendingMove.sourceFirst = flatSourceFirst;
        m_pendingMove.sourceLast = flatSourceLast;
        m_pendingMove.destRow = flatDestRow;
        m_pendingMove.oldDepth = oldDepth;
        m_pendingMove.newDepth = newDepth;
        m_pendingMove.movedItems = movedItems;

    } else if (sourceVisible && !destVisible) {
        // Items are moving from a visible area to an invisible area.
        // This looks like a removal to the flat table.
        removeFlatRange(sourceParent, sourceFirst, sourceLast);
    }
    // !sourceVisible && destVisible: handled in onSourceRowsMoved as insertion,
    // because we can only read the items from their new position after the
    // move completes.
}

void QTreeToTableModel::onSourceRowsMoved(const QModelIndex &sourceParent,
                                          int sourceFirst,
                                          int sourceLast,
                                          const QModelIndex &destParent,
                                          int destRow)
{
    const bool sourceVisible = isParentVisible(sourceParent);
    const bool destVisible = isParentVisible(destParent);

    if (!sourceVisible && !destVisible)
        return;

    if (sourceVisible && destVisible) {
        if (m_pendingMove.active) {
            // Normal case: we captured the move in aboutToBeMoved. Now apply
            // it to the flat list.
            const int flatSourceFirst = m_pendingMove.sourceFirst;
            const int flatSourceLast = m_pendingMove.sourceLast;
            const int flatDestRow = m_pendingMove.destRow;
            const int moveCount = flatSourceLast - flatSourceFirst + 1;

            // Adjust depths of all moved items if the depth changed.
            const int depthDelta = m_pendingMove.newDepth - m_pendingMove.oldDepth;
            if (depthDelta != 0) {
                for (FlatItem &item : m_pendingMove.movedItems)
                    item.depth += depthDelta;
            }

            // Try to emit a proper move signal. beginMoveRows will return
            // false if the move is a no-op (source == dest in flat space).
            if (beginMoveRows(QModelIndex(),
                              flatSourceFirst,
                              flatSourceLast,
                              QModelIndex(),
                              flatDestRow)) {
                // Remove items from old position and re-insert at new position.
                m_items.remove(flatSourceFirst, moveCount);

                // Adjust insertion position: if we removed items before the
                // destination, the destination shifts left by moveCount.
                int insertAt = flatDestRow;
                if (flatSourceFirst < flatDestRow)
                    insertAt -= moveCount;

                m_items.insert(insertAt, moveCount, FlatItem{});
                for (int i = 0; i < moveCount; ++i)
                    m_items[insertAt + i] = m_pendingMove.movedItems[i];

                endMoveRows();

                // Notify views that depth changed for all moved items.
                if (depthDelta != 0) {
                    const int lastCol = columnCount() - 1;
                    Q_EMIT dataChanged(createIndex(insertAt, 0),
                                       createIndex(insertAt + moveCount - 1, lastCol),
                                       {static_cast<int>(Roles::Depth)});
                }
            } else {
                // beginMoveRows failed (no-op move in flat space). Fall back
                // to separate remove + insert signals so the state stays
                // consistent.
                beginRemoveRows(QModelIndex(), flatSourceFirst, flatSourceLast);
                m_items.remove(flatSourceFirst, moveCount);
                endRemoveRows();

                int insertAt = flatDestRow;
                if (flatSourceFirst < flatDestRow)
                    insertAt -= moveCount;

                beginInsertRows(QModelIndex(), insertAt, insertAt + moveCount - 1);
                m_items.insert(insertAt, moveCount, FlatItem{});
                for (int i = 0; i < moveCount; ++i)
                    m_items[insertAt + i] = m_pendingMove.movedItems[i];
                endInsertRows();

                // Notify views that depth changed in the fallback path too.
                if (depthDelta != 0) {
                    const int lastCol = columnCount() - 1;
                    Q_EMIT dataChanged(createIndex(insertAt, 0),
                                       createIndex(insertAt + moveCount - 1, lastCol),
                                       {static_cast<int>(Roles::Depth)});
                }
            }

            m_pendingMove = PendingMove{};
        } else {
            // No items are recorded in m_pendingMove — either they were hidden
            // by maxDepth at the source location, or they were found but
            // intentionally removed by the maxDepth depth-change path (so a
            // fresh re-flatten is cheaper than a move). Both parents are
            // visible, so check whether items are visible at their destination
            // and insert them.
            insertFlatItems(destParent, destRow, sourceLast - sourceFirst + 1);
        }
    } else if (!sourceVisible && destVisible) {
        // Items are moving from an invisible area into the visible area.
        // This looks like an insertion to the flat table.
        insertFlatItems(destParent, destRow, sourceLast - sourceFirst + 1);
    }

    m_lastLookupRow = -1; // Invalidate lookup cache after move.
}

// -- Column change handling --
//
// Column changes are only forwarded when they occur at the effective root of
// the flattened table, because QTreeToTableModel flattens the column count
// from the root level only.

void QTreeToTableModel::onSourceColumnsAboutToBeInserted(const QModelIndex &parent,
                                                         int first,
                                                         int last)
{
    if (isColumnChangeAtRoot(parent))
        beginInsertColumns(QModelIndex(), first, last);
}

void QTreeToTableModel::onSourceColumnsInserted(const QModelIndex &parent, int first, int last)
{
    Q_UNUSED(first)
    Q_UNUSED(last)

    if (isColumnChangeAtRoot(parent))
        endInsertColumns();
}

void QTreeToTableModel::onSourceColumnsAboutToBeRemoved(const QModelIndex &parent,
                                                        int first,
                                                        int last)
{
    if (isColumnChangeAtRoot(parent))
        beginRemoveColumns(QModelIndex(), first, last);
}

void QTreeToTableModel::onSourceColumnsRemoved(const QModelIndex &parent, int first, int last)
{
    Q_UNUSED(first)
    Q_UNUSED(last)

    if (isColumnChangeAtRoot(parent))
        endRemoveColumns();
}

// =============================================================================
// Internal Helpers
// =============================================================================

void QTreeToTableModel::rebuildFlatList()
{
    m_items.clear();
    m_lastLookupRow = -1;

    if (!m_sourceModel)
        return;

    // Flatten starting from the root index (or the invisible root if no root
    // index is set). Depth 0 = direct children of the root.
    flattenSubtree(m_rootIndex, 0, m_items);
}

void QTreeToTableModel::flattenSubtree(const QModelIndex &parentIndex,
                                       int depth,
                                       QList<FlatItem> &items) const
{
    if (!m_sourceModel)
        return;

    // Respect maxDepth: if maxDepth > 0 and we've reached it, stop recursing.
    if (m_maxDepth > 0 && depth >= m_maxDepth)
        return;

    const int rows = m_sourceModel->rowCount(parentIndex);
    for (int row = 0; row < rows; ++row) {
        const QModelIndex childIdx = m_sourceModel->index(row, 0, parentIndex);
        items.append(FlatItem(childIdx, depth));

        // Recursively flatten children (depth-first order).
        if (m_sourceModel->hasChildren(childIdx))
            flattenSubtree(childIdx, depth + 1, items);
    }
}

bool QTreeToTableModel::isParentVisible(const QModelIndex &parent) const
{
    // The invisible root is visible when no root index is set.
    if (!parent.isValid())
        return !m_rootIndex.isValid();

    // The root index itself is always visible (its children are shown).
    // Otherwise, walk up the parent chain looking for the root index.
    if (!m_rootIndex.isValid())
        return true;

    QModelIndex idx = parent;
    while (idx.isValid()) {
        if (idx == m_rootIndex)
            return true;
        idx = idx.parent();
    }
    return false;
}

int QTreeToTableModel::calculateDepth(const QModelIndex &sourceIndex) const
{
    if (!sourceIndex.isValid())
        return -1;

    // Walk up from the item's parent to the root index, counting steps.
    int depth = 0;
    QModelIndex idx = sourceIndex.parent();

    while (idx.isValid() && idx != m_rootIndex) {
        ++depth;
        idx = idx.parent();
    }

    return depth;
}

int QTreeToTableModel::findFlatRow(const QModelIndex &sourceIndex) const
{
    if (!sourceIndex.isValid())
        return -1;

    // Normalize to column 0 since FlatItem stores column-0 indexes.
    const QModelIndex normalizedIndex = sourceIndex.sibling(sourceIndex.row(), 0);

    // Check single-entry cache first (optimization for sequential access).
    if (m_lastLookupRow >= 0 && m_lastLookupRow < m_items.size()) {
        if (m_items.at(m_lastLookupRow).sourceIndex == normalizedIndex)
            return m_lastLookupRow;
    }

    // Linear scan through the flat list.
    for (int i = 0; i < m_items.size(); ++i) {
        if (m_items.at(i).sourceIndex == normalizedIndex) {
            m_lastLookupRow = i;
            return i;
        }
    }

    return -1;
}

int QTreeToTableModel::findInsertPosition(const QModelIndex &parentIndex, int childRow) const
{
    if (m_items.isEmpty())
        return 0;

    // If inserting under the root (or invisible root when no root index is
    // set), the position depends on the sibling before the insertion point.
    if (parentIndex == m_rootIndex || !parentIndex.isValid()) {
        if (childRow == 0)
            return 0; // Insert at the very beginning.

        // Find the previous sibling and insert after its entire subtree.
        const QModelIndex prevSibling = m_sourceModel->index(childRow - 1, 0, parentIndex);
        const int prevRow = findFlatRow(prevSibling);
        if (prevRow >= 0) {
            const int depth = m_items.at(prevRow).depth;
            return prevRow + countSubtreeItems(prevRow, depth);
        }
        return m_items.size(); // Fallback: append to the end.
    }

    // For non-root parents, find the parent in the flat list first.
    const int parentRow = findFlatRow(parentIndex);
    if (parentRow < 0)
        return m_items.size(); // Parent not visible; append to end.

    const int parentDepth = m_items.at(parentRow).depth;

    if (childRow == 0)
        return parentRow + 1; // Insert right after the parent.

    // Find the previous sibling and insert after its subtree.
    const QModelIndex prevSibling = m_sourceModel->index(childRow - 1, 0, parentIndex);
    const int prevRow = findFlatRow(prevSibling);
    if (prevRow >= 0) {
        const int prevDepth = m_items.at(prevRow).depth;
        return prevRow + countSubtreeItems(prevRow, prevDepth);
    }

    // Fallback: insert after the parent's entire subtree.
    return parentRow + countSubtreeItems(parentRow, parentDepth);
}

bool QTreeToTableModel::isColumnChangeAtRoot(const QModelIndex &parent) const
{
    if (!parent.isValid())
        return !m_rootIndex.isValid();
    return m_rootIndex.isValid() && parent == m_rootIndex;
}

bool QTreeToTableModel::removeFlatRange(const QModelIndex &parent, int sourceFirst, int sourceLast)
{
    int removeFirst = -1;
    int removeLast = -1;

    for (int row = sourceFirst; row <= sourceLast; ++row) {
        const QModelIndex childIdx = m_sourceModel->index(row, 0, parent);
        const int flatRow = findFlatRow(childIdx);
        if (flatRow >= 0) {
            const int depth = m_items.at(flatRow).depth;
            const int subtreeCount = countSubtreeItems(flatRow, depth);

            if (removeFirst < 0 || flatRow < removeFirst)
                removeFirst = flatRow;
            if (flatRow + subtreeCount - 1 > removeLast)
                removeLast = flatRow + subtreeCount - 1;
        }
    }

    if (removeFirst >= 0 && removeLast >= removeFirst) {
        beginRemoveRows(QModelIndex(), removeFirst, removeLast);
        m_items.remove(removeFirst, removeLast - removeFirst + 1);
        endRemoveRows();
        m_lastLookupRow = -1;
        return true;
    }
    return false;
}

void QTreeToTableModel::insertFlatItems(const QModelIndex &destParent, int destRow, int count)
{
    // Compute child depth from the parent. Children of the root index (or the
    // invisible root when no rootIndex is set) are at depth 0. Otherwise the
    // depth is one more than the parent's own depth.
    int newDepth = 0;
    if (destParent.isValid() && destParent != m_rootIndex)
        newDepth = calculateDepth(destParent) + 1;
    if (m_maxDepth > 0 && newDepth >= m_maxDepth)
        return;

    const int insertPos = findInsertPosition(destParent, destRow);

    QList<FlatItem> newItems;
    for (int i = 0; i < count; ++i) {
        const QModelIndex childIdx = m_sourceModel->index(destRow + i, 0, destParent);
        newItems.append(FlatItem(childIdx, newDepth));
        if (m_sourceModel->hasChildren(childIdx))
            flattenSubtree(childIdx, newDepth + 1, newItems);
    }

    if (!newItems.isEmpty()) {
        beginInsertRows(QModelIndex(), insertPos, insertPos + newItems.size() - 1);
        m_items.insert(insertPos, newItems.size(), FlatItem{});
        for (int i = 0; i < newItems.size(); ++i)
            m_items[insertPos + i] = newItems[i];
        endInsertRows();
    }
}

int QTreeToTableModel::countSubtreeItems(int startRow, int subtreeDepth) const
{
    // Scan forward from startRow. Items with depth > subtreeDepth are
    // descendants. The first item with depth <= subtreeDepth marks the end
    // of the subtree.
    int count = 1; // Include the item itself.
    for (int i = startRow + 1; i < m_items.size(); ++i) {
        if (m_items.at(i).depth <= subtreeDepth)
            break;
        ++count;
    }
    return count;
}