@wordpress/boot 0.1.1-next.2f1c7c01b.0

package/src/components/app/router.tsx

@@ -0,0 +1,198 @@
+/**
+ * External dependencies
+ */
+import {
+	createRouter,
+	createRootRoute,
+	createRoute,
+	RouterProvider,
+	createBrowserHistory,
+	type AnyRoute,
+} from '@tanstack/react-router';
+import { parseHref } from '@tanstack/history';
+import type { ComponentType } from 'react';
+
+/**
+ * WordPress dependencies
+ */
+import { __ } from '@wordpress/i18n';
+import { lazy, useState, useEffect } from '@wordpress/element';
+import { Page } from '@wordpress/admin-ui';
+
+/**
+ * Internal dependencies
+ */
+import Root from '../root';
+import type { Route, RouteLoaderContext } from '../../store/types';
+
+// Not found component
+function NotFoundComponent() {
+	return (
+		<div className="boot-layout__stage">
+			<Page title={ __( 'Route not found' ) } hasPadding>
+				{ __( "The page you're looking for does not exist" ) }
+			</Page>
+		</div>
+	);
+}
+
+function RouteComponent( {
+	stage: Stage,
+	inspector: Inspector,
+}: {
+	stage?: ComponentType;
+	inspector?: ComponentType;
+} ) {
+	return (
+		<>
+			{ Stage && (
+				<div className="boot-layout__stage">
+					<Stage />
+				</div>
+			) }
+			{ Inspector && (
+				<div className="boot-layout__inspector">
+					<Inspector />
+				</div>
+			) }
+		</>
+	);
+}
+
+/**
+ * Creates a TanStack route from a Route definition.
+ *
+ * @param route       Route configuration
+ * @param parentRoute Parent route.
+ * @return Tanstack Route.
+ */
+async function createRouteFromDefinition(
+	route: Route,
+	parentRoute: AnyRoute
+) {
+	// Create lazy components for stage and inspector surfaces
+	const SurfacesModule = route.content_module
+		? lazy( async () => {
+				const module = await import( route.content_module! );
+				// Return a component that renders the surfaces
+				return {
+					default: () => (
+						<RouteComponent
+							stage={ module.stage }
+							inspector={ module.inspector }
+						/>
+					),
+				};
+		  } )
+		: () => null;
+
+	// Load route module for lifecycle functions if specified
+	let routeConfig: {
+		beforeLoad?: ( context: RouteLoaderContext ) => void | Promise< void >;
+		loader?: ( context: RouteLoaderContext ) => Promise< unknown >;
+	} = {};
+
+	if ( route.route_module ) {
+		const module = await import( route.route_module );
+		routeConfig = module.route || {};
+	}
+
+	return createRoute( {
+		getParentRoute: () => parentRoute,
+		path: route.path,
+		beforeLoad: routeConfig.beforeLoad
+			? async ( opts: any ) => {
+					const context: RouteLoaderContext = {
+						params: opts.params || {},
+						search: opts.search || {},
+					};
+					await routeConfig.beforeLoad!( context );
+			  }
+			: undefined,
+		loader: routeConfig.loader
+			? async ( opts: any ) => {
+					const context: RouteLoaderContext = {
+						params: opts.params || {},
+						search: opts.search || {},
+					};
+					return await routeConfig.loader!( context );
+			  }
+			: undefined,
+		component: SurfacesModule,
+	} );
+}
+
+/**
+ * Creates a route tree from route definitions.
+ *
+ * @param routes Routes definition.
+ * @return Router tree.
+ */
+async function createRouteTree( routes: Route[] ) {
+	const rootRoute = createRootRoute( {
+		component: Root,
+		context: () => ( {} ),
+	} );
+
+	// Create routes from definitions
+	const dynamicRoutes = await Promise.all(
+		routes.map( ( route ) => createRouteFromDefinition( route, rootRoute ) )
+	);
+
+	return rootRoute.addChildren( dynamicRoutes );
+}
+
+// Create custom history that parses ?p= query parameter
+function createPathHistory() {
+	return createBrowserHistory( {
+		parseLocation: () => {
+			const url = new URL( window.location.href );
+			const path = url.searchParams.get( 'p' ) || '/';
+			const pathHref = `${ path }${ url.hash }`;
+			return parseHref( pathHref, window.history.state );
+		},
+		createHref: ( href ) => {
+			const searchParams = new URLSearchParams( window.location.search );
+			searchParams.set( 'p', href );
+			return `${ window.location.pathname }?${ searchParams }`;
+		},
+	} );
+}
+
+interface RouterProps {
+	routes: Route[];
+}
+
+export default function Router( { routes }: RouterProps ) {
+	const [ router, setRouter ] = useState< any >( null );
+
+	useEffect( () => {
+		let cancelled = false;
+
+		async function initializeRouter() {
+			const history = createPathHistory();
+			const routeTree = await createRouteTree( routes );
+
+			if ( ! cancelled ) {
+				const newRouter = createRouter( {
+					history,
+					routeTree,
+					defaultNotFoundComponent: NotFoundComponent,
+				} );
+				setRouter( newRouter );
+			}
+		}
+
+		initializeRouter();
+
+		return () => {
+			cancelled = true;
+		};
+	}, [ routes ] );
+
+	if ( ! router ) {
+		return <div>Loading routes...</div>;
+	}
+
+	return <RouterProvider router={ router } />;
+}

