NavPanel

The panel renders the tree given to Items, with a header, a search box and the toggle button on top of it. Each BitNavItem carries its Text, an optional IconName, Description and Url, and the items nested in its ChildItems turn it into an expandable node. Typing in the search box filters the list, and the toggle button collapses the panel down to a rail of icons.

By default the panel takes the width its container gives it. FitWidth shrinks it to the width of its widest item, so it takes no more room than the items it holds. Its width is then the items' rather than the panel's, and they lose their text the moment the panel collapses - so this is the one mode whose toggle resizes in a single step instead of sliding.

FullWidth stretches the panel over the whole width of its container, which is what a panel sitting in a column of its own usually wants.

Width gives the panel a width of its own in px, and ToggledWidth does the same for the rail it collapses into, so the two states are sized without a stylesheet. Both are ignored in the FitWidth and FullWidth modes, which decide the width themselves.

ExpandOnHover brings the collapsed panel back to its full width while the pointer is over it - or while the keyboard is inside it, so the text of the items is reachable without a mouse - so the rail stays a rail and still shows what its icons stand for on the way to one. The panel widens in place, which moves the content beside it along with it. Collapse the panel below with its toggle button, then hover it or tab into it.

NoToggle removes the rail mode altogether: the toggle button is gone and the panel can no longer be collapsed, not even through IsToggled or the Toggle method. HideToggle only takes the button away and leaves the mode itself in place, for a panel that is toggled from somewhere else on the page. ToggleAriaLabel renames the button the two of them take away, which otherwise says what it is about to do in English.

IconUrl renders a logo at the start of the header, and IconNavUrl wraps it in an anchor pointing at the home page of the app. The logo is hidden while the panel is collapsed into its rail, where there is no room for it. IconAriaLabel is what a screen reader reads it as - the name of the link, or the alternative text of the bare image - which is not the same thing as the name of the navigation landmark AriaLabel gives the nav.

SearchBoxPlaceholder replaces the text shown in the empty search box, and doubles as its accessible name and as the tooltip of the search button the rail shows in place of the box. SearchIcon and SearchIconName replace the glyph of that button.

NoSearchBox removes the search box, for a short menu that has nothing to filter.

An item matches when every word of the term appears in its Text, its Description or its Data, so each word typed narrows the list further; a matched item keeps the whole branch under it, so a group that matches still shows what it groups. SearchText two-way binds the term, so the search can be driven from anywhere on the page, OnSearch reports every change of it, and SearchDebounceTime sets how long the typing settles before the list is filtered. SearchFilter replaces the matching itself with a function of your own - here only the text of an item is looked at, and only from its start. However many items the search leaves, a live region announces the count to a screen reader, which SearchAnnouncementProvider rewrites for a localized app.

Searching for something that is nowhere in the list replaces it with a message. EmptyListMessage changes the text of that message, and EmptyListTemplate replaces it with markup of your own.

In the default Automatic mode the panel keeps the selection in sync with the current URL, matched as NavMatch says (exactly, by prefix, by wildcard or by regular expression) and against the AdditionalUrls of an item as well as its own. The Manual mode hands that over to the app: the clicked item becomes the selected one, the initial selection comes from DefaultSelectedItem (which the automatic mode has no use for, since the URL is what decides there), and SelectedItem two-way binds it so the selection can be driven from anywhere else on the page. Reselectable reports a click on the item that is already selected as a selection of its own.

AllExpanded opens every group as it is first rendered, SingleExpand keeps a single open branch at a time - opening one closes the one that was open - and NoCollapse hides the chevrons altogether, for a tree that is only ever opened by the URL or by the selection. ExpandAriaLabel and CollapseAriaLabel name the chevron in each of its two states, for the items that carry no name of their own for it. The panel below is in single-expand mode.

The panel is generic, so any class can be the item type. NameSelectors is what tells it where to read each field from: a property name, or a selector function when the value is computed. Anything left out keeps the name it has on BitNavItem.

