NavigationRail.qml

Go to the documentation of this file.

// SPDX-FileCopyrightText: 2026 Pier Luigi Fiorini <pierluigi.fiorini@gmail.com>
// SPDX-License-Identifier: MPL-2.0
 
pragma ComponentBehavior: Bound
 
import QtQuick
import QtQuick.Templates as T
import QtQuick.Window
import Fluid as MD
import "../core/UiMetrics.js" as UiMetrics
import "../internal/MotionAnimation.js" as MotionAnimation
 
T.Container {
    id: control
 
    enum Arrangement {
        Top,
        Center,
        Bottom
    }
 
    property bool expanded: false
 
    property int arrangement: NavigationRail.Arrangement.Top
 
    property Component header: null
 
    property color containerColor: control.MD.Style.surfaceColor
 
    property bool _modal: false
 
    property bool _syncingSelection: false
 
    property real _layoutProgress: expanded ? 1 : 0
 
    readonly property real _naturalExpandedWidth: {
        const headerItem = headerLoader.item as Item;
        let naturalWidth = headerItem ? headerItem.implicitWidth : 0;
        for (let index = 0; index < count; ++index) {
            const item = itemAt(index) as MD.NavigationRailItem;
            if (item)
                naturalWidth = Math.max(naturalWidth,
                                        item._expandedImplicitWidth
                                        + MD.Tokens.navigationRail.itemHorizontalPadding);
        }
        return naturalWidth;
    }
 
    readonly property real _collapsedWidth: MD.Tokens.navigationRail.collapsedContainerWidth
                                            + leftPadding + rightPadding
 
    readonly property real _expandedWidth: Math.min(
                                               MD.Tokens.navigationRail.expandedContainerWidthMaximum,
                                               Math.max(MD.Tokens.navigationRail.expandedContainerWidthMinimum,
                                                        _naturalExpandedWidth + leftPadding + rightPadding))
 
    readonly property real _itemSpacing: MD.Tokens.navigationRail.collapsedItemVerticalSpace
                                         * (1 - _layoutProgress)
 
    readonly property real _itemsHeight: {
        let total = 0;
        for (let index = 0; index < count; ++index) {
            const item = itemAt(index);
            if (item)
                total += item.implicitHeight;
        }
        return total + Math.max(0, count - 1) * _itemSpacing;
    }
 
    readonly property int _tabStopIndex: {
        const selected = itemAt(currentIndex);
        if (selected && selected.enabled)
            return currentIndex;
        for (let index = 0; index < count; ++index) {
            const item = itemAt(index);
            if (item && item.enabled)
                return index;
        }
        return -1;
    }
 
    readonly property Item _headerItem: headerLoader.item as Item
 
    function _headerFocusItem(item) {
        const candidate = item || control._headerItem;
        if (!candidate || !candidate.visible || !candidate.enabled)
            return null;
        if (candidate.focusPolicy !== undefined && candidate.focusPolicy !== Qt.NoFocus)
            return candidate;
        for (let index = 0; index < candidate.children.length; ++index) {
            const descendant = control._headerFocusItem(candidate.children[index]);
            if (descendant)
                return descendant;
        }
        return null;
    }
 
    readonly property real _headerOffset: {
        const headerItem = headerLoader.item as Item;
        return headerItem && headerItem.height > 0
               ? headerItem.height + MD.Tokens.navigationRail.headerSpaceMinimum
               : 0;
    }
 
    readonly property real _itemsOrigin: {
        if (arrangement === NavigationRail.Arrangement.Center)
            return Math.max(headerLoader.item ? (headerLoader.item as Item).height : 0,
                            (contentArea.height - _itemsHeight) / 2);
        if (arrangement === NavigationRail.Arrangement.Bottom)
            return Math.max(_headerOffset, contentArea.height - _itemsHeight);
        return _headerOffset;
    }
 
    function expand() {
        control.expanded = true;
    }
 
    function collapse() {
        control.expanded = false;
    }
 
    function toggle() {
        control.expanded = !control.expanded;
    }
 
    function _itemY(itemIndex) {
        let itemY = control._itemsOrigin;
        for (let index = 0; index < itemIndex; ++index) {
            const previous = control.itemAt(index);
            if (previous)
                itemY += previous.implicitHeight + control._itemSpacing;
        }
        return itemY;
    }
 
    function _bindItems() {
        for (let index = 0; index < control.count; ++index) {
            const item = control.itemAt(index) as MD.NavigationRailItem;
            if (!item)
                continue;
            item.rail = control;
            item._railIndex = index;
            item.x = Qt.binding(function() {
                return MD.Tokens.navigationRail.itemHorizontalPadding
                       * control._layoutProgress / 2;
            });
            item.y = Qt.binding(function() { return control._itemY(index); });
            item.width = Qt.binding(function() {
                return Math.max(0, contentArea.width
                                - MD.Tokens.navigationRail.itemHorizontalPadding
                                  * control._layoutProgress);
            });
        }
        control._syncSelection();
    }
 
    function _syncSelection() {
        if (control._syncingSelection)
            return;
        control._syncingSelection = true;
        for (let index = 0; index < control.count; ++index) {
            const item = control.itemAt(index) as MD.NavigationRailItem;
            if (item)
                item.checked = index === control.currentIndex;
        }
        control._syncingSelection = false;
    }
 
    function _activateItem(item) {
        if (!item || !item.enabled || item._railIndex < 0)
            return;
        control.currentIndex = item._railIndex;
        item.forceActiveFocus(Qt.TabFocusReason);
    }
 
    function _itemCheckedChanged(item) {
        if (control._syncingSelection || !item || item._railIndex < 0)
            return;
        if (item.checked)
            control.currentIndex = item._railIndex;
        else if (control.currentIndex === item._railIndex)
            control.currentIndex = -1;
    }
 
    function _selectIndex(index) {
        const item = control.itemAt(index) as MD.NavigationRailItem;
        if (!item || !item.enabled)
            return false;
        control.currentIndex = index;
        item.forceActiveFocus(Qt.TabFocusReason);
        return true;
    }
 
    function _moveSelection(direction) {
        if (control.count <= 0)
            return;
        let index = control.currentIndex;
        for (let attempt = 0; attempt < control.count; ++attempt) {
            index = (index + direction + control.count) % control.count;
            if (control._selectIndex(index))
                return;
        }
    }
 
    function _selectBoundary(last) {
        let index = last ? control.count - 1 : 0;
        const end = last ? -1 : control.count;
        const direction = last ? -1 : 1;
        for (; index !== end; index += direction) {
            if (control._selectIndex(index))
                return;
        }
    }
 
    currentIndex: 0
    implicitWidth: _collapsedWidth + (_expandedWidth - _collapsedWidth) * _layoutProgress
    implicitHeight: topPadding + bottomPadding + Math.max(_headerOffset + _itemsHeight,
                                                          MD.Tokens.navigationRail.itemContainerHeight)
 
    topPadding: SafeArea.margins.top + MD.Tokens.navigationRail.topSpace
    bottomPadding: SafeArea.margins.bottom + MD.Tokens.navigationRail.topSpace
    leftPadding: mirrored ? 0 : SafeArea.margins.left
    rightPadding: mirrored ? SafeArea.margins.right : 0
    leftInset: 0
    rightInset: 0
    topInset: 0
    bottomInset: 0
 
    // Destinations, rather than the container, own keyboard focus. This creates
    // one Tab entry point while retaining a PageTabList node for screen readers.
    focusPolicy: Qt.NoFocus
    clip: true
    LayoutMirroring.childrenInherit: true
 
    Accessible.role: Accessible.PageTabList
 
    Behavior on _layoutProgress {
        NumberAnimation {
            duration: MotionAnimation.expressiveDefaultSpatialDuration
            easing.type: Easing.BezierSpline
            easing.bezierCurve: MotionAnimation.expressiveDefaultSpatialCurve
        }
    }
 
    onCountChanged: Qt.callLater(control._bindItems)
    onCurrentIndexChanged: control._syncSelection()
    onExpandedChanged: control._bindItems()
    Component.onCompleted: control._bindItems()
 
    // These handlers also cover the rare case where the modal wrapper focuses
    // an empty rail; instantiated destinations provide the same key contract.
    Keys.onUpPressed: control._moveSelection(-1)
    Keys.onDownPressed: control._moveSelection(1)
    Keys.onPressed: event => {
        if (event.key === Qt.Key_Home) {
            control._selectBoundary(false);
            event.accepted = true;
        } else if (event.key === Qt.Key_End) {
            control._selectBoundary(true);
            event.accepted = true;
        } else {
            event.accepted = false;
        }
    }
 
    contentItem: Item {
        id: contentArea
        objectName: "navigationRailContent"
        LayoutMirroring.enabled: control.mirrored
        LayoutMirroring.childrenInherit: true
    }
 
    data: Loader {
        id: headerLoader
        objectName: "navigationRailHeader"
 
        x: control.leftPadding
        y: control.topPadding
        width: Math.max(0, control.width - control.leftPadding - control.rightPadding)
        sourceComponent: control.header
        active: control.header !== null
        LayoutMirroring.enabled: control.mirrored
        LayoutMirroring.childrenInherit: true
 
        // The loader is structural only. Its accessible header descendants stay
        // available, while the wrapper itself does not add a redundant node.
        Accessible.ignored: true
    }
 
    background: MD.ElevationRectangle {
        objectName: "navigationRailBackground"
 
        readonly property var containerShape: control._modal && control.expanded
                                              ? MD.Tokens.navigationRail.modalContainerShape
                                              : MD.Tokens.navigationRail.containerShape
 
        color: control.containerColor
        elevation: control._modal && control.expanded
                   ? MD.Tokens.navigationRail.modalContainerElevation
                   : MD.Tokens.navigationRail.containerElevation
        topLeftRadius: UiMetrics.resolveShapeRadius(containerShape.topLeft, width, height)
        topRightRadius: UiMetrics.resolveShapeRadius(containerShape.topRight, width, height)
        bottomLeftRadius: UiMetrics.resolveShapeRadius(containerShape.bottomLeft, width, height)
        bottomRightRadius: UiMetrics.resolveShapeRadius(containerShape.bottomRight, width, height)
    }
}