package/src/components/navigation/drilldown-item/index.tsx

@@ -0,0 +1,88 @@
+/**
+ * External dependencies
+ */
+import clsx from 'clsx';
+import type { ReactNode } from 'react';
+
+/**
+ * WordPress dependencies
+ */
+import {
+	FlexBlock,
+	__experimentalItem as Item,
+	// @ts-ignore
+	__experimentalHStack as HStack,
+	Icon,
+} from '@wordpress/components';
+import { isRTL } from '@wordpress/i18n';
+import { chevronRightSmall, chevronLeftSmall } from '@wordpress/icons';
+
+/**
+ * Internal dependencies
+ */
+import { wrapIcon } from '../items';
+import type { IconType } from '../../../store/types';
+
+interface DrilldownItemProps {
+	/**
+	 * Optional CSS class name.
+	 */
+	className?: string;
+	/**
+	 * Identifier of the navigation item.
+	 */
+	id: string;
+	/**
+	 * Icon to display with the navigation item.
+	 */
+	icon?: IconType;
+	/**
+	 * Whether to show placeholder icons for alignment.
+	 */
+	shouldShowPlaceholder?: boolean;
+	/**
+	 * Content to display inside the navigation item.
+	 */
+	children: ReactNode;
+	/**
+	 * Function to handle sidebar navigation when the item is clicked.
+	 */
+	onNavigate: ( {
+		id,
+		direction,
+	}: {
+		id?: string;
+		direction: 'forward' | 'backward';
+	} ) => void;
+}
+
+export default function DrilldownItem( {
+	className,
+	id,
+	icon,
+	shouldShowPlaceholder = true,
+	children,
+	onNavigate,
+}: DrilldownItemProps ) {
+	const handleClick = ( e: React.MouseEvent ) => {
+		e.preventDefault();
+		onNavigate( { id, direction: 'forward' } );
+	};
+
+	return (
+		<Item
+			className={ clsx( 'boot-navigation-item', className ) }
+			onClick={ handleClick }
+		>
+			<HStack
+				justify="flex-start"
+				spacing={ 2 }
+				style={ { flexGrow: '1' } }
+			>
+				{ wrapIcon( icon, shouldShowPlaceholder ) }
+				<FlexBlock>{ children }</FlexBlock>
+				<Icon icon={ isRTL() ? chevronLeftSmall : chevronRightSmall } />
+			</HStack>
+		</Item>
+	);
+}

package/src/components/navigation/dropdown-item/index.tsx

