Navigation

Phase 6 navigation widgets now include a proposed QtMaterialTabs implementation aligned with the repository architecture.

Why this corrected iteration exists

The earlier experimental Tabs patches were useful to validate feature scope, but they had three structural weaknesses:

• metadata was stored by raw tab index in maps, which is fragile after insertTab() / removeTab()

• the theme application path mutated the authored spec instead of resolving into a separate runtime spec

• generic QObject binding was flexible, but too weakly typed for a library that is trying to stabilize its public API

This corrected patch fixes those points while preserving the recent features:

• Material 3 themed states

• overflow menu

• lazy loading

• routes and URL navigation

• test IDs for automation

• multi-widget synchronization through navigation controllers

Public types

TabsSpec

TabsSpec remains a simple value type in qtmaterial3_specs.

It covers:

• variant

• density

• alignment

• overflow mode

• color roles

• state-layer opacities

• sizing and animation values

• scroll and wrap-navigation behavior

QtMaterialRoute

QtMaterialRoute is a small typed wrapper over a normalized route path.

Example:

QtMaterialRoute(QStringLiteral("settings/profile"))

QtMaterialNavigationController

Instead of binding Tabs directly to arbitrary QObjects, this patch introduces a narrow controller contract:

class QtMaterialNavigationController : public QObject {
    Q_OBJECT
    Q_PROPERTY(int currentIndex READ currentIndex WRITE setCurrentIndex NOTIFY currentIndexChanged)
};

That makes multi-widget synchronization explicit and testable.

A convenience adapter for QStackedWidget is included:

QtMaterialStackedWidgetController

QtMaterialTabs

Spec flow

The widget now keeps two specs:

• authoredSpec() — exactly what the consumer provided

• resolvedSpec() — runtime spec after theme resolution

That matches the repository rule:

widgets render from resolved specs, not from ad hoc theme lookups

Metadata model

All per-tab metadata now lives in a descriptor vector synchronized with the real tab order.

Stored per tab:

• tabId

• tabTestId

• route

• lazy-loading factory

• loaded state

• badge content and visibility

This avoids index/key drift after insertions and removals.

Automation surface

Automation data is exposed through dynamic properties on each page widget:

• materialTabId

• materialTabTestId

• materialTabRoute

• materialTabIndex

The tab bar also gets a stable object name:

qtmaterial_tabs_bar

This is a better split than overloading accessibility text for test automation.

Lazy loading

Lazy loading no longer assumes the tab page itself does not exist.

Instead:

• the tab page exists as a normal QWidget

• the factory creates the page content on first activation

• content is inserted into the page layout when needed

That integrates cleanly with QTabWidget.

URL navigation

navigateToUrl() now resolves both host and path:

app://settings/profile

becomes:

settings/profile

This avoids the common bug where only the trailing path segment is used.

Integration checklist

The patch archive contains:

• include/qtmaterial/specs/qtmaterialtabsspec.h

• include/qtmaterial/widgets/navigation/qtmaterialnavigationcontroller.h

• include/qtmaterial/widgets/navigation/qtmaterialtabs.h

• src/specs/qtmaterialtabsspec.cpp

• src/widgets/navigation/qtmaterialtabs.cpp

• tests/widgets/navigation/tst_tabs.cpp

To integrate into the repository:

1. add the new spec source/header to qtmaterial3_specs

2. add the new widget source/header to qtmaterial3_widgets

3. add tst_tabs to tests/CMakeLists.txt

The provided script patches those files automatically.