From fdd212c7cb0496afe5fe4ad165ede29c08f7db84 Mon Sep 17 00:00:00 2001 From: Marco Ciampini Date: Mon, 19 Aug 2024 13:54:59 +0200 Subject: [PATCH 01/38] Remove experimental status from Storybook --- packages/components/src/navigator/stories/index.story.tsx | 2 +- storybook/manager-head.html | 1 + 2 files changed, 2 insertions(+), 1 deletion(-) diff --git a/packages/components/src/navigator/stories/index.story.tsx b/packages/components/src/navigator/stories/index.story.tsx index f703969320ca57..b1e5dc3f73cc5d 100644 --- a/packages/components/src/navigator/stories/index.story.tsx +++ b/packages/components/src/navigator/stories/index.story.tsx @@ -21,7 +21,7 @@ const meta: Meta< typeof NavigatorProvider > = { component: NavigatorProvider, // @ts-expect-error - See https://github.com/storybookjs/storybook/issues/23170 subcomponents: { NavigatorScreen, NavigatorButton, NavigatorBackButton }, - title: 'Components (Experimental)/Navigator', + title: 'Components/Navigator', argTypes: { as: { control: { type: null } }, children: { control: { type: null } }, diff --git a/storybook/manager-head.html b/storybook/manager-head.html index f3eaef13509218..8525e48fffa585 100644 --- a/storybook/manager-head.html +++ b/storybook/manager-head.html @@ -7,6 +7,7 @@ 'customselectcontrol-v2', 'dimensioncontrol', 'navigation', + 'navigator', 'progressbar', 'theme', ]; From 03b69f7e0504bad63bdadbf95fb493a16801f1c0 Mon Sep 17 00:00:00 2001 From: Marco Ciampini Date: Mon, 19 Aug 2024 13:55:50 +0200 Subject: [PATCH 02/38] NavigatorProvider => Navigator (internally) --- .../{navigator-provider => navigator}/README.md | 0 .../{navigator-provider => navigator}/component.tsx | 11 +++-------- packages/components/src/navigator/styles.ts | 2 +- 3 files changed, 4 insertions(+), 9 deletions(-) rename packages/components/src/navigator/{navigator-provider => navigator}/README.md (100%) rename packages/components/src/navigator/{navigator-provider => navigator}/component.tsx (97%) diff --git a/packages/components/src/navigator/navigator-provider/README.md b/packages/components/src/navigator/navigator/README.md similarity index 100% rename from packages/components/src/navigator/navigator-provider/README.md rename to packages/components/src/navigator/navigator/README.md diff --git a/packages/components/src/navigator/navigator-provider/component.tsx b/packages/components/src/navigator/navigator/component.tsx similarity index 97% rename from packages/components/src/navigator/navigator-provider/component.tsx rename to packages/components/src/navigator/navigator/component.tsx index 604034a9525577..bb3296e440ffb1 100644 --- a/packages/components/src/navigator/navigator-provider/component.tsx +++ b/packages/components/src/navigator/navigator/component.tsx @@ -222,7 +222,7 @@ function UnconnectedNavigator( children, className, ...otherProps - } = useContextSystem( props, 'NavigatorProvider' ); + } = useContextSystem( props, 'Navigator' ); const [ routerState, dispatch ] = useReducer( routerReducer, @@ -275,7 +275,7 @@ function UnconnectedNavigator( const cx = useCx(); const classes = useMemo( - () => cx( styles.navigatorProviderWrapper, className ), + () => cx( styles.navigatorWrapper, className ), [ className, cx ] ); @@ -321,9 +321,4 @@ function UnconnectedNavigator( * ); * ``` */ -export const Navigator = contextConnect( - UnconnectedNavigator, - 'NavigatorProvider' -); - -export default Navigator; +export const Navigator = contextConnect( UnconnectedNavigator, 'Navigator' ); diff --git a/packages/components/src/navigator/styles.ts b/packages/components/src/navigator/styles.ts index fd355bf4dd48fb..167d4ac07de3d6 100644 --- a/packages/components/src/navigator/styles.ts +++ b/packages/components/src/navigator/styles.ts @@ -3,7 +3,7 @@ */ import { css, keyframes } from '@emotion/react'; -export const navigatorProviderWrapper = css` +export const navigatorWrapper = css` position: relative; /* Prevents horizontal overflow while animating screen transitions */ overflow-x: clip; From b2273a7caf5edcdff3176829425c8424dd490454 Mon Sep 17 00:00:00 2001 From: Marco Ciampini Date: Mon, 19 Aug 2024 13:59:09 +0200 Subject: [PATCH 03/38] Move legacy exports to separate file --- packages/components/src/navigator/legacy.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/components/src/navigator/legacy.ts b/packages/components/src/navigator/legacy.ts index 54bc9e13829b16..0b2fbb2f005662 100644 --- a/packages/components/src/navigator/legacy.ts +++ b/packages/components/src/navigator/legacy.ts @@ -1,7 +1,7 @@ /** * Internal dependencies */ -import { Navigator as InternalNavigator } from './navigator-provider/component'; +import { Navigator as InternalNavigator } from './navigator/component'; import { NavigatorScreen as InternalNavigatorScreen } from './navigator-screen/component'; import { NavigatorButton as InternalNavigatorButton } from './navigator-button/component'; import { NavigatorBackButton as InternalNavigatorBackButton } from './navigator-back-button/component'; From f2897cc9e89dc765e33fec23eba4f6fe2f5c9850 Mon Sep 17 00:00:00 2001 From: Marco Ciampini Date: Mon, 19 Aug 2024 15:02:19 +0200 Subject: [PATCH 04/38] Export overloaded notation --- packages/components/src/navigator/index.ts | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) create mode 100644 packages/components/src/navigator/index.ts diff --git a/packages/components/src/navigator/index.ts b/packages/components/src/navigator/index.ts new file mode 100644 index 00000000000000..b76256c59a4f19 --- /dev/null +++ b/packages/components/src/navigator/index.ts @@ -0,0 +1,21 @@ +/** + * Internal dependencies + */ +import { Navigator as NavigatorProvider } from './navigator/component'; +import { NavigatorScreen } from './navigator-screen/component'; +import { NavigatorButton } from './navigator-button/component'; +import { NavigatorBackButton } from './navigator-back-button/component'; +export { useNavigator } from './use-navigator'; + +export const Navigator = Object.assign( NavigatorProvider, { + dislayName: 'Navigator', + Screen: Object.assign( NavigatorScreen, { + displayName: 'Navigator.Screen', + } ), + Button: Object.assign( NavigatorButton, { + displayName: 'Navigator.Button', + } ), + BackButton: Object.assign( NavigatorBackButton, { + displayName: 'Navigator.BackButton', + } ), +} ); From c35b80f4da0b8172613d76c3b928622a97b8de35 Mon Sep 17 00:00:00 2001 From: Marco Ciampini Date: Mon, 19 Aug 2024 15:02:39 +0200 Subject: [PATCH 05/38] Use overloaded notation in Storybook --- .../src/navigator/stories/index.story.tsx | 92 +++++++++---------- 1 file changed, 46 insertions(+), 46 deletions(-) diff --git a/packages/components/src/navigator/stories/index.story.tsx b/packages/components/src/navigator/stories/index.story.tsx index b1e5dc3f73cc5d..846fe0acf05f48 100644 --- a/packages/components/src/navigator/stories/index.story.tsx +++ b/packages/components/src/navigator/stories/index.story.tsx @@ -8,19 +8,19 @@ import type { Meta, StoryObj } from '@storybook/react'; */ import Button from '../../button'; import { VStack } from '../../v-stack'; -import { - NavigatorProvider, - NavigatorScreen, - NavigatorButton, - NavigatorBackButton, - useNavigator, -} from '../legacy'; import { HStack } from '../../h-stack'; - -const meta: Meta< typeof NavigatorProvider > = { - component: NavigatorProvider, - // @ts-expect-error - See https://github.com/storybookjs/storybook/issues/23170 - subcomponents: { NavigatorScreen, NavigatorButton, NavigatorBackButton }, +import { Navigator, useNavigator } from '../'; + +const meta: Meta< typeof Navigator > = { + component: Navigator, + subcomponents: { + // @ts-expect-error - See https://github.com/storybookjs/storybook/issues/23170 + Screen: Navigator.Screen, + // @ts-expect-error - See https://github.com/storybookjs/storybook/issues/23170 + Button: Navigator.Button, + // @ts-expect-error - See https://github.com/storybookjs/storybook/issues/23170 + BackButton: Navigator.BackButton, + }, title: 'Components/Navigator', argTypes: { as: { control: { type: null } }, @@ -55,55 +55,55 @@ const meta: Meta< typeof NavigatorProvider > = { }; export default meta; -export const Default: StoryObj< typeof NavigatorProvider > = { +export const Default: StoryObj< typeof Navigator > = { args: { initialPath: '/', children: ( <> - +

This is the home screen.

- + Go to child screen. - + - + Go to dynamic path screen with id 1. - + - + Go to dynamic path screen with id 2. - + - + - +

This is the child screen.

- + Go back - + - Go to grand child screen. - + - + - +

This is the grand child screen.

- + Go back - - + + - + - + ), }, @@ -119,14 +119,14 @@ function DynamicScreen() { This screen can parse params dynamically. The current id is:{ ' ' } { params.id }

- + Go back - + ); } -export const WithNestedInitialPath: StoryObj< typeof NavigatorProvider > = { +export const WithNestedInitialPath: StoryObj< typeof Navigator > = { ...Default, args: { ...Default.args, @@ -138,7 +138,7 @@ const NavigatorButtonWithSkipFocus = ( { path, onClick, ...props -}: React.ComponentProps< typeof NavigatorButton > ) => { +}: React.ComponentProps< typeof Navigator.Button > ) => { const { goTo } = useNavigator(); return ( @@ -156,7 +156,7 @@ const NavigatorButtonWithSkipFocus = ( { ); }; -export const SkipFocus: StoryObj< typeof NavigatorProvider > = { +export const SkipFocus: StoryObj< typeof Navigator > = { args: { initialPath: '/', children: ( @@ -170,19 +170,19 @@ export const SkipFocus: StoryObj< typeof NavigatorProvider > = { display: 'contents', } } > - +

Home screen

- + Go to child screen. - - + + - +

Child screen

- + Go back to home screen - - + + From f6592761d63610734770845f3e51cebdb9af25f9 Mon Sep 17 00:00:00 2001 From: Marco Ciampini Date: Mon, 19 Aug 2024 15:07:46 +0200 Subject: [PATCH 06/38] Use overloaded notation in unit tests (skipping deprecated component for now) --- .../components/src/navigator/test/index.tsx | 120 +++++++++--------- 1 file changed, 58 insertions(+), 62 deletions(-) diff --git a/packages/components/src/navigator/test/index.tsx b/packages/components/src/navigator/test/index.tsx index 81ffd8d69208d7..0fdaf85926819d 100644 --- a/packages/components/src/navigator/test/index.tsx +++ b/packages/components/src/navigator/test/index.tsx @@ -14,14 +14,7 @@ import { useState } from '@wordpress/element'; * Internal dependencies */ import Button from '../../button'; -import { - NavigatorProvider, - NavigatorScreen, - NavigatorButton, - NavigatorBackButton, - NavigatorToParentButton, - useNavigator, -} from '../legacy'; +import { Navigator, useNavigator } from '..'; import type { NavigateOptions } from '../types'; const INVALID_HTML_ATTRIBUTE = { @@ -76,11 +69,11 @@ function CustomNavigatorButton( { path, onClick, ...props -}: Omit< ComponentPropsWithoutRef< typeof NavigatorButton >, 'onClick' > & { +}: Omit< ComponentPropsWithoutRef< typeof Navigator.Button >, 'onClick' > & { onClick?: CustomTestOnClickHandler; } ) { return ( - { // Used to spy on the values passed to `navigator.goTo`. onClick?.( { type: 'goTo', path } ); @@ -95,7 +88,7 @@ function CustomNavigatorGoToBackButton( { path, onClick, ...props -}: Omit< ComponentPropsWithoutRef< typeof NavigatorButton >, 'onClick' > & { +}: Omit< ComponentPropsWithoutRef< typeof Navigator.Button >, 'onClick' > & { onClick?: CustomTestOnClickHandler; } ) { const { goTo } = useNavigator(); @@ -115,7 +108,7 @@ function CustomNavigatorGoToSkipFocusButton( { path, onClick, ...props -}: Omit< ComponentPropsWithoutRef< typeof NavigatorButton >, 'onClick' > & { +}: Omit< ComponentPropsWithoutRef< typeof Navigator.Button >, 'onClick' > & { onClick?: CustomTestOnClickHandler; } ) { const { goTo } = useNavigator(); @@ -134,11 +127,14 @@ function CustomNavigatorGoToSkipFocusButton( { function CustomNavigatorBackButton( { onClick, ...props -}: Omit< ComponentPropsWithoutRef< typeof NavigatorBackButton >, 'onClick' > & { +}: Omit< + ComponentPropsWithoutRef< typeof Navigator.BackButton >, + 'onClick' +> & { onClick?: CustomTestOnClickHandler; } ) { return ( - { // Used to spy on the values passed to `navigator.goBack`. onClick?.( { type: 'goBack' } ); @@ -148,22 +144,22 @@ function CustomNavigatorBackButton( { ); } -function CustomNavigatorToParentButton( { - onClick, - ...props -}: Omit< ComponentPropsWithoutRef< typeof NavigatorBackButton >, 'onClick' > & { - onClick?: CustomTestOnClickHandler; -} ) { - return ( - { - // Used to spy on the values passed to `navigator.goBack`. - onClick?.( { type: 'goToParent' } ); - } } - { ...props } - /> - ); -} +// function CustomNavigatorToParentButton( { +// onClick, +// ...props +// }: Omit< ComponentPropsWithoutRef< typeof Navigator.BackButton >, 'onClick' > & { +// onClick?: CustomTestOnClickHandler; +// } ) { +// return ( +// { +// // Used to spy on the values passed to `navigator.goBack`. +// onClick?.( { type: 'goToParent' } ); +// } } +// { ...props } +// /> +// ); +// } function CustomNavigatorToParentButtonAlternative( { onClick, @@ -194,13 +190,13 @@ const ProductScreen = ( { const { params } = useNavigator(); return ( - +

{ SCREEN_TEXT.product }

Product ID is { params.productId }

{ BUTTON_TEXT.back } - + ); }; @@ -215,8 +211,8 @@ const MyNavigation = ( { const [ outerInputValue, setOuterInputValue ] = useState( '' ); return ( <> - - + +

{ SCREEN_TEXT.home }

{ /* * A button useful to test focus restoration. This button is the first @@ -254,9 +250,9 @@ const MyNavigation = ( { > { BUTTON_TEXT.toInvalidHtmlPathScreen } - + - +

{ SCREEN_TEXT.child }

{ /* * A button useful to test focus restoration. This button is the first @@ -286,30 +282,30 @@ const MyNavigation = ( { } } value={ innerInputValue } /> - + - +

{ SCREEN_TEXT.nested }

{ BUTTON_TEXT.back } - + - +

{ SCREEN_TEXT.invalidHtmlPath }

{ BUTTON_TEXT.back } - + { /* A `NavigatorScreen` with `path={ PATHS.NOT_FOUND }` is purposefully not included. */ } - + { return ( <> - - + +

{ SCREEN_TEXT.home }

{ /* * A button useful to test focus restoration. This button is the first @@ -349,9 +345,9 @@ const MyHierarchicalNavigation = ( { > { BUTTON_TEXT.toChildScreen } - + - +

{ SCREEN_TEXT.child }

{ /* * A button useful to test focus restoration. This button is the first @@ -370,9 +366,9 @@ const MyHierarchicalNavigation = ( { > { BUTTON_TEXT.back } - + - +

{ SCREEN_TEXT.nested }

{ BUTTON_TEXT.backUsingGoTo } - + { BUTTON_TEXT.goToWithSkipFocus } - + ); }; @@ -406,8 +402,8 @@ const MyDeprecatedNavigation = ( { } ) => { return ( <> - - + +

{ SCREEN_TEXT.home }

{ /* * A button useful to test focus restoration. This button is the first @@ -421,9 +417,9 @@ const MyDeprecatedNavigation = ( { > { BUTTON_TEXT.toChildScreen } - + - +

{ SCREEN_TEXT.child }

{ /* * A button useful to test focus restoration. This button is the first @@ -437,22 +433,22 @@ const MyDeprecatedNavigation = ( { > { BUTTON_TEXT.toNestedScreen } - { BUTTON_TEXT.back } - - + */ } + - +

{ SCREEN_TEXT.nested }

{ BUTTON_TEXT.back } - - + + ); }; @@ -643,7 +639,7 @@ describe( 'Navigator', () => { } ); it( 'should warn if the `path` prop does not follow the required format', () => { - render( Test ); + render( Test ); expect( console ).toHaveWarnedWith( 'wp.components.NavigatorScreen: the `path` should follow a URL-like scheme; it should start with and be separated by the `/` character.' @@ -860,7 +856,7 @@ describe( 'Navigator', () => { } ); describe( 'deprecated APIs', () => { - it( 'should log a deprecation notice when using the NavigatorToParentButton component', async () => { + it.skip( 'should log a deprecation notice when using the NavigatorToParentButton component', async () => { const user = userEvent.setup(); render( ); From a489aa79a3bd98d1680c76a8487b8c21820c402b Mon Sep 17 00:00:00 2001 From: Marco Ciampini Date: Mon, 19 Aug 2024 15:21:27 +0200 Subject: [PATCH 07/38] Update docs manifest.json --- docs/manifest.json | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/manifest.json b/docs/manifest.json index d76717fbdedfc1..09244c14b02eec 100644 --- a/docs/manifest.json +++ b/docs/manifest.json @@ -1110,9 +1110,9 @@ "parent": "components" }, { - "title": "NavigatorProvider", - "slug": "navigator-provider", - "markdown_source": "../packages/components/src/navigator/navigator-provider/README.md", + "title": "Navigator", + "slug": "navigator", + "markdown_source": "../packages/components/src/navigator/navigator/README.md", "parent": "components" }, { From af0c4d902eadbd2f006e4bac0831efc55fa099df Mon Sep 17 00:00:00 2001 From: Marco Ciampini Date: Mon, 19 Aug 2024 15:22:31 +0200 Subject: [PATCH 08/38] Navigator: update docs --- packages/components/src/navigator/index.ts | 32 +++++++++++++++-- .../src/navigator/navigator/README.md | 34 +++++++------------ .../src/navigator/navigator/component.tsx | 33 ++++++++---------- 3 files changed, 56 insertions(+), 43 deletions(-) diff --git a/packages/components/src/navigator/index.ts b/packages/components/src/navigator/index.ts index b76256c59a4f19..7c6fb7d9ac9288 100644 --- a/packages/components/src/navigator/index.ts +++ b/packages/components/src/navigator/index.ts @@ -1,13 +1,41 @@ /** * Internal dependencies */ -import { Navigator as NavigatorProvider } from './navigator/component'; +import { Navigator as TopLevelNavigator } from './navigator/component'; import { NavigatorScreen } from './navigator-screen/component'; import { NavigatorButton } from './navigator-button/component'; import { NavigatorBackButton } from './navigator-back-button/component'; export { useNavigator } from './use-navigator'; -export const Navigator = Object.assign( NavigatorProvider, { +/** + * The `Navigator` component allows rendering nested views/panels/menus + * (via the `Navigator.Screen` component) and navigate between these different + * view (via the `Navigator.Button` and `Navigator.BackButton` components or the + * `useNavigator` hook). + * + * ```jsx + * import { Navigator } from '@wordpress/components'; + * + * const MyNavigation = () => ( + * + * + *

This is the home screen.

+ * + * Navigate to child screen. + * + * + * + * + *

This is the child screen.

+ * + * Go back + * + * + * + * ); + * ``` + */ +export const Navigator = Object.assign( TopLevelNavigator, { dislayName: 'Navigator', Screen: Object.assign( NavigatorScreen, { displayName: 'Navigator.Screen', diff --git a/packages/components/src/navigator/navigator/README.md b/packages/components/src/navigator/navigator/README.md index b9bc8f0c6bcdc9..32d697a438a674 100644 --- a/packages/components/src/navigator/navigator/README.md +++ b/packages/components/src/navigator/navigator/README.md @@ -1,35 +1,25 @@ -# `NavigatorProvider` +# `Navigator` -
-This feature is still experimental. “Experimental” means this is an early implementation subject to drastic and breaking changes. -
- -The `NavigatorProvider` component allows rendering nested views/panels/menus (via the [`NavigatorScreen` component](/packages/components/src/navigator/navigator-screen/README.md)) and navigate between these different states (via the [`NavigatorButton`](/packages/components/src/navigator/navigator-button/README.md), [`NavigatorToParentButton`](/packages/components/src/navigator/navigator-to-parent-button/README.md) and [`NavigatorBackButton`](/packages/components/src/navigator/navigator-back-button/README.md) components or the `useNavigator` hook). The Global Styles sidebar is an example of this. +The `Navigator` component allows rendering nested views/panels/menus (via the [`Navigator.Screen` component](/packages/components/src/navigator/navigator-screen/README.md)) and navigate between these different states (via the [`Navigator.Button`](/packages/components/src/navigator/navigator-button/README.md) and [`Navigator.BackButton`](/packages/components/src/navigator/navigator-back-button/README.md) components or the `useNavigator` hook). ## Usage ```jsx -import { - __experimentalNavigatorProvider as NavigatorProvider, - __experimentalNavigatorScreen as NavigatorScreen, - __experimentalNavigatorButton as NavigatorButton, - __experimentalNavigatorBackButton as NavigatorBackButton, -} from '@wordpress/components'; +import { Navigator } from '@wordpress/components'; const MyNavigation = () => ( - - + +

This is the home screen.

- + Navigate to child screen. - - - - + + + *

This is the child screen.

- Go back - - + Go back + + ); ``` diff --git a/packages/components/src/navigator/navigator/component.tsx b/packages/components/src/navigator/navigator/component.tsx index bb3296e440ffb1..63dfd540640d1f 100644 --- a/packages/components/src/navigator/navigator/component.tsx +++ b/packages/components/src/navigator/navigator/component.tsx @@ -289,35 +289,30 @@ function UnconnectedNavigator( } /** - * The `NavigatorProvider` component allows rendering nested views/panels/menus - * (via the `NavigatorScreen` component and navigate between these different - * view (via the `NavigatorButton` and `NavigatorBackButton` components or the + * The `Navigator` component allows rendering nested views/panels/menus + * (via the `Navigator.Screen` component) and navigate between these different + * view (via the `Navigator.Button` and `Navigator.BackButton` components or the * `useNavigator` hook). * * ```jsx - * import { - * __experimentalNavigatorProvider as NavigatorProvider, - * __experimentalNavigatorScreen as NavigatorScreen, - * __experimentalNavigatorButton as NavigatorButton, - * __experimentalNavigatorBackButton as NavigatorBackButton, - * } from '@wordpress/components'; + * import { Navigator } from '@wordpress/components'; * * const MyNavigation = () => ( - * - * + * + * *

This is the home screen.

- * + * * Navigate to child screen. - * - * + * + * * - * + * *

This is the child screen.

- * + * * Go back - * - * - * + * + * + * * ); * ``` */ From ca58f316771d68edb3ecdb582f7205cf0489ad21 Mon Sep 17 00:00:00 2001 From: Marco Ciampini Date: Mon, 19 Aug 2024 15:36:44 +0200 Subject: [PATCH 09/38] Navigator.BackButton: update docs --- docs/manifest.json | 2 +- packages/components/src/navigator/index.ts | 30 +++++++++++++++++++ .../navigator/navigator-back-button/README.md | 12 +++----- 3 files changed, 35 insertions(+), 9 deletions(-) diff --git a/docs/manifest.json b/docs/manifest.json index 09244c14b02eec..ca0e9a2f584ec4 100644 --- a/docs/manifest.json +++ b/docs/manifest.json @@ -1098,7 +1098,7 @@ "parent": "components" }, { - "title": "NavigatorBackButton", + "title": "Navigator.BackButton", "slug": "navigator-back-button", "markdown_source": "../packages/components/src/navigator/navigator-back-button/README.md", "parent": "components" diff --git a/packages/components/src/navigator/index.ts b/packages/components/src/navigator/index.ts index 7c6fb7d9ac9288..27293c2d1b2d92 100644 --- a/packages/components/src/navigator/index.ts +++ b/packages/components/src/navigator/index.ts @@ -13,6 +13,7 @@ export { useNavigator } from './use-navigator'; * view (via the `Navigator.Button` and `Navigator.BackButton` components or the * `useNavigator` hook). * + * @example * ```jsx * import { Navigator } from '@wordpress/components'; * @@ -43,6 +44,35 @@ export const Navigator = Object.assign( TopLevelNavigator, { Button: Object.assign( NavigatorButton, { displayName: 'Navigator.Button', } ), + /** + * The `Navigator.BackButton` component can be used to navigate to a screen and + * should be used in combination with the `Navigator`, the + * `Navigator.Screen` and the `Navigator.Button` components, and the `useNavigator` + * hook. + * + * @example + * ```jsx + * import { Navigator } from '@wordpress/components'; + * + * const MyNavigation = () => ( + * + * + *

This is the home screen.

+ * + * Navigate to child screen. + * + * + * + * + *

This is the child screen.

+ * + * Go back + * + * + * + * ); + * ``` + */ BackButton: Object.assign( NavigatorBackButton, { displayName: 'Navigator.BackButton', } ), diff --git a/packages/components/src/navigator/navigator-back-button/README.md b/packages/components/src/navigator/navigator-back-button/README.md index 01d4221be536e5..6388805e5af828 100644 --- a/packages/components/src/navigator/navigator-back-button/README.md +++ b/packages/components/src/navigator/navigator-back-button/README.md @@ -1,15 +1,11 @@ -# `NavigatorBackButton` +# `Navigator.BackButton` -
-This feature is still experimental. “Experimental” means this is an early implementation subject to drastic and breaking changes. -
- -The `NavigatorBackButton` component can be used to navigate to a screen and should be used in combination with the [`NavigatorProvider`](/packages/components/src/navigator/navigator-provider/README.md), the [`NavigatorScreen`](/packages/components/src/navigator/navigator-screen/README.md) and the [`NavigatorButton`](/packages/components/src/navigator/navigator-button/README.md) components (or the `useNavigator` hook). +The `Navigator.BackButton` component can be used to navigate to a screen and should be used in combination with the [`Navigator`](/packages/components/src/navigator/navigator/README.md), the [`Navigator.Screen`](/packages/components/src/navigator/navigator-screen/README.md) and the [`Navigator.Button`](/packages/components/src/navigator/navigator-button/README.md) components, and the `useNavigator` hook. ## Usage -Refer to [the `NavigatorProvider` component](/packages/components/src/navigator/navigator-provider/README.md#usage) for a usage example. +Refer to [the `Navigator` component](/packages/components/src/navigator/navigator/README.md#usage) for a usage example. ### Inherited props -`NavigatorBackButton` also inherits all of the [`Button` props](/packages/components/src/button/README.md#props), except for `href` and `target`. +`Navigator.BackButton` also inherits all of the [`Button` props](/packages/components/src/button/README.md#props), except for `href` and `target`. From adf9678710ee1049263be8a47a9a0ae7b7259cac Mon Sep 17 00:00:00 2001 From: Marco Ciampini Date: Mon, 19 Aug 2024 15:37:01 +0200 Subject: [PATCH 10/38] NavigatorToParentButton: delete README --- docs/manifest.json | 6 ------ .../navigator-to-parent-button/README.md | 17 ----------------- 2 files changed, 23 deletions(-) delete mode 100644 packages/components/src/navigator/navigator-to-parent-button/README.md diff --git a/docs/manifest.json b/docs/manifest.json index ca0e9a2f584ec4..894daae1dea696 100644 --- a/docs/manifest.json +++ b/docs/manifest.json @@ -1121,12 +1121,6 @@ "markdown_source": "../packages/components/src/navigator/navigator-screen/README.md", "parent": "components" }, - { - "title": "NavigatorToParentButton", - "slug": "navigator-to-parent-button", - "markdown_source": "../packages/components/src/navigator/navigator-to-parent-button/README.md", - "parent": "components" - }, { "title": "Notice", "slug": "notice", diff --git a/packages/components/src/navigator/navigator-to-parent-button/README.md b/packages/components/src/navigator/navigator-to-parent-button/README.md deleted file mode 100644 index 0100ea9b8d2e1f..00000000000000 --- a/packages/components/src/navigator/navigator-to-parent-button/README.md +++ /dev/null @@ -1,17 +0,0 @@ -# `NavigatorToParentButton` - -
-This feature is still experimental. “Experimental” means this is an early implementation subject to drastic and breaking changes. -
- -This component is deprecated. Please use the [`NavigatorBackButton`](/packages/components/src/navigator/navigator-back-button/README.md) component instead. - -The `NavigatorToParentButton` component can be used to navigate to a screen and should be used in combination with the [`NavigatorProvider`](/packages/components/src/navigator/navigator-provider/README.md), the [`NavigatorScreen`](/packages/components/src/navigator/navigator-screen/README.md) and the [`NavigatorButton`](/packages/components/src/navigator/navigator-button/README.md) components (or the `useNavigator` hook). - -## Usage - -Refer to [the `NavigatorProvider` component](/packages/components/src/navigator/navigator-provider/README.md#usage) for a usage example. - -### Inherited props - -`NavigatorToParentButton` also inherits all of the [`Button` props](/packages/components/src/button/README.md#props), except for `href` and `target`. From 7fc659376e628af9bf3e4e1d35ee1234abf49e4b Mon Sep 17 00:00:00 2001 From: Marco Ciampini Date: Mon, 19 Aug 2024 15:40:33 +0200 Subject: [PATCH 11/38] Navigator.Button: update docs --- docs/manifest.json | 2 +- packages/components/src/navigator/index.ts | 33 +++++++++++++++++-- .../src/navigator/navigator-button/README.md | 10 ++---- 3 files changed, 34 insertions(+), 11 deletions(-) diff --git a/docs/manifest.json b/docs/manifest.json index 894daae1dea696..3bf25ec585c2ed 100644 --- a/docs/manifest.json +++ b/docs/manifest.json @@ -1104,7 +1104,7 @@ "parent": "components" }, { - "title": "NavigatorButton", + "title": "Navigator.Button", "slug": "navigator-button", "markdown_source": "../packages/components/src/navigator/navigator-button/README.md", "parent": "components" diff --git a/packages/components/src/navigator/index.ts b/packages/components/src/navigator/index.ts index 27293c2d1b2d92..093fe022d2a51a 100644 --- a/packages/components/src/navigator/index.ts +++ b/packages/components/src/navigator/index.ts @@ -41,14 +41,41 @@ export const Navigator = Object.assign( TopLevelNavigator, { Screen: Object.assign( NavigatorScreen, { displayName: 'Navigator.Screen', } ), + /** + * The `Navigator.Button` component can be used to navigate to a screen and + * should be used in combination with the `Navigator`, the `Navigator.Screen` + * and the `Navigator.BackButton` components, and the `useNavigator` hook. + * + * @example + * ```jsx + * import { Navigator } from '@wordpress/components'; + * + * const MyNavigation = () => ( + * + * + *

This is the home screen.

+ * + * Navigate to child screen. + * + * + * + * + *

This is the child screen.

+ * + * Go back + * + * + * + * ); + * ``` + */ Button: Object.assign( NavigatorButton, { displayName: 'Navigator.Button', } ), /** * The `Navigator.BackButton` component can be used to navigate to a screen and - * should be used in combination with the `Navigator`, the - * `Navigator.Screen` and the `Navigator.Button` components, and the `useNavigator` - * hook. + * should be used in combination with the `Navigator`, the `Navigator.Screen` + * and the `Navigator.Button` components, and the `useNavigator` hook. * * @example * ```jsx diff --git a/packages/components/src/navigator/navigator-button/README.md b/packages/components/src/navigator/navigator-button/README.md index 72154ec317da44..773879e00a1707 100644 --- a/packages/components/src/navigator/navigator-button/README.md +++ b/packages/components/src/navigator/navigator-button/README.md @@ -1,14 +1,10 @@ -# `NavigatorButton` +# `Navigator.Button` -
-This feature is still experimental. “Experimental” means this is an early implementation subject to drastic and breaking changes. -
- -The `NavigatorButton` component can be used to navigate to a screen and should be used in combination with the [`NavigatorProvider`](/packages/components/src/navigator/navigator-provider/README.md), the [`NavigatorScreen`](/packages/components/src/navigator/navigator-screen/README.md) and the [`NavigatorBackButton`](/packages/components/src/navigator/navigator-back-button/README.md) components (or the `useNavigator` hook). +The `Navigator.Button` component can be used to navigate to a screen and should be used in combination with the [`Navigator`](/packages/components/src/navigator/navigator/README.md), the [`Navigator.Screen`](/packages/components/src/navigator/navigator-screen/README.md) and the [`Navigator.BackButton`](/packages/components/src/navigator/navigator-back-button/README.md) components, and the `useNavigator` hook. ## Usage -Refer to [the `NavigatorProvider` component](/packages/components/src/navigator/navigator-provider/README.md#usage) for a usage example. +Refer to [the `Navigator` component](/packages/components/src/navigator/navigator/README.md#usage) for a usage example. ## Props From 37384e69453b5a5a9cc0ba01cd183d47b70fcc5a Mon Sep 17 00:00:00 2001 From: Marco Ciampini Date: Mon, 19 Aug 2024 15:43:24 +0200 Subject: [PATCH 12/38] NavigatorScreen: update docs --- docs/manifest.json | 2 +- packages/components/src/navigator/index.ts | 28 +++++++++++++++++++ .../src/navigator/navigator-screen/README.md | 10 ++----- .../navigator/navigator-screen/component.tsx | 2 +- 4 files changed, 33 insertions(+), 9 deletions(-) diff --git a/docs/manifest.json b/docs/manifest.json index 3bf25ec585c2ed..30222d699142ae 100644 --- a/docs/manifest.json +++ b/docs/manifest.json @@ -1116,7 +1116,7 @@ "parent": "components" }, { - "title": "NavigatorScreen", + "title": "Navigator.Screen", "slug": "navigator-screen", "markdown_source": "../packages/components/src/navigator/navigator-screen/README.md", "parent": "components" diff --git a/packages/components/src/navigator/index.ts b/packages/components/src/navigator/index.ts index 093fe022d2a51a..cea9b7c56b0c7c 100644 --- a/packages/components/src/navigator/index.ts +++ b/packages/components/src/navigator/index.ts @@ -38,6 +38,34 @@ export { useNavigator } from './use-navigator'; */ export const Navigator = Object.assign( TopLevelNavigator, { dislayName: 'Navigator', + /** + * The `Navigator.Screen` component represents a single view/screen/panel and + * should be used in combination with the `Navigator`, the `Navigator.Button` + * and the `Navigator.BackButton` components, and the `useNavigator` hook. + * + * @example + * ```jsx + * import { Navigator } from '@wordpress/components'; + * + * const MyNavigation = () => ( + * + * + *

This is the home screen.

+ * + * Navigate to child screen. + * + * + * + * + *

This is the child screen.

+ * + * Go back + * + * + * + * ); + * ``` + */ Screen: Object.assign( NavigatorScreen, { displayName: 'Navigator.Screen', } ), diff --git a/packages/components/src/navigator/navigator-screen/README.md b/packages/components/src/navigator/navigator-screen/README.md index 583da461cd3c27..3b87b66ab1842f 100644 --- a/packages/components/src/navigator/navigator-screen/README.md +++ b/packages/components/src/navigator/navigator-screen/README.md @@ -1,14 +1,10 @@ -# `NavigatorScreen` +# `Navigator.Screen` -
-This feature is still experimental. “Experimental” means this is an early implementation subject to drastic and breaking changes. -
- -The `NavigatorScreen` component represents a single view/screen/panel and should be used in combination with the [`NavigatorProvider`](/packages/components/src/navigator/navigator-provider/README.md), the [`NavigatorButton`](/packages/components/src/navigator/navigator-button/README.md) and the [`NavigatorBackButton`](/packages/components/src/navigator/navigator-back-button/README.md) components (or the `useNavigator` hook). +The `Navigator.Screen` component represents a single view/screen/panel and should be used in combination with the [`Navigator`](/packages/components/src/navigator/navigator/README.md), the [`Navigator.Button`](/packages/components/src/navigator/navigator-button/README.md) and the [`Navigator.BackButton`](/packages/components/src/navigator/navigator-back-button/README.md) components, and the `useNavigator` hook. ## Usage -Refer to [the `NavigatorProvider` component](/packages/components/src/navigator/navigator-provider/README.md#usage) for a usage example. +Refer to [the `Navigator` component](/packages/components/src/navigator/navigator/README.md#usage) for a usage example. ## Props diff --git a/packages/components/src/navigator/navigator-screen/component.tsx b/packages/components/src/navigator/navigator-screen/component.tsx index 16cc0df24e35dd..23b30e7f711e01 100644 --- a/packages/components/src/navigator/navigator-screen/component.tsx +++ b/packages/components/src/navigator/navigator-screen/component.tsx @@ -36,7 +36,7 @@ function UnconnectedNavigatorScreen( ) { if ( ! /^\//.test( props.path ) ) { warning( - 'wp.components.NavigatorScreen: the `path` should follow a URL-like scheme; it should start with and be separated by the `/` character.' + 'wp.components.Navigator.Screen: the `path` should follow a URL-like scheme; it should start with and be separated by the `/` character.' ); } From 30dbe5fd58f789f2b8026dd057c773c9f0702f79 Mon Sep 17 00:00:00 2001 From: Marco Ciampini Date: Mon, 19 Aug 2024 16:08:47 +0200 Subject: [PATCH 13/38] Restore `NavigatorToParentButton` test --- .../components/src/navigator/test/index.tsx | 48 +++++++++++-------- 1 file changed, 29 insertions(+), 19 deletions(-) diff --git a/packages/components/src/navigator/test/index.tsx b/packages/components/src/navigator/test/index.tsx index 0fdaf85926819d..502d907404a8eb 100644 --- a/packages/components/src/navigator/test/index.tsx +++ b/packages/components/src/navigator/test/index.tsx @@ -15,6 +15,13 @@ import { useState } from '@wordpress/element'; */ import Button from '../../button'; import { Navigator, useNavigator } from '..'; +import { + // NavigatorProvider, + // NavigatorScreen, + // NavigatorButton, + // NavigatorBackButton, + NavigatorToParentButton, +} from '../legacy'; import type { NavigateOptions } from '../types'; const INVALID_HTML_ATTRIBUTE = { @@ -144,22 +151,25 @@ function CustomNavigatorBackButton( { ); } -// function CustomNavigatorToParentButton( { -// onClick, -// ...props -// }: Omit< ComponentPropsWithoutRef< typeof Navigator.BackButton >, 'onClick' > & { -// onClick?: CustomTestOnClickHandler; -// } ) { -// return ( -// { -// // Used to spy on the values passed to `navigator.goBack`. -// onClick?.( { type: 'goToParent' } ); -// } } -// { ...props } -// /> -// ); -// } +function CustomNavigatorToParentButton( { + onClick, + ...props +}: Omit< + ComponentPropsWithoutRef< typeof Navigator.BackButton >, + 'onClick' +> & { + onClick?: CustomTestOnClickHandler; +} ) { + return ( + { + // Used to spy on the values passed to `navigator.goBack`. + onClick?.( { type: 'goToParent' } ); + } } + { ...props } + /> + ); +} function CustomNavigatorToParentButtonAlternative( { onClick, @@ -433,11 +443,11 @@ const MyDeprecatedNavigation = ( { > { BUTTON_TEXT.toNestedScreen } - { /* { BUTTON_TEXT.back } - */ } + @@ -856,7 +866,7 @@ describe( 'Navigator', () => { } ); describe( 'deprecated APIs', () => { - it.skip( 'should log a deprecation notice when using the NavigatorToParentButton component', async () => { + it( 'should log a deprecation notice when using the NavigatorToParentButton component', async () => { const user = userEvent.setup(); render( ); From f4da1e64a090a4be810c94b082b2aff83ba7c40e Mon Sep 17 00:00:00 2001 From: Marco Ciampini Date: Mon, 19 Aug 2024 16:25:50 +0200 Subject: [PATCH 14/38] Use dot notation in context namespaces too --- .../src/navigator/navigator-back-button/component.tsx | 2 +- .../components/src/navigator/navigator-button/component.tsx | 2 +- .../components/src/navigator/navigator-screen/component.tsx | 2 +- .../src/navigator/navigator-to-parent-button/component.tsx | 2 +- 4 files changed, 4 insertions(+), 4 deletions(-) diff --git a/packages/components/src/navigator/navigator-back-button/component.tsx b/packages/components/src/navigator/navigator-back-button/component.tsx index 9e8d98a963d25b..b5c4de7df78a85 100644 --- a/packages/components/src/navigator/navigator-back-button/component.tsx +++ b/packages/components/src/navigator/navigator-back-button/component.tsx @@ -23,5 +23,5 @@ function UnconnectedNavigatorBackButton( export const NavigatorBackButton = contextConnect( UnconnectedNavigatorBackButton, - 'NavigatorBackButton' + 'Navigator.BackButton' ); diff --git a/packages/components/src/navigator/navigator-button/component.tsx b/packages/components/src/navigator/navigator-button/component.tsx index 7c14c8108e82c4..a6dc7963376723 100644 --- a/packages/components/src/navigator/navigator-button/component.tsx +++ b/packages/components/src/navigator/navigator-button/component.tsx @@ -23,5 +23,5 @@ function UnconnectedNavigatorButton( export const NavigatorButton = contextConnect( UnconnectedNavigatorButton, - 'NavigatorButton' + 'Navigator.Button' ); diff --git a/packages/components/src/navigator/navigator-screen/component.tsx b/packages/components/src/navigator/navigator-screen/component.tsx index 23b30e7f711e01..98be7b0dab9999 100644 --- a/packages/components/src/navigator/navigator-screen/component.tsx +++ b/packages/components/src/navigator/navigator-screen/component.tsx @@ -155,5 +155,5 @@ function UnconnectedNavigatorScreen( export const NavigatorScreen = contextConnect( UnconnectedNavigatorScreen, - 'NavigatorScreen' + 'Navigator.Screen' ); diff --git a/packages/components/src/navigator/navigator-to-parent-button/component.tsx b/packages/components/src/navigator/navigator-to-parent-button/component.tsx index 161370a4323f48..5283b6d7bd7c12 100644 --- a/packages/components/src/navigator/navigator-to-parent-button/component.tsx +++ b/packages/components/src/navigator/navigator-to-parent-button/component.tsx @@ -25,5 +25,5 @@ function UnconnectedNavigatorToParentButton( export const NavigatorToParentButton = contextConnect( UnconnectedNavigatorToParentButton, - 'NavigatorToParentButton' + 'Navigator.ToParentButton' ); From d9fe1d83db8e41f77591b23f3f9ee2e627eb3a12 Mon Sep 17 00:00:00 2001 From: Marco Ciampini Date: Mon, 19 Aug 2024 16:26:09 +0200 Subject: [PATCH 15/38] Use named export for `NavigatorToParentButton` too --- .../src/navigator/navigator-to-parent-button/component.tsx | 3 +++ 1 file changed, 3 insertions(+) diff --git a/packages/components/src/navigator/navigator-to-parent-button/component.tsx b/packages/components/src/navigator/navigator-to-parent-button/component.tsx index 5283b6d7bd7c12..be7e61e764239d 100644 --- a/packages/components/src/navigator/navigator-to-parent-button/component.tsx +++ b/packages/components/src/navigator/navigator-to-parent-button/component.tsx @@ -23,6 +23,9 @@ function UnconnectedNavigatorToParentButton( return ; } +/** + * @deprecated + */ export const NavigatorToParentButton = contextConnect( UnconnectedNavigatorToParentButton, 'Navigator.ToParentButton' From 1d27a8962a5cfea85e02941e5d077a955bca9b7c Mon Sep 17 00:00:00 2001 From: Marco Ciampini Date: Mon, 19 Aug 2024 16:27:28 +0200 Subject: [PATCH 16/38] Fixup docs manifest --- docs/manifest.json | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/manifest.json b/docs/manifest.json index 30222d699142ae..cabbd6e2e37daf 100644 --- a/docs/manifest.json +++ b/docs/manifest.json @@ -1098,27 +1098,27 @@ "parent": "components" }, { - "title": "Navigator.BackButton", + "title": "NavigatorBackButton", "slug": "navigator-back-button", "markdown_source": "../packages/components/src/navigator/navigator-back-button/README.md", "parent": "components" }, { - "title": "Navigator.Button", + "title": "NavigatorButton", "slug": "navigator-button", "markdown_source": "../packages/components/src/navigator/navigator-button/README.md", "parent": "components" }, { - "title": "Navigator", - "slug": "navigator", - "markdown_source": "../packages/components/src/navigator/navigator/README.md", + "title": "NavigatorScreen", + "slug": "navigator-screen", + "markdown_source": "../packages/components/src/navigator/navigator-screen/README.md", "parent": "components" }, { - "title": "Navigator.Screen", - "slug": "navigator-screen", - "markdown_source": "../packages/components/src/navigator/navigator-screen/README.md", + "title": "Navigator", + "slug": "navigator", + "markdown_source": "../packages/components/src/navigator/navigator/README.md", "parent": "components" }, { From 2617d23d3baa3c6a93678a3a4467b3ab741ea313 Mon Sep 17 00:00:00 2001 From: Marco Ciampini Date: Mon, 19 Aug 2024 16:29:53 +0200 Subject: [PATCH 17/38] Export stable version from components package --- packages/components/src/index.ts | 1 + 1 file changed, 1 insertion(+) diff --git a/packages/components/src/index.ts b/packages/components/src/index.ts index 37ba116a7f679e..cc3c0265c42208 100644 --- a/packages/components/src/index.ts +++ b/packages/components/src/index.ts @@ -132,6 +132,7 @@ export { NavigatorToParentButton as __experimentalNavigatorToParentButton, useNavigator as __experimentalUseNavigator, } from './navigator/legacy'; +export { Navigator, useNavigator } from './navigator'; export { default as Notice } from './notice'; export { default as __experimentalNumberControl } from './number-control'; export { default as NoticeList } from './notice/list'; From 24d0bc341c7d545cf9a9214d2156eedf5406c8a7 Mon Sep 17 00:00:00 2001 From: Marco Ciampini Date: Mon, 19 Aug 2024 16:50:50 +0200 Subject: [PATCH 18/38] CHANGELOG --- packages/components/CHANGELOG.md | 1 + 1 file changed, 1 insertion(+) diff --git a/packages/components/CHANGELOG.md b/packages/components/CHANGELOG.md index d34b411833468f..8ef1c7c3bd2002 100644 --- a/packages/components/CHANGELOG.md +++ b/packages/components/CHANGELOG.md @@ -19,6 +19,7 @@ - `Navigator`: add support for exit animation ([#64777](https://github.com/WordPress/gutenberg/pull/64777)). - `Guide`: Update finish button to use the new default size ([#65680](https://github.com/WordPress/gutenberg/pull/65680)). - `BorderControl`: Use `__next40pxDefaultSize` prop for Reset button ([#65682](https://github.com/WordPress/gutenberg/pull/65682)). +- `Navigator`: stabilize APIs ([#64613](https://github.com/WordPress/gutenberg/pull/64613)). ## 28.8.0 (2024-09-19) From d21bb272fd87465bebdf0f05a585fc99781ea9ee Mon Sep 17 00:00:00 2001 From: Marco Ciampini Date: Wed, 21 Aug 2024 17:37:46 +0200 Subject: [PATCH 19/38] Change index.ts extension to tsx to allow Storybook to extract JSDocs better, remove duplicate JSDocs --- .../src/navigator/{index.ts => index.tsx} | 0 .../src/navigator/navigator/component.tsx | 28 ------------------- 2 files changed, 28 deletions(-) rename packages/components/src/navigator/{index.ts => index.tsx} (100%) diff --git a/packages/components/src/navigator/index.ts b/packages/components/src/navigator/index.tsx similarity index 100% rename from packages/components/src/navigator/index.ts rename to packages/components/src/navigator/index.tsx diff --git a/packages/components/src/navigator/navigator/component.tsx b/packages/components/src/navigator/navigator/component.tsx index 63dfd540640d1f..bd49b3682fb144 100644 --- a/packages/components/src/navigator/navigator/component.tsx +++ b/packages/components/src/navigator/navigator/component.tsx @@ -288,32 +288,4 @@ function UnconnectedNavigator( ); } -/** - * The `Navigator` component allows rendering nested views/panels/menus - * (via the `Navigator.Screen` component) and navigate between these different - * view (via the `Navigator.Button` and `Navigator.BackButton` components or the - * `useNavigator` hook). - * - * ```jsx - * import { Navigator } from '@wordpress/components'; - * - * const MyNavigation = () => ( - * - * - *

This is the home screen.

- * - * Navigate to child screen. - * - * - * - * - *

This is the child screen.

- * - * Go back - * - * - * - * ); - * ``` - */ export const Navigator = contextConnect( UnconnectedNavigator, 'Navigator' ); From c805a37390abaa086aa31bf3877e761b71f0a308 Mon Sep 17 00:00:00 2001 From: Marco Ciampini Date: Mon, 26 Aug 2024 10:59:43 +0200 Subject: [PATCH 20/38] Remove unnecessary and mispelled display name for top-level `Navigator` --- packages/components/src/navigator/index.tsx | 1 - 1 file changed, 1 deletion(-) diff --git a/packages/components/src/navigator/index.tsx b/packages/components/src/navigator/index.tsx index cea9b7c56b0c7c..90ae49e3a0a7ba 100644 --- a/packages/components/src/navigator/index.tsx +++ b/packages/components/src/navigator/index.tsx @@ -37,7 +37,6 @@ export { useNavigator } from './use-navigator'; * ``` */ export const Navigator = Object.assign( TopLevelNavigator, { - dislayName: 'Navigator', /** * The `Navigator.Screen` component represents a single view/screen/panel and * should be used in combination with the `Navigator`, the `Navigator.Button` From aa9b28ad1e771917753130e57bd0404e29baedea Mon Sep 17 00:00:00 2001 From: Marco Ciampini Date: Mon, 26 Aug 2024 11:01:02 +0200 Subject: [PATCH 21/38] Remove @example tag from top-level export --- packages/components/src/navigator/index.tsx | 1 - 1 file changed, 1 deletion(-) diff --git a/packages/components/src/navigator/index.tsx b/packages/components/src/navigator/index.tsx index 90ae49e3a0a7ba..7e4762324a3da2 100644 --- a/packages/components/src/navigator/index.tsx +++ b/packages/components/src/navigator/index.tsx @@ -13,7 +13,6 @@ export { useNavigator } from './use-navigator'; * view (via the `Navigator.Button` and `Navigator.BackButton` components or the * `useNavigator` hook). * - * @example * ```jsx * import { Navigator } from '@wordpress/components'; * From 212e29c12dd5926b1bb3c7e649a4225e3951e404 Mon Sep 17 00:00:00 2001 From: Marco Ciampini Date: Mon, 26 Aug 2024 11:02:19 +0200 Subject: [PATCH 22/38] Clean up unused imports --- packages/components/src/navigator/test/index.tsx | 8 +------- 1 file changed, 1 insertion(+), 7 deletions(-) diff --git a/packages/components/src/navigator/test/index.tsx b/packages/components/src/navigator/test/index.tsx index 502d907404a8eb..36916ad9d7d9bc 100644 --- a/packages/components/src/navigator/test/index.tsx +++ b/packages/components/src/navigator/test/index.tsx @@ -15,13 +15,7 @@ import { useState } from '@wordpress/element'; */ import Button from '../../button'; import { Navigator, useNavigator } from '..'; -import { - // NavigatorProvider, - // NavigatorScreen, - // NavigatorButton, - // NavigatorBackButton, - NavigatorToParentButton, -} from '../legacy'; +import { NavigatorToParentButton } from '../legacy'; import type { NavigateOptions } from '../types'; const INVALID_HTML_ATTRIBUTE = { From 0cdc3f42d7a3b58121c7c64c4d14e84be19a9fbf Mon Sep 17 00:00:00 2001 From: Marco Ciampini Date: Thu, 26 Sep 2024 10:33:17 +0200 Subject: [PATCH 23/38] Fix storybook styles --- packages/components/src/navigator/stories/index.story.tsx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/components/src/navigator/stories/index.story.tsx b/packages/components/src/navigator/stories/index.story.tsx index 846fe0acf05f48..6f33d39e3fe451 100644 --- a/packages/components/src/navigator/stories/index.story.tsx +++ b/packages/components/src/navigator/stories/index.story.tsx @@ -40,7 +40,7 @@ const meta: Meta< typeof Navigator > = { * detail of the Navigator component. Do not use outside of * its source code. */ - [data-wp-component="NavigatorProvider"] { + [data-wp-component="Navigator"] { height: 250px; } [data-wp-component="NavigatorScreen"]:not([data-sticky]) { From a2699e964435fb4d74aaf46fb662fbda801facdd Mon Sep 17 00:00:00 2001 From: Marco Ciampini Date: Thu, 26 Sep 2024 10:33:27 +0200 Subject: [PATCH 24/38] Update new section of the docs --- packages/components/src/navigator/navigator/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/components/src/navigator/navigator/README.md b/packages/components/src/navigator/navigator/README.md index 32d697a438a674..e2aafcb49c0be2 100644 --- a/packages/components/src/navigator/navigator/README.md +++ b/packages/components/src/navigator/navigator/README.md @@ -39,7 +39,7 @@ For example: ### Height and animations -Due to how `NavigatorScreen` animations work, it is recommended that the `NavigatorProvider` component is assigned a `height` to prevent some potential UI jumps while moving across screens. +Due to how `Navigator.Screen` animations work, it is recommended that the `Navigator` component is assigned a `height` to prevent some potential UI jumps while moving across screens. ## Props From eb0276db8d435d8bf0acb232da89987647873b40 Mon Sep 17 00:00:00 2001 From: Marco Ciampini Date: Thu, 26 Sep 2024 10:41:01 +0200 Subject: [PATCH 25/38] Update more docs --- packages/components/src/navigator/navigator-button/README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/packages/components/src/navigator/navigator-button/README.md b/packages/components/src/navigator/navigator-button/README.md index 773879e00a1707..916a1f038b35a0 100644 --- a/packages/components/src/navigator/navigator-button/README.md +++ b/packages/components/src/navigator/navigator-button/README.md @@ -12,7 +12,7 @@ The component accepts the following props: ### `attributeName`: `string` -The HTML attribute used to identify the `NavigatorButton`, which is used by `Navigator` to restore focus. +The HTML attribute used to identify the `Navigator.Button`, which is used by `Navigator` to restore focus. - Required: No - Default: `id` @@ -31,4 +31,4 @@ The path of the screen to navigate to. The value of this prop needs to be [a val ### Inherited props -`NavigatorButton` also inherits all of the [`Button` props](/packages/components/src/button/README.md#props), except for `href` and `target`. +`Navigator.Button` also inherits all of the [`Button` props](/packages/components/src/button/README.md#props), except for `href` and `target`. From 7228e33dc13b66edcc6c960b961e4b910f8b30b6 Mon Sep 17 00:00:00 2001 From: Marco Ciampini Date: Thu, 26 Sep 2024 10:41:13 +0200 Subject: [PATCH 26/38] Update deprecation warning --- .../src/navigator/navigator-to-parent-button/component.tsx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/components/src/navigator/navigator-to-parent-button/component.tsx b/packages/components/src/navigator/navigator-to-parent-button/component.tsx index be7e61e764239d..f1c2d27e2284a1 100644 --- a/packages/components/src/navigator/navigator-to-parent-button/component.tsx +++ b/packages/components/src/navigator/navigator-to-parent-button/component.tsx @@ -17,7 +17,7 @@ function UnconnectedNavigatorToParentButton( ) { deprecated( 'wp.components.NavigatorToParentButton', { since: '6.7', - alternative: 'wp.components.NavigatorBackButton', + alternative: 'wp.components.Navigator.BackButton', } ); return ; From 585faacc5549ba2350eac23228c1d893eedb0a66 Mon Sep 17 00:00:00 2001 From: Marco Ciampini Date: Thu, 26 Sep 2024 16:31:20 +0200 Subject: [PATCH 27/38] Update and align docs --- packages/components/src/navigator/index.tsx | 4 ++-- packages/components/src/navigator/legacy.ts | 2 +- packages/components/src/navigator/navigator/README.md | 2 +- 3 files changed, 4 insertions(+), 4 deletions(-) diff --git a/packages/components/src/navigator/index.tsx b/packages/components/src/navigator/index.tsx index 7e4762324a3da2..9bfc8ecb3a197e 100644 --- a/packages/components/src/navigator/index.tsx +++ b/packages/components/src/navigator/index.tsx @@ -10,8 +10,8 @@ export { useNavigator } from './use-navigator'; /** * The `Navigator` component allows rendering nested views/panels/menus * (via the `Navigator.Screen` component) and navigate between these different - * view (via the `Navigator.Button` and `Navigator.BackButton` components or the - * `useNavigator` hook). + * views (via the `Navigator.Button` and `Navigator.BackButton` components or + * the `useNavigator` hook). * * ```jsx * import { Navigator } from '@wordpress/components'; diff --git a/packages/components/src/navigator/legacy.ts b/packages/components/src/navigator/legacy.ts index 0b2fbb2f005662..77ebc8b0328589 100644 --- a/packages/components/src/navigator/legacy.ts +++ b/packages/components/src/navigator/legacy.ts @@ -11,7 +11,7 @@ export { useNavigator } from './use-navigator'; /** * The `NavigatorProvider` component allows rendering nested views/panels/menus * (via the `NavigatorScreen` component and navigate between these different - * view (via the `NavigatorButton` and `NavigatorBackButton` components or the + * views (via the `NavigatorButton` and `NavigatorBackButton` components or the * `useNavigator` hook). * * ```jsx diff --git a/packages/components/src/navigator/navigator/README.md b/packages/components/src/navigator/navigator/README.md index e2aafcb49c0be2..74ec6832d8d577 100644 --- a/packages/components/src/navigator/navigator/README.md +++ b/packages/components/src/navigator/navigator/README.md @@ -1,6 +1,6 @@ # `Navigator` -The `Navigator` component allows rendering nested views/panels/menus (via the [`Navigator.Screen` component](/packages/components/src/navigator/navigator-screen/README.md)) and navigate between these different states (via the [`Navigator.Button`](/packages/components/src/navigator/navigator-button/README.md) and [`Navigator.BackButton`](/packages/components/src/navigator/navigator-back-button/README.md) components or the `useNavigator` hook). +The `Navigator` component allows rendering nested views/panels/menus (via the [`Navigator.Screen` component](/packages/components/src/navigator/navigator-screen/README.md)) and navigate between these different views (via the [`Navigator.Button`](/packages/components/src/navigator/navigator-button/README.md) and [`Navigator.BackButton`](/packages/components/src/navigator/navigator-back-button/README.md) components or the `useNavigator` hook). ## Usage From c0a754f2482ca4aacf47f8d5fe404a053b181f4a Mon Sep 17 00:00:00 2001 From: Marco Ciampini Date: Thu, 26 Sep 2024 16:31:30 +0200 Subject: [PATCH 28/38] Fix tests warning checks --- packages/components/src/navigator/test/index.tsx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/packages/components/src/navigator/test/index.tsx b/packages/components/src/navigator/test/index.tsx index 36916ad9d7d9bc..f75b5c659dfeeb 100644 --- a/packages/components/src/navigator/test/index.tsx +++ b/packages/components/src/navigator/test/index.tsx @@ -646,7 +646,7 @@ describe( 'Navigator', () => { render( Test ); expect( console ).toHaveWarnedWith( - 'wp.components.NavigatorScreen: the `path` should follow a URL-like scheme; it should start with and be separated by the `/` character.' + 'wp.components.Navigator.Screen: the `path` should follow a URL-like scheme; it should start with and be separated by the `/` character.' ); } ); @@ -880,7 +880,7 @@ describe( 'Navigator', () => { // Rendering `NavigatorToParentButton` logs a deprecation notice expect( console ).toHaveWarnedWith( - 'wp.components.NavigatorToParentButton is deprecated since version 6.7. Please use wp.components.NavigatorBackButton instead.' + 'wp.components.NavigatorToParentButton is deprecated since version 6.7. Please use wp.components.Navigator.BackButton instead.' ); } ); From 521ca866684edb7313d705aba1e3a2fcc804d8ad Mon Sep 17 00:00:00 2001 From: Marco Ciampini Date: Thu, 26 Sep 2024 16:35:22 +0200 Subject: [PATCH 29/38] Typo --- packages/components/src/navigator/navigator/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/components/src/navigator/navigator/README.md b/packages/components/src/navigator/navigator/README.md index 74ec6832d8d577..9b08e9f76d5f65 100644 --- a/packages/components/src/navigator/navigator/README.md +++ b/packages/components/src/navigator/navigator/README.md @@ -15,7 +15,7 @@ const MyNavigation = () => ( Navigate to child screen. - * +

This is the child screen.

Go back From 72cd0bc5cab5189cc128275dec28b24518fc7dd4 Mon Sep 17 00:00:00 2001 From: Marco Ciampini Date: Thu, 26 Sep 2024 19:49:19 +0200 Subject: [PATCH 30/38] Fix useContextSystem names --- packages/components/src/navigator/navigator-back-button/hook.ts | 2 +- packages/components/src/navigator/navigator-button/hook.ts | 2 +- .../components/src/navigator/navigator-screen/component.tsx | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/packages/components/src/navigator/navigator-back-button/hook.ts b/packages/components/src/navigator/navigator-back-button/hook.ts index 9ddc095292190a..d6fcd39647bff9 100644 --- a/packages/components/src/navigator/navigator-back-button/hook.ts +++ b/packages/components/src/navigator/navigator-back-button/hook.ts @@ -20,7 +20,7 @@ export function useNavigatorBackButton( as = Button, ...otherProps - } = useContextSystem( props, 'NavigatorBackButton' ); + } = useContextSystem( props, 'Navigator.BackButton' ); const { goBack } = useNavigator(); const handleClick: React.MouseEventHandler< HTMLButtonElement > = diff --git a/packages/components/src/navigator/navigator-button/hook.ts b/packages/components/src/navigator/navigator-button/hook.ts index 3e39b05661e1b2..59d2aaa65662d7 100644 --- a/packages/components/src/navigator/navigator-button/hook.ts +++ b/packages/components/src/navigator/navigator-button/hook.ts @@ -25,7 +25,7 @@ export function useNavigatorButton( as = Button, attributeName = 'id', ...otherProps - } = useContextSystem( props, 'NavigatorButton' ); + } = useContextSystem( props, 'Navigator.Button' ); const escapedPath = escapeAttribute( path ); diff --git a/packages/components/src/navigator/navigator-screen/component.tsx b/packages/components/src/navigator/navigator-screen/component.tsx index 98be7b0dab9999..fe0d81b90a17be 100644 --- a/packages/components/src/navigator/navigator-screen/component.tsx +++ b/packages/components/src/navigator/navigator-screen/component.tsx @@ -48,7 +48,7 @@ function UnconnectedNavigatorScreen( path, onAnimationEnd: onAnimationEndProp, ...otherProps - } = useContextSystem( props, 'NavigatorScreen' ); + } = useContextSystem( props, 'Navigator.Screen' ); const { location, match, addScreen, removeScreen } = useContext( NavigatorContext ); From 0987fac5799e554cc823fa53067481106957a5b6 Mon Sep 17 00:00:00 2001 From: Marco Ciampini Date: Thu, 26 Sep 2024 19:59:03 +0200 Subject: [PATCH 31/38] Remove mentions of the `useNavigator` hook --- packages/components/src/navigator/index.tsx | 11 +++++------ packages/components/src/navigator/legacy.ts | 13 +++++-------- .../src/navigator/navigator-back-button/README.md | 2 +- .../src/navigator/navigator-button/README.md | 2 +- .../src/navigator/navigator-screen/README.md | 2 +- .../components/src/navigator/navigator/README.md | 2 +- 6 files changed, 14 insertions(+), 18 deletions(-) diff --git a/packages/components/src/navigator/index.tsx b/packages/components/src/navigator/index.tsx index 9bfc8ecb3a197e..1d9ae95441e01a 100644 --- a/packages/components/src/navigator/index.tsx +++ b/packages/components/src/navigator/index.tsx @@ -9,9 +9,8 @@ export { useNavigator } from './use-navigator'; /** * The `Navigator` component allows rendering nested views/panels/menus - * (via the `Navigator.Screen` component) and navigate between these different - * views (via the `Navigator.Button` and `Navigator.BackButton` components or - * the `useNavigator` hook). + * (via the `Navigator.Screen` component) and navigate between them + * (via the `Navigator.Button` and `Navigator.BackButton` components). * * ```jsx * import { Navigator } from '@wordpress/components'; @@ -39,7 +38,7 @@ export const Navigator = Object.assign( TopLevelNavigator, { /** * The `Navigator.Screen` component represents a single view/screen/panel and * should be used in combination with the `Navigator`, the `Navigator.Button` - * and the `Navigator.BackButton` components, and the `useNavigator` hook. + * and the `Navigator.BackButton` components. * * @example * ```jsx @@ -70,7 +69,7 @@ export const Navigator = Object.assign( TopLevelNavigator, { /** * The `Navigator.Button` component can be used to navigate to a screen and * should be used in combination with the `Navigator`, the `Navigator.Screen` - * and the `Navigator.BackButton` components, and the `useNavigator` hook. + * and the `Navigator.BackButton` components. * * @example * ```jsx @@ -101,7 +100,7 @@ export const Navigator = Object.assign( TopLevelNavigator, { /** * The `Navigator.BackButton` component can be used to navigate to a screen and * should be used in combination with the `Navigator`, the `Navigator.Screen` - * and the `Navigator.Button` components, and the `useNavigator` hook. + * and the `Navigator.Button` components. * * @example * ```jsx diff --git a/packages/components/src/navigator/legacy.ts b/packages/components/src/navigator/legacy.ts index 77ebc8b0328589..1caa5380fc049e 100644 --- a/packages/components/src/navigator/legacy.ts +++ b/packages/components/src/navigator/legacy.ts @@ -10,9 +10,8 @@ export { useNavigator } from './use-navigator'; /** * The `NavigatorProvider` component allows rendering nested views/panels/menus - * (via the `NavigatorScreen` component and navigate between these different - * views (via the `NavigatorButton` and `NavigatorBackButton` components or the - * `useNavigator` hook). + * (via the `NavigatorScreen` component and navigate between them + * (via the `NavigatorButton` and `NavigatorBackButton` components). * * ```jsx * import { @@ -48,8 +47,7 @@ export const NavigatorProvider = Object.assign( InternalNavigator, { /** * The `NavigatorScreen` component represents a single view/screen/panel and * should be used in combination with the `NavigatorProvider`, the - * `NavigatorButton` and the `NavigatorBackButton` components (or the `useNavigator` - * hook). + * `NavigatorButton` and the `NavigatorBackButton` components. * * @example * ```jsx @@ -86,7 +84,7 @@ export const NavigatorScreen = Object.assign( InternalNavigatorScreen, { /** * The `NavigatorButton` component can be used to navigate to a screen and should * be used in combination with the `NavigatorProvider`, the `NavigatorScreen` - * and the `NavigatorBackButton` components (or the `useNavigator` hook). + * and the `NavigatorBackButton` components. * * @example * ```jsx @@ -123,8 +121,7 @@ export const NavigatorButton = Object.assign( InternalNavigatorButton, { /** * The `NavigatorBackButton` component can be used to navigate to a screen and * should be used in combination with the `NavigatorProvider`, the - * `NavigatorScreen` and the `NavigatorButton` components (or the `useNavigator` - * hook). + * `NavigatorScreen` and the `NavigatorButton` components. * * @example * ```jsx diff --git a/packages/components/src/navigator/navigator-back-button/README.md b/packages/components/src/navigator/navigator-back-button/README.md index 6388805e5af828..b7e45dab5a437d 100644 --- a/packages/components/src/navigator/navigator-back-button/README.md +++ b/packages/components/src/navigator/navigator-back-button/README.md @@ -1,6 +1,6 @@ # `Navigator.BackButton` -The `Navigator.BackButton` component can be used to navigate to a screen and should be used in combination with the [`Navigator`](/packages/components/src/navigator/navigator/README.md), the [`Navigator.Screen`](/packages/components/src/navigator/navigator-screen/README.md) and the [`Navigator.Button`](/packages/components/src/navigator/navigator-button/README.md) components, and the `useNavigator` hook. +The `Navigator.BackButton` component can be used to navigate to a screen and should be used in combination with the [`Navigator`](/packages/components/src/navigator/navigator/README.md), the [`Navigator.Screen`](/packages/components/src/navigator/navigator-screen/README.md) and the [`Navigator.Button`](/packages/components/src/navigator/navigator-button/README.md) components. ## Usage diff --git a/packages/components/src/navigator/navigator-button/README.md b/packages/components/src/navigator/navigator-button/README.md index 916a1f038b35a0..10f035040afe3e 100644 --- a/packages/components/src/navigator/navigator-button/README.md +++ b/packages/components/src/navigator/navigator-button/README.md @@ -1,6 +1,6 @@ # `Navigator.Button` -The `Navigator.Button` component can be used to navigate to a screen and should be used in combination with the [`Navigator`](/packages/components/src/navigator/navigator/README.md), the [`Navigator.Screen`](/packages/components/src/navigator/navigator-screen/README.md) and the [`Navigator.BackButton`](/packages/components/src/navigator/navigator-back-button/README.md) components, and the `useNavigator` hook. +The `Navigator.Button` component can be used to navigate to a screen and should be used in combination with the [`Navigator`](/packages/components/src/navigator/navigator/README.md), the [`Navigator.Screen`](/packages/components/src/navigator/navigator-screen/README.md) and the [`Navigator.BackButton`](/packages/components/src/navigator/navigator-back-button/README.md) components. ## Usage diff --git a/packages/components/src/navigator/navigator-screen/README.md b/packages/components/src/navigator/navigator-screen/README.md index 3b87b66ab1842f..28db08825ea90d 100644 --- a/packages/components/src/navigator/navigator-screen/README.md +++ b/packages/components/src/navigator/navigator-screen/README.md @@ -1,6 +1,6 @@ # `Navigator.Screen` -The `Navigator.Screen` component represents a single view/screen/panel and should be used in combination with the [`Navigator`](/packages/components/src/navigator/navigator/README.md), the [`Navigator.Button`](/packages/components/src/navigator/navigator-button/README.md) and the [`Navigator.BackButton`](/packages/components/src/navigator/navigator-back-button/README.md) components, and the `useNavigator` hook. +The `Navigator.Screen` component represents a single view/screen/panel and should be used in combination with the [`Navigator`](/packages/components/src/navigator/navigator/README.md), the [`Navigator.Button`](/packages/components/src/navigator/navigator-button/README.md) and the [`Navigator.BackButton`](/packages/components/src/navigator/navigator-back-button/README.md) components. ## Usage diff --git a/packages/components/src/navigator/navigator/README.md b/packages/components/src/navigator/navigator/README.md index 9b08e9f76d5f65..7df4da21cceb98 100644 --- a/packages/components/src/navigator/navigator/README.md +++ b/packages/components/src/navigator/navigator/README.md @@ -1,6 +1,6 @@ # `Navigator` -The `Navigator` component allows rendering nested views/panels/menus (via the [`Navigator.Screen` component](/packages/components/src/navigator/navigator-screen/README.md)) and navigate between these different views (via the [`Navigator.Button`](/packages/components/src/navigator/navigator-button/README.md) and [`Navigator.BackButton`](/packages/components/src/navigator/navigator-back-button/README.md) components or the `useNavigator` hook). +The `Navigator` component allows rendering nested views/panels/menus (via the [`Navigator.Screen` component](/packages/components/src/navigator/navigator-screen/README.md)) and navigate between them (via the [`Navigator.Button`](/packages/components/src/navigator/navigator-button/README.md) and [`Navigator.BackButton`](/packages/components/src/navigator/navigator-back-button/README.md) components). ## Usage From ca7ac76904560ea2cf36a2e3db9dd8d3c9b53f8e Mon Sep 17 00:00:00 2001 From: Marco Ciampini Date: Thu, 26 Sep 2024 20:04:54 +0200 Subject: [PATCH 32/38] useNavigator JSDocs --- packages/components/src/navigator/use-navigator.ts | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/packages/components/src/navigator/use-navigator.ts b/packages/components/src/navigator/use-navigator.ts index 7ac35d73150d32..1ea99f3f1c857d 100644 --- a/packages/components/src/navigator/use-navigator.ts +++ b/packages/components/src/navigator/use-navigator.ts @@ -10,7 +10,10 @@ import { NavigatorContext } from './context'; import type { Navigator } from './types'; /** - * Retrieves a `navigator` instance. + * Retrieves a `navigator` instance. This hook provides advanced functionality, + * such as imperatively navigating to a new location (with options like + * navigating back or skipping focus restoration) and accessing the current + * location and path parameters. */ export function useNavigator(): Navigator { const { location, params, goTo, goBack, goToParent } = From 1d29ff11a2f3ef4818ce4c82fdbc633228d606f7 Mon Sep 17 00:00:00 2001 From: Marco Ciampini Date: Thu, 26 Sep 2024 20:31:58 +0200 Subject: [PATCH 33/38] Move all READMEs under the main README --- .../navigator/navigator-back-button/README.md | 11 -- .../src/navigator/navigator-button/README.md | 34 ------ .../src/navigator/navigator-screen/README.md | 29 ----- .../src/navigator/navigator/README.md | 104 ++++++++++++++++-- 4 files changed, 92 insertions(+), 86 deletions(-) delete mode 100644 packages/components/src/navigator/navigator-back-button/README.md delete mode 100644 packages/components/src/navigator/navigator-button/README.md delete mode 100644 packages/components/src/navigator/navigator-screen/README.md diff --git a/packages/components/src/navigator/navigator-back-button/README.md b/packages/components/src/navigator/navigator-back-button/README.md deleted file mode 100644 index b7e45dab5a437d..00000000000000 --- a/packages/components/src/navigator/navigator-back-button/README.md +++ /dev/null @@ -1,11 +0,0 @@ -# `Navigator.BackButton` - -The `Navigator.BackButton` component can be used to navigate to a screen and should be used in combination with the [`Navigator`](/packages/components/src/navigator/navigator/README.md), the [`Navigator.Screen`](/packages/components/src/navigator/navigator-screen/README.md) and the [`Navigator.Button`](/packages/components/src/navigator/navigator-button/README.md) components. - -## Usage - -Refer to [the `Navigator` component](/packages/components/src/navigator/navigator/README.md#usage) for a usage example. - -### Inherited props - -`Navigator.BackButton` also inherits all of the [`Button` props](/packages/components/src/button/README.md#props), except for `href` and `target`. diff --git a/packages/components/src/navigator/navigator-button/README.md b/packages/components/src/navigator/navigator-button/README.md deleted file mode 100644 index 10f035040afe3e..00000000000000 --- a/packages/components/src/navigator/navigator-button/README.md +++ /dev/null @@ -1,34 +0,0 @@ -# `Navigator.Button` - -The `Navigator.Button` component can be used to navigate to a screen and should be used in combination with the [`Navigator`](/packages/components/src/navigator/navigator/README.md), the [`Navigator.Screen`](/packages/components/src/navigator/navigator-screen/README.md) and the [`Navigator.BackButton`](/packages/components/src/navigator/navigator-back-button/README.md) components. - -## Usage - -Refer to [the `Navigator` component](/packages/components/src/navigator/navigator/README.md#usage) for a usage example. - -## Props - -The component accepts the following props: - -### `attributeName`: `string` - -The HTML attribute used to identify the `Navigator.Button`, which is used by `Navigator` to restore focus. - -- Required: No -- Default: `id` - -### `onClick`: `React.MouseEventHandler< HTMLElement >` - -The callback called in response to a `click` event. - -- Required: No - -### `path`: `string` - -The path of the screen to navigate to. The value of this prop needs to be [a valid value for an HTML attribute](https://html.spec.whatwg.org/multipage/syntax.html#attributes-2). - -- Required: Yes - -### Inherited props - -`Navigator.Button` also inherits all of the [`Button` props](/packages/components/src/button/README.md#props), except for `href` and `target`. diff --git a/packages/components/src/navigator/navigator-screen/README.md b/packages/components/src/navigator/navigator-screen/README.md deleted file mode 100644 index 28db08825ea90d..00000000000000 --- a/packages/components/src/navigator/navigator-screen/README.md +++ /dev/null @@ -1,29 +0,0 @@ -# `Navigator.Screen` - -The `Navigator.Screen` component represents a single view/screen/panel and should be used in combination with the [`Navigator`](/packages/components/src/navigator/navigator/README.md), the [`Navigator.Button`](/packages/components/src/navigator/navigator-button/README.md) and the [`Navigator.BackButton`](/packages/components/src/navigator/navigator-back-button/README.md) components. - -## Usage - -Refer to [the `Navigator` component](/packages/components/src/navigator/navigator/README.md#usage) for a usage example. - -## Props - -The component accepts the following props: - -### `path`: `string` - -The screen"s path, matched against the current path stored in the navigator. - -`Navigator` assumes that screens are organized hierarchically according to their `path`, which should follow a URL-like scheme where each path segment starts with and is separated by the `/` character. - -`Navigator` will treat "back" navigations as going to the parent screen — it is therefore responsibility of the consumer of the component to create the correct screen hierarchy. - -For example: - -- `/` is the root of all paths. There should always be a screen with `path="/"`. -- `/parent/child` is a child of `/parent`. -- `/parent/child/grand-child` is a child of `/parent/child`. -- `/parent/:param` is a child of `/parent` as well. -- if the current screen has a `path` with value `/parent/child/grand-child`, when going "back" `Navigator` will try to recursively navigate the path hierarchy until a matching screen (or the root `/`) is found. - -- Required: Yes diff --git a/packages/components/src/navigator/navigator/README.md b/packages/components/src/navigator/navigator/README.md index 7df4da21cceb98..0cf54c766012ca 100644 --- a/packages/components/src/navigator/navigator/README.md +++ b/packages/components/src/navigator/navigator/README.md @@ -1,6 +1,6 @@ # `Navigator` -The `Navigator` component allows rendering nested views/panels/menus (via the [`Navigator.Screen` component](/packages/components/src/navigator/navigator-screen/README.md)) and navigate between them (via the [`Navigator.Button`](/packages/components/src/navigator/navigator-button/README.md) and [`Navigator.BackButton`](/packages/components/src/navigator/navigator-back-button/README.md) components). +`Navigator` is a collection components that allow rendering nested views/panels/menus (via the [`Navigator.Screen` component](/packages/components/src/navigator/navigator-screen/README.md)) and navigate between them (via the [`Navigator.Button`](/packages/components/src/navigator/navigator-button/README.md) and [`Navigator.BackButton`](/packages/components/src/navigator/navigator-back-button/README.md) components). ## Usage @@ -31,33 +31,113 @@ const MyNavigation = () => ( For example: +- `/` is the root of all paths. There should always be a screen with `path="/"`; +- `/parent/child` is a child of `/parent`; +- `/parent/child/grand-child` is a child of `/parent/child`; +- `/parent/:param` is a child of `/parent` as well; +- if the current screen has a `path="/parent/child/grand-child"`, when going "back" `Navigator` will try to recursively navigate the path hierarchy until a matching screen (or the root `/`) is found. + +### Height and animations + +Due to how `Navigator.Screen` animations work, it is recommended that the `Navigator` component is assigned a `height` to prevent some potential UI jumps while moving across screens. + +### Individual components + +`Navigator` is comprised of four individual components: + +- `Navigator`: a wrapper component and context provider. It holds the main logic for hiding and showing screens. +- `Navigator.Screen`: represents a single view/screen/panel; +- `Navigator.Button`: renders a button that allows navigating to a different `Navigator.Screen`; +- `Navigator.BackButton`: renders a button that allows navigating to the parent `Navigator.Screen` (see the section above about hierarchical paths). + +For advanced usages, consumers can use the `useNavigator` hook. + +#### `Navigator` + +##### Props + +###### `initialPath`: `string` + +The initial active path. + +- Required: Yes + +###### `children`: `string` + +The children elements. + +- Required: Yes + +#### `Navigator.Screen` + +###### `path`: `string` + +The screen"s path, matched against the current path stored in the navigator. + +`Navigator` assumes that screens are organized hierarchically according to their `path`, which should follow a URL-like scheme where each path segment starts with and is separated by the `/` character. + +`Navigator` will treat "back" navigations as going to the parent screen — it is therefore responsibility of the consumer of the component to create the correct screen hierarchy. + +For example: + - `/` is the root of all paths. There should always be a screen with `path="/"`. - `/parent/child` is a child of `/parent`. - `/parent/child/grand-child` is a child of `/parent/child`. - `/parent/:param` is a child of `/parent` as well. - if the current screen has a `path` with value `/parent/child/grand-child`, when going "back" `Navigator` will try to recursively navigate the path hierarchy until a matching screen (or the root `/`) is found. -### Height and animations +- Required: Yes -Due to how `Navigator.Screen` animations work, it is recommended that the `Navigator` component is assigned a `height` to prevent some potential UI jumps while moving across screens. +###### `children`: `string` -## Props +The children elements. -The component accepts the following props: +- Required: Yes -### `initialPath`: `string` +##### `Navigator.Button` -The initial active path. +###### `path`: `string` + +The path of the screen to navigate to. The value of this prop needs to be [a valid value for an HTML attribute](https://html.spec.whatwg.org/multipage/syntax.html#attributes-2). + +- Required: Yes + +###### `attributeName`: `string` + +The HTML attribute used to identify the `Navigator.Button`, which is used by `Navigator` to restore focus. - Required: No +- Default: `id` + +###### `children`: `string` + +The children elements. + +- Required: No + +###### Inherited props + +`Navigator.Button` also inherits all of the [`Button` props](/packages/components/src/button/README.md#props), except for `href` and `target`. + +##### `Navigator.BackButton` + +###### `children`: `string` + +The children elements. + +- Required: No + +###### Inherited props + +`Navigator.BackButton` also inherits all of the [`Button` props](/packages/components/src/button/README.md#props), except for `href` and `target`. -## The `navigator` object +###### `useNavigator` You can retrieve a `navigator` instance by using the `useNavigator` hook. The `navigator` instance has a few properties: -### `goTo`: `( path: string, options: NavigateOptions ) => void` +###### `goTo`: `( path: string, options: NavigateOptions ) => void` The `goTo` function allows navigating to a given path. The second argument can augment the navigation operations with different options. @@ -67,7 +147,7 @@ The available options are: - `isBack`: `boolean`. An optional property used to specify whether the navigation should be considered as backwards (thus enabling focus restoration when possible, and causing the animation to be backwards too); - `skipFocus`: `boolean`. An optional property used to opt out of `Navigator`'s focus management, useful when the consumer of the component wants to manage focus themselves; -### `goBack`: `( path: string, options: NavigateOptions ) => void` +###### `goBack`: `( path: string, options: NavigateOptions ) => void` The `goBack` function allows navigating to the parent screen. Parent/child navigation only works if the paths you define are hierarchical (see note above). @@ -75,7 +155,7 @@ When a match is not found, the function will try to recursively navigate the pat The available options are the same as for the `goTo` method, except for the `isBack` property, which is not available for the `goBack` method. -### `location`: `NavigatorLocation` +###### `location`: `NavigatorLocation` The `location` object represent the current location, and has a few properties: @@ -83,6 +163,6 @@ The `location` object represent the current location, and has a few properties: - `isBack`: `boolean`. A flag that is `true` when the current location was reached by navigating backwards. - `isInitial`: `boolean`. A flag that is `true` only for the initial location. -### `params`: `Record< string, string | string[] >` +###### `params`: `Record< string, string | string[] >` The parsed record of parameters from the current location. For example if the current screen path is `/product/:productId` and the location is `/product/123`, then `params` will be `{ productId: '123' }`. From 616015a27ec83c71853fcdfe54196ad6e2efbc84 Mon Sep 17 00:00:00 2001 From: Marco Ciampini Date: Thu, 26 Sep 2024 20:32:21 +0200 Subject: [PATCH 34/38] Move README to component's root folder --- packages/components/src/navigator/{navigator => }/README.md | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename packages/components/src/navigator/{navigator => }/README.md (100%) diff --git a/packages/components/src/navigator/navigator/README.md b/packages/components/src/navigator/README.md similarity index 100% rename from packages/components/src/navigator/navigator/README.md rename to packages/components/src/navigator/README.md From 4639c0ba03a3aa7925050bc6ce273e583522c3d3 Mon Sep 17 00:00:00 2001 From: Marco Ciampini Date: Thu, 26 Sep 2024 20:32:35 +0200 Subject: [PATCH 35/38] Update types JSDocs to match README --- packages/components/src/navigator/types.ts | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/packages/components/src/navigator/types.ts b/packages/components/src/navigator/types.ts index ad26d3f1c9f490..aa0e30c97389e3 100644 --- a/packages/components/src/navigator/types.ts +++ b/packages/components/src/navigator/types.ts @@ -100,6 +100,24 @@ export type NavigatorProps = { export type NavigatorScreenProps = { /** * The screen's path, matched against the current path stored in the navigator. + * + * `Navigator` assumes that screens are organized hierarchically according + * to their `path`, which should follow a URL-like scheme where each path + * segment starts with and is separated by the `/` character. + * + * `Navigator` will treat "back" navigations as going to the parent screen — + * it is therefore responsibility of the consumer of the component to create + * the correct screen hierarchy. + * + * For example: + * - `/` is the root of all paths. There should always be a screen with + * `path="/"`; + * - `/parent/child` is a child of `/parent`; + * - `/parent/child/grand-child` is a child of `/parent/child`; + * - `/parent/:param` is a child of `/parent` as well; + * - if the current screen has a `path="/parent/child/grand-child"`, when + * going "back" `Navigator` will try to recursively navigate the path + * hierarchy until a matching screen (or the root `/`) is found. */ path: string; /** From 4ea2a099a44ac7850b145de3c63eb352f749c367 Mon Sep 17 00:00:00 2001 From: Marco Ciampini Date: Thu, 26 Sep 2024 20:38:22 +0200 Subject: [PATCH 36/38] Update docs manifest --- docs/manifest.json | 20 +------------------- 1 file changed, 1 insertion(+), 19 deletions(-) diff --git a/docs/manifest.json b/docs/manifest.json index cabbd6e2e37daf..8387b9079694c0 100644 --- a/docs/manifest.json +++ b/docs/manifest.json @@ -1097,28 +1097,10 @@ "markdown_source": "../packages/components/src/navigation/README.md", "parent": "components" }, - { - "title": "NavigatorBackButton", - "slug": "navigator-back-button", - "markdown_source": "../packages/components/src/navigator/navigator-back-button/README.md", - "parent": "components" - }, - { - "title": "NavigatorButton", - "slug": "navigator-button", - "markdown_source": "../packages/components/src/navigator/navigator-button/README.md", - "parent": "components" - }, - { - "title": "NavigatorScreen", - "slug": "navigator-screen", - "markdown_source": "../packages/components/src/navigator/navigator-screen/README.md", - "parent": "components" - }, { "title": "Navigator", "slug": "navigator", - "markdown_source": "../packages/components/src/navigator/navigator/README.md", + "markdown_source": "../packages/components/src/navigator/README.md", "parent": "components" }, { From 999795a95b324bc2cbefb636c5c3fbe96d1c4a96 Mon Sep 17 00:00:00 2001 From: Marco Ciampini Date: Fri, 27 Sep 2024 16:24:56 +0200 Subject: [PATCH 37/38] Fix JSDocs typos, grammar, and broken links. --- packages/components/src/navigator/README.md | 12 ++++++------ packages/components/src/navigator/test/index.tsx | 2 +- packages/components/src/navigator/types.ts | 4 ++-- 3 files changed, 9 insertions(+), 9 deletions(-) diff --git a/packages/components/src/navigator/README.md b/packages/components/src/navigator/README.md index 0cf54c766012ca..00b1cfaeebe0f7 100644 --- a/packages/components/src/navigator/README.md +++ b/packages/components/src/navigator/README.md @@ -1,6 +1,6 @@ # `Navigator` -`Navigator` is a collection components that allow rendering nested views/panels/menus (via the [`Navigator.Screen` component](/packages/components/src/navigator/navigator-screen/README.md)) and navigate between them (via the [`Navigator.Button`](/packages/components/src/navigator/navigator-button/README.md) and [`Navigator.BackButton`](/packages/components/src/navigator/navigator-back-button/README.md) components). +`Navigator` is a collection components that allow rendering nested views/panels/menus (via the `Navigator.Screen` component) and navigate between them (via the `Navigator.Button` and `Navigator.BackButton` components). ## Usage @@ -27,7 +27,7 @@ const MyNavigation = () => ( `Navigator` assumes that screens are organized hierarchically according to their `path`, which should follow a URL-like scheme where each path segment starts with and is separated by the `/` character. -`Navigator` will treat "back" navigations as going to the parent screen — it is therefore responsibility of the consumer of the component to create the correct screen hierarchy. +`Navigator` will treat "back" navigations as going to the parent screen — it is, therefore, the responsibility of the consumer of the component to create the correct screen hierarchy. For example: @@ -72,11 +72,11 @@ The children elements. ###### `path`: `string` -The screen"s path, matched against the current path stored in the navigator. +The screen's path, matched against the current path stored in the navigator. `Navigator` assumes that screens are organized hierarchically according to their `path`, which should follow a URL-like scheme where each path segment starts with and is separated by the `/` character. -`Navigator` will treat "back" navigations as going to the parent screen — it is therefore responsibility of the consumer of the component to create the correct screen hierarchy. +`Navigator` will treat "back" navigations as going to the parent screen — it is, therefore, the responsibility of the consumer of the component to create the correct screen hierarchy. For example: @@ -151,13 +151,13 @@ The available options are: The `goBack` function allows navigating to the parent screen. Parent/child navigation only works if the paths you define are hierarchical (see note above). -When a match is not found, the function will try to recursively navigate the path hierarchy until a matching screen (or the root `/`) are found. +When a match is not found, the function will try to recursively navigate the path hierarchy until a matching screen (or the root `/`) is found. The available options are the same as for the `goTo` method, except for the `isBack` property, which is not available for the `goBack` method. ###### `location`: `NavigatorLocation` -The `location` object represent the current location, and has a few properties: +The `location` object represents the current location, and has a few properties: - `path`: `string`. The path associated to the location. - `isBack`: `boolean`. A flag that is `true` when the current location was reached by navigating backwards. diff --git a/packages/components/src/navigator/test/index.tsx b/packages/components/src/navigator/test/index.tsx index f75b5c659dfeeb..cab6e9a4cdadff 100644 --- a/packages/components/src/navigator/test/index.tsx +++ b/packages/components/src/navigator/test/index.tsx @@ -308,7 +308,7 @@ const MyNavigation = ( { - { /* A `NavigatorScreen` with `path={ PATHS.NOT_FOUND }` is purposefully not included. */ } + { /* A `Navigator.Screen` with `path={ PATHS.NOT_FOUND }` is purposefully not included. */ } diff --git a/packages/components/src/navigator/types.ts b/packages/components/src/navigator/types.ts index aa0e30c97389e3..aeb5fd3b12c7fb 100644 --- a/packages/components/src/navigator/types.ts +++ b/packages/components/src/navigator/types.ts @@ -106,8 +106,8 @@ export type NavigatorScreenProps = { * segment starts with and is separated by the `/` character. * * `Navigator` will treat "back" navigations as going to the parent screen — - * it is therefore responsibility of the consumer of the component to create - * the correct screen hierarchy. + * it is, therefore, the responsibility of the consumer of the component to + * create the correct screen hierarchy. * * For example: * - `/` is the root of all paths. There should always be a screen with From 578c98a4c606aa7cc8306603815daf3dacae92da Mon Sep 17 00:00:00 2001 From: Marco Ciampini Date: Fri, 27 Sep 2024 16:30:45 +0200 Subject: [PATCH 38/38] Update storybook selector --- packages/components/src/navigator/stories/index.story.tsx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/components/src/navigator/stories/index.story.tsx b/packages/components/src/navigator/stories/index.story.tsx index 6f33d39e3fe451..e9e342bb0d2eee 100644 --- a/packages/components/src/navigator/stories/index.story.tsx +++ b/packages/components/src/navigator/stories/index.story.tsx @@ -43,7 +43,7 @@ const meta: Meta< typeof Navigator > = { [data-wp-component="Navigator"] { height: 250px; } - [data-wp-component="NavigatorScreen"]:not([data-sticky]) { + [data-wp-component="Navigator.Screen"] { padding: 8px; } ` }