Navigation Component: Composition Proposal

docs/manifest.json

@@ -1055,6 +1055,12 @@
 		"markdown_source": "../packages/components/src/navigable-container/README.md",
 		"parent": "components"
 	},
+	{
+		"title": "Navigation",
+		"slug": "navigation",
+		"markdown_source": "../packages/components/src/navigation/README.md",
+		"parent": "components"
+	},
 	{
 		"title": "Notice",
 		"slug": "notice",

packages/components/CHANGELOG.md

@@ -2,6 +2,8 @@
 
 ## Unreleased
 
+- Introduce `Navigation` component as `__experimentalNavigation` for displaying a hierarchy of items.
+
 ## 10.0.0 (2020-07-07)
 
 ### Breaking Change

packages/components/src/index.js

@@ -67,6 +67,10 @@ export { default as MenuItemsChoice } from './menu-items-choice';
 export { default as Modal } from './modal';
 export { default as ScrollLock } from './scroll-lock';
 export { NavigableMenu, TabbableContainer } from './navigable-container';
+export { default as __experimentalNavigation } from './navigation';
+export { default as __experimentalNavigationGroup } from './navigation/group';
+export { default as __experimentalNavigationItem } from './navigation/item';
+export { default as __experimentalNavigationLevel } from './navigation/level';
 export { default as Notice } from './notice';
 export { default as __experimentalNumberControl } from './number-control';
 export { default as NoticeList } from './notice/list';

packages/components/src/navigation/README.md

@@ -0,0 +1,174 @@
+# Navigation
+
+Render a navigation list with optional groupings and hierarchy.
+
+## Usage
+
+```jsx
+import {
+	__experimentalNavigation as Navigation,
+	__experimentalNavigationGroup as NavigationGroup,
+	__experimentalNavigationItem as NavigationItem,
+	__experimentalNavigationLevel as NavigationLevel,
+} from '@wordpress/components';
+
+const MyNavigation = () => {
+	const [ activeItem, setActiveItem ] = useState( 'item-1' );
+	const [ activeLevel, setActiveLevel ] = useState( 'root' );
+
+	return (
+		<Navigation
+			activeItem={ activeItem }
+			activeLevel={ activeLevel }
+			setActiveItem={ setActiveItem }
+			setActiveLevel={ setActiveLevel }
+		>
+			<NavigationLevel title="Home">
+				<NavigationGroup title="Group 1">
+					<NavigationItem item="item-1" title="Item 1" />
+					<NavigationItem item="item-2" title="Item 2" />
+				</NavigationGroup>
+				<NavigationGroup title="Group 2">
+					<NavigationItem
+						item="item-3"
+						navigateToLevel="category"
+						title="Category"
+					/>
+				</NavigationGroup>
+			</NavigationLevel>
+
+			<NavigationLevel
+				level="category"
+				parentLevel="root"
+				parentLevelTitle="Home"
+				title="Category"
+			>
+				<ul>
+					<NavigationItem
+						badge="1"
+						item="child-1"
+						title="Child 1"
+					/>
+					<NavigationItem item="child-2" title="Child 2" />
+				</ul>
+			</NavigationLevel>
+		</Navigation>
+	);
+};
+```
+
+## Navigation Props
+
+`Navigation` supports the following props.
+
+### `activeItem`
+
+-   Type: `string`
+-   Required: No
+
+The active item slug.
+
+### `activeLevel`
+
+-   Type: `string`
+-   Required: No
+-   Default: "root"
+
+The active level slug.
+
+### `setActiveItem`
+
+-   Type: `function`
+-   Required: No
+
+Sync the active item between the external state and the Navigation's internal state.
+
+### `setActiveLevel`
+
+-   Type: `function`
+-   Required: No
+
+Sync the active level between the external state and the Navigation's internal state.
+
+## Navigation Level
+
+`NavigationLevel` supports the following props.
+
+### `level`
+
+-   Type: `string`
+-   Required: No
+-   Default: "root"
+
+The level slug.
+
+### `parentLevel`
+
+-   Type: `string`
+-   Required: No
+
+The parent level slug; used by nested levels to indicate their parent level.
+
+### `parentLevelTitle`
+
+-   Type: `string`
+-   Required: No
+
+The parent level title; used as back button label by nested levels.
+
+### `title`
+
+-   Type: `string`
+-   Required: No
+
+The level title.
+
+## Navigation Group
+
+`NavigationGroup` supports the following props.
+
+### `title`
+
+-   Type: `string`
+-   Required: No
+
+The group title.
+
+## Navigation Item
+
+`NavigationItem` supports the following props.
+
+### `badge`
+
+-   Type: `string|Number`
+-   Required: No
+
+The item badge content.
+
+### `href`
+
+-   Type: `string`
+-   Required: No
+
+If provided, renders `a` instead of `button`.
+
+### `navigateToLevel`
+
+-   Type: `string`
+-   Required: No
+
+The child level slug. If provided, clicking on the item will navigate to the target level.
+
+### `onClick`
+
+-   Type: `function`
+-   Required: No
+
+A callback to handle clicking on a menu item.
+
+### `title`
+
+-   Type: `string`
+-   Required: No
+
+The item title.

packages/components/src/navigation/context.js

@@ -0,0 +1,22 @@
+/**
+ * External dependencies
+ */
+import { noop } from 'lodash';
+
+/**
+ * WordPress dependencies
+ */
+import { createContext, useContext } from '@wordpress/element';
+
+/**
+ * Internal dependencies
+ */
+import { DEFAULT_LEVEL } from './utils';
+
+export const NavigationContext = createContext( {
+	activeItem: undefined,
+	activeLevel: DEFAULT_LEVEL,
+	setActiveItem: noop,
+	setActiveLevel: noop,
+} );
+export const useNavigationContext = () => useContext( NavigationContext );

packages/components/src/navigation/group.js

@@ -0,0 +1,21 @@
+/**
+ * Internal dependencies
+ */
+import { MenuGroupTitleUI } from './styles/navigation-styles';
+
+export default function NavigationGroup( { children, title } ) {
+	return (
+		<div className="components-navigation__menu-group">
+			{ title && (
+				<MenuGroupTitleUI
+					as="h3"
+					className="components-navigation__menu-group-title"
+					variant="caption"
+				>
+					{ title }
+				</MenuGroupTitleUI>
+			) }
+			<ul>{ children }</ul>
+		</div>
+	);
+}

packages/components/src/navigation/index.js

@@ -0,0 +1,87 @@
+/**
+ * External dependencies
+ */
+import classnames from 'classnames';
+import { noop } from 'lodash';
+
+/**
+ * WordPress dependencies
+ */
+import { useEffect, useRef, useState } from '@wordpress/element';
+
+/**
+ * Internal dependencies
+ */
+import Animate from '../animate';
+import { NavigationContext } from './context';
+import { DEFAULT_LEVEL } from './utils';
+import { Root } from './styles/navigation-styles';
+
+export default function Navigation( {
+	children,
+	activeItem,
+	activeLevel = DEFAULT_LEVEL,
+	setActiveItem = noop,
+	setActiveLevel = noop,
+} ) {
+	const [ item, setItem ] = useState( activeItem );
+	const [ level, setLevel ] = useState( activeLevel );
+	const [ slideOrigin, setSlideOrigin ] = useState();
+
+	const activateItem = ( itemId ) => {
+		setItem( itemId );
+		setActiveItem( itemId );
+	};
+
+	const activateLevel = ( levelId, slideInOrigin = 'left' ) => {
+		setSlideOrigin( slideInOrigin );
+		setLevel( levelId );
+		setActiveLevel( levelId );
+	};
+
+	const isMounted = useRef( false );
+	useEffect( () => {
+		if ( ! isMounted.current ) {
+			isMounted.current = true;
+		}
+	}, [] );
+
+	useEffect( () => {
+		if ( activeItem !== item ) {
+			activateItem( activeItem );
+		}
+		if ( activeLevel !== level ) {
+			activateLevel( activeLevel );
+		}
+	}, [ activeItem, activeLevel ] );
+
+	const context = {
+		activeItem: item,
+		activeLevel: level,
+		setActiveItem: activateItem,
+		setActiveLevel: activateLevel,
+	};
+
+	return (
+		<Root className="components-navigation">
+			<Animate
+				key={ level }
+				type="slide-in"
+				options={ { origin: slideOrigin } }
+			>
+				{ ( { className: animateClassName } ) => (
+					<div
+						className={ classnames( {
+							[ animateClassName ]:
+								isMounted.current && slideOrigin,
+						} ) }
+					>
+						<NavigationContext.Provider value={ context }>
+							{ children }
+						</NavigationContext.Provider>
+					</div>
+				) }
+			</Animate>
+		</Root>
+	);
+}