On a small screen the open panel closes on a click on the overlay behind it, on the Escape key, on a swipe towards the side it came from, and on the navigation of an item. NoAutoClose keeps it open after a navigation, NoOverlay drops the overlay so the page behind it stays clickable, and NoSwipe turns the swipe gesture off. The panel below shows all three, so the only ways left to close it are its own button and the Escape key, which none of the three takes away. AutoFocus goes the other way and moves the focus into the drawer as it opens - onto the search box, or onto the first item of a panel without one - which is what a surface covering the page is expected to do. All of these belong to the drawer of a small screen: the column of a wide one is not a surface over the page, so it neither closes on the Escape key nor takes the focus.

Header and Footer replace the two ends of the panel - the header replaces the logo and the buttons beside it, so a custom header that wants to keep the rail renders a control of its own calling the Toggle method - while ItemTemplate customizes how the content of every item is rendered, and HeaderTemplate does the same for the group headers of the Grouped render type. ItemTemplateRenderMode and HeaderTemplateRenderMode decide whether a template fills the link the panel renders, or replaces it outright.

OnItemClick reports every click on an item, OnItemToggle every expand and collapse of a group, and OnSelectItem the item that became the selected one.

Clicked item:
Toggled item:

A reference to the panel drives it from the outside: Toggle switches the rail on and off, Open and Close drive the small-screen drawer, ExpandAll and CollapseAll open and close every group, ClearSearch empties the search box, and FocusSearchBox moves the focus into it, leaving the rail first when the panel is collapsed. One item at a time is reached the same way: ExpandItem, CollapseItem and ToggleItem open and close a single branch, IsItemExpanded reports whether one is open, SelectItem selects an item exactly like a click on it would, and FocusItem moves the focus onto it, opening the branches it is nested in on the way.

RenderType set to Grouped turns every root item into the header of the group it holds instead of a link of its own, which is what a long menu split into named sections wants. ReversedChevron moves the expander to the far end of each row, IndentValue sets how far every level of depth is indented - with IndentPadding and IndentReversedPadding for the room a row without children leaves in place of a chevron - and NoPad takes the padding off the panel so its rows run to its edges.

Below the md breakpoint the panel is an off-canvas drawer that covers the page, and it behaves like the modal surface it looks like: it reports itself as a dialog, the page behind it stops scrolling, the focus stays inside it so Tab cannot wander onto the page underneath, and it is handed back to whatever held it once the drawer closes. Position decides which edge the drawer comes from - End docks it to the other side, and the swipe that closes it goes that way too - while NoScrollLock, NoFocusTrap and NoRestoreFocus each give one of those three behaviors back. A panel with NoOverlay never covers the page at all, so none of them apply to it. ShowCloseButton puts a close button in the header for the screens the panel is a drawer on - where the toggle button, which collapses a permanent panel into a rail, has nothing to do - so a touch user has something to aim at besides the overlay and the swipe; CloseIcon, CloseIconName and CloseAriaLabel describe it. Narrow the window below the breakpoint to see all of it.

The panel scrolls as one by default, so a long list carries the header and the search box out of sight along with it. StickyEnds hands the overflow to the items instead: the header (with the box that filters them) and the footer stay where they are, and only the list between them scrolls.

Color sets the color of the parts that carry one - the icons, the search box and the selection - and Accent paints the background of the panel itself.

Besides the built-in icons, the Icon of an item, the ToggleIcon of the toggle button and the ChevronDownIcon of the expanders all accept the CSS classes of any external icon library, such as FontAwesome or Bootstrap Icons, and take precedence over their name-based counterparts.

Size scales the metrics of every item at once: the height of the rows, the size of their icons, and the size of their text and description.

Styles and Classes reach every part of the panel itself, while NavStyles / NavClasses and SearchBoxStyles / SearchBoxClasses pass the same kind of map on to the nav and the search box inside it.

Set Dir to BitDir.Rtl to render the panel in a right-to-left layout: it docks to the right, the indentation and the chevrons flip, and the swipe that closes it goes the other way.