@@ -0,0 +1,134 @@
+/**
+ * External dependencies
+ */
+import clsx from 'clsx';
+import type { ReactNode } from 'react';
+
+/**
+ * WordPress dependencies
+ */
+import {
+	FlexBlock,
+	__experimentalItem as Item,
+	// @ts-ignore
+	__experimentalHStack as HStack,
+	Icon,
+	__unstableMotion as motion,
+	__unstableAnimatePresence as AnimatePresence,
+} from '@wordpress/components';
+import { chevronDownSmall } from '@wordpress/icons';
+import { useReducedMotion } from '@wordpress/compose';
+import { useSelect } from '@wordpress/data';
+
+/**
+ * Internal dependencies
+ */
+import { STORE_NAME } from '../../../store';
+import NavigationItem from '../navigation-item';
+import { wrapIcon } from '../items';
+import type { IconType, MenuItem } from '../../../store/types';
+import './style.scss';
+
+const ANIMATION_DURATION = 0.2;
+
+interface DropdownItemProps {
+	/**
+	 * Optional CSS class name.
+	 */
+	className?: string;
+	/**
+	 * Identifier of the parent menu item.
+	 */
+	id: string;
+	/**
+	 * Icon to display with the dropdown item.
+	 */
+	icon?: IconType;
+	/**
+	 * Whether to show placeholder icons for alignment.
+	 */
+	shouldShowPlaceholder?: boolean;
+	/**
+	 * Content to display inside the dropdown item.
+	 */
+	children: ReactNode;
+	/**
+	 * Whether this dropdown is currently expanded.
+	 */
+	isExpanded: boolean;
+	/**
+	 * Function to toggle this dropdown's expanded state.
+	 */
+	onToggle: () => void;
+}
+
+export default function DropdownItem( {
+	className,
+	id,
+	icon,
+	children,
+	isExpanded,
+	onToggle,
+}: DropdownItemProps ) {
+	const menuItems: MenuItem[] = useSelect(
+		( select ) =>
+			// @ts-ignore
+			select( STORE_NAME ).getMenuItems(),
+		[]
+	);
+	const items = menuItems.filter( ( item ) => item.parent === id );
+	const disableMotion = useReducedMotion();
+	return (
+		<div className="boot-dropdown-item">
+			<Item
+				className={ clsx( 'boot-navigation-item', className ) }
+				onClick={ ( e ) => {
+					e.preventDefault();
+					e.stopPropagation();
+					onToggle();
+				} }
+				onMouseDown={ ( e ) => e.preventDefault() }
+			>
+				<HStack
+					justify="flex-start"
+					spacing={ 2 }
+					style={ { flexGrow: '1' } }
+				>
+					{ wrapIcon( icon, false ) }
+					<FlexBlock>{ children }</FlexBlock>
+					<Icon
+						icon={ chevronDownSmall }
+						className={ clsx( 'boot-dropdown-item__chevron', {
+							'is-up': isExpanded,
+						} ) }
+					/>
+				</HStack>
+			</Item>
+			<AnimatePresence initial={ false }>
+				{ isExpanded && (
+					<motion.div
+						initial={ { height: 0 } }
+						animate={ { height: 'auto' } }
+						exit={ { height: 0 } }
+						transition={ {
+							type: 'tween',
+							duration: disableMotion ? 0 : ANIMATION_DURATION,
+							ease: 'easeOut',
+						} }
+						className="boot-dropdown-item__children"
+					>
+						{ items.map( ( item, index ) => (
+							<NavigationItem
+								key={ index }
+								to={ item.to }
+								shouldShowPlaceholder={ false }
+							>
+								{ item.label }
+							</NavigationItem>
+						) ) }
+					</motion.div>
+				) }
+			</AnimatePresence>
+		</div>
+	);
+}

package/src/components/navigation/dropdown-item/style.scss

@@ -0,0 +1,23 @@
+@use "@wordpress/base-styles/variables";
+
+.boot-dropdown-item__children {
+	display: flex;
+	flex-direction: column;
+
+	// In order to avoid the focus ring of each list item from being cut off,
+	// we add padding around the menu items.
+	// At the same time, we use the same value to tweak margins so that
+	// the items still retain the same position and footprint.
+	$padding-to-avoid-cutting-focus-ring: 2px;
+	padding: $padding-to-avoid-cutting-focus-ring;
+	margin-block-start: -$padding-to-avoid-cutting-focus-ring;
+	margin-block-end: $padding-to-avoid-cutting-focus-ring;
+	margin-inline-start:
+		variables.$grid-unit-40 -
+		$padding-to-avoid-cutting-focus-ring;
+	overflow: hidden;
+}
+
+.boot-dropdown-item__chevron.is-up {
+	transform: rotate(180deg);
+}

package/src/components/navigation/index.tsx

