Add support for navigation views

Documentation/Reference/README.md

@@ -50,6 +50,8 @@
 -   [MenuSection](structs/MenuSection.md)
 -   [ModifierStopper](structs/ModifierStopper.md)
 -   [NavigationSplitView](structs/NavigationSplitView.md)
+-   [NavigationView](structs/NavigationView.md)
+-   [NavigationView.NavigationStack](structs/NavigationView.NavigationStack.md)
 -   [Overlay](structs/Overlay.md)
 -   [OverlaySplitView](structs/OverlaySplitView.md)
 -   [PasswordEntryRow](structs/PasswordEntryRow.md)
@@ -99,7 +101,9 @@
 -   [Edge](enums/Edge.md)
 -   [Icon](enums/Icon.md)
 -   [Icon.DefaultIcon](enums/Icon.DefaultIcon.md)
+-   [NavigationView.Action](enums/NavigationView.Action.md)
 -   [Transition](enums/Transition.md)
+-   [UpdateManager](enums/UpdateManager.md)
 -   [ViewBuilder](enums/ViewBuilder.md)
 -   [ViewBuilder.Component](enums/ViewBuilder.Component.md)
 
@@ -123,6 +127,7 @@
 -   [Menu](extensions/Menu.md)
 -   [MenuItem](extensions/MenuItem.md)
 -   [MenuItemGroup](extensions/MenuItemGroup.md)
+-   [NavigationView](extensions/NavigationView.md)
 -   [OpaquePointer](extensions/OpaquePointer.md)
 -   [OverlaySplitView](extensions/OverlaySplitView.md)
 -   [PasswordEntryRow](extensions/PasswordEntryRow.md)
@@ -154,6 +159,7 @@
 -   [List](typealiases/List.md)
 -   [MenuBuilder](typealiases/MenuBuilder.md)
 -   [MenuContent](typealiases/MenuContent.md)
+-   [NavigationStack](typealiases/NavigationStack.md)
 -   [Scene](typealiases/Scene.md)
 -   [SceneBuilder](typealiases/SceneBuilder.md)
 -   [ScrollView](typealiases/ScrollView.md)

Documentation/Reference/enums/NavigationView.Action.md

@@ -0,0 +1,14 @@
+**ENUM**
+
+# `NavigationView.Action`
+
+An action to run on a view update.
+
+## Cases
+### `pop`
+
+Remove the last item.
+
+### `push(component:)`
+
+Add a new item.

Documentation/Reference/enums/UpdateManager.md

@@ -0,0 +1,16 @@
+**ENUM**
+
+# `UpdateManager`
+
+This type manages view updates.
+
+## Properties
+### `blockUpdates`
+
+The class storing the value.
+
+## Methods
+### `updateViews(force:)`
+
+Update all of the views.
+- Parameter force: Whether to force all views to update.

Documentation/Reference/extensions/NavigationView.md

@@ -0,0 +1,18 @@
+**EXTENSION**
+
+# `NavigationView`
+
+## Properties
+### `componentID`
+
+The ID for the component field in a content storage.
+
+## Methods
+### `init(_:_:content:initialView:)`
+
+Initialize a navigation view.
+- Parameters:
+  - stack: The navigation stack for pushing and popping.
+  - initialTitle: The title of the initial view.
+  - content: The view for a path component.
+  - initialView: The view that is displayed when the path is empty.

Documentation/Reference/structs/Label.md

@@ -34,7 +34,7 @@ visited. In this case, label node also gets a .link style class.
 
 The GtkLabel implementation of the GtkBuildable interface supports a
 custom `<attributes>` element, which supports any number of `<attribute>`
-elements. The <attribute> element has attributes named “name“, “value“,
+elements. The `<attribute>` element has attributes named “name“, “value“,
 “start“ and “end“ and allows you to specify [[email protected]]
 values for this label.
 
@@ -64,8 +64,9 @@ to the functions [[email protected]_with_mnemonic] or
 Mnemonics automatically activate any activatable widget the label is
 inside, such as a [[email protected]]; if the label is not inside the
 mnemonic’s target widget, you have to tell the label about the target
