Navigation Utilities

These functions parse and process the navigation property from a blocklet's metadata and state, enabling the construction of dynamic and coherent user interfaces. They handle complex tasks such as merging navigation from multiple components, handling custom user configurations, and structuring the data for different UI sections.

Core Function#

The primary function is parseNavigation, which orchestrates the entire process of generating the final navigation structure. It combines built-in navigation defined in blocklet.yml files with custom navigation stored in the blocklet's settings.

parseNavigation(blocklet, options)#

Processes a blocklet's full state to produce a comprehensive and unified navigation structure, merging definitions from blocklet.yml and user settings.

Processing Flow

Parameters

Name	Type	Description
blocklet	Blocklet	The blocklet state object, which includes metadata, children, and settings.
options	ParseNavigationOption	Optional. Configuration for the parsing process.
options.beforeProcess	(data) => any	An optional function to preprocess the built-in navigation data before it is compacted and merged.

Returns

An object containing the processed navigation data:

Name	Type	Description
navigationList	NavigationItem[]	The final, merged, and deduplicated list of navigation items from both built-in and custom sources.
components	ComponentItem[]	A list of all components that contribute navigation items, along with their mount points.
builtinList	NavigationItem[]	The processed list of navigation items derived purely from blocklet.yml files.

Example

Tree & List Manipulation Utilities#

These are helper functions for traversing and transforming the tree-like navigation structures.

deepWalk(tree, callback, options)#

Recursively traverses a tree-like structure and executes a callback for each node.

Name	Type	Description
tree	TreeNode	The tree or array of trees to traverse.
callback	(current, parent, options) => void	The function to execute on each node. Receives the current node, its parent, and an object with { index, level }.
options	object	Configuration for the traversal.
options.key	string	The property name for the children array (default: 'items').
options.order	'first' | 'last'	The traversal order: 'first' for pre-order, 'last' for post-order (default: 'first').

flattenNavigation(list, options)#

Flattens a navigation tree to a specified depth, creating a flat list.

Name	Type	Description
list	NavigationItem[]	The navigation tree to flatten.
options	object	Optional. Configuration for flattening.
options.depth	number	The depth to flatten to (default: 1, resulting in a completely flat list).
options.transform	(current, parent) => any	A function to transform each item as it's being flattened.

nestNavigationList(list)#

Converts a flat list of navigation items that have parent properties back into a nested tree structure. It's the conceptual inverse of flattenNavigation.

Example

splitNavigationBySection(navigation)#

Splits a navigation tree into multiple trees, one for each unique section (e.g., 'header', 'footer'). This is useful for rendering different menus in different parts of the UI.

compactNavigation(navigation, depth)#

Compacts a multi-level navigation tree to a maximum specified depth. During compaction, properties from parent items (like link, section, role) are inherited by their children, and component names are concatenated.

Filtering & Cleanup Utilities#

Functions to filter, clean, and organize navigation lists for final presentation.

filterNavigation(navigationList, components)#

Filters out navigation items that should not be visible. It removes items explicitly marked as visible: false and also hides items whose associated component is not present in the provided components list.

cleanOrphanNavigation(list)#

Cleans up the navigation structure by promoting single-child menu items to their parent's level. This simplifies the UI by removing unnecessary sub-menus, particularly for sections like 'header' and 'footer'.

uniq(navigation)#

Removes duplicate navigation items from the list. An item is considered a duplicate if it has the same link and section as another item that appears earlier in the list.

sortRootNavigation(navigation)#

Sorts the root-level navigation items to ensure a consistent order, specifically placing the /team navigation item first if it exists.

cleanOldNavigationHistory(navigation)#

An internal utility to clean up specific historical navigation data that may exist in older configurations, ensuring a clean state.

Link & Section Utilities#

joinLink(navigation, components)#

Recursively walks through a navigation tree and correctly joins parent and child link segments to form absolute paths. It resolves links for items defined by components by prefixing them with the component's mountPoint.

isMatchSection(sections, section)#

Checks if a given section matches a navigation item's sections property, which can be a single string or an array of strings. Returns true if there is a match.

checkLink(link)#

A simple utility to validate if a given link is a string that should be processed for path joining. It helps differentiate between navigation items that are links versus those that are just containers for sub-menus.