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?

Spit legacy and stable exports:
- Legacy exports will keep adopting the same naming conventions as the experimental API currently do;
- The stable exports will adopt slightly different names 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)
- Moved away from default exports to named exports-only internally to the component

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

TBD

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 <mciampini@git.wordpress.org>
Co-authored-by: mirka <0mirka00@git.wordpress.org>
Co-authored-by: tyxla <tyxla@git.wordpress.org>

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

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.

…for now)

… better, remove duplicate JSDocs

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 👍

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 added 5 commits August 26, 2024 10:55

Use named export for useNavigator

6cb6329

Remove experimental status from Storybook

57e4f60

NavigatorProvider => Navigator (internally)

5bf15f6

Move legacy exports to separate file

4a66808

Export overloaded notation

6a288c5

ciampo added 23 commits August 26, 2024 10:57

Use overloaded notation in Storybook

01a124e

Use overloaded notation in unit tests (skipping deprecated component …

4454b58

…for now)

Update docs manifest.json

f32daf1

Navigator: update docs

b321190

Remove unnecessary Storybook types

b96aa22

Navigator.BackButton: update docs

9f5fa94

NavigatorToParentButton: delete README

eebb8db

Navigator.Button: update docs

98ca581

NavigatorScreen: update docs

e5b9b64

Use named export for all subcomponents

653ec0d

Add JSDocs back to legacy exports

4e535d8

Remove JSDocs from internal implementations

e092d17

Restore NavigatorToParentButton test

8e81016

Use dot notation in context namespaces too

192e3f0

Use named export for NavigatorToParentButton too

3825aab

Fixup docs manifest

b93ff89

Export stable version from components package

d5f0c4b

CHANGELOG

f96125e

Change index.ts extension to tsx to allow Storybook to extract JSDocs…

b19ff41

… better, remove duplicate JSDocs

Move CHANGELOG entry under enhancements

af97de9

Remove unnecessary and mispelled display name for top-level Navigator

8193121

Remove @example tag from top-level export

e7d2019

Clean up unused imports

0f2d077

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

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

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

Are you sure you want to change the base?

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

ciampo Aug 19, 2024

Choose a reason for hiding this comment

ciampo Aug 19, 2024

Choose a reason for hiding this comment

ciampo Aug 19, 2024 • edited Loading

Choose a reason for hiding this comment

ciampo Aug 19, 2024

Choose a reason for hiding this comment

ciampo Aug 21, 2024

Choose a reason for hiding this comment

ciampo Aug 19, 2024

Choose a reason for hiding this comment

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

mirka Aug 22, 2024

Choose a reason for hiding this comment

ciampo Aug 22, 2024

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