-using [[email protected]_mnemonic_widget]. Here’s a simple example where
-the label is inside a button:
+using [[email protected]_mnemonic_widget].
+
+Here’s a simple example where the label is inside a button:
 
 ```c
 // Pressing Alt+H will activate this button

Documentation/Reference/structs/NavigationView.NavigationStack.md

@@ -0,0 +1,24 @@
+**STRUCT**
+
+# `NavigationView.NavigationStack`
+
+A stack controls a navigation view.
+
+## Properties
+### `action`
+
+The action to run at the next view update, if any.
+
+## Methods
+### `init()`
+
+Initialize a navigation stack.
+
+### `pop()`
+
+Remove the last item from the navigation view.
+
+### `push(_:)`
+
+Add a new item to the navigation view.
+- Parameter component: The component's value.

Documentation/Reference/structs/NavigationView.md

@@ -0,0 +1,248 @@
+**STRUCT**
+
+# `NavigationView`
+
+A page-based navigation container.
+
+<picture><source srcset="navigation-view-dark.png" media="(prefers-color-scheme: dark)"><img src="navigation-view.png" alt="navigation-view"></picture>
+
+`AdwNavigationView` presents one child at a time, similar to
+[[email protected]].
+
+`AdwNavigationView` can only contain [class@NavigationPage] children.
+
+It maintains a navigation stack that can be controlled with
+[[email protected]] and [[email protected]]. The whole
+navigation stack can also be replaced using [[email protected]].
+
+`AdwNavigationView` allows to manage pages statically or dynamically.
+
+Static pages can be added using the [[email protected]] method. The
+`AdwNavigationView` will keep a reference to these pages, but they aren't
+accessible to the user until [[email protected]] is called (except
+for the first page, which is pushed automatically). Use the
+[[email protected]] method to remove them. This is useful for
+applications that have a small number of unique pages and just need
+navigation between them.
+
+Dynamic pages are automatically destroyed once they are popped off the
+navigation stack. To add a page like this, push it using the
+[[email protected]] method without calling
+[[email protected]] first.
+
+## Tags
+
+Static pages, as well as any pages in the navigation stack, can be accessed
+by their [property@NavigationPage:tag]. For example,
+[[email protected]_by_tag] can be used to push a static page that's
+not in the navigation stack without having to keep a reference to it manually.
+
+## Header Bar Integration
+
+When used inside `AdwNavigationView`, [class@HeaderBar] will automatically
+display a back button that can be used to go back to the previous page when
+possible. The button also has a context menu, allowing to pop multiple pages
+at once, potentially across multiple navigation views.
+
+Set [property@HeaderBar:show-back-button] to `FALSE` to disable this behavior
+if it's unwanted.
+
+`AdwHeaderBar` will also display the title of the `AdwNavigationPage` it's
+placed into, so most applications shouldn't need to customize it at all.
+
+## Shortcuts and Gestures
+
+`AdwNavigationView` supports the following shortcuts for going to the
+previous page:
+
+- <kbd>Escape</kbd> (unless [property@NavigationView:pop-on-escape] is set to
+`FALSE`)
+- <kbd>Alt</kbd>+<kbd>←</kbd>
+- Back mouse button
+
+Additionally, it supports interactive gestures:
+
+- One-finger swipe towards the right on touchscreens
+- Scrolling towards the right on touchpads (usually two-finger swipe)
+
+These gestures have transitions enabled regardless of the
+[property@NavigationView:animate-transitions] value.
+
+Applications can also enable shortcuts for pushing another page onto the
+navigation stack via connecting to the [signal@NavigationView::get-next-page]
+signal, in that case the following shortcuts are supported:
+
+- <kbd>Alt</kbd>+<kbd>→</kbd>
+- Forward mouse button
+- Swipe/scrolling towards the left
+
+For right-to-left locales, the gestures and shortcuts are reversed.
+
+[property@NavigationPage:can-pop] can be used to disable them, along with the
+header bar back buttons.
+
+## Actions
+
+`AdwNavigationView` defines actions for controlling the navigation stack.
+actions for controlling the navigation stack:
+
+- `navigation.push` takes a string parameter specifying the tag of the page to
+push, and is equivalent to calling [[email protected]_by_tag].
+
+- `navigation.pop` doesn't take any parameters and pops the current page from
+the navigation stack, equivalent to calling [[email protected]].
+
+## `AdwNavigationView` as `GtkBuildable`
+
+`AdwNavigationView` allows to add pages as children, equivalent to using the
+[[email protected]] method.
+
+Example of an `AdwNavigationView` UI definition:
+
+```xml
+<object class="AdwNavigationView"><child><object class="AdwNavigationPage"><property name="title" translatable="yes">Page 1</property><property name="child"><object class="AdwToolbarView"><child type="top"><object class="AdwHeaderBar"/></child><property name="content"><object class="GtkButton"><property name="label" translatable="yes">Open Page 2</property><property name="halign">center</property><property name="valign">center</property><property name="action-name">navigation.push</property><property name="action-target">'page-2'</property><style><class name="pill"/></style></object></property></object></property></object></child><child><object class="AdwNavigationPage"><property name="title" translatable="yes">Page 2</property><property name="tag">page-2</property><property name="child"><object class="AdwToolbarView"><child type="top"><object class="AdwHeaderBar"/></child><property name="content"><!-- ... --></property></object></property></object></child></object>
+```
+
+<picture><source srcset="navigation-view-example-dark.png" media="(prefers-color-scheme: dark)"><img src="navigation-view-example.png" alt="navigation-view-example"></picture>
+
+## CSS nodes
+
+`AdwNavigationView` has a single CSS node with the name `navigation-view`.
+
+## Accessibility
+
+`AdwNavigationView` uses the `GTK_ACCESSIBLE_ROLE_GROUP` role.
+
+## Properties
+### `updateFunctions`
+
+Additional update functions for type extensions.
+
+### `appearFunctions`
+
+Additional appear functions for type extensions.
+
+### `animateTransitions`
+
+Whether to animate page transitions.
+
+Gesture-based transitions are always animated.
+
+### `popOnEscape`
+
+Whether pressing Escape pops the current page.
+
+Applications using `AdwNavigationView` to implement a browser may want to
+disable it.
+
+### `getNextPage`
+
+Emitted when a push shortcut or a gesture is triggered.
+
+To support the push shortcuts and gestures, the application is expected to
+return the page to push in the handler.
+
+This signal can be emitted multiple times for the gestures, for example
+when the gesture is cancelled by the user. As such, the application must
+not make any irreversible changes in the handler, such as removing the page
+from a forward stack.
+
+Instead, it should be done in the [signal@NavigationView::pushed] handler.
+
+### `popped`
+
+Emitted after @page has been popped from the navigation stack.
+
+See [[email protected]].
+
+When using [[email protected]_to_page] or
+[[email protected]_to_tag], this signal is emitted for each of the
+popped pages.
+
+### `pushed`
+
+Emitted after a page has been pushed to the navigation stack.
+
+See [[email protected]].
+
+### `replaced`
+
+Emitted after the navigation stack has been replaced.
+
+See [[email protected]].
+
+### `app`
+
+The application.
+
+### `window`
+
+The window.
+
+## Methods
+### `init()`
+
+Initialize `NavigationView`.
+
+### `container(modifiers:)`
+
+Get the widget's view storage.
+- Parameter modifiers: The view modifiers.
+- Returns: The view storage.
+
+### `update(_:modifiers:updateProperties:)`
+
+Update the widget's view storage.
+- Parameters:
+    - storage: The view storage.
+    - modifiers: The view modifiers.
+    - updateProperties: Whether to update the view's properties.
+
+### `animateTransitions(_:)`
+
+Whether to animate page transitions.
+
+Gesture-based transitions are always animated.
+
+### `popOnEscape(_:)`
+
+Whether pressing Escape pops the current page.
+
+Applications using `AdwNavigationView` to implement a browser may want to
+disable it.
+
+### `getNextPage(_:)`
+
+Emitted when a push shortcut or a gesture is triggered.
+
+To support the push shortcuts and gestures, the application is expected to
+return the page to push in the handler.
+
+This signal can be emitted multiple times for the gestures, for example
+when the gesture is cancelled by the user. As such, the application must
+not make any irreversible changes in the handler, such as removing the page
+from a forward stack.
+
+Instead, it should be done in the [signal@NavigationView::pushed] handler.
+
+### `popped(_:)`
+
+Emitted after @page has been popped from the navigation stack.
+
+See [[email protected]].
+
+When using [[email protected]_to_page] or
+[[email protected]_to_tag], this signal is emitted for each of the
+popped pages.
+
+### `pushed(_:)`
+
+Emitted after a page has been pushed to the navigation stack.
+
+See [[email protected]].
+
+### `replaced(_:)`
+
+Emitted after the navigation stack has been replaced.
+
+See [[email protected]].