diff --git a/bin/api-docs/update-api-docs.js b/bin/api-docs/update-api-docs.js index 3ee55ff0c3d814..ff4b6c21fef371 100755 --- a/bin/api-docs/update-api-docs.js +++ b/bin/api-docs/update-api-docs.js @@ -38,10 +38,7 @@ const PACKAGES_DIR = resolve( ROOT_DIR, 'packages' ); * * @type {string} */ -const DATA_DOCS_DIR = resolve( - ROOT_DIR, - 'docs/designers-developers/developers/data' -); +const DATA_DOCS_DIR = resolve( ROOT_DIR, 'docs/reference-guides/data' ); /** * Pattern matching start token of a README file. diff --git a/docs/reference-guides/data/data-core-annotations.md b/docs/reference-guides/data/data-core-annotations.md index 7b347df85a7f51..99c86d36cf7d4d 100644 --- a/docs/reference-guides/data/data-core-annotations.md +++ b/docs/reference-guides/data/data-core-annotations.md @@ -4,16 +4,17 @@ Namespace: `core/annotations`. ## Selectors - + Nothing to document. - + ## Actions - + Nothing to document. - + + diff --git a/docs/reference-guides/data/data-core-block-editor.md b/docs/reference-guides/data/data-core-block-editor.md index 97011bcce91059..fc01e5cd49f65f 100644 --- a/docs/reference-guides/data/data-core-block-editor.md +++ b/docs/reference-guides/data/data-core-block-editor.md @@ -4,7 +4,7 @@ Namespace: `core/block-editor`. ## Selectors - + # **areInnerBlocksControlled** @@ -705,11 +705,11 @@ Returns the defined block template _Parameters_ -- _state_ `boolean`: +- _state_ `boolean`: _Returns_ -- `?Array`: Block Template +- `?Array`: Block Template. # **getTemplateLock** @@ -1027,17 +1027,31 @@ Returns whether the blocks matches the template or not. _Parameters_ -- _state_ `boolean`: +- _state_ `boolean`: _Returns_ - `?boolean`: Whether the template is valid or not. - +# **wasBlockJustInserted** + +Tells if the block with the passed clientId was just inserted. + +_Parameters_ + +- _state_ `Object`: Global application state. +- _clientId_ `Object`: Client Id of the block. +- _source_ `?string`: Optional insertion source of the block. + +_Returns_ + +- `boolean`: True if the block matches the last block inserted from the specified source. + + ## Actions - + # **clearSelectedBlock** @@ -1053,8 +1067,8 @@ Generator that triggers an action used to duplicate a list of blocks. _Parameters_ -- _clientIds_ `string[]`: -- _updateSelection_ `boolean`: +- _clientIds_ `string[]`: +- _updateSelection_ `boolean`: # **enterFormattedText** @@ -1095,7 +1109,7 @@ Generator used to insert an empty block before a given block. _Parameters_ -- _clientId_ `string`: +- _clientId_ `string`: # **insertBeforeBlock** @@ -1103,7 +1117,7 @@ Generator used to insert an empty block after a given block. _Parameters_ -- _clientId_ `string`: +- _clientId_ `string`: # **insertBlock** @@ -1116,6 +1130,7 @@ _Parameters_ - _index_ `?number`: Index at which block should be inserted. - _rootClientId_ `?string`: Optional root client ID of block list on which to insert. - _updateSelection_ `?boolean`: If true block selection will be updated. If false, block selection will not change. Defaults to true. +- _meta_ `?Object`: Optional Meta values to be passed to the action object. _Returns_ @@ -1131,7 +1146,7 @@ _Parameters_ - _blocks_ `Object[]`: Block objects to insert. - _index_ `?number`: Index at which block should be inserted. - _rootClientId_ `?string`: Optional root client ID of block list on which to insert. -- _updateSelection_ `?boolean`: If true block selection will be updated. If false, block selection will not change. Defaults to true. +- _updateSelection_ `?boolean`: If true block selection will be updated. If false, block selection will not change. Defaults to true. - _initialPosition_ `0|-1|null`: Initial focus position. Setting it to null prevent focusing the inserted block. - _meta_ `?Object`: Optional Meta values to be passed to the action object. @@ -1406,6 +1421,7 @@ _Parameters_ - _rootClientId_ `?string`: Optional root client ID of block list on which to insert. - _index_ `?number`: Index at which block should be inserted. +- _\_\_unstableOptions_ `Object`: Wether or not to show an inserter button. _Returns_ @@ -1570,4 +1586,5 @@ _Parameters_ - _blocks_ `Array`: Array of blocks. - + + diff --git a/docs/reference-guides/data/data-core-blocks.md b/docs/reference-guides/data/data-core-blocks.md index 64949ca0f7b9e4..4aa8f73009e90f 100644 --- a/docs/reference-guides/data/data-core-blocks.md +++ b/docs/reference-guides/data/data-core-blocks.md @@ -4,7 +4,31 @@ Namespace: `core/blocks`. ## Selectors - + + +# **getActiveBlockVariation** + +Returns the active block variation for a given block based on its attributes. +Variations are determined by their `isActive` property. +Which is either an array of block attribute keys or a function. + +In case of an array of block attribute keys, the `attributes` are compared +to the variation's attributes using strict equality check. + +In case of function type, the function should accept a block's attributes +and the variation's attributes and determines if a variation is active. +A function that accepts a block's attributes and the variation's attributes and determines if a variation is active. + +_Parameters_ + +- _state_ `Object`: Data state. +- _blockName_ `string`: Name of block (example: “core/columns”). +- _attributes_ `Object`: Block attributes used to determine active variation. +- _scope_ `[WPBlockVariationScope]`: Block variation scope name. + +_Returns_ + +- `(WPBlockVariation|undefined)`: Active block variation. # **getBlockStyles** @@ -27,7 +51,7 @@ _Parameters_ - _state_ `Object`: Data state. - _nameOrType_ `(string|Object)`: Block name or type object -- _feature_ `string`: Feature to retrieve +- _feature_ `Array|string`: Feature to retrieve - _defaultSupports_ `*`: Default value to return if not explicitly defined _Returns_ @@ -231,11 +255,11 @@ _Returns_ - `Object[]`: Whether block type matches search term. - + ## Actions - + # **addBlockCollection** @@ -416,4 +440,5 @@ _Returns_ - `Object`: Action object. - + + diff --git a/docs/reference-guides/data/data-core-edit-post.md b/docs/reference-guides/data/data-core-edit-post.md index b238dbe264fc40..7ef45b337962b6 100644 --- a/docs/reference-guides/data/data-core-edit-post.md +++ b/docs/reference-guides/data/data-core-edit-post.md @@ -4,7 +4,7 @@ Namespace: `core/edit-post`. ## Selectors - + # **getActiveGeneralSidebarName** @@ -49,6 +49,14 @@ _Returns_ - `Array`: List of meta boxes. +# **getEditedPostTemplate** + +Retrieves the template of the currently edited post. + +_Returns_ + +- `Object?`: Post Template. + # **getEditorMode** Returns the current editing mode. @@ -201,6 +209,18 @@ _Returns_ - `boolean`: Whether the inserter is opened. +# **isListViewOpened** + +Returns true if the list view is opened. + +_Parameters_ + +- _state_ `Object`: Global application state. + +_Returns_ + +- `boolean`: Whether the list view is opened. + # **isMetaBoxLocationActive** Returns true if there is an active meta box in the given location, or false @@ -261,7 +281,7 @@ Returns true if the plugin sidebar is opened. _Parameters_ -- _state_ `Object`: Global application state +- _state_ `Object`: Global application state. _Returns_ @@ -291,11 +311,11 @@ _Returns_ - `boolean`: Whether the metaboxes are being saved. - + ## Actions - + # **closeGeneralSidebar** @@ -331,9 +351,17 @@ _Returns_ - `Object`: Action object. +# **metaBoxUpdatesFailure** + +Returns an action object used to signal a failed meta box update. + +_Returns_ + +- `Object`: Action object. + # **metaBoxUpdatesSuccess** -Returns an action object used signal a successful meta box update. +Returns an action object used to signal a successful meta box update. _Returns_ @@ -411,7 +439,21 @@ Returns an action object used to open/close the inserter. _Parameters_ -- _value_ `boolean`: A boolean representing whether the inserter should be opened or closed. +- _value_ `boolean|Object`: Whether the inserter should be opened (true) or closed (false). To specify an insertion point, use an object. +- _value.rootClientId_ `string`: The root client ID to insert at. +- _value.insertionIndex_ `number`: The index to insert at. + +_Returns_ + +- `Object`: Action object. + +# **setIsListViewOpened** + +Returns an action object used to open/close the list view. + +_Parameters_ + +- _isOpen_ `boolean`: A boolean representing whether the list view should be opened or closed. _Returns_ @@ -503,4 +545,5 @@ _Returns_ - `Object`: Action object. - + + diff --git a/docs/reference-guides/data/data-core-editor.md b/docs/reference-guides/data/data-core-editor.md index 87a14b0b1482f8..a3decea1e286cb 100644 --- a/docs/reference-guides/data/data-core-editor.md +++ b/docs/reference-guides/data/data-core-editor.md @@ -4,7 +4,7 @@ Namespace: `core/editor`. ## Selectors - + # **canInsertBlockType** @@ -367,7 +367,7 @@ Return the current block list. _Parameters_ -- _state_ `Object`: +- _state_ `Object`: _Returns_ @@ -379,7 +379,7 @@ Returns the current selection. _Parameters_ -- _state_ `Object`: +- _state_ `Object`: _Returns_ @@ -393,7 +393,7 @@ Returns the current selection end. _Parameters_ -- _state_ `Object`: +- _state_ `Object`: _Returns_ @@ -407,7 +407,7 @@ Returns the current selection start. _Parameters_ -- _state_ `Object`: +- _state_ `Object`: _Returns_ @@ -529,6 +529,18 @@ _Returns_ - `Object`: A user object. +# **getPostTypeLabel** + +Returns a post type label depending on the current post. + +_Parameters_ + +- _state_ `Object`: Global application state. + +_Returns_ + +- `string|undefined`: The post type label if available, otherwise undefined. + # **getPreviousBlockClientId** _Related_ @@ -1032,6 +1044,18 @@ _Returns_ - `boolean`: Whether the pre-publish panel should be shown or not. +# **isSavingNonPostEntityChanges** + +Returns true if non-post entities are currently being saved, or false otherwise. + +_Parameters_ + +- _state_ `Object`: Global application state. + +_Returns_ + +- `boolean`: Whether non-post entities are being saved. + # **isSavingPost** Returns true if the post is currently being saved, or false otherwise. @@ -1062,15 +1086,15 @@ _Related_ - isValidTemplate in core/block-editor store. - + ## Actions - + # **autosave** -Action generator used in signalling that the post should autosave. This +Action generator used in signalling that the post should autosave. This includes server-side autosaving (default) and client-side (a.k.a. local) autosaving (e.g. on the Web, the post might be committed to Session Storage). @@ -1340,7 +1364,7 @@ Action generator for saving the current post in the editor. _Parameters_ -- _options_ `Object`: +- _options_ `Object`: # **selectBlock** @@ -1513,4 +1537,5 @@ _Returns_ - `Object`: Action object. - + + diff --git a/docs/reference-guides/data/data-core-keyboard-shortcuts.md b/docs/reference-guides/data/data-core-keyboard-shortcuts.md index 044bd248ecb12a..d19af87e9f71b9 100644 --- a/docs/reference-guides/data/data-core-keyboard-shortcuts.md +++ b/docs/reference-guides/data/data-core-keyboard-shortcuts.md @@ -4,7 +4,11 @@ Namespace: `core/keyboard-shortcuts`. ## Selectors - + + +# **getAllShortcutKeyCombinations** + +Undocumented declaration. # **getAllShortcutRawKeyCombinations** @@ -85,11 +89,11 @@ _Returns_ - `string?`: Shortcut representation. - + ## Actions - + # **registerShortcut** @@ -115,4 +119,5 @@ _Returns_ - `Object`: action. - + + diff --git a/docs/reference-guides/data/data-core-notices.md b/docs/reference-guides/data/data-core-notices.md index 5e2675afeb447a..9f45e4d4c61530 100644 --- a/docs/reference-guides/data/data-core-notices.md +++ b/docs/reference-guides/data/data-core-notices.md @@ -4,7 +4,7 @@ Namespace: `core/notices`. ## Selectors - + # **getNotices** @@ -20,11 +20,11 @@ _Returns_ - `WPNotice[]`: Array of notices. - + ## Actions - + # **createErrorNotice** @@ -134,4 +134,5 @@ _Returns_ - `Object`: Action object. - + + diff --git a/docs/reference-guides/data/data-core-nux.md b/docs/reference-guides/data/data-core-nux.md index 3f65bbc359c8a2..79a5bba662b4fe 100644 --- a/docs/reference-guides/data/data-core-nux.md +++ b/docs/reference-guides/data/data-core-nux.md @@ -4,7 +4,7 @@ Namespace: `core/nux`. ## Selectors - + # **areTipsEnabled** @@ -47,11 +47,11 @@ _Returns_ - `boolean`: Whether or not the given tip is showing. - + ## Actions - + # **disableTips** @@ -96,4 +96,5 @@ _Returns_ - `Object`: Action object. - + + diff --git a/docs/reference-guides/data/data-core-viewport.md b/docs/reference-guides/data/data-core-viewport.md index c84524dc9b2f48..c2d77bae1ad050 100644 --- a/docs/reference-guides/data/data-core-viewport.md +++ b/docs/reference-guides/data/data-core-viewport.md @@ -4,7 +4,7 @@ Namespace: `core/viewport`. ## Selectors - + # **isViewportMatch** @@ -26,11 +26,11 @@ _Returns_ - `boolean`: Whether viewport matches query. - + ## Actions - + # **setIsMatching** @@ -46,4 +46,5 @@ _Returns_ - `Object`: Action object. - + + diff --git a/docs/reference-guides/data/data-core.md b/docs/reference-guides/data/data-core.md index c2545d9645e242..acccf7e3ce9541 100644 --- a/docs/reference-guides/data/data-core.md +++ b/docs/reference-guides/data/data-core.md @@ -4,7 +4,7 @@ Namespace: `core`. ## Selectors - + # **canUser** @@ -27,6 +27,26 @@ _Returns_ - `boolean|undefined`: Whether or not the user can perform the action, or `undefined` if the OPTIONS request is still being made. +# **canUserEditEntityRecord** + +Returns whether the current user can edit the given entity. + +Calling this may trigger an OPTIONS request to the REST API via the +`canUser()` resolver. + + + +_Parameters_ + +- _state_ `Object`: Data state. +- _kind_ `string`: Entity kind. +- _name_ `string`: Entity name. +- _recordId_ `string`: Record's id. + +_Returns_ + +- `boolean|undefined`: Whether or not the user can edit, or `undefined` if the OPTIONS request is still being made. + # **getAuthors** Returns all available authors. @@ -135,7 +155,7 @@ _Parameters_ _Returns_ -- `boolean`: Whether the entities are loaded +- `Array`: Array of entities with config matching kind. # **getEntity** @@ -408,25 +428,6 @@ _Returns_ - `boolean`: Whether there is a previous edit or not. -# **hasUploadPermissions** - -> **Deprecated** since 5.0. Callers should use the more generic `canUser()` selector instead of `hasUploadPermissions()`, e.g. `canUser( 'create', 'media' )`. - -Returns whether the current user can upload media. - -Calling this may trigger an OPTIONS request to the REST API via the -`canUser()` resolver. - - - -_Parameters_ - -- _state_ `Object`: Data state. - -_Returns_ - -- `boolean`: Whether or not the user can upload media. Defaults to `true` if the OPTIONS request is being made. - # **isAutosavingEntityRecord** Returns true if the specified entity record is autosaving, and false otherwise. @@ -503,11 +504,11 @@ _Returns_ - `boolean`: Whether the entity record is saving or not. - + ## Actions - + # **addEntities** @@ -706,4 +707,5 @@ _Parameters_ Action triggered to undo the last edit to an entity record, if any. - + +