@@ -0,0 +1,126 @@
+/**
+ * WordPress dependencies
+ */
+import { useState, useMemo, useRef } from '@wordpress/element';
+import { useSelect } from '@wordpress/data';
+
+/**
+ * Internal dependencies
+ */
+import { STORE_NAME } from '../../store';
+import NavigationItem from './navigation-item';
+import DrilldownItem from './drilldown-item';
+import DropdownItem from './dropdown-item';
+import NavigationScreen from './navigation-screen';
+import { useSidebarParent } from './use-sidebar-parent';
+import type { MenuItem } from '../../store/types';
+
+function Navigation() {
+	const backButtonRef = useRef< HTMLButtonElement >( null );
+	const [ animationDirection, setAnimationDirection ] = useState<
+		'forward' | 'backward' | null
+	>( null );
+	const [ parentId, setParentId, parentDropdownId, setParentDropdownId ] =
+		useSidebarParent();
+	const menuItems = useSelect(
+		( select ) =>
+			// @ts-ignore
+			select( STORE_NAME ).getMenuItems() as MenuItem[],
+		[]
+	);
+	const parent = useMemo(
+		() => menuItems.find( ( item ) => item.id === parentId ),
+		[ menuItems, parentId ]
+	);
+	// Create a unique key for the current navigation state
+	// The sidebar will animate when the key changes.
+	const navigationKey = parent ? `drilldown-${ parent.id }` : 'root';
+
+	// We use transitions to handle navigation clicks
+	// This allows smooth animations and non blocking navigation.
+	const handleNavigate = ( {
+		id,
+		direction,
+	}: {
+		id?: string;
+		direction: 'forward' | 'backward';
+	} ) => {
+		setAnimationDirection( direction );
+		setParentId( id );
+	};
+
+	const handleDropdownToggle = ( dropdownId: string ) => {
+		setParentDropdownId(
+			parentDropdownId === dropdownId ? undefined : dropdownId
+		);
+	};
+
+	const items = useMemo(
+		() => menuItems.filter( ( item ) => item.parent === parentId ),
+		[ menuItems, parentId ]
+	);
+
+	const hasRealIcons = items.some( ( item ) => !! item.icon );
+
+	return (
+		<NavigationScreen
+			isRoot={ ! parent }
+			title={ parent ? parent.label : '' }
+			backMenuItem={ parent?.parent }
+			backButtonRef={ backButtonRef }
+			animationDirection={ animationDirection || undefined }
+			navigationKey={ navigationKey }
+			onNavigate={ handleNavigate }
+			content={
+				<>
+					{ items.map( ( item: MenuItem ) => {
+						if ( item.parent_type === 'dropdown' ) {
+							return (
+								<DropdownItem
+									key={ item.id }
+									id={ item.id }
+									className="boot-navigation-item"
+									icon={ item.icon }
+									shouldShowPlaceholder={ hasRealIcons }
+									isExpanded={ parentDropdownId === item.id }
+									onToggle={ () =>
+										handleDropdownToggle( item.id )
+									}
+								>
+									{ item.label }
+								</DropdownItem>
+							);
+						}
+
+						if ( item.parent_type === 'drilldown' ) {
+							return (
+								<DrilldownItem
+									key={ item.id }
+									id={ item.id }
+									icon={ item.icon }
+									shouldShowPlaceholder={ hasRealIcons }
+									onNavigate={ handleNavigate }
+								>
+									{ item.label }
+								</DrilldownItem>
+							);
+						}
+
+						return (
+							<NavigationItem
+								key={ item.id }
+								to={ item.to }
+								icon={ item.icon }
+								shouldShowPlaceholder={ hasRealIcons }
+							>
+								{ item.label }
+							</NavigationItem>
+						);
+					} ) }
+				</>
+			}
+		/>
+	);
+}
+
+export default Navigation;

package/src/components/navigation/items.tsx

@@ -0,0 +1,93 @@
+/**
+ * WordPress dependencies
+ */
+import { isValidElement } from '@wordpress/element';
+import { Dashicon, Icon } from '@wordpress/components';
+import { SVG } from '@wordpress/primitives';
+
+/**
+ * Internal dependencies
+ */
+import type { IconType } from '../../store/types';
+
+/**
+ * Type guard for verifying whether a given element
+ * is a valid SVG element for the Icon component.
+ *
+ * @param element - The element to check
+ */
+function isSvg( element: unknown ): element is JSX.Element {
+	return (
+		isValidElement( element ) &&
+		( element.type === SVG || element.type === 'svg' )
+	);
+}
+
+/**
+ * Converts the given IconType into a renderable component:
+ * - Dashicon string into a Dashicon component
+ * - JSX SVG element into an Icon component
+ * - Data URL into an img element
+ *
+ * @param icon                  - The icon to convert
+ * @param shouldShowPlaceholder - Whether to show placeholder when no icon is provided
+ * @return The converted icon as a JSX element
+ */
+export function wrapIcon(
+	icon?: IconType,
+	shouldShowPlaceholder: boolean = true
+) {
+	if ( isSvg( icon ) ) {
+		return <Icon icon={ icon } />;
+	}
+
+	if ( typeof icon === 'string' && icon.startsWith( 'dashicons-' ) ) {
+		const iconKey = icon.replace(
+			/^dashicons-/,
+			''
+		) as React.ComponentProps< typeof Dashicon >[ 'icon' ];
+
+		return (
+			<Dashicon
+				style={ { padding: '2px' } }
+				icon={ iconKey }
+				aria-hidden="true"
+			/>
+		);
+	}
+
+	// Handle data URLs (SVG images)
+	if ( typeof icon === 'string' && icon.startsWith( 'data:' ) ) {
+		return (
+			<img
+				src={ icon }
+				alt=""
+				aria-hidden="true"
+				style={ {
+					width: '20px',
+					height: '20px',
+					display: 'block',
+					padding: '2px',
+				} }
+			/>
+		);
+	}
+
+	// If icon is provided and valid, return it as-is
+	if ( icon ) {
+		return icon;
+	}
+
+	// Return empty 24px placeholder for alignment when no icon is provided
+	// Only if shouldShowPlaceholder is true
+	if ( shouldShowPlaceholder ) {
+		return (
+			<div
+				style={ { width: '24px', height: '24px' } }
+				aria-hidden="true"
+			/>
+		);
+	}
+
+	return null;
+}