RFC: allow routes to declare a React context

[slorber]

Have you read the Contributing Guidelines on issues?

• [X] I have read the Contributing Guidelines on issues.

Motivation

It is convenient to be able to access page metadata as a hook, from anywhere in the tree, without any props drilling.

Some use-cases:

• @roydukkey implemented a useFrontMatter() hook in https://github.com/roydukkey/docusaurus-theme-frontmatter
• @Josh-Cena add a doc metadata banner to some docs, but it's a bit boilerplate: https://github.com/Josh-Cena/Josh-Cena.github.io/blob/04ba69169f6181bd623185bb8f9be1070a6fdb4c/src/components/DocMetadataBanner.tsx
• See also discussion: https://github.com/facebook/docusaurus/discussions/5468#discussioncomment-2238465

I think it could make sense to have a more generic Docusaurus core API to provide an official route context feature?

addRoute({
  path: "/docs/",
  component: "DocVersion",
  context: {sidebars}, // Something here
  routes: [
    addRoute({
	    path: "/docs/",
	    component: "DocItem",
	    context: {docMetadata}, // Something here
	}}
  ],
}}

We could expose a generic useRouteContext(): unknown, and content plugins could expose consuming hooks to read it in a typesafe way.

If the route has multiple layers like above, we could merge the context (similar to MDXProvider components), eventually throw an error if some key is overridden.

This also means that we could remove the regular props from the existing layout components: now all the static data can always be read from the context hooks (apart from the dynamic props related to the UI state)

IMHO having "props-less" theme components also present some advantages. It would notably allow more flexibility to refactor theme components without any props breaking change.

Using context hooks also helps clarify the API surface to the context, and provides an additional layer for us to try to provide retro compatible changes in case the underlying data structures need to be updated.

---

I wonder what you think of this idea?

Of course, it would be a quite significant breaking change for users that have a lot of swizzled components, as props would have to be replaced by hooks calls in many places.

Self-service

• [X] I'd be willing to do some initial work on this proposal myself.

[Josh-Cena]

Yes 👍 I'm also thinking about refactoring props to context.

However, there are certain places where props make more sense. For example, the paginators should probably receive next and prev to remain general-purpose and not tied to a specific plugin.

[slorber]

Yes I definitively don't mean that we should use context/hooks everywhere and remove all props, just that to access page data it might be more convenient to use hooks rather than props.