Navigator: stabilize and export APIs #64613

ciampo · 2024-08-19T13:46:09Z

What?

Part of #59418
Supersedes #60927
Follow-up to #63317

Export the Navigator component, its subcomponents, and the useNavigator hook as stable APIs from the @wordpress/components package

Why?

This is part of a larger effort to remove __experimental prefix from all "experimental" components, effectively promoting them to regular stable components. See the related issue for more context.

How?

Aside from the existing legacy exports, which use the __experimental prefix, add new, unprefixed exports:
- Legacy exports stay untouched;
- The new, stable exports will adopt slightly different names compared to legacy and the overloaded naming convention that we agreed to apply for component components:
  - NavigatorProvider => Navigator
  - NavigatorScreen => Navigator.Screen
  - NavigatorButton => Navigator.Button
  - NavigatorBackButton => Navigator.BackButton
  - NavigatorToParentButton won't be exported since it's already deprecated in the experimental version of the component
Updated all JSDocs and README
Updated Storybook and Unit Tests to use the stable version of the component
Added Storybook redirect to avoid getting broken links
A few smaller changes:
- Updated the internal context namespacing (which shouldn't be a breaking change since context is an internal API of the @wordpress/components package)

Next steps?

refactor existing usages in Gutenberg to stable version
deprecate experimental version (both in JSDocs and with a runtime warning) (+ add unit tests for deprecation warnings)

Testing Instructions

Technically there shouldn't be any runtime (behavioral) changes to Navigator;
Make sure that Storybook examples are documented correctly and work as expected;
Smoke test Navigator usages across the editor;
Review JSDocs, READMEs, and IntelliSense snippets for both legacy and stable APIs

✍️ Dev note

The legacy set of __experimentalNavigator* APIs is deprecated and should instead be imported as Navigator. All of the sub-components are also available via the Navigator namespace.

Moreover, the __experimentalNavigatorToParentButton component and the goToParent method available via the __experimentalUseNavigator hook are now deprecated, and they now behave identically to the __experimentalNavigatorBackButton and the goBack method.

To recap:

__experimentalNavigatorProvider => Navigator
__experimentalNavigatorScreen => Navigator.Screen
__experimentalNavigatorButton => Navigator.Button
__experimentalNavigatorBackButton => Navigator.BackButton
__experimentalNavigatorToParentButton => Navigator.BackButton
__experimentalUseNavigator => useNavigator

ciampo · 2024-08-19T14:18:47Z

packages/components/src/navigator/legacy.ts

Legacy exports have been moved to a separate legacy.ts file (including the legacy JSDocs mentioning the components with their experimental export name).

This makes it easy to have separate names from the stable version, different JSDocs, and deprecation warnings.

ciampo · 2024-08-19T14:19:24Z

packages/components/src/navigator/index.ts

New exports (and their up-to-date JSDocs) have been moved to the folder's main index.ts file

ciampo · 2024-08-19T14:20:40Z

packages/components/src/navigator/navigator-back-button/README.md

All READMEs have also been updated:

removed experimental snippet

updated the naming of all Navigator sub-components, including internal links to other READMEs

ciampo · 2024-08-19T14:21:33Z

packages/components/src/navigator/navigator-provider/index.ts

This file was actually renamed to packages/components/src/navigator/navigator/index.tsx, but GitHub is not picking that up

ciampo · 2024-08-19T14:23:25Z

packages/components/src/navigator/navigator/component.tsx

- * 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


The top level Navigator component (previously named NavigatorProvider) is the only component for which I've kept a JSDoc for the internal implementation, because apparently Storybook uses it when displaying docs 🤷 Not sure why it doesn't use the one defined in packages/components/src/navigator/index.ts

it seems like the ts extension was the problem — changing it to .tsx seems to allow Storybook to pick the JSDoc up 😅 85471a9

cc @mirka

ciampo · 2024-08-19T14:24:07Z

packages/components/src/navigator/stories/index.story.tsx

+		// @ts-expect-error - See https://github.com/storybookjs/storybook/issues/23170
+		BackButton: Navigator.BackButton,
+	},
+	title: 'Components/Navigator',


Updated the PREVIOUSLY_EXPERIMENTAL_COMPONENTS in storybook/manager-head.html to make sure old links still work

github-actions · 2024-08-19T14:51:25Z

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message.

Co-authored-by: ciampo <[email protected]>
Co-authored-by: mirka <[email protected]>
Co-authored-by: tyxla <[email protected]>

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

mirka · 2024-08-22T09:16:00Z

docs/manifest.json

-	{
-		"title": "NavigatorProvider",
-		"slug": "navigator-provider",
-		"markdown_source": "../packages/components/src/navigator/navigator-provider/README.md",
-		"parent": "components"
-	},


FYI, removing things from the manifest is not going to remove it from the Block Editor Handbook 😱 There are some extra steps, see #60003 (comment)

Thank you! I'll follow-up accordingly

Just a reminder we'll need to take care of this one after merging.

Hey @WordPress/wordpress-org-meta-team , could you help with this? We need to update the Block Editor Handbook, removing the following components:

NavigatorProvider

NavigatorButton

NavigatorBackButton

NavigatorScreen

NavigatorToParentButton

If possible, we'd also like to set a redirect for those pages being removed. The redirect should point to the Navigator component.

Could you please help with that? Thank you 🙏

These updates have shipped. I noticed the formatting on the new doc loses consistency around the Navigator.Button point (heading is not bold):

Thank you!

I noticed the formatting on the new doc loses consistency around the Navigator.Button point (heading is not bold):

Good catch! Opened #65763 to fix it

packages/components/CHANGELOG.md

packages/components/src/navigator/index.tsx

packages/components/src/navigator/navigator-back-button/component.tsx

packages/components/src/navigator/test/index.tsx

ciampo · 2024-08-22T10:27:00Z

I'm going to resume work on this PR after #64675 is merged.

tyxla · 2024-08-23T10:24:33Z

I'm going to resume work on this PR after #64675 is merged.

Sounds good. I was starting to review it, but I will halt it for now.

I wonder if it's a good idea to approach this modularly and split whatever we can to separate PRs to keep this one smaller.

ciampo · 2024-08-26T09:09:00Z

I rebased and addressed simple feedback.

I would still wait before reviewing this PR. The current plan of action is:

Review and merge Navigator: fix isInitial, refine focusSelector logic #64786
Review and merge Navigator: add support for exit animation #64777
Rebase this PR and prepare for final review

I've also updated the tracking issue adding all of the planned follow-up step to this PR.

I wonder if it's a good idea to approach this modularly and split whatever we can to separate PRs to keep this one smaller.

@tyxla , Even if the size of the PR is medium-large, I believe 99% of the changes left in this PR are simple renames — and in that sense I feel ok with the current size. Having said that, I'll re-assess once all dependency PRs are merged, before asking for a final round of review.

tyxla · 2024-08-28T17:55:02Z

@tyxla , Even if the size of the PR is medium-large, I believe 99% of the changes left in this PR are simple renames — and in that sense I feel ok with the current size. Having said that, I'll re-assess once all dependency PRs are merged, before asking for a final round of review.

That makes sense, @ciampo, will help with the review once all the dependencies are merged 👍

See WordPress/gutenberg#64613 (comment)

@example

* Remove experimental status from Storybook * NavigatorProvider => Navigator (internally) * Move legacy exports to separate file * Export overloaded notation * Use overloaded notation in Storybook * Use overloaded notation in unit tests (skipping deprecated component for now) * Update docs manifest.json * Navigator: update docs * Navigator.BackButton: update docs * NavigatorToParentButton: delete README * Navigator.Button: update docs * NavigatorScreen: update docs * Restore `NavigatorToParentButton` test * Use dot notation in context namespaces too * Use named export for `NavigatorToParentButton` too * Fixup docs manifest * Export stable version from components package * CHANGELOG * Change index.ts extension to tsx to allow Storybook to extract JSDocs better, remove duplicate JSDocs * Remove unnecessary and mispelled display name for top-level `Navigator` * Remove @example tag from top-level export * Clean up unused imports * Fix storybook styles * Update new section of the docs * Update more docs * Update deprecation warning * Update and align docs * Fix tests warning checks * Typo * Fix useContextSystem names * Remove mentions of the `useNavigator` hook * useNavigator JSDocs * Move all READMEs under the main README * Move README to component's root folder * Update types JSDocs to match README * Update docs manifest * Fix JSDocs typos, grammar, and broken links. * Update storybook selector --- Co-authored-by: ciampo <[email protected]> Co-authored-by: mirka <[email protected]> Co-authored-by: tyxla <[email protected]>

This reverts commit cedb4d4.

ciampo commented Aug 19, 2024

View reviewed changes

This was referenced Aug 19, 2024

Components: Assess stabilization of Navigator #60927

Closed

Components: Remove "Experimental" designation #59418

Open

ciampo self-assigned this Aug 19, 2024

ciampo added [Package] Components /packages/components [Type] New API New API to be used by plugin developers or package users. labels Aug 19, 2024

ciampo marked this pull request as ready for review August 19, 2024 14:51

ciampo requested review from ajitbohra, ryanwelcher, juanmaguitar, fabiankaegy and ndiego as code owners August 19, 2024 14:51

ciampo requested review from youknowriad and a team August 19, 2024 14:51

ciampo added the Needs Dev Note Requires a developer note for a major WordPress release cycle label Aug 19, 2024

ciampo force-pushed the feat/stabilize-navigator/introduce-stable-version branch from 965220a to 85471a9 Compare August 21, 2024 15:37

mirka reviewed Aug 22, 2024

View reviewed changes

ciampo force-pushed the feat/stabilize-navigator/introduce-stable-version branch from 85471a9 to 0f2d077 Compare August 26, 2024 09:03

This was referenced Aug 26, 2024

Components: move displayName assignment to top-level files #64793

Merged

Navigator: polish Storybook examples #64798

Merged

ciampo added 17 commits September 27, 2024 16:19

Remove @example tag from top-level export

aa9b28a

Clean up unused imports

212e29c

Fix storybook styles

0cdc3f4

Update new section of the docs

a2699e9

Update more docs

eb0276d

Update deprecation warning

7228e33

Update and align docs

585faac

Fix tests warning checks

c0a754f

Typo

521ca86

Fix useContextSystem names

72cd0bc

Remove mentions of the useNavigator hook

0987fac

useNavigator JSDocs

ca7ac76

Move all READMEs under the main README

1d29ff1

Move README to component's root folder

616015a

Update types JSDocs to match README

4639c0b

Update docs manifest

4ea2a09

Fix JSDocs typos, grammar, and broken links.

999795a

ciampo force-pushed the feat/stabilize-navigator/introduce-stable-version branch from cea2b8e to 999795a Compare September 27, 2024 14:25

Update storybook selector

578c98a

ciampo enabled auto-merge (squash) September 27, 2024 14:31

ciampo merged commit 6f0fd8e into trunk Sep 27, 2024
64 checks passed

ciampo deleted the feat/stabilize-navigator/introduce-stable-version branch September 27, 2024 15:07

github-actions bot added this to the Gutenberg 19.4 milestone Sep 27, 2024

adamwoodnz added a commit to WordPress/wporg-developer that referenced this pull request Sep 30, 2024

Add redirects for Block Editor Navigator doc restructuring

034722c

See WordPress/gutenberg#64613 (comment)

ciampo mentioned this pull request Sep 30, 2024

Navigator: fix README heading hierarchy #65763

Merged

fabiankaegy mentioned this pull request Oct 1, 2024

6.7 Dev Note Tracking Issue #65784

Closed

97 tasks

huubl added a commit to huubl/gutenberg that referenced this pull request Oct 2, 2024

Revert "Navigator: stabilize and export APIs (WordPress#64613)"

4a95e8c

This reverts commit cedb4d4.

ciampo added has dev note when dev note is done (for upcoming WordPress release) and removed Needs Dev Note Requires a developer note for a major WordPress release cycle labels Oct 9, 2024

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Navigator: stabilize and export APIs #64613

Navigator: stabilize and export APIs #64613

ciampo commented Aug 19, 2024 •

edited

Loading

ciampo Aug 19, 2024 •

edited

Loading

ciampo Aug 19, 2024

ciampo Aug 19, 2024

ciampo Aug 19, 2024 •

edited

Loading

ciampo Aug 19, 2024

ciampo Aug 21, 2024

ciampo Aug 19, 2024

github-actions bot commented Aug 19, 2024 •

edited

Loading

mirka Aug 22, 2024

ciampo Aug 22, 2024

tyxla Sep 26, 2024

ciampo Sep 30, 2024

adamwoodnz Sep 30, 2024

ciampo Sep 30, 2024

ciampo commented Aug 22, 2024

tyxla commented Aug 23, 2024

ciampo commented Aug 26, 2024 •

edited

Loading

tyxla commented Aug 28, 2024

Navigator: stabilize and export APIs #64613

Navigator: stabilize and export APIs #64613

Conversation

ciampo commented Aug 19, 2024 • edited Loading

What?

Why?

How?

Next steps?

Testing Instructions

✍️ Dev note

ciampo Aug 19, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ciampo Aug 19, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

github-actions bot commented Aug 19, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ciampo commented Aug 22, 2024

tyxla commented Aug 23, 2024

ciampo commented Aug 26, 2024 • edited Loading

tyxla commented Aug 28, 2024

ciampo commented Aug 19, 2024 •

edited

Loading

ciampo Aug 19, 2024 •

edited

Loading

ciampo Aug 19, 2024 •

edited

Loading

github-actions bot commented Aug 19, 2024 •

edited

Loading

ciampo commented Aug 26, 2024 •

edited

Loading