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 heirarchy of items.
+
 ## 10.0.0 (2020-07-07)
 
 ### Breaking Change

packages/components/src/index.js

@@ -67,6 +67,11 @@ 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,
+	NavigationMenu as __experimentalNavigationMenu,
+	NavigationMenuItem as __experimentalNavigationMenuItem,
+} from './navigation';
 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,155 @@
+# Navigation
+
+Render a flat array of menu items into a waterfall style hierarchy navigation.
+
+## Usage
+
+```jsx
+import {
+	__experimentalNavigation as Navigation,
+	__experimentalNavigationMenu as NavigationMenu,
+	__experimentalNavigationMenuItem as NavigationMenuItem,
+} from '@wordpress/components';
+import { useState } from '@wordpress/compose';
+
+const data = [
+    {
+		title: 'Item 1',
+		id: 'item-1',
+	},
+	{
+		title: 'Item 2',
+		id: 'item-2',
+	},
+	{
+		title: 'Category',
+		id: 'item-3',
+		badge: '2',
+	},
+	{
+		title: 'Child 1',
+		id: 'child-1',
+		parent: 'item-3',
+		badge: '1',
+	},
+	{
+		title: 'Child 2',
+		id: 'child-2',
+		parent: 'item-3',
+	},
+];
+
+const MyNavigation = () => {
+    const [ active, setActive ] = useState( 'item-1' );
+
+	return (
+		<Navigation activeItemId={ active } data={ data } rootTitle="Home">
+			{ ( { level, parentLevel, NavigationBackButton } ) => {
+				return (
+					<>
+						{ parentLevel && (
+							<NavigationBackButton>
+								<Icon icon={ arrowLeft } />
+								{ parentLevel.title }
+							</NavigationBackButton>
+						) }
+						<h1>{ level.title }</h1>
+						<NavigationMenu>
+							{ level.children.map( ( item ) => {
+								return (
+									<NavigationMenuItem
+										{ ...item }
+										key={ item.id }
+										onClick={ ( selected ) =>
+											setActive( selected.id )
+										}
+									/>
+								);
+							} ) }
+						</NavigationMenu>
+					</>
+				);
+			} }
+		</Navigation>
+};
+```
+
+## Navigation Props
+
+Navigation supports the following props.
+
+### `data`
+
+-   Type: `array`
+-   Required: Yes
+
+An array of config objects for each menu item.
+
+Config objects can be represented
+
+#### `data.title`
+
+-   Type: `string`
+-   Required: Yes
+
+A menu item's title.
+
+#### `data.id`
+
+-   Type: `string|Number`
+-   Required: Yes
+
+A menu item's id.
+
+#### `data.parent`
+
+-   Type: `string|Number`
+-   Required: No
+
+Specify a menu item's parent id. Defaults to the menu item's parent if none is provided.
+
+#### `data.href`
+
+-   Type: `string`
+-   Required: No
+
+Turn a menu item into a link by supplying a url.
+
+#### `data.linkProps`
+
+-   Type: `object`
+-   Required: No
+
+Supply properties passed to the menu-item.
+
+#### `data.LinkComponent`
+
+-   Type: `Node`
+-   Required: No
+
+Supply a React component to render as the menu item. This is useful for router link components for internal navigation.
+
+### `activeItemId`
+
+-   Type: `string`
+-   Required: Yes
+
+The active screen id.
+
+### `rootTitle`
+
+-   Type: `string`
+-   Required: No
+
+A top level title.
+
+## NavigationMenuItem Props
+
+NavigationMenuItem supports the following props.
+
+### `onClick`
+
+-   Type: `function`
+-   Required: No
+
+A callback to handle selection of a menu item.

packages/components/src/navigation/components-composition-navigation.js

@@ -0,0 +1,141 @@
+/**
+ * External dependencies
+ */
+import classnames from 'classnames';
+
+/**
+ * WordPress dependencies
+ */
+import { useEffect, useState, useRef } from '@wordpress/element';
+import { Icon, chevronLeft, chevronRight } from '@wordpress/icons';
+
+/**
+ * Internal dependencies
+ */
+import Animate from '../animate';
+import {
+	BackButtonUI,
+	MenuItemTitleUI,
+	MenuItemUI,
+	MenuTitleUI,
+	MenuUI,
+	Root,
+} from './styles/navigation-styles';
+import Button from '../button';
+
+export default function ComponentsCompositionNavigation( {
+	initialActiveLevel,
+	children,
+} ) {
+	const [ activeLevel, setActiveLevel ] = useState( initialActiveLevel );
+	const [ slideOrigin, setSlideOrigin ] = useState( 'left' );
+
+	const isMounted = useRef( false );
+	useEffect( () => {
+		if ( ! isMounted.current ) {
+			isMounted.current = true;
+		}
+	}, [] );
+
+	const navigateTo = ( level ) => {
+		setActiveLevel( level );
+		setSlideOrigin( 'left' );
+	};
+
+	const navigateBack = ( level ) => {
+		setActiveLevel( level );
+		setSlideOrigin( 'right' );
+	};
+
+	function NavigationLevel( {
+		children: levelChildren,
+		slug,
+		title,
+		parentLevel,
+		parentTite,
+	} ) {
+		if ( activeLevel !== slug ) {
+			return null;
+		}
+
+		return (
+			<div className="components-navigation__level">
+				{ parentLevel ? (
+					<BackButtonUI
+						className="components-navigation__back-button"
+						isTertiary
+						onClick={ () => navigateBack( parentLevel ) }
+					>
+						<Icon icon={ chevronLeft } />
+						{ parentTite }
+					</BackButtonUI>
+				) : null }
+				<MenuUI>
+					<MenuTitleUI
+						variant="subtitle"
+						className="components-navigation__menu-title"
+					>
+						{ title }
+					</MenuTitleUI>
+					<ul>{ levelChildren }</ul>
+				</MenuUI>
+			</div>
+		);
+	}
+
+	const NavigationCategory = ( { title, navigateTo: to } ) => {
+		return (
+			<MenuItemUI className="components-navigation__menu-item">
+				<Button onClick={ () => navigateTo( to ) }>
+					{ title }
+					<Icon icon={ chevronRight } />
+				</Button>
+			</MenuItemUI>
+		);
+	};
+
+	return (
+		<Root className="components-navigation">
+			<Animate
+				key={ activeLevel }
+				type="slide-in"
+				options={ { origin: slideOrigin } }
+			>
+				{ ( { className: animateClassName } ) => (
+					<div
+						className={ classnames( {
+							[ animateClassName ]: isMounted.current,
+						} ) }
+					>
+						{ children( {
+							activeLevel,
+							navigateTo,
+							NavigationCategory,
+							NavigationLevel,
+						} ) }
+					</div>
+				) }
+			</Animate>
+		</Root>
+	);
+}
+
+export function NavigationItem( { slug, title, onClick, activeItem } ) {
+	const classes = classnames( 'components-navigation__menu-item', {
+		'is-active': activeItem === slug,
+	} );
+
+	return (
+		<MenuItemUI className={ classes }>
+			<Button onClick={ onClick }>
+				<MenuItemTitleUI
+					className="components-navigation__menu-item-title"
+					variant="body.small"
+					as="span"
+				>
+					{ title }
+				</MenuItemTitleUI>
+			</Button>
+		</MenuItemUI>
+	);
+}