From ccff0e882fe8c9e4f7550e550698841aa094f5e2 Mon Sep 17 00:00:00 2001
From: Nate Gay <nate.gay@wpengine.com>
Date: Thu, 16 May 2024 12:11:59 -0500
Subject: [PATCH 1/5] Add documentation for the EditorProvider and
ExperimentalEditorProvider components
---
packages/editor/README.md | 32 ++++++++-
.../editor/src/components/provider/README.md | 37 -----------
.../editor/src/components/provider/index.js | 66 +++++++++++++++++++
3 files changed, 97 insertions(+), 38 deletions(-)
delete mode 100644 packages/editor/src/components/provider/README.md
diff --git a/packages/editor/README.md b/packages/editor/README.md
index 64e28992ee2c3a..a9c0694565ac8f 100644
--- a/packages/editor/README.md
+++ b/packages/editor/README.md
@@ -350,7 +350,37 @@ _Returns_
### EditorProvider
-Undocumented declaration.
+EditorProvider component.
+
+This component establishes a new post editing context, and serves as the entry point for a new post editor (or post with template editor).
+
+It supports a large number of post types, including post, page, templates, custom post types, patterns, template parts.
+
+All modification and changes are performed to the `@wordpress/core-data` store.
+
+_Usage_
+
+```jsx
+<EditorProvider
+ post={ post }
+ settings={ settings }
+ __unstableTemplate={ template }
+>
+ { children }
+</EditorProvider>
+```
+
+_Parameters_
+
+- _props_ `Object`: - The component props.
+- _props.post_ `[Object]`: - The post object to edit. This is required.
+- _props.\_\_unstableTemplate_ `[Object]`: - The template object wrapper the edited post. This is optional and can only be used when the post type supports templates (like posts and pages).
+- _props.settings_ `[Object]`: - The settings object to use for the editor. This is optional and can be used to override the default settings.
+- _props.children_ `[Element]`: - Children elements for which the BlockEditorProvider context should apply. This is optional.
+
+_Returns_
+
+- `JSX.Element`: The rendered component.
### EditorSnackbars
diff --git a/packages/editor/src/components/provider/README.md b/packages/editor/src/components/provider/README.md
deleted file mode 100644
index deaa9375bba746..00000000000000
--- a/packages/editor/src/components/provider/README.md
+++ /dev/null
@@ -1,37 +0,0 @@
-# EditorProvider
-
-EditorProvider is a component which establishes a new post editing context, and serves as the entry point for a new post editor (or post with template editor).
-
-It supports a big number of post types, including post, page, templates, custom post types, patterns, template parts.
-
-All modification and changes are performed to the `@wordpress/core-data` store.
-
-## Props
-
-### `post`
-
-- **Type:** `Object`
-- **Required** `yes`
-
-The post object to edit
-
-### `__unstableTemplate`
-
-- **Type:** `Object`
-- **Required** `no`
-
-The template object wrapper the edited post. This is optional and can only be used when the post type supports templates (like posts and pages).
-
-### `settings`
-
-- **Type:** `Object`
-- **Required** `no`
-
-The settings object to use for the editor. This is optional and can be used to override the default settings.
-
-### `children`
-
-- **Type:** `Element`
-- **Required** `no`
-
-Children elements for which the BlockEditorProvider context should apply.
diff --git a/packages/editor/src/components/provider/index.js b/packages/editor/src/components/provider/index.js
index 56c86968f0274f..6b44e1701f33da 100644
--- a/packages/editor/src/components/provider/index.js
+++ b/packages/editor/src/components/provider/index.js
@@ -59,6 +59,12 @@ const NON_CONTEXTUAL_POST_TYPES = [
* @param {Array} post Block list.
* @param {boolean} template Whether the page content has focus (and the surrounding template is inert). If `true` return page content blocks. Default `false`.
* @param {string} mode Rendering mode.
+ *
+ * @example
+ * ```jsx
+ * const [ blocks, onInput, onChange ] = useBlockEditorProps( post, template, mode );
+ * ```
+ *
* @return {Array} Block editor props.
*/
function useBlockEditorProps( post, template, mode ) {
@@ -118,6 +124,34 @@ function useBlockEditorProps( post, template, mode ) {
];
}
+/**
+ * ExperimentalEditorProvider component.
+ *
+ * This component provides the editor context and manages the state of the block editor.
+ *
+ * @param {Object} props The component props.
+ * @param {Object} props.post The post object.
+ * @param {Object} props.settings The editor settings.
+ * @param {boolean} props.recovery Indicates if the editor is in recovery mode.
+ * @param {Array} props.initialEdits The initial edits for the editor.
+ * @param {Object} props.children The child components.
+ * @param {Object} [props.BlockEditorProviderComponent] The block editor provider component to use. Defaults to ExperimentalBlockEditorProvider.
+ * @param {Object} [props.__unstableTemplate] The template object.
+ *
+ * @example
+ * ```jsx
+ * <ExperimentalEditorProvider
+ * post={ post }
+ * settings={ settings }
+ * recovery={ recovery }
+ * initialEdits={ initialEdits }
+ * __unstableTemplate={ template }
+ * >
+ * { children }
+ * </ExperimentalEditorProvider>
+ *
+ * @return {Object} The rendered component.
+ */
export const ExperimentalEditorProvider = withRegistryProvider(
( {
post,
@@ -293,6 +327,38 @@ export const ExperimentalEditorProvider = withRegistryProvider(
}
);
+/**
+ * EditorProvider component.
+ *
+ * This component establishes a new post editing context, and serves as the entry point for a new post editor (or post with template editor).
+ *
+ * It supports a large number of post types, including post, page, templates,
+ * custom post types, patterns, template parts.
+ *
+ * All modification and changes are performed to the `@wordpress/core-data` store.
+ *
+ * @param {Object} props - The component props.
+ * @param {Object} [props.post] - The post object to edit. This is required.
+ * @param {Object} [props.__unstableTemplate] - The template object wrapper the edited post.
+ * This is optional and can only be used when the post type supports templates (like posts and pages).
+ * @param {Object} [props.settings] - The settings object to use for the editor.
+ * This is optional and can be used to override the default settings.
+ * @param {Element} [props.children] - Children elements for which the BlockEditorProvider context should apply.
+ * This is optional.
+ *
+ * @example
+ * ```jsx
+ * <EditorProvider
+ * post={ post }
+ * settings={ settings }
+ * __unstableTemplate={ template }
+ * >
+ * { children }
+ * </EditorProvider>
+ * ```
+ *
+ * @return {JSX.Element} The rendered component.
+ */
export function EditorProvider( props ) {
return (
<ExperimentalEditorProvider
From 43e45a9e665e349137bd93c5efcead0fa756c569 Mon Sep 17 00:00:00 2001
From: Damon Cook <damonacook@gmail.com>
Date: Fri, 17 May 2024 18:44:47 -0400
Subject: [PATCH 2/5] Address ESLint warning react-hooks/exhaustive-deps
---
packages/editor/src/components/provider/index.js | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/packages/editor/src/components/provider/index.js b/packages/editor/src/components/provider/index.js
index 6b44e1701f33da..2b74cb356471c2 100644
--- a/packages/editor/src/components/provider/index.js
+++ b/packages/editor/src/components/provider/index.js
@@ -252,7 +252,7 @@ export const ExperimentalEditorProvider = withRegistryProvider(
}
);
}
- }, [] );
+ } );
// Synchronizes the active post with the state
useEffect( () => {
From 16844c2ae637a3c9301ef3908217cdcc92ba4393 Mon Sep 17 00:00:00 2001
From: Damon Cook <damonacook@gmail.com>
Date: Fri, 17 May 2024 18:45:21 -0400
Subject: [PATCH 3/5] Refine EditorProvider editor component JSDocs
---
.../editor/src/components/provider/index.js | 18 +++++++-----------
1 file changed, 7 insertions(+), 11 deletions(-)
diff --git a/packages/editor/src/components/provider/index.js b/packages/editor/src/components/provider/index.js
index 2b74cb356471c2..eebef31386a0ed 100644
--- a/packages/editor/src/components/provider/index.js
+++ b/packages/editor/src/components/provider/index.js
@@ -125,8 +125,6 @@ function useBlockEditorProps( post, template, mode ) {
}
/**
- * ExperimentalEditorProvider component.
- *
* This component provides the editor context and manages the state of the block editor.
*
* @param {Object} props The component props.
@@ -150,7 +148,7 @@ function useBlockEditorProps( post, template, mode ) {
* { children }
* </ExperimentalEditorProvider>
*
- * @return {Object} The rendered component.
+ * @return {Object} The rendered ExperimentalEditorProvider component.
*/
export const ExperimentalEditorProvider = withRegistryProvider(
( {
@@ -328,8 +326,6 @@ export const ExperimentalEditorProvider = withRegistryProvider(
);
/**
- * EditorProvider component.
- *
* This component establishes a new post editing context, and serves as the entry point for a new post editor (or post with template editor).
*
* It supports a large number of post types, including post, page, templates,
@@ -337,13 +333,13 @@ export const ExperimentalEditorProvider = withRegistryProvider(
*
* All modification and changes are performed to the `@wordpress/core-data` store.
*
- * @param {Object} props - The component props.
- * @param {Object} [props.post] - The post object to edit. This is required.
- * @param {Object} [props.__unstableTemplate] - The template object wrapper the edited post.
+ * @param {Object} props The component props.
+ * @param {Object} [props.post] The post object to edit. This is required.
+ * @param {Object} [props.__unstableTemplate] The template object wrapper the edited post.
* This is optional and can only be used when the post type supports templates (like posts and pages).
- * @param {Object} [props.settings] - The settings object to use for the editor.
+ * @param {Object} [props.settings] The settings object to use for the editor.
* This is optional and can be used to override the default settings.
- * @param {Element} [props.children] - Children elements for which the BlockEditorProvider context should apply.
+ * @param {Element} [props.children] Children elements for which the BlockEditorProvider context should apply.
* This is optional.
*
* @example
@@ -357,7 +353,7 @@ export const ExperimentalEditorProvider = withRegistryProvider(
* </EditorProvider>
* ```
*
- * @return {JSX.Element} The rendered component.
+ * @return {JSX.Element} The rendered EditorProvider component.
*/
export function EditorProvider( props ) {
return (
From 1ea02edc9bfb951af04b25ea2ec74737c5849c48 Mon Sep 17 00:00:00 2001
From: Damon Cook <damonacook@gmail.com>
Date: Fri, 17 May 2024 18:45:49 -0400
Subject: [PATCH 4/5] Auto-generate EditorProvider editor docs
---
packages/editor/README.md | 14 ++++++--------
1 file changed, 6 insertions(+), 8 deletions(-)
diff --git a/packages/editor/README.md b/packages/editor/README.md
index a9c0694565ac8f..16cb5bb0a7210d 100644
--- a/packages/editor/README.md
+++ b/packages/editor/README.md
@@ -350,8 +350,6 @@ _Returns_
### EditorProvider
-EditorProvider component.
-
This component establishes a new post editing context, and serves as the entry point for a new post editor (or post with template editor).
It supports a large number of post types, including post, page, templates, custom post types, patterns, template parts.
@@ -372,15 +370,15 @@ _Usage_
_Parameters_
-- _props_ `Object`: - The component props.
-- _props.post_ `[Object]`: - The post object to edit. This is required.
-- _props.\_\_unstableTemplate_ `[Object]`: - The template object wrapper the edited post. This is optional and can only be used when the post type supports templates (like posts and pages).
-- _props.settings_ `[Object]`: - The settings object to use for the editor. This is optional and can be used to override the default settings.
-- _props.children_ `[Element]`: - Children elements for which the BlockEditorProvider context should apply. This is optional.
+- _props_ `Object`: The component props.
+- _props.post_ `[Object]`: The post object to edit. This is required.
+- _props.\_\_unstableTemplate_ `[Object]`: The template object wrapper the edited post. This is optional and can only be used when the post type supports templates (like posts and pages).
+- _props.settings_ `[Object]`: The settings object to use for the editor. This is optional and can be used to override the default settings.
+- _props.children_ `[Element]`: Children elements for which the BlockEditorProvider context should apply. This is optional.
_Returns_
-- `JSX.Element`: The rendered component.
+- `JSX.Element`: The rendered EditorProvider component.
### EditorSnackbars
From b4a137db9b88226710f09e84600dc61261ee4977 Mon Sep 17 00:00:00 2001
From: Damon Cook <damonacook@gmail.com>
Date: Fri, 24 May 2024 10:17:08 -0400
Subject: [PATCH 5/5] Revert "Address ESLint warning
react-hooks/exhaustive-deps"
This reverts commit 3f15d73f57e88680abdb2aeb4bf41976ebbca14b.
---
packages/editor/src/components/provider/index.js | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/packages/editor/src/components/provider/index.js b/packages/editor/src/components/provider/index.js
index eebef31386a0ed..081b1cdfa0f1b2 100644
--- a/packages/editor/src/components/provider/index.js
+++ b/packages/editor/src/components/provider/index.js
@@ -250,7 +250,7 @@ export const ExperimentalEditorProvider = withRegistryProvider(
}
);
}
- } );
+ }, [] );
// Synchronizes the active post with the state
useEffect( () => {