diff --git a/docs/designers-developers/developers/data/data-core-annotations.md b/docs/designers-developers/developers/data/data-core-annotations.md index 0aaf9963ba48a..e71aefd27d212 100644 --- a/docs/designers-developers/developers/data/data-core-annotations.md +++ b/docs/designers-developers/developers/data/data-core-annotations.md @@ -1,8 +1,20 @@ -# **core/annotations**: Annotations +# Annotations + +Namespace: `core/annotations`. ## Selectors + + +Nothing to document. + + ## Actions + + +Nothing to document. + + diff --git a/docs/designers-developers/developers/data/data-core-block-editor.md b/docs/designers-developers/developers/data/data-core-block-editor.md index d152b4475f8b2..380b3366a64e0 100644 --- a/docs/designers-developers/developers/data/data-core-block-editor.md +++ b/docs/designers-developers/developers/data/data-core-block-editor.md @@ -1,8 +1,86 @@ -# **core/block-editor**: The Block Editor’s Data +# The Block Editor’s Data + +Namespace: `core/block-editor`. ## Selectors -### getBlockDependantsCacheBust + + +# **canInsertBlockType** + +Determines if the given block type is allowed to be inserted into the block list. + +_Parameters_ + +- _state_ `Object`: Editor state. +- _blockName_ `string`: The name of the block type, e.g.' core/paragraph'. +- _rootClientId_ `?string`: Optional root client ID of block list. + +_Returns_ + +- `boolean`: Whether the given block type is allowed to be inserted. + +# **getAdjacentBlockClientId** + +Returns the client ID of the block adjacent one at the given reference +startClientId and modifier directionality. Defaults start startClientId to +the selected block, and direction as next block. Returns null if there is no +adjacent block. + +_Parameters_ + +- _state_ `Object`: Editor state. +- _startClientId_ `?string`: Optional client ID of block from which to search. +- _modifier_ `?number`: Directionality multiplier (1 next, -1 previous). + +_Returns_ + +- `?string`: Return the client ID of the block, or null if none exists. + +# **getBlock** + +Returns a block given its client ID. This is a parsed copy of the block, +containing its `blockName`, `clientId`, and current `attributes` state. This +is not the block's registration settings, which must be retrieved from the +blocks module registration store. + +_Parameters_ + +- _state_ `Object`: Editor state. +- _clientId_ `string`: Block client ID. + +_Returns_ + +- `Object`: Parsed block object. + +# **getBlockAttributes** + +Returns a block's attributes given its client ID, or null if no block exists with +the client ID. + +_Parameters_ + +- _state_ `Object`: Editor state. +- _clientId_ `string`: Block client ID. + +_Returns_ + +- `?Object`: Block attributes. + +# **getBlockCount** + +Returns the number of blocks currently present in the post. + +_Parameters_ + +- _state_ `Object`: Editor state. +- _rootClientId_ `?string`: Optional root client ID of block list. + +_Returns_ + +- `number`: Number of blocks in the post. + +# **getBlockDependantsCacheBust** Returns a new reference when the inner blocks of a given block client ID change. This is used exclusively as a memoized selector dependant, relying @@ -11,69 +89,128 @@ blocks defined as dependencies. This abuses mechanics of the selector memoization to return from the original selector function only when dependants change. -*Parameters* +_Parameters_ - * state: Editor state. - * clientId: Block client ID. +- _state_ `Object`: Editor state. +- _clientId_ `string`: Block client ID. -### getBlockName +_Returns_ -Returns a block's name given its client ID, or null if no block exists with -the client ID. +- `*`: A value whose reference will change only when inner blocks of the given block client ID change. -*Parameters* +# **getBlockHierarchyRootClientId** - * state: Editor state. - * clientId: Block client ID. +Given a block client ID, returns the root of the hierarchy from which the block is nested, return the block itself for root level blocks. -*Returns* +_Parameters_ -Block name. +- _state_ `Object`: Editor state. +- _clientId_ `string`: Block from which to find root client ID. -### isBlockValid +_Returns_ -Returns whether a block is valid or not. +- `string`: Root client ID + +# **getBlockIndex** -*Parameters* +Returns the index at which the block corresponding to the specified client +ID occurs within the block order, or `-1` if the block does not exist. - * state: Editor state. - * clientId: Block client ID. +_Parameters_ -*Returns* +- _state_ `Object`: Editor state. +- _clientId_ `string`: Block client ID. +- _rootClientId_ `?string`: Optional root client ID of block list. -Is Valid. +_Returns_ -### getBlockAttributes +- `number`: Index at which block exists in order. -Returns a block's attributes given its client ID, or null if no block exists with +# **getBlockInsertionPoint** + +Returns the insertion point, the index at which the new inserted block would +be placed. Defaults to the last index. + +_Parameters_ + +- _state_ `Object`: Editor state. + +_Returns_ + +- `Object`: Insertion point object with `rootClientId`, `index`. + +# **getBlockListSettings** + +Returns the Block List settings of a block, if any exist. + +_Parameters_ + +- _state_ `Object`: Editor state. +- _clientId_ `?string`: Block client ID. + +_Returns_ + +- `?Object`: Block settings of the block if set. + +# **getBlockMode** + +Returns the block's editing mode, defaulting to "visual" if not explicitly +assigned. + +_Parameters_ + +- _state_ `Object`: Editor state. +- _clientId_ `string`: Block client ID. + +_Returns_ + +- `Object`: Block editing mode. + +# **getBlockName** + +Returns a block's name given its client ID, or null if no block exists with the client ID. -*Parameters* +_Parameters_ - * state: Editor state. - * clientId: Block client ID. +- _state_ `Object`: Editor state. +- _clientId_ `string`: Block client ID. -*Returns* +_Returns_ -Block attributes. +- `string`: Block name. -### getBlock +# **getBlockOrder** -Returns a block given its client ID. This is a parsed copy of the block, -containing its `blockName`, `clientId`, and current `attributes` state. This -is not the block's registration settings, which must be retrieved from the -blocks module registration store. +Returns an array containing all block client IDs in the editor in the order +they appear. Optionally accepts a root client ID of the block list for which +the order should be returned, defaulting to the top-level block order. + +_Parameters_ + +- _state_ `Object`: Editor state. +- _rootClientId_ `?string`: Optional root client ID of block list. -*Parameters* +_Returns_ - * state: Editor state. - * clientId: Block client ID. +- `Array`: Ordered client IDs of editor blocks. -*Returns* +# **getBlockRootClientId** -Parsed block object. +Given a block client ID, returns the root block from which the block is +nested, an empty string for top-level blocks, or null if the block does not +exist. + +_Parameters_ + +- _state_ `Object`: Editor state. +- _clientId_ `string`: Block from which to find root client ID. + +_Returns_ -### getBlocks +- `?string`: Root client ID, if exists + +# **getBlocks** Returns all block objects for the current post being edited as an array in the order they appear in the post. @@ -81,1017 +218,1010 @@ the order they appear in the post. Note: It's important to memoize this selector to avoid return a new instance on each call -*Parameters* +_Parameters_ - * state: Editor state. - * rootClientId: Optional root client ID of block list. +- _state_ `Object`: Editor state. +- _rootClientId_ `?String`: Optional root client ID of block list. -*Returns* +_Returns_ -Post blocks. +- `Array`: Post blocks. -### getClientIdsOfDescendants +# **getBlocksByClientId** -Returns an array containing the clientIds of all descendants -of the blocks given. +Given an array of block client IDs, returns the corresponding array of block +objects. -*Parameters* +_Parameters_ - * state: Global application state. - * clientIds: Array of blocks to inspect. +- _state_ `Object`: Editor state. +- _clientIds_ `Array`: Client IDs for which blocks are to be returned. -*Returns* +_Returns_ -ids of descendants. +- `Array`: Block objects. -### getClientIdsWithDescendants +# **getBlockSelectionEnd** -Returns an array containing the clientIds of the top-level blocks -and their descendants of any depth (for nested blocks). +Returns the current block selection end. This value may be null, and it +may represent either a singular block selection or multi-selection end. +A selection is singular if its start and end match. -*Parameters* +_Parameters_ - * state: Global application state. +- _state_ `Object`: Global application state. -*Returns* +_Returns_ -ids of top-level and descendant blocks. +- `?string`: Client ID of block selection end. -### getGlobalBlockCount +# **getBlockSelectionStart** -Returns the total number of blocks, or the total number of blocks with a specific name in a post. -The number returned includes nested blocks. +Returns the current block selection start. This value may be null, and it +may represent either a singular block selection or multi-selection start. +A selection is singular if its start and end match. -*Parameters* +_Parameters_ - * state: Global application state. - * blockName: Optional block name, if specified only blocks of that type will be counted. +- _state_ `Object`: Global application state. -*Returns* +_Returns_ -Number of blocks in the post, or number of blocks with name equal to blockName. +- `?string`: Client ID of block selection start. -### getBlocksByClientId +# **getClientIdsOfDescendants** -Given an array of block client IDs, returns the corresponding array of block -objects. +Returns an array containing the clientIds of all descendants +of the blocks given. -*Parameters* +_Parameters_ - * state: Editor state. - * clientIds: Client IDs for which blocks are to be returned. +- _state_ `Object`: Global application state. +- _clientIds_ `Array`: Array of blocks to inspect. -*Returns* +_Returns_ -Block objects. +- `Array`: ids of descendants. -### getBlockCount +# **getClientIdsWithDescendants** -Returns the number of blocks currently present in the post. +Returns an array containing the clientIds of the top-level blocks +and their descendants of any depth (for nested blocks). -*Parameters* +_Parameters_ - * state: Editor state. - * rootClientId: Optional root client ID of block list. +- _state_ `Object`: Global application state. -*Returns* +_Returns_ -Number of blocks in the post. +- `Array`: ids of top-level and descendant blocks. -### getSelectionStart +# **getFirstMultiSelectedBlockClientId** -Returns the current selection start block client ID, attribute key and text -offset. +Returns the client ID of the first block in the multi-selection set, or null +if there is no multi-selection. -*Parameters* +_Parameters_ - * state: Block editor state. +- _state_ `Object`: Editor state. -*Returns* +_Returns_ -Selection start information. +- `?string`: First block client ID in the multi-selection set. -### getSelectionEnd +# **getGlobalBlockCount** -Returns the current selection end block client ID, attribute key and text -offset. +Returns the total number of blocks, or the total number of blocks with a specific name in a post. +The number returned includes nested blocks. -*Parameters* +_Parameters_ - * state: Block editor state. +- _state_ `Object`: Global application state. +- _blockName_ `?String`: Optional block name, if specified only blocks of that type will be counted. -*Returns* +_Returns_ -Selection end information. +- `number`: Number of blocks in the post, or number of blocks with name equal to blockName. -### getBlockSelectionStart +# **getInserterItems** -Returns the current block selection start. This value may be null, and it -may represent either a singular block selection or multi-selection start. -A selection is singular if its start and end match. - -*Parameters* +Determines the items that appear in the inserter. Includes both static +items (e.g. a regular block type) and dynamic items (e.g. a reusable block). - * state: Global application state. +Each item object contains what's necessary to display a button in the +inserter and handle its selection. -*Returns* +The 'utility' property indicates how useful we think an item will be to the +user. There are 4 levels of utility: -Client ID of block selection start. +1. Blocks that are contextually useful (utility = 3) +2. Blocks that have been previously inserted (utility = 2) +3. Blocks that are in the common category (utility = 1) +4. All other blocks (utility = 0) -### getBlockSelectionEnd +The 'frecency' property is a heuristic () +that combines block usage frequenty and recency. -Returns the current block selection end. This value may be null, and it -may represent either a singular block selection or multi-selection end. -A selection is singular if its start and end match. +Items are returned ordered descendingly by their 'utility' and 'frecency'. -*Parameters* +_Parameters_ - * state: Global application state. +- _state_ `Object`: Editor state. +- _rootClientId_ `?string`: Optional root client ID of block list. -*Returns* +_Returns_ -Client ID of block selection end. +- `Array`: Items that appear in inserter. -### getSelectedBlockCount +# **getLastMultiSelectedBlockClientId** -Returns the number of blocks currently selected in the post. +Returns the client ID of the last block in the multi-selection set, or null +if there is no multi-selection. -*Parameters* +_Parameters_ - * state: Global application state. +- _state_ `Object`: Editor state. -*Returns* +_Returns_ -Number of blocks selected in the post. +- `?string`: Last block client ID in the multi-selection set. -### hasSelectedBlock +# **getMultiSelectedBlockClientIds** -Returns true if there is a single selected block, or false otherwise. +Returns the current multi-selection set of block client IDs, or an empty +array if there is no multi-selection. -*Parameters* +_Parameters_ - * state: Editor state. +- _state_ `Object`: Editor state. -*Returns* +_Returns_ -Whether a single block is selected. +- `Array`: Multi-selected block client IDs. -### getSelectedBlockClientId +# **getMultiSelectedBlocks** -Returns the currently selected block client ID, or null if there is no -selected block. +Returns the current multi-selection set of blocks, or an empty array if +there is no multi-selection. -*Parameters* +_Parameters_ - * state: Editor state. +- _state_ `Object`: Editor state. -*Returns* +_Returns_ -Selected block client ID. +- `Array`: Multi-selected block objects. -### getSelectedBlock +# **getMultiSelectedBlocksEndClientId** -Returns the currently selected block, or null if there is no selected block. +Returns the client ID of the block which ends the multi-selection set, or +null if there is no multi-selection. -*Parameters* +This is not necessarily the last client ID in the selection. - * state: Global application state. +_Related_ -*Returns* +- getLastMultiSelectedBlockClientId -Selected block. +_Parameters_ -### getBlockRootClientId +- _state_ `Object`: Editor state. -Given a block client ID, returns the root block from which the block is -nested, an empty string for top-level blocks, or null if the block does not -exist. +_Returns_ -*Parameters* +- `?string`: Client ID of block ending multi-selection. - * state: Editor state. - * clientId: Block from which to find root client ID. +# **getMultiSelectedBlocksStartClientId** -*Returns* +Returns the client ID of the block which begins the multi-selection set, or +null if there is no multi-selection. -Root client ID, if exists +This is not necessarily the first client ID in the selection. -### getBlockHierarchyRootClientId +_Related_ -Given a block client ID, returns the root of the hierarchy from which the block is nested, return the block itself for root level blocks. +- getFirstMultiSelectedBlockClientId -*Parameters* +_Parameters_ - * state: Editor state. - * clientId: Block from which to find root client ID. +- _state_ `Object`: Editor state. -*Returns* +_Returns_ -Root client ID +- `?string`: Client ID of block beginning multi-selection. -### getAdjacentBlockClientId +# **getNextBlockClientId** -Returns the client ID of the block adjacent one at the given reference -startClientId and modifier directionality. Defaults start startClientId to -the selected block, and direction as next block. Returns null if there is no -adjacent block. +Returns the next block's client ID from the given reference start ID. +Defaults start to the selected block. Returns null if there is no next +block. -*Parameters* +_Parameters_ - * state: Editor state. - * startClientId: Optional client ID of block from which to - search. - * modifier: Directionality multiplier (1 next, -1 - previous). +- _state_ `Object`: Editor state. +- _startClientId_ `?string`: Optional client ID of block from which to search. -*Returns* +_Returns_ -Return the client ID of the block, or null if none exists. +- `?string`: Adjacent block's client ID, or null if none exists. -### getPreviousBlockClientId +# **getPreviousBlockClientId** Returns the previous block's client ID from the given reference start ID. Defaults start to the selected block. Returns null if there is no previous block. -*Parameters* +_Parameters_ - * state: Editor state. - * startClientId: Optional client ID of block from which to - search. +- _state_ `Object`: Editor state. +- _startClientId_ `?string`: Optional client ID of block from which to search. -*Returns* +_Returns_ -Adjacent block's client ID, or null if none exists. +- `?string`: Adjacent block's client ID, or null if none exists. -### getNextBlockClientId +# **getSelectedBlock** -Returns the next block's client ID from the given reference start ID. -Defaults start to the selected block. Returns null if there is no next -block. +Returns the currently selected block, or null if there is no selected block. -*Parameters* +_Parameters_ - * state: Editor state. - * startClientId: Optional client ID of block from which to - search. +- _state_ `Object`: Global application state. -*Returns* +_Returns_ -Adjacent block's client ID, or null if none exists. +- `?Object`: Selected block. -### getSelectedBlocksInitialCaretPosition +# **getSelectedBlockClientId** -Returns the initial caret position for the selected block. -This position is to used to position the caret properly when the selected block changes. +Returns the currently selected block client ID, or null if there is no +selected block. -*Parameters* +_Parameters_ - * state: Global application state. +- _state_ `Object`: Editor state. -*Returns* +_Returns_ -Selected block. +- `?string`: Selected block client ID. -### getSelectedBlockClientIds +# **getSelectedBlockClientIds** Returns the current selection set of block client IDs (multiselection or single selection). -*Parameters* +_Parameters_ - * state: Editor state. +- _state_ `Object`: Editor state. -*Returns* +_Returns_ -Multi-selected block client IDs. +- `Array`: Multi-selected block client IDs. -### getMultiSelectedBlockClientIds +# **getSelectedBlockCount** -Returns the current multi-selection set of block client IDs, or an empty -array if there is no multi-selection. +Returns the number of blocks currently selected in the post. -*Parameters* +_Parameters_ - * state: Editor state. +- _state_ `Object`: Global application state. -*Returns* +_Returns_ -Multi-selected block client IDs. +- `number`: Number of blocks selected in the post. -### getMultiSelectedBlocks +# **getSelectedBlocksInitialCaretPosition** -Returns the current multi-selection set of blocks, or an empty array if -there is no multi-selection. +Returns the initial caret position for the selected block. +This position is to used to position the caret properly when the selected block changes. -*Parameters* +_Parameters_ - * state: Editor state. +- _state_ `Object`: Global application state. -*Returns* +_Returns_ -Multi-selected block objects. +- `?Object`: Selected block. -### getFirstMultiSelectedBlockClientId +# **getSelectionEnd** -Returns the client ID of the first block in the multi-selection set, or null -if there is no multi-selection. +Returns the current selection end block client ID, attribute key and text +offset. -*Parameters* +_Parameters_ - * state: Editor state. +- _state_ `Object`: Block editor state. -*Returns* +_Returns_ -First block client ID in the multi-selection set. +- `WPBlockSelection`: Selection end information. -### getLastMultiSelectedBlockClientId +# **getSelectionStart** -Returns the client ID of the last block in the multi-selection set, or null -if there is no multi-selection. +Returns the current selection start block client ID, attribute key and text +offset. -*Parameters* +_Parameters_ - * state: Editor state. +- _state_ `Object`: Block editor state. -*Returns* +_Returns_ -Last block client ID in the multi-selection set. +- `WPBlockSelection`: Selection start information. -### isFirstMultiSelectedBlock +# **getSettings** -Returns true if a multi-selection exists, and the block corresponding to the -specified client ID is the first block of the multi-selection set, or false -otherwise. +Returns the editor settings. -*Parameters* +_Parameters_ - * state: Editor state. - * clientId: Block client ID. +- _state_ `Object`: Editor state. -*Returns* +_Returns_ -Whether block is first in multi-selection. +- `Object`: The editor settings object. -### isBlockMultiSelected +# **getTemplate** -Returns true if the client ID occurs within the block multi-selection, or -false otherwise. +Returns the defined block template -*Parameters* +_Parameters_ - * state: Editor state. - * clientId: Block client ID. +- _state_ `boolean`: -*Returns* +_Returns_ -Whether block is in multi-selection set. +- `?Array`: Block Template -### isAncestorMultiSelected +# **getTemplateLock** -Returns true if an ancestor of the block is multi-selected, or false -otherwise. +Returns the defined block template lock. Optionally accepts a root block +client ID as context, otherwise defaulting to the global context. -*Parameters* +_Parameters_ - * state: Editor state. - * clientId: Block client ID. +- _state_ `Object`: Editor state. +- _rootClientId_ `?string`: Optional block root client ID. -*Returns* +_Returns_ -Whether an ancestor of the block is in multi-selection - set. +- `?string`: Block Template Lock -### getMultiSelectedBlocksStartClientId +# **hasInserterItems** -Returns the client ID of the block which begins the multi-selection set, or -null if there is no multi-selection. +Determines whether there are items to show in the inserter. -This is not necessarily the first client ID in the selection. +_Parameters_ -*Parameters* +- _state_ `Object`: Editor state. +- _rootClientId_ `?string`: Optional root client ID of block list. - * state: Editor state. +_Returns_ -*Returns* +- `boolean`: Items that appear in inserter. -Client ID of block beginning multi-selection. +# **hasMultiSelection** -### getMultiSelectedBlocksEndClientId +Returns true if a multi-selection has been made, or false otherwise. -Returns the client ID of the block which ends the multi-selection set, or -null if there is no multi-selection. +_Parameters_ -This is not necessarily the last client ID in the selection. +- _state_ `Object`: Editor state. -*Parameters* +_Returns_ - * state: Editor state. +- `boolean`: Whether multi-selection has been made. -*Returns* +# **hasSelectedBlock** -Client ID of block ending multi-selection. +Returns true if there is a single selected block, or false otherwise. -### getBlockOrder +_Parameters_ -Returns an array containing all block client IDs in the editor in the order -they appear. Optionally accepts a root client ID of the block list for which -the order should be returned, defaulting to the top-level block order. +- _state_ `Object`: Editor state. -*Parameters* +_Returns_ - * state: Editor state. - * rootClientId: Optional root client ID of block list. +- `boolean`: Whether a single block is selected. -*Returns* +# **hasSelectedInnerBlock** -Ordered client IDs of editor blocks. +Returns true if one of the block's inner blocks is selected. -### getBlockIndex +_Parameters_ -Returns the index at which the block corresponding to the specified client -ID occurs within the block order, or `-1` if the block does not exist. +- _state_ `Object`: Editor state. +- _clientId_ `string`: Block client ID. +- _deep_ `boolean`: Perform a deep check. -*Parameters* +_Returns_ - * state: Editor state. - * clientId: Block client ID. - * rootClientId: Optional root client ID of block list. +- `boolean`: Whether the block as an inner block selected -*Returns* +# **isAncestorMultiSelected** -Index at which block exists in order. +Returns true if an ancestor of the block is multi-selected, or false +otherwise. -### isBlockSelected +_Parameters_ -Returns true if the block corresponding to the specified client ID is -currently selected and no multi-selection exists, or false otherwise. +- _state_ `Object`: Editor state. +- _clientId_ `string`: Block client ID. -*Parameters* +_Returns_ - * state: Editor state. - * clientId: Block client ID. +- `boolean`: Whether an ancestor of the block is in multi-selection set. -*Returns* +# **isBlockInsertionPointVisible** -Whether block is selected and multi-selection exists. +Returns true if we should show the block insertion point. -### hasSelectedInnerBlock +_Parameters_ -Returns true if one of the block's inner blocks is selected. +- _state_ `Object`: Global application state. -*Parameters* +_Returns_ - * state: Editor state. - * clientId: Block client ID. - * deep: Perform a deep check. +- `?boolean`: Whether the insertion point is visible or not. -*Returns* +# **isBlockMultiSelected** -Whether the block as an inner block selected +Returns true if the client ID occurs within the block multi-selection, or +false otherwise. + +_Parameters_ + +- _state_ `Object`: Editor state. +- _clientId_ `string`: Block client ID. + +_Returns_ + +- `boolean`: Whether block is in multi-selection set. -### isBlockWithinSelection +# **isBlockSelected** Returns true if the block corresponding to the specified client ID is -currently selected but isn't the last of the selected blocks. Here "last" -refers to the block sequence in the document, _not_ the sequence of -multi-selection, which is why `state.blockSelection.end` isn't used. +currently selected and no multi-selection exists, or false otherwise. -*Parameters* +_Parameters_ - * state: Editor state. - * clientId: Block client ID. +- _state_ `Object`: Editor state. +- _clientId_ `string`: Block client ID. -*Returns* +_Returns_ -Whether block is selected and not the last in the - selection. +- `boolean`: Whether block is selected and multi-selection exists. -### hasMultiSelection +# **isBlockValid** -Returns true if a multi-selection has been made, or false otherwise. +Returns whether a block is valid or not. -*Parameters* +_Parameters_ - * state: Editor state. +- _state_ `Object`: Editor state. +- _clientId_ `string`: Block client ID. -*Returns* +_Returns_ -Whether multi-selection has been made. +- `boolean`: Is Valid. -### isMultiSelecting +# **isBlockWithinSelection** -Whether in the process of multi-selecting or not. This flag is only true -while the multi-selection is being selected (by mouse move), and is false -once the multi-selection has been settled. +Returns true if the block corresponding to the specified client ID is +currently selected but isn't the last of the selected blocks. Here "last" +refers to the block sequence in the document, _not_ the sequence of +multi-selection, which is why `state.blockSelection.end` isn't used. -*Parameters* +_Parameters_ - * state: Global application state. +- _state_ `Object`: Editor state. +- _clientId_ `string`: Block client ID. -*Returns* +_Returns_ -True if multi-selecting, false if not. +- `boolean`: Whether block is selected and not the last in the selection. -### isSelectionEnabled +# **isCaretWithinFormattedText** -Selector that returns if multi-selection is enabled or not. +Returns true if the caret is within formatted text, or false otherwise. -*Parameters* +_Parameters_ - * state: Global application state. +- _state_ `Object`: Global application state. -*Returns* +_Returns_ -True if it should be possible to multi-select blocks, false if multi-selection is disabled. +- `boolean`: Whether the caret is within formatted text. -### getBlockMode +# **isFirstMultiSelectedBlock** -Returns the block's editing mode, defaulting to "visual" if not explicitly -assigned. +Returns true if a multi-selection exists, and the block corresponding to the +specified client ID is the first block of the multi-selection set, or false +otherwise. -*Parameters* +_Parameters_ - * state: Editor state. - * clientId: Block client ID. +- _state_ `Object`: Editor state. +- _clientId_ `string`: Block client ID. -*Returns* +_Returns_ -Block editing mode. +- `boolean`: Whether block is first in multi-selection. -### isTyping +# **isLastBlockChangePersistent** -Returns true if the user is typing, or false otherwise. +Returns true if the most recent block change is be considered persistent, or +false otherwise. A persistent change is one committed by BlockEditorProvider +via its `onChange` callback, in addition to `onInput`. -*Parameters* +_Parameters_ - * state: Global application state. +- _state_ `Object`: Block editor state. -*Returns* +_Returns_ -Whether user is typing. +- `boolean`: Whether the most recent block change was persistent. -### isCaretWithinFormattedText +# **isMultiSelecting** -Returns true if the caret is within formatted text, or false otherwise. +Whether in the process of multi-selecting or not. This flag is only true +while the multi-selection is being selected (by mouse move), and is false +once the multi-selection has been settled. -*Parameters* +_Related_ - * state: Global application state. +- hasMultiSelection -*Returns* +_Parameters_ -Whether the caret is within formatted text. +- _state_ `Object`: Global application state. -### getBlockInsertionPoint +_Returns_ -Returns the insertion point, the index at which the new inserted block would -be placed. Defaults to the last index. +- `boolean`: True if multi-selecting, false if not. -*Parameters* +# **isSelectionEnabled** - * state: Editor state. +Selector that returns if multi-selection is enabled or not. -*Returns* +_Parameters_ -Insertion point object with `rootClientId`, `index`. +- _state_ `Object`: Global application state. -### isBlockInsertionPointVisible +_Returns_ -Returns true if we should show the block insertion point. +- `boolean`: True if it should be possible to multi-select blocks, false if multi-selection is disabled. + +# **isTyping** + +Returns true if the user is typing, or false otherwise. -*Parameters* +_Parameters_ - * state: Global application state. +- _state_ `Object`: Global application state. -*Returns* +_Returns_ -Whether the insertion point is visible or not. +- `boolean`: Whether user is typing. -### isValidTemplate +# **isValidTemplate** Returns whether the blocks matches the template or not. -*Parameters* +_Parameters_ - * state: null +- _state_ `boolean`: -*Returns* +_Returns_ -Whether the template is valid or not. +- `?boolean`: Whether the template is valid or not. -### getTemplate -Returns the defined block template + -*Parameters* +## Actions - * state: null + -*Returns* +# **clearSelectedBlock** -Block Template +Returns an action object used in signalling that the block selection is cleared. -### getTemplateLock +_Returns_ -Returns the defined block template lock. Optionally accepts a root block -client ID as context, otherwise defaulting to the global context. +- `Object`: Action object. -*Parameters* +# **enterFormattedText** - * state: Editor state. - * rootClientId: Optional block root client ID. +Returns an action object used in signalling that the caret has entered formatted text. -*Returns* +_Returns_ -Block Template Lock +- `Object`: Action object. -### canInsertBlockType +# **exitFormattedText** -Determines if the given block type is allowed to be inserted into the block list. +Returns an action object used in signalling that the user caret has exited formatted text. -*Parameters* +_Returns_ - * state: Editor state. - * blockName: The name of the block type, e.g.' core/paragraph'. - * rootClientId: Optional root client ID of block list. +- `Object`: Action object. -*Returns* +# **hideInsertionPoint** -Whether the given block type is allowed to be inserted. +Returns an action object hiding the insertion point. -### getInserterItems +_Returns_ -Determines the items that appear in the inserter. Includes both static -items (e.g. a regular block type) and dynamic items (e.g. a reusable block). +- `Object`: Action object. -Each item object contains what's necessary to display a button in the -inserter and handle its selection. +# **insertBlock** -The 'utility' property indicates how useful we think an item will be to the -user. There are 4 levels of utility: +Returns an action object used in signalling that a single block should be +inserted, optionally at a specific index respective a root block list. -1. Blocks that are contextually useful (utility = 3) -2. Blocks that have been previously inserted (utility = 2) -3. Blocks that are in the common category (utility = 1) -4. All other blocks (utility = 0) +_Parameters_ -The 'frecency' property is a heuristic (https://en.wikipedia.org/wiki/Frecency) -that combines block usage frequenty and recency. +- _block_ `Object`: Block object 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. -Items are returned ordered descendingly by their 'utility' and 'frecency'. +_Returns_ -*Parameters* +- `Object`: Action object. - * state: Editor state. - * rootClientId: Optional root client ID of block list. +# **insertBlocks** -*Returns* +Returns an action object used in signalling that an array of blocks should +be inserted, optionally at a specific index respective a root block list. -Items that appear in inserter. +_Parameters_ -### hasInserterItems +- _blocks_ `Array`: 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. -Determines whether there are items to show in the inserter. +_Returns_ -*Parameters* +- `Object`: Action object. - * state: Editor state. - * rootClientId: Optional root client ID of block list. +# **insertDefaultBlock** -*Returns* +Returns an action object used in signalling that a new block of the default +type should be added to the block list. -Items that appear in inserter. +_Parameters_ -### getBlockListSettings +- _attributes_ `?Object`: Optional attributes of the block to assign. +- _rootClientId_ `?string`: Optional root client ID of block list on which to append. +- _index_ `?number`: Optional index where to insert the default block -Returns the Block List settings of a block, if any exist. +_Returns_ -*Parameters* +- `Object`: Action object - * state: Editor state. - * clientId: Block client ID. +# **mergeBlocks** -*Returns* +Returns an action object used in signalling that two blocks should be merged -Block settings of the block if set. +_Parameters_ -### getSettings +- _firstBlockClientId_ `string`: Client ID of the first block to merge. +- _secondBlockClientId_ `string`: Client ID of the second block to merge. -Returns the editor settings. +_Returns_ -*Parameters* +- `Object`: Action object. - * state: Editor state. +# **moveBlocksDown** -*Returns* +Undocumented declaration. -The editor settings object. +# **moveBlocksUp** -### isLastBlockChangePersistent +Undocumented declaration. -Returns true if the most recent block change is be considered persistent, or -false otherwise. A persistent change is one committed by BlockEditorProvider -via its `onChange` callback, in addition to `onInput`. +# **moveBlockToPosition** -*Parameters* +Returns an action object signalling that an indexed block should be moved +to a new index. - * state: Block editor state. +_Parameters_ -*Returns* +- _clientId_ `?string`: The client ID of the block. +- _fromRootClientId_ `?string`: Root client ID source. +- _toRootClientId_ `?string`: Root client ID destination. +- _index_ `number`: The index to move the block into. -Whether the most recent block change was persistent. +# **multiSelect** -## Actions +Returns an action object used in signalling that block multi-selection changed. -### resetBlocks +_Parameters_ -Returns an action object used in signalling that blocks state should be -reset to the specified array of blocks, taking precedence over any other -content reflected as an edit in state. +- _start_ `string`: First block of the multi selection. +- _end_ `string`: Last block of the multiselection. -*Parameters* +_Returns_ - * blocks: Array of blocks. +- `Object`: Action object. -### receiveBlocks +# **receiveBlocks** Returns an action object used in signalling that blocks have been received. Unlike resetBlocks, these should be appended to the existing known set, not replacing. -*Parameters* +_Parameters_ - * blocks: Array of block objects. +- _blocks_ `Array`: Array of block objects. -### updateBlockAttributes +_Returns_ -Returns an action object used in signalling that the block attributes with -the specified client ID has been updated. +- `Object`: Action object. -*Parameters* +# **removeBlock** - * clientId: Block client ID. - * attributes: Block attributes to be merged. +Returns an action object used in signalling that the block with the +specified client ID is to be removed. -### updateBlock +_Parameters_ -Returns an action object used in signalling that the block with the -specified client ID has been updated. +- _clientId_ `string`: Client ID of block to remove. +- _selectPrevious_ `boolean`: True if the previous block should be selected when a block is removed. -*Parameters* +_Returns_ - * clientId: Block client ID. - * updates: Block attributes to be merged. +- `Object`: Action object. -### selectBlock +# **removeBlocks** -Returns an action object used in signalling that the block with the -specified client ID has been selected, optionally accepting a position -value reflecting its selection directionality. An initialPosition of -1 -reflects a reverse selection. +Yields action objects used in signalling that the blocks corresponding to +the set of specified client IDs are to be removed. -*Parameters* +_Parameters_ - * clientId: Block client ID. - * initialPosition: Optional initial position. Pass as -1 to - reflect reverse selection. +- _clientIds_ `(string|Array)`: Client IDs of blocks to remove. +- _selectPrevious_ `boolean`: True if the previous block should be selected when a block is removed. -### selectPreviousBlock +# **replaceBlock** -Yields action objects used in signalling that the block preceding the given -clientId should be selected. +Returns an action object signalling that a single block should be replaced +with one or more replacement blocks. -*Parameters* +_Parameters_ - * clientId: Block client ID. +- _clientId_ `(string|Array)`: Block client ID to replace. +- _block_ `(Object|Array)`: Replacement block(s). -### selectNextBlock +_Returns_ -Yields action objects used in signalling that the block following the given -clientId should be selected. +- `Object`: Action object. -*Parameters* +# **replaceBlocks** - * clientId: Block client ID. +Returns an action object signalling that a blocks should be replaced with +one or more replacement blocks. -### startMultiSelect +_Parameters_ -Returns an action object used in signalling that a block multi-selection has started. +- _clientIds_ `(string|Array)`: Block client ID(s) to replace. +- _blocks_ `(Object|Array)`: Replacement block(s). -### stopMultiSelect +# **replaceInnerBlocks** -Returns an action object used in signalling that block multi-selection stopped. +Returns an action object used in signalling that the inner blocks with the +specified client ID should be replaced. -### multiSelect +_Parameters_ -Returns an action object used in signalling that block multi-selection changed. +- _rootClientId_ `string`: Client ID of the block whose InnerBlocks will re replaced. +- _blocks_ `Array`: Block objects to insert as new InnerBlocks +- _updateSelection_ `?boolean`: If true block selection will be updated. If false, block selection will not change. Defaults to true. -*Parameters* +_Returns_ - * start: First block of the multi selection. - * end: Last block of the multiselection. +- `Object`: Action object. -### clearSelectedBlock +# **resetBlocks** -Returns an action object used in signalling that the block selection is cleared. +Returns an action object used in signalling that blocks state should be +reset to the specified array of blocks, taking precedence over any other +content reflected as an edit in state. -### toggleSelection +_Parameters_ -Returns an action object that enables or disables block selection. +- _blocks_ `Array`: Array of blocks. -*Parameters* +_Returns_ - * boolean: [isSelectionEnabled=true] Whether block selection should - be enabled. +- `Object`: Action object. -### replaceBlocks +# **selectBlock** -Returns an action object signalling that a blocks should be replaced with -one or more replacement blocks. +Returns an action object used in signalling that the block with the +specified client ID has been selected, optionally accepting a position +value reflecting its selection directionality. An initialPosition of -1 +reflects a reverse selection. -*Parameters* +_Parameters_ - * clientIds: Block client ID(s) to replace. - * blocks: Replacement block(s). +- _clientId_ `string`: Block client ID. +- _initialPosition_ `?number`: Optional initial position. Pass as -1 to reflect reverse selection. -### replaceBlock +_Returns_ -Returns an action object signalling that a single block should be replaced -with one or more replacement blocks. +- `Object`: Action object. -*Parameters* +# **selectionChange** - * clientId: Block client ID to replace. - * block: Replacement block(s). +Returns an action object used in signalling that the user caret has changed +position. -### moveBlockToPosition +_Parameters_ -Returns an action object signalling that an indexed block should be moved -to a new index. +- _clientId_ `string`: The selected block client ID. +- _attributeKey_ `string`: The selected block attribute key. +- _startOffset_ `number`: The start offset. +- _endOffset_ `number`: The end offset. -*Parameters* +_Returns_ - * clientId: The client ID of the block. - * fromRootClientId: Root client ID source. - * toRootClientId: Root client ID destination. - * index: The index to move the block into. +- `Object`: Action object. -### insertBlock +# **selectNextBlock** -Returns an action object used in signalling that a single block should be -inserted, optionally at a specific index respective a root block list. +Yields action objects used in signalling that the block following the given +clientId should be selected. -*Parameters* +_Parameters_ - * block: Block object to insert. - * index: Index at which block should be inserted. - * rootClientId: Optional root client ID of block list on which to insert. - * updateSelection: If true block selection will be updated. If false, block selection will not change. Defaults to true. +- _clientId_ `string`: Block client ID. -### insertBlocks +# **selectPreviousBlock** -Returns an action object used in signalling that an array of blocks should -be inserted, optionally at a specific index respective a root block list. +Yields action objects used in signalling that the block preceding the given +clientId should be selected. -*Parameters* +_Parameters_ - * blocks: Block objects to insert. - * index: Index at which block should be inserted. - * rootClientId: Optional root client ID of block list on which to insert. - * updateSelection: If true block selection will be updated. If false, block selection will not change. Defaults to true. +- _clientId_ `string`: Block client ID. -### showInsertionPoint +# **setTemplateValidity** -Returns an action object used in signalling that the insertion point should -be shown. +Returns an action object resetting the template validity. -*Parameters* +_Parameters_ - * rootClientId: Optional root client ID of block list on - which to insert. - * index: Index at which block should be inserted. +- _isValid_ `boolean`: template validity flag. -### hideInsertionPoint +_Returns_ -Returns an action object hiding the insertion point. +- `Object`: Action object. -### setTemplateValidity +# **showInsertionPoint** -Returns an action object resetting the template validity. +Returns an action object used in signalling that the insertion point should +be shown. -*Parameters* +_Parameters_ - * isValid: template validity flag. +- _rootClientId_ `?string`: Optional root client ID of block list on which to insert. +- _index_ `?number`: Index at which block should be inserted. -### synchronizeTemplate +_Returns_ -Returns an action object synchronize the template with the list of blocks +- `Object`: Action object. -### mergeBlocks +# **startMultiSelect** -Returns an action object used in signalling that two blocks should be merged +Returns an action object used in signalling that a block multi-selection has started. -*Parameters* +_Returns_ - * firstBlockClientId: Client ID of the first block to merge. - * secondBlockClientId: Client ID of the second block to merge. +- `Object`: Action object. -### removeBlocks +# **startTyping** -Yields action objects used in signalling that the blocks corresponding to -the set of specified client IDs are to be removed. +Returns an action object used in signalling that the user has begun to type. -*Parameters* +_Returns_ - * clientIds: Client IDs of blocks to remove. - * selectPrevious: True if the previous block should be - selected when a block is removed. +- `Object`: Action object. -### removeBlock +# **stopMultiSelect** -Returns an action object used in signalling that the block with the -specified client ID is to be removed. +Returns an action object used in signalling that block multi-selection stopped. -*Parameters* +_Returns_ - * clientId: Client ID of block to remove. - * selectPrevious: True if the previous block should be - selected when a block is removed. +- `Object`: Action object. -### replaceInnerBlocks +# **stopTyping** -Returns an action object used in signalling that the inner blocks with the -specified client ID should be replaced. +Returns an action object used in signalling that the user has stopped typing. + +_Returns_ + +- `Object`: Action object. + +# **synchronizeTemplate** + +Returns an action object synchronize the template with the list of blocks -*Parameters* +_Returns_ - * rootClientId: Client ID of the block whose InnerBlocks will re replaced. - * blocks: Block objects to insert as new InnerBlocks - * updateSelection: If true block selection will be updated. If false, block selection will not change. Defaults to true. +- `Object`: Action object. -### toggleBlockMode +# **toggleBlockMode** Returns an action object used to toggle the block editing mode between visual and HTML modes. -*Parameters* +_Parameters_ - * clientId: Block client ID. +- _clientId_ `string`: Block client ID. -### startTyping +_Returns_ -Returns an action object used in signalling that the user has begun to type. +- `Object`: Action object. -### stopTyping +# **toggleSelection** -Returns an action object used in signalling that the user has stopped typing. +Returns an action object that enables or disables block selection. -### enterFormattedText +_Parameters_ -Returns an action object used in signalling that the caret has entered formatted text. +- _isSelectionEnabled_ `[boolean]`: Whether block selection should be enabled. -### exitFormattedText +_Returns_ -Returns an action object used in signalling that the user caret has exited formatted text. +- `Object`: Action object. -### selectionChange +# **updateBlock** -Returns an action object used in signalling that the user caret has changed -position. +Returns an action object used in signalling that the block with the +specified client ID has been updated. -*Parameters* +_Parameters_ - * clientId: The selected block client ID. - * attributeKey: The selected block attribute key. - * startOffset: The start offset. - * endOffset: The end offset. +- _clientId_ `string`: Block client ID. +- _updates_ `Object`: Block attributes to be merged. -### insertDefaultBlock +_Returns_ -Returns an action object used in signalling that a new block of the default -type should be added to the block list. +- `Object`: Action object. + +# **updateBlockAttributes** -*Parameters* +Returns an action object used in signalling that the block attributes with +the specified client ID has been updated. + +_Parameters_ - * attributes: Optional attributes of the block to assign. - * rootClientId: Optional root client ID of block list on which - to append. - * index: Optional index where to insert the default block +- _clientId_ `string`: Block client ID. +- _attributes_ `Object`: Block attributes to be merged. -### updateBlockListSettings +_Returns_ + +- `Object`: Action object. + +# **updateBlockListSettings** Returns an action object that changes the nested settings of a given block. -*Parameters* +_Parameters_ + +- _clientId_ `string`: Client ID of the block whose nested setting are being received. +- _settings_ `Object`: Object with the new settings for the nested block. - * clientId: Client ID of the block whose nested setting are - being received. - * settings: Object with the new settings for the nested block. +_Returns_ -### updateSettings +- `Object`: Action object -Returns an action object used in signalling that the block editor settings have been updated. +# **updateSettings** -*Parameters* +Undocumented declaration. - * settings: Updated settings \ No newline at end of file + diff --git a/docs/designers-developers/developers/data/data-core-blocks.md b/docs/designers-developers/developers/data/data-core-blocks.md index c7a63e769f350..5256587043602 100644 --- a/docs/designers-developers/developers/data/data-core-blocks.md +++ b/docs/designers-developers/developers/data/data-core-blocks.md @@ -1,251 +1,299 @@ -# **core/blocks**: Block Types Data +# Block Types Data + +Namespace: `core/blocks`. ## Selectors -### getBlockTypes + -Returns all the available block types. +# **getBlockStyles** + +Returns block styles by block name. + +_Parameters_ + +- _state_ `Object`: Data state. +- _name_ `string`: Block type name. + +_Returns_ + +- `?Array`: Block Styles. + +# **getBlockSupport** + +Returns the block support value for a feature, if defined. + +_Parameters_ + +- _state_ `Object`: Data state. +- _nameOrType_ `(string|Object)`: Block name or type object +- _feature_ `string`: Feature to retrieve +- _defaultSupports_ `*`: Default value to return if not explicitly defined -*Parameters* +_Returns_ - * state: Data state. +- `?*`: Block support value -### getBlockType +# **getBlockType** Returns a block type by name. -*Parameters* +_Parameters_ - * state: Data state. - * name: Block type name. +- _state_ `Object`: Data state. +- _name_ `string`: Block type name. -*Returns* +_Returns_ -Block Type. +- `?Object`: Block Type. -### getBlockStyles +# **getBlockTypes** -Returns block styles by block name. +Returns all the available block types. -*Parameters* +_Parameters_ - * state: Data state. - * name: Block type name. +- _state_ `Object`: Data state. -*Returns* +_Returns_ -Block Styles. +- `Array`: Block Types. -### getCategories +# **getCategories** Returns all the available categories. -*Parameters* +_Parameters_ + +- _state_ `Object`: Data state. + +_Returns_ - * state: Data state. +- `Array`: Categories list. + +# **getChildBlockNames** + +Returns an array with the child blocks of a given block. -*Returns* +_Parameters_ -Categories list. +- _state_ `Object`: Data state. +- _blockName_ `string`: Block type name. -### getDefaultBlockName +_Returns_ + +- `Array`: Array of child block names. + +# **getDefaultBlockName** Returns the name of the default block name. -*Parameters* +_Parameters_ - * state: Data state. +- _state_ `Object`: Data state. -*Returns* +_Returns_ -Default block name. +- `?string`: Default block name. -### getFreeformFallbackBlockName +# **getFreeformFallbackBlockName** Returns the name of the block for handling non-block content. -*Parameters* +_Parameters_ - * state: Data state. +- _state_ `Object`: Data state. -*Returns* +_Returns_ -Name of the block for handling non-block content. +- `?string`: Name of the block for handling non-block content. -### getUnregisteredFallbackBlockName +# **getUnregisteredFallbackBlockName** Returns the name of the block for handling unregistered blocks. -*Parameters* +_Parameters_ - * state: Data state. +- _state_ `Object`: Data state. -*Returns* +_Returns_ -Name of the block for handling unregistered blocks. +- `?string`: Name of the block for handling unregistered blocks. -### getChildBlockNames +# **hasBlockSupport** -Returns an array with the child blocks of a given block. +Returns true if the block defines support for a feature, or false otherwise. -*Parameters* +_Parameters_ - * state: Data state. - * blockName: Block type name. +- _state_ `Object`: Data state. +- _nameOrType_ `(string|Object)`: Block name or type object. +- _feature_ `string`: Feature to test. +- _defaultSupports_ `boolean`: Whether feature is supported by default if not explicitly defined. -*Returns* +_Returns_ -Array of child block names. +- `boolean`: Whether block supports feature. -### getBlockSupport +# **hasChildBlocks** -Returns the block support value for a feature, if defined. +Returns a boolean indicating if a block has child blocks or not. -*Parameters* +_Parameters_ - * state: Data state. - * nameOrType: Block name or type object - * feature: Feature to retrieve - * defaultSupports: Default value to return if not - explicitly defined +- _state_ `Object`: Data state. +- _blockName_ `string`: Block type name. -*Returns* +_Returns_ -Block support value +- `boolean`: True if a block contains child blocks and false otherwise. -### hasBlockSupport +# **hasChildBlocksWithInserterSupport** -Returns true if the block defines support for a feature, or false otherwise. +Returns a boolean indicating if a block has at least one child block with inserter support. -*Parameters* +_Parameters_ - * state: Data state. - * nameOrType: Block name or type object. - * feature: Feature to test. - * defaultSupports: Whether feature is supported by - default if not explicitly defined. +- _state_ `Object`: Data state. +- _blockName_ `string`: Block type name. -*Returns* +_Returns_ -Whether block supports feature. +- `boolean`: True if a block contains at least one child blocks with inserter support and false otherwise. -### isMatchingSearchTerm +# **isMatchingSearchTerm** Returns true if the block type by the given name or object value matches a search term, or false otherwise. -*Parameters* +_Parameters_ - * state: Blocks state. - * nameOrType: Block name or type object. - * searchTerm: Search term by which to filter. +- _state_ `Object`: Blocks state. +- _nameOrType_ `(string|Object)`: Block name or type object. +- _searchTerm_ `string`: Search term by which to filter. -*Returns* +_Returns_ -Wheter block type matches search term. +- `Array`: Wheter block type matches search term. -### hasChildBlocks -Returns a boolean indicating if a block has child blocks or not. + -*Parameters* +## Actions - * state: Data state. - * blockName: Block type name. + -*Returns* +# **addBlockStyles** -True if a block contains child blocks and false otherwise. +Returns an action object used in signalling that new block styles have been added. -### hasChildBlocksWithInserterSupport +_Parameters_ -Returns a boolean indicating if a block has at least one child block with inserter support. +- _blockName_ `string`: Block name. +- _styles_ `(Array|Object)`: Block styles. -*Parameters* +_Returns_ - * state: Data state. - * blockName: Block type name. +- `Object`: Action object. -*Returns* +# **addBlockTypes** -True if a block contains at least one child blocks with inserter support - and false otherwise. +Returns an action object used in signalling that block types have been added. -## Actions +_Parameters_ -### addBlockTypes +- _blockTypes_ `(Array|Object)`: Block types received. -Returns an action object used in signalling that block types have been added. +_Returns_ + +- `Object`: Action object. + +# **removeBlockStyles** + +Returns an action object used in signalling that block styles have been removed. -*Parameters* +_Parameters_ - * blockTypes: Block types received. +- _blockName_ `string`: Block name. +- _styleNames_ `(Array|string)`: Block style names. -### removeBlockTypes +_Returns_ + +- `Object`: Action object. + +# **removeBlockTypes** Returns an action object used to remove a registered block type. -*Parameters* +_Parameters_ - * names: Block name. +- _names_ `(string|Array)`: Block name. -### addBlockStyles +_Returns_ -Returns an action object used in signalling that new block styles have been added. +- `Object`: Action object. -*Parameters* +# **setCategories** - * blockName: Block name. - * styles: Block styles. +Returns an action object used to set block categories. -### removeBlockStyles +_Parameters_ -Returns an action object used in signalling that block styles have been removed. +- _categories_ `Array`: Block categories. -*Parameters* +_Returns_ - * blockName: Block name. - * styleNames: Block style names. +- `Object`: Action object. -### setDefaultBlockName +# **setDefaultBlockName** Returns an action object used to set the default block name. -*Parameters* +_Parameters_ + +- _name_ `string`: Block name. + +_Returns_ - * name: Block name. +- `Object`: Action object. -### setFreeformFallbackBlockName +# **setFreeformFallbackBlockName** Returns an action object used to set the name of the block used as a fallback for non-block content. -*Parameters* +_Parameters_ - * name: Block name. +- _name_ `string`: Block name. -### setUnregisteredFallbackBlockName +_Returns_ + +- `Object`: Action object. + +# **setUnregisteredFallbackBlockName** Returns an action object used to set the name of the block used as a fallback for unregistered blocks. -*Parameters* +_Parameters_ - * name: Block name. +- _name_ `string`: Block name. -### setCategories +_Returns_ -Returns an action object used to set block categories. +- `Object`: Action object. -*Parameters* +# **updateCategory** - * categories: Block categories. +Returns an action object used to update a category. -### updateCategory +_Parameters_ -Returns an action object used to update a category. +- _slug_ `string`: Block category slug. +- _category_ `Object`: Object containing the category properties that should be updated. + +_Returns_ -*Parameters* +- `Object`: Action object. - * slug: Block category slug. - * category: Object containing the category properties that should be updated. \ No newline at end of file + diff --git a/docs/designers-developers/developers/data/data-core-edit-post.md b/docs/designers-developers/developers/data/data-core-edit-post.md index f36cf5bc47068..00e60869dbb87 100644 --- a/docs/designers-developers/developers/data/data-core-edit-post.md +++ b/docs/designers-developers/developers/data/data-core-edit-post.md @@ -1,375 +1,462 @@ -# **core/edit-post**: The Editor’s UI Data +# The Editor’s UI Data + +Namespace: `core/edit-post`. ## Selectors -### getEditorMode + -Returns the current editing mode. +# **getActiveGeneralSidebarName** -*Parameters* +Returns the current active general sidebar name, or null if there is no +general sidebar active. The active general sidebar is a unique name to +identify either an editor or plugin sidebar. - * state: Global application state. +Examples: -### isEditorSidebarOpened +- `edit-post/document` +- `my-plugin/insert-image-sidebar` -Returns true if the editor sidebar is opened. +_Parameters_ -*Parameters* +- _state_ `Object`: Global application state. - * state: Global application state +_Returns_ -*Returns* +- `?string`: Active general sidebar name. -Whether the editor sidebar is opened. +# **getActiveMetaBoxLocations** -### isPluginSidebarOpened +Returns an array of active meta box locations. -Returns true if the plugin sidebar is opened. +_Parameters_ -*Parameters* +- _state_ `Object`: Post editor state. - * state: Global application state +_Returns_ -*Returns* +- `Array`: Active meta box locations. -Whether the plugin sidebar is opened. +# **getAllMetaBoxes** -### getActiveGeneralSidebarName +Returns the list of all the available meta boxes. -Returns the current active general sidebar name, or null if there is no -general sidebar active. The active general sidebar is a unique name to -identify either an editor or plugin sidebar. +_Parameters_ -Examples: +- _state_ `Object`: Global application state. + +_Returns_ - - `edit-post/document` - - `my-plugin/insert-image-sidebar` +- `Array`: List of meta boxes. -*Parameters* +# **getEditorMode** - * state: Global application state. +Returns the current editing mode. -*Returns* +_Parameters_ -Active general sidebar name. +- _state_ `Object`: Global application state. -### getPreferences +_Returns_ -Returns the preferences (these preferences are persisted locally). +- `string`: Editing mode. -*Parameters* +# **getMetaBoxesPerLocation** - * state: Global application state. +Returns the list of all the available meta boxes for a given location. -*Returns* +_Parameters_ -Preferences Object. +- _state_ `Object`: Global application state. +- _location_ `string`: Meta box location to test. -### getPreference +_Returns_ -*Parameters* +- `?Array`: List of meta boxes. - * state: Global application state. - * preferenceKey: Preference Key. - * defaultValue: Default Value. +# **getPreference** -*Returns* +_Parameters_ -Preference Value. +- _state_ `Object`: Global application state. +- _preferenceKey_ `string`: Preference Key. +- _defaultValue_ `Mixed`: Default Value. -### isPublishSidebarOpened +_Returns_ -Returns true if the publish sidebar is opened. +- `Mixed`: Preference Value. -*Parameters* +# **getPreferences** - * state: Global application state +Returns the preferences (these preferences are persisted locally). -*Returns* +_Parameters_ -Whether the publish sidebar is open. +- _state_ `Object`: Global application state. -### isEditorPanelRemoved +_Returns_ -Returns true if the given panel was programmatically removed, or false otherwise. -All panels are not removed by default. +- `Object`: Preferences Object. -*Parameters* +# **hasMetaBoxes** - * state: Global application state. - * panelName: A string that identifies the panel. +Returns true if the post is using Meta Boxes -*Returns* +_Parameters_ -Whether or not the panel is removed. +- _state_ `Object`: Global application state -### isEditorPanelEnabled +_Returns_ + +- `boolean`: Whether there are metaboxes or not. + +# **isEditorPanelEnabled** Returns true if the given panel is enabled, or false otherwise. Panels are enabled by default. -*Parameters* +_Parameters_ - * state: Global application state. - * panelName: A string that identifies the panel. +- _state_ `Object`: Global application state. +- _panelName_ `string`: A string that identifies the panel. -*Returns* +_Returns_ -Whether or not the panel is enabled. +- `boolean`: Whether or not the panel is enabled. -### isEditorPanelOpened +# **isEditorPanelOpened** Returns true if the given panel is open, or false otherwise. Panels are closed by default. -*Parameters* +_Parameters_ - * state: Global application state. - * panelName: A string that identifies the panel. +- _state_ `Object`: Global application state. +- _panelName_ `string`: A string that identifies the panel. -*Returns* +_Returns_ -Whether or not the panel is open. +- `boolean`: Whether or not the panel is open. -### isModalActive +# **isEditorPanelRemoved** -Returns true if a modal is active, or false otherwise. +Returns true if the given panel was programmatically removed, or false otherwise. +All panels are not removed by default. -*Parameters* +_Parameters_ - * state: Global application state. - * modalName: A string that uniquely identifies the modal. +- _state_ `Object`: Global application state. +- _panelName_ `string`: A string that identifies the panel. -*Returns* +_Returns_ -Whether the modal is active. +- `boolean`: Whether or not the panel is removed. -### isFeatureActive +# **isEditorSidebarOpened** -Returns whether the given feature is enabled or not. +Returns true if the editor sidebar is opened. -*Parameters* +_Parameters_ - * state: Global application state. - * feature: Feature slug. +- _state_ `Object`: Global application state -*Returns* +_Returns_ -Is active. +- `boolean`: Whether the editor sidebar is opened. -### isPluginItemPinned +# **isFeatureActive** -Returns true if the plugin item is pinned to the header. -When the value is not set it defaults to true. +Returns whether the given feature is enabled or not. -*Parameters* +_Parameters_ - * state: Global application state. - * pluginName: Plugin item name. +- _state_ `Object`: Global application state. +- _feature_ `string`: Feature slug. -*Returns* +_Returns_ -Whether the plugin item is pinned. +- `boolean`: Is active. -### getActiveMetaBoxLocations +# **isMetaBoxLocationActive** -Returns an array of active meta box locations. +Returns true if there is an active meta box in the given location, or false +otherwise. -*Parameters* +_Parameters_ - * state: Post editor state. +- _state_ `Object`: Post editor state. +- _location_ `string`: Meta box location to test. -*Returns* +_Returns_ -Active meta box locations. +- `boolean`: Whether the meta box location is active. -### isMetaBoxLocationVisible +# **isMetaBoxLocationVisible** Returns true if a metabox location is active and visible -*Parameters* +_Parameters_ - * state: Post editor state. - * location: Meta box location to test. +- _state_ `Object`: Post editor state. +- _location_ `string`: Meta box location to test. -*Returns* +_Returns_ -Whether the meta box location is active and visible. +- `boolean`: Whether the meta box location is active and visible. -### isMetaBoxLocationActive +# **isModalActive** -Returns true if there is an active meta box in the given location, or false -otherwise. +Returns true if a modal is active, or false otherwise. -*Parameters* +_Parameters_ - * state: Post editor state. - * location: Meta box location to test. +- _state_ `Object`: Global application state. +- _modalName_ `string`: A string that uniquely identifies the modal. -*Returns* +_Returns_ -Whether the meta box location is active. +- `boolean`: Whether the modal is active. -### getMetaBoxesPerLocation +# **isPluginItemPinned** -Returns the list of all the available meta boxes for a given location. +Returns true if the plugin item is pinned to the header. +When the value is not set it defaults to true. -*Parameters* +_Parameters_ - * state: Global application state. - * location: Meta box location to test. +- _state_ `Object`: Global application state. +- _pluginName_ `string`: Plugin item name. -*Returns* +_Returns_ -List of meta boxes. +- `boolean`: Whether the plugin item is pinned. -### getAllMetaBoxes +# **isPluginSidebarOpened** -Returns the list of all the available meta boxes. +Returns true if the plugin sidebar is opened. -*Parameters* +_Parameters_ - * state: Global application state. +- _state_ `Object`: Global application state -*Returns* +_Returns_ -List of meta boxes. +- `boolean`: Whether the plugin sidebar is opened. -### hasMetaBoxes +# **isPublishSidebarOpened** -Returns true if the post is using Meta Boxes +Returns true if the publish sidebar is opened. -*Parameters* +_Parameters_ - * state: Global application state +- _state_ `Object`: Global application state -*Returns* +_Returns_ -Whether there are metaboxes or not. +- `boolean`: Whether the publish sidebar is open. -### isSavingMetaBoxes +# **isSavingMetaBoxes** Returns true if the Meta Boxes are being saved. -*Parameters* +_Parameters_ + +- _state_ `Object`: Global application state. - * state: Global application state. +_Returns_ -*Returns* +- `boolean`: Whether the metaboxes are being saved. -Whether the metaboxes are being saved. + + ## Actions -### openGeneralSidebar + + +# **closeGeneralSidebar** + +Returns an action object signalling that the user closed the sidebar. + +_Returns_ + +- `Object`: Action object. + +# **closeModal** + +Returns an action object signalling that the user closed a modal. + +_Returns_ + +- `Object`: Action object. + +# **closePublishSidebar** + +Returns an action object used in signalling that the user closed the +publish sidebar. + +_Returns_ + +- `Object`: Action object. + +# **hideBlockTypes** + +Returns an action object used in signalling that block types by the given +name(s) should be hidden. + +_Parameters_ + +- _blockNames_ `Array`: Names of block types to hide. + +_Returns_ + +- `Object`: Action object. + +# **metaBoxUpdatesSuccess** + +Returns an action object used signal a successful meta box update. + +_Returns_ + +- `Object`: Action object. + +# **openGeneralSidebar** Returns an action object used in signalling that the user opened an editor sidebar. -*Parameters* +_Parameters_ - * name: Sidebar name to be opened. +- _name_ `string`: Sidebar name to be opened. -### closeGeneralSidebar +_Returns_ -Returns an action object signalling that the user closed the sidebar. +- `Object`: Action object. -### openModal +# **openModal** Returns an action object used in signalling that the user opened a modal. -*Parameters* +_Parameters_ - * name: A string that uniquely identifies the modal. +- _name_ `string`: A string that uniquely identifies the modal. -### closeModal +_Returns_ -Returns an action object signalling that the user closed a modal. +- `Object`: Action object. -### openPublishSidebar +# **openPublishSidebar** Returns an action object used in signalling that the user opened the publish sidebar. -### closePublishSidebar +_Returns_ -Returns an action object used in signalling that the user closed the -publish sidebar. +- `Object`: Action object -### togglePublishSidebar +# **removeEditorPanel** -Returns an action object used in signalling that the user toggles the publish sidebar. +Returns an action object used to remove a panel from the editor. -### toggleEditorPanelEnabled +_Parameters_ -Returns an action object used to enable or disable a panel in the editor. +- _panelName_ `string`: A string that identifies the panel to remove. -*Parameters* +_Returns_ - * panelName: A string that identifies the panel to enable or disable. +- `Object`: Action object. -### toggleEditorPanelOpened +# **requestMetaBoxUpdates** -Returns an action object used to open or close a panel in the editor. +Returns an action object used to request meta box update. -*Parameters* +_Returns_ - * panelName: A string that identifies the panel to open or close. +- `Object`: Action object. -### removeEditorPanel +# **setAvailableMetaBoxesPerLocation** -Returns an action object used to remove a panel from the editor. +Returns an action object used in signaling +what Meta boxes are available in which location. -*Parameters* +_Parameters_ - * panelName: A string that identifies the panel to remove. +- _metaBoxesPerLocation_ `Object`: Meta boxes per location. -### toggleFeature +_Returns_ -Returns an action object used to toggle a feature flag. +- `Object`: Action object. -*Parameters* +# **showBlockTypes** - * feature: Feature name. +Returns an action object used in signalling that block types by the given +name(s) should be shown. -### togglePinnedPluginItem +_Parameters_ -Returns an action object used to toggle a plugin name flag. +- _blockNames_ `Array`: Names of block types to show. -*Parameters* +_Returns_ - * pluginName: Plugin name. +- `Object`: Action object. -### hideBlockTypes +# **switchEditorMode** -Returns an action object used in signalling that block types by the given -name(s) should be hidden. +Undocumented declaration. -*Parameters* +# **toggleEditorPanelEnabled** - * blockNames: Names of block types to hide. +Returns an action object used to enable or disable a panel in the editor. -### showBlockTypes +_Parameters_ -Returns an action object used in signalling that block types by the given -name(s) should be shown. +- _panelName_ `string`: A string that identifies the panel to enable or disable. -*Parameters* +_Returns_ - * blockNames: Names of block types to show. +- `Object`: Action object. -### setAvailableMetaBoxesPerLocation +# **toggleEditorPanelOpened** -Returns an action object used in signaling -what Meta boxes are available in which location. +Returns an action object used to open or close a panel in the editor. -*Parameters* +_Parameters_ - * metaBoxesPerLocation: Meta boxes per location. +- _panelName_ `string`: A string that identifies the panel to open or close. -### requestMetaBoxUpdates +_Returns_ -Returns an action object used to request meta box update. +- `Object`: Action object. + +# **toggleFeature** + +Returns an action object used to toggle a feature flag. + +_Parameters_ + +- _feature_ `string`: Feature name. + +_Returns_ + +- `Object`: Action object. + +# **togglePinnedPluginItem** + +Returns an action object used to toggle a plugin name flag. + +_Parameters_ + +- _pluginName_ `string`: Plugin name. + +_Returns_ + +- `Object`: Action object. + +# **togglePublishSidebar** + +Returns an action object used in signalling that the user toggles the publish sidebar. + +_Returns_ -### metaBoxUpdatesSuccess +- `Object`: Action object -Returns an action object used signal a successful meta box update. \ No newline at end of file + diff --git a/docs/designers-developers/developers/data/data-core-editor.md b/docs/designers-developers/developers/data/data-core-editor.md index 8a770b01e3029..b5cc78a84c087 100644 --- a/docs/designers-developers/developers/data/data-core-editor.md +++ b/docs/designers-developers/developers/data/data-core-editor.md @@ -1,370 +1,795 @@ -# **core/editor**: The Post Editor’s Data +# The Post Editor’s Data + +Namespace: `core/editor`. ## Selectors -### hasEditorUndo + -Returns true if any past editor history snapshots exist, or false otherwise. +# **canInsertBlockType** -*Parameters* +_Related_ - * state: Global application state. +- canInsertBlockType in core/block-editor store. -### hasEditorRedo +# **canUserUseUnfilteredHTML** -Returns true if any future editor history snapshots exist, or false +Returns whether or not the user has the unfiltered_html capability. + +_Parameters_ + +- _state_ `Object`: Editor state. + +_Returns_ + +- `boolean`: Whether the user can or can't post unfiltered HTML. + +# **didPostSaveRequestFail** + +Returns true if a previous post save was attempted but failed, or false otherwise. -*Parameters* +_Parameters_ - * state: Global application state. +- _state_ `Object`: Global application state. -*Returns* +_Returns_ -Whether redo history exists. +- `boolean`: Whether the post save failed. -### isEditedPostNew +# **didPostSaveRequestSucceed** -Returns true if the currently edited post is yet to be saved, or false if -the post has been saved. +Returns true if a previous post save was attempted successfully, or false +otherwise. -*Parameters* +_Parameters_ - * state: Global application state. +- _state_ `Object`: Global application state. -*Returns* +_Returns_ -Whether the post is new. +- `boolean`: Whether the post was saved successfully. -### hasChangedContent +# **getActivePostLock** -Returns true if content includes unsaved changes, or false otherwise. +Returns the active post lock. -*Parameters* +_Parameters_ - * state: Editor state. +- _state_ `Object`: Global application state. -*Returns* +_Returns_ -Whether content includes unsaved changes. +- `Object`: The lock object. -### isEditedPostDirty +# **getAdjacentBlockClientId** -Returns true if there are unsaved values for the current edit session, or -false if the editing state matches the saved or new post. +_Related_ + +- getAdjacentBlockClientId in core/block-editor store. + +# **getAutosave** + +> **Deprecated** since 5.6. Callers should use the `getAutosave( postType, postId, userId )` selector from the '@wordpress/core-data' package. -*Parameters* +Returns the current autosave, or null if one is not set (i.e. if the post +has yet to be autosaved, or has been saved or published since the last +autosave). - * state: Global application state. +_Parameters_ -*Returns* +- _state_ `Object`: Editor state. -Whether unsaved values exist. +_Returns_ -### isCleanNewPost +- `?Object`: Current autosave, if exists. -Returns true if there are no unsaved values for the current edit session and -if the currently edited post is new (has never been saved before). +# **getAutosaveAttribute** + +> **Deprecated** since 5.6. Callers should use the `getAutosave( postType, postId, userId )` selector from the '@wordpress/core-data' package and access properties on the returned autosave object using getPostRawValue. + +Returns an attribute value of the current autosave revision for a post, or +null if there is no autosave for the post. + +_Parameters_ + +- _state_ `Object`: Global application state. +- _attributeName_ `string`: Autosave attribute name. + +_Returns_ + +- `*`: Autosave attribute value. + +# **getBlock** + +_Related_ + +- getBlock in core/block-editor store. + +# **getBlockAttributes** + +_Related_ + +- getBlockAttributes in core/block-editor store. + +# **getBlockCount** + +_Related_ + +- getBlockCount in core/block-editor store. + +# **getBlockDependantsCacheBust** + +_Related_ + +- getBlockDependantsCacheBust in core/block-editor store. + +# **getBlockHierarchyRootClientId** + +_Related_ + +- getBlockHierarchyRootClientId in core/block-editor store. + +# **getBlockIndex** + +_Related_ + +- getBlockIndex in core/block-editor store. + +# **getBlockInsertionPoint** + +_Related_ + +- getBlockInsertionPoint in core/block-editor store. + +# **getBlockListSettings** + +_Related_ -*Parameters* +- getBlockListSettings in core/block-editor store. - * state: Global application state. +# **getBlockMode** -*Returns* +_Related_ -Whether new post and unsaved values exist. +- getBlockMode in core/block-editor store. -### getCurrentPost +# **getBlockName** + +_Related_ + +- getBlockName in core/block-editor store. + +# **getBlockOrder** + +_Related_ + +- getBlockOrder in core/block-editor store. + +# **getBlockRootClientId** + +_Related_ + +- getBlockRootClientId in core/block-editor store. + +# **getBlocks** + +_Related_ + +- getBlocks in core/block-editor store. + +# **getBlocksByClientId** + +_Related_ + +- getBlocksByClientId in core/block-editor store. + +# **getBlockSelectionEnd** + +_Related_ + +- getBlockSelectionEnd in core/block-editor store. + +# **getBlockSelectionStart** + +_Related_ + +- getBlockSelectionStart in core/block-editor store. + +# **getBlocksForSerialization** + +Returns a set of blocks which are to be used in consideration of the post's +generated save content. + +_Parameters_ + +- _state_ `Object`: Editor state. + +_Returns_ + +- `Array`: Filtered set of blocks for save. + +# **getClientIdsOfDescendants** + +_Related_ + +- getClientIdsOfDescendants in core/block-editor store. + +# **getClientIdsWithDescendants** + +_Related_ + +- getClientIdsWithDescendants in core/block-editor store. + +# **getCurrentPost** Returns the post currently being edited in its last known saved state, not including unsaved edits. Returns an object containing relevant default post values if the post has not yet been saved. -*Parameters* +_Parameters_ - * state: Global application state. +- _state_ `Object`: Global application state. -*Returns* +_Returns_ -Post object. +- `Object`: Post object. -### getCurrentPostType +# **getCurrentPostAttribute** -Returns the post type of the post currently being edited. +Returns an attribute value of the saved post. -*Parameters* +_Parameters_ - * state: Global application state. +- _state_ `Object`: Global application state. +- _attributeName_ `string`: Post attribute name. -*Returns* +_Returns_ -Post type. +- `*`: Post attribute value. -### getCurrentPostId +# **getCurrentPostId** Returns the ID of the post currently being edited, or null if the post has not yet been saved. -*Parameters* +_Parameters_ + +- _state_ `Object`: Global application state. + +_Returns_ + +- `?number`: ID of current post. + +# **getCurrentPostLastRevisionId** + +Returns the last revision ID of the post currently being edited, +or null if the post has no revisions. - * state: Global application state. +_Parameters_ -*Returns* +- _state_ `Object`: Global application state. -ID of current post. +_Returns_ -### getCurrentPostRevisionsCount +- `?number`: ID of the last revision. + +# **getCurrentPostRevisionsCount** Returns the number of revisions of the post currently being edited. -*Parameters* +_Parameters_ - * state: Global application state. +- _state_ `Object`: Global application state. -*Returns* +_Returns_ -Number of revisions. +- `number`: Number of revisions. -### getCurrentPostLastRevisionId +# **getCurrentPostType** -Returns the last revision ID of the post currently being edited, -or null if the post has no revisions. +Returns the post type of the post currently being edited. + +_Parameters_ + +- _state_ `Object`: Global application state. + +_Returns_ + +- `string`: Post type. + +# **getEditedPostAttribute** + +Returns a single attribute of the post being edited, preferring the unsaved +edit if one exists, but falling back to the attribute for the last known +saved state of the post. + +_Parameters_ -*Parameters* +- _state_ `Object`: Global application state. +- _attributeName_ `string`: Post attribute name. - * state: Global application state. +_Returns_ -*Returns* +- `*`: Post attribute value. -ID of the last revision. +# **getEditedPostContent** -### getPostEdits +Returns the content of the post being edited, preferring raw string edit +before falling back to serialization of block state. + +_Parameters_ + +- _state_ `Object`: Global application state. + +_Returns_ + +- `string`: Post content. + +# **getEditedPostPreviewLink** + +Returns the post preview link + +_Parameters_ + +- _state_ `Object`: Global application state. + +_Returns_ + +- `?string`: Preview Link. + +# **getEditedPostVisibility** + +Returns the current visibility of the post being edited, preferring the +unsaved value if different than the saved post. The return value is one of +"private", "password", or "public". + +_Parameters_ + +- _state_ `Object`: Global application state. + +_Returns_ + +- `string`: Post visibility. + +# **getEditorBlocks** + +Return the current block list. + +_Parameters_ + +- _state_ `Object`: + +_Returns_ + +- `Array`: Block list. + +# **getEditorSettings** + +Returns the post editor settings. + +_Parameters_ + +- _state_ `Object`: Editor state. + +_Returns_ + +- `Object`: The editor settings object. + +# **getFirstMultiSelectedBlockClientId** + +_Related_ + +- getFirstMultiSelectedBlockClientId in core/block-editor store. + +# **getGlobalBlockCount** + +_Related_ + +- getGlobalBlockCount in core/block-editor store. + +# **getInserterItems** + +_Related_ + +- getInserterItems in core/block-editor store. + +# **getLastMultiSelectedBlockClientId** + +_Related_ + +- getLastMultiSelectedBlockClientId in core/block-editor store. + +# **getMultiSelectedBlockClientIds** + +_Related_ + +- getMultiSelectedBlockClientIds in core/block-editor store. + +# **getMultiSelectedBlocks** + +_Related_ + +- getMultiSelectedBlocks in core/block-editor store. + +# **getMultiSelectedBlocksEndClientId** + +_Related_ + +- getMultiSelectedBlocksEndClientId in core/block-editor store. + +# **getMultiSelectedBlocksStartClientId** + +_Related_ + +- getMultiSelectedBlocksStartClientId in core/block-editor store. + +# **getNextBlockClientId** + +_Related_ + +- getNextBlockClientId in core/block-editor store. + +# **getPermalink** + +Returns the permalink for the post. + +_Parameters_ + +- _state_ `Object`: Editor state. + +_Returns_ + +- `?string`: The permalink, or null if the post is not viewable. + +# **getPermalinkParts** + +Returns the permalink for a post, split into it's three parts: the prefix, +the postName, and the suffix. + +_Parameters_ + +- _state_ `Object`: Editor state. + +_Returns_ + +- `Object`: An object containing the prefix, postName, and suffix for the permalink, or null if the post is not viewable. + +# **getPostEdits** Returns any post values which have been changed in the editor but not yet been saved. -*Parameters* +_Parameters_ + +- _state_ `Object`: Global application state. + +_Returns_ + +- `Object`: Object of key value pairs comprising unsaved edits. + +# **getPostLockUser** + +Returns details about the post lock user. + +_Parameters_ + +- _state_ `Object`: Global application state. - * state: Global application state. +_Returns_ -*Returns* +- `Object`: A user object. -Object of key value pairs comprising unsaved edits. +# **getPreviousBlockClientId** -### getReferenceByDistinctEdits +_Related_ + +- getPreviousBlockClientId in core/block-editor store. + +# **getReferenceByDistinctEdits** Returns a new reference when edited values have changed. This is useful in inferring where an edit has been made between states by comparison of the return values using strict equality. -*Parameters* +_Usage_ - * state: Editor state. + const hasEditOccurred = ( + getReferenceByDistinctEdits( beforeState ) !== + getReferenceByDistinctEdits( afterState ) + ); -*Returns* +_Parameters_ -A value whose reference will change only when an edit occurs. +- _state_ `Object`: Editor state. -### getCurrentPostAttribute +_Returns_ -Returns an attribute value of the saved post. +- `*`: A value whose reference will change only when an edit occurs. -*Parameters* +# **getSelectedBlock** - * state: Global application state. - * attributeName: Post attribute name. +_Related_ -*Returns* +- getSelectedBlock in core/block-editor store. -Post attribute value. +# **getSelectedBlockClientId** -### getEditedPostAttribute +_Related_ -Returns a single attribute of the post being edited, preferring the unsaved -edit if one exists, but falling back to the attribute for the last known -saved state of the post. +- getSelectedBlockClientId in core/block-editor store. -*Parameters* +# **getSelectedBlockCount** - * state: Global application state. - * attributeName: Post attribute name. +_Related_ -*Returns* +- getSelectedBlockCount in core/block-editor store. -Post attribute value. +# **getSelectedBlocksInitialCaretPosition** -### getAutosaveAttribute (deprecated) +_Related_ -Returns an attribute value of the current autosave revision for a post, or -null if there is no autosave for the post. +- getSelectedBlocksInitialCaretPosition in core/block-editor store. -*Deprecated* +# **getStateBeforeOptimisticTransaction** -Deprecated since 5.6. Callers should use the `getAutosave( postType, postId, userId )` selector - from the '@wordpress/core-data' package and access properties on the returned - autosave object using getPostRawValue. +Returns state object prior to a specified optimist transaction ID, or `null` +if the transaction corresponding to the given ID cannot be found. -*Parameters* +_Parameters_ - * state: Global application state. - * attributeName: Autosave attribute name. +- _state_ `Object`: Current global application state. +- _transactionId_ `Object`: Optimist transaction ID. -*Returns* +_Returns_ -Autosave attribute value. +- `Object`: Global application state prior to transaction. -### getEditedPostVisibility +# **getSuggestedPostFormat** -Returns the current visibility of the post being edited, preferring the -unsaved value if different than the saved post. The return value is one of -"private", "password", or "public". +Returns a suggested post format for the current post, inferred only if there +is a single block within the post and it is of a type known to match a +default post format. Returns null if the format cannot be determined. -*Parameters* +_Parameters_ - * state: Global application state. +- _state_ `Object`: Global application state. -*Returns* +_Returns_ -Post visibility. +- `?string`: Suggested post format. -### isCurrentPostPending +# **getTemplate** -Returns true if post is pending review. +_Related_ -*Parameters* +- getTemplate in core/block-editor store. - * state: Global application state. +# **getTemplateLock** -*Returns* +_Related_ -Whether current post is pending review. +- getTemplateLock in core/block-editor store. -### isCurrentPostPublished +# **hasAutosave** -Return true if the current post has already been published. +> **Deprecated** since 5.6. Callers should use the `getAutosave( postType, postId, userId )` selector from the '@wordpress/core-data' package and check for a truthy value. -*Parameters* +Returns the true if there is an existing autosave, otherwise false. - * state: Global application state. +_Parameters_ -*Returns* +- _state_ `Object`: Global application state. -Whether the post has been published. +_Returns_ -### isCurrentPostScheduled +- `boolean`: Whether there is an existing autosave. -Returns true if post is already scheduled. +# **hasChangedContent** -*Parameters* +Returns true if content includes unsaved changes, or false otherwise. - * state: Global application state. +_Parameters_ -*Returns* +- _state_ `Object`: Editor state. -Whether current post is scheduled to be posted. +_Returns_ -### isEditedPostPublishable +- `boolean`: Whether content includes unsaved changes. -Return true if the post being edited can be published. +# **hasEditorRedo** -*Parameters* +Returns true if any future editor history snapshots exist, or false +otherwise. - * state: Global application state. +_Parameters_ -*Returns* +- _state_ `Object`: Global application state. -Whether the post can been published. +_Returns_ -### isEditedPostSaveable +- `boolean`: Whether redo history exists. -Returns true if the post can be saved, or false otherwise. A post must -contain a title, an excerpt, or non-empty content to be valid for save. +# **hasEditorUndo** -*Parameters* +Returns true if any past editor history snapshots exist, or false otherwise. - * state: Global application state. +_Parameters_ -*Returns* +- _state_ `Object`: Global application state. -Whether the post can be saved. +_Returns_ -### isEditedPostEmpty +- `boolean`: Whether undo history exists. -Returns true if the edited post has content. A post has content if it has at -least one saveable block or otherwise has a non-empty content property -assigned. +# **hasInserterItems** -*Parameters* +_Related_ - * state: Global application state. +- hasInserterItems in core/block-editor store. -*Returns* +# **hasMultiSelection** -Whether post has content. +_Related_ -### isEditedPostAutosaveable +- hasMultiSelection in core/block-editor store. -Returns true if the post can be autosaved, or false otherwise. +# **hasSelectedBlock** -*Parameters* +_Related_ - * state: Global application state. - * autosave: A raw autosave object from the REST API. +- hasSelectedBlock in core/block-editor store. -*Returns* +# **hasSelectedInnerBlock** -Whether the post can be autosaved. +_Related_ -### getAutosave (deprecated) +- hasSelectedInnerBlock in core/block-editor store. -Returns the current autosave, or null if one is not set (i.e. if the post -has yet to be autosaved, or has been saved or published since the last -autosave). +# **inSomeHistory** -*Deprecated* +Returns true if an optimistic transaction is pending commit, for which the +before state satisfies the given predicate function. -Deprecated since 5.6. Callers should use the `getAutosave( postType, postId, userId )` - selector from the '@wordpress/core-data' package. +_Parameters_ -*Parameters* +- _state_ `Object`: Editor state. +- _predicate_ `Function`: Function given state, returning true if match. - * state: Editor state. +_Returns_ -*Returns* +- `boolean`: Whether predicate matches for some history. -Current autosave, if exists. +# **isAncestorMultiSelected** -### hasAutosave (deprecated) +_Related_ -Returns the true if there is an existing autosave, otherwise false. +- isAncestorMultiSelected in core/block-editor store. + +# **isAutosavingPost** + +Returns true if the post is autosaving, or false otherwise. + +_Parameters_ + +- _state_ `Object`: Global application state. + +_Returns_ + +- `boolean`: Whether the post is autosaving. + +# **isBlockInsertionPointVisible** + +_Related_ + +- isBlockInsertionPointVisible in core/block-editor store. + +# **isBlockMultiSelected** + +_Related_ + +- isBlockMultiSelected in core/block-editor store. + +# **isBlockSelected** + +_Related_ + +- isBlockSelected in core/block-editor store. + +# **isBlockValid** + +_Related_ + +- isBlockValid in core/block-editor store. + +# **isBlockWithinSelection** + +_Related_ + +- isBlockWithinSelection in core/block-editor store. + +# **isCaretWithinFormattedText** + +_Related_ + +- isCaretWithinFormattedText in core/block-editor store. + +# **isCleanNewPost** + +Returns true if there are no unsaved values for the current edit session and +if the currently edited post is new (has never been saved before). + +_Parameters_ + +- _state_ `Object`: Global application state. + +_Returns_ + +- `boolean`: Whether new post and unsaved values exist. + +# **isCurrentPostPending** + +Returns true if post is pending review. + +_Parameters_ + +- _state_ `Object`: Global application state. + +_Returns_ + +- `boolean`: Whether current post is pending review. + +# **isCurrentPostPublished** + +Return true if the current post has already been published. + +_Parameters_ + +- _state_ `Object`: Global application state. + +_Returns_ + +- `boolean`: Whether the post has been published. + +# **isCurrentPostScheduled** + +Returns true if post is already scheduled. -*Deprecated* +_Parameters_ -Deprecated since 5.6. Callers should use the `getAutosave( postType, postId, userId )` selector - from the '@wordpress/core-data' package and check for a truthy value. +- _state_ `Object`: Global application state. -*Parameters* +_Returns_ - * state: Global application state. +- `boolean`: Whether current post is scheduled to be posted. -*Returns* +# **isEditedPostAutosaveable** -Whether there is an existing autosave. +Returns true if the post can be autosaved, or false otherwise. + +_Parameters_ + +- _state_ `Object`: Global application state. +- _autosave_ `Object`: A raw autosave object from the REST API. + +_Returns_ -### isEditedPostBeingScheduled +- `boolean`: Whether the post can be autosaved. + +# **isEditedPostBeingScheduled** Return true if the post being edited is being scheduled. Preferring the unsaved status values. -*Parameters* +_Parameters_ - * state: Global application state. +- _state_ `Object`: Global application state. -*Returns* +_Returns_ -Whether the post has been published. +- `boolean`: Whether the post has been published. -### isEditedPostDateFloating +# **isEditedPostDateFloating** Returns whether the current post should be considered to have a "floating" date (i.e. that it would publish "Immediately" rather than at a set time). @@ -374,463 +799,590 @@ where the 0000-00-00T00:00:00 placeholder is present in the database. To infer that a post is set to publish "Immediately" we check whether the date and modified date are the same. -*Parameters* +_Parameters_ - * state: Editor state. +- _state_ `Object`: Editor state. -*Returns* +_Returns_ -Whether the edited post has a floating date value. +- `boolean`: Whether the edited post has a floating date value. -### isSavingPost +# **isEditedPostDirty** -Returns true if the post is currently being saved, or false otherwise. +Returns true if there are unsaved values for the current edit session, or +false if the editing state matches the saved or new post. -*Parameters* +_Parameters_ - * state: Global application state. +- _state_ `Object`: Global application state. -*Returns* +_Returns_ -Whether post is being saved. +- `boolean`: Whether unsaved values exist. -### didPostSaveRequestSucceed +# **isEditedPostEmpty** -Returns true if a previous post save was attempted successfully, or false -otherwise. +Returns true if the edited post has content. A post has content if it has at +least one saveable block or otherwise has a non-empty content property +assigned. -*Parameters* +_Parameters_ - * state: Global application state. +- _state_ `Object`: Global application state. -*Returns* +_Returns_ -Whether the post was saved successfully. +- `boolean`: Whether post has content. -### didPostSaveRequestFail +# **isEditedPostNew** -Returns true if a previous post save was attempted but failed, or false -otherwise. +Returns true if the currently edited post is yet to be saved, or false if +the post has been saved. -*Parameters* +_Parameters_ - * state: Global application state. +- _state_ `Object`: Global application state. -*Returns* +_Returns_ -Whether the post save failed. +- `boolean`: Whether the post is new. -### isAutosavingPost +# **isEditedPostPublishable** -Returns true if the post is autosaving, or false otherwise. +Return true if the post being edited can be published. -*Parameters* +_Parameters_ - * state: Global application state. +- _state_ `Object`: Global application state. -*Returns* +_Returns_ -Whether the post is autosaving. +- `boolean`: Whether the post can been published. -### isPreviewingPost +# **isEditedPostSaveable** -Returns true if the post is being previewed, or false otherwise. +Returns true if the post can be saved, or false otherwise. A post must +contain a title, an excerpt, or non-empty content to be valid for save. -*Parameters* +_Parameters_ - * state: Global application state. +- _state_ `Object`: Global application state. -*Returns* +_Returns_ -Whether the post is being previewed. +- `boolean`: Whether the post can be saved. -### getEditedPostPreviewLink +# **isFirstMultiSelectedBlock** -Returns the post preview link +_Related_ -*Parameters* +- isFirstMultiSelectedBlock in core/block-editor store. - * state: Global application state. +# **isMultiSelecting** -*Returns* +_Related_ -Preview Link. +- isMultiSelecting in core/block-editor store. -### getSuggestedPostFormat +# **isPermalinkEditable** -Returns a suggested post format for the current post, inferred only if there -is a single block within the post and it is of a type known to match a -default post format. Returns null if the format cannot be determined. +Returns whether the permalink is editable or not. -*Parameters* +_Parameters_ - * state: Global application state. +- _state_ `Object`: Editor state. -*Returns* +_Returns_ -Suggested post format. +- `boolean`: Whether or not the permalink is editable. -### getBlocksForSerialization +# **isPostLocked** -Returns a set of blocks which are to be used in consideration of the post's -generated save content. +Returns whether the post is locked. -*Parameters* +_Parameters_ - * state: Editor state. +- _state_ `Object`: Global application state. -*Returns* +_Returns_ -Filtered set of blocks for save. +- `boolean`: Is locked. -### getEditedPostContent +# **isPostLockTakeover** -Returns the content of the post being edited, preferring raw string edit -before falling back to serialization of block state. +Returns whether the edition of the post has been taken over. -*Parameters* +_Parameters_ - * state: Global application state. +- _state_ `Object`: Global application state. -*Returns* +_Returns_ -Post content. +- `boolean`: Is post lock takeover. -### getStateBeforeOptimisticTransaction +# **isPostSavingLocked** -Returns state object prior to a specified optimist transaction ID, or `null` -if the transaction corresponding to the given ID cannot be found. +Returns whether post saving is locked. -*Parameters* +_Parameters_ - * state: Current global application state. - * transactionId: Optimist transaction ID. +- _state_ `Object`: Global application state. -*Returns* +_Returns_ -Global application state prior to transaction. +- `boolean`: Is locked. -### isPublishingPost +# **isPreviewingPost** + +Returns true if the post is being previewed, or false otherwise. + +_Parameters_ + +- _state_ `Object`: Global application state. + +_Returns_ + +- `boolean`: Whether the post is being previewed. + +# **isPublishingPost** Returns true if the post is being published, or false otherwise. -*Parameters* +_Parameters_ - * state: Global application state. +- _state_ `Object`: Global application state. -*Returns* +_Returns_ -Whether post is being published. +- `boolean`: Whether post is being published. -### isPermalinkEditable +# **isPublishSidebarEnabled** -Returns whether the permalink is editable or not. +Returns whether the pre-publish panel should be shown +or skipped when the user clicks the "publish" button. -*Parameters* +_Parameters_ - * state: Editor state. +- _state_ `Object`: Global application state. -*Returns* +_Returns_ -Whether or not the permalink is editable. +- `boolean`: Whether the pre-publish panel should be shown or not. -### getPermalink +# **isSavingPost** -Returns the permalink for the post. +Returns true if the post is currently being saved, or false otherwise. -*Parameters* +_Parameters_ - * state: Editor state. +- _state_ `Object`: Global application state. -*Returns* +_Returns_ -The permalink, or null if the post is not viewable. +- `boolean`: Whether post is being saved. -### getPermalinkParts +# **isSelectionEnabled** -Returns the permalink for a post, split into it's three parts: the prefix, -the postName, and the suffix. +_Related_ -*Parameters* +- isSelectionEnabled in core/block-editor store. - * state: Editor state. +# **isTyping** -*Returns* +_Related_ -An object containing the prefix, postName, and suffix for - the permalink, or null if the post is not viewable. +- isTyping in core/block-editor store. -### inSomeHistory +# **isValidTemplate** -Returns true if an optimistic transaction is pending commit, for which the -before state satisfies the given predicate function. +_Related_ -*Parameters* +- isValidTemplate in core/block-editor store. - * state: Editor state. - * predicate: Function given state, returning true if match. -*Returns* + -Whether predicate matches for some history. +## Actions -### isPostLocked + -Returns whether the post is locked. +# **autosave** -*Parameters* +Action generator used in signalling that the post should autosave. - * state: Global application state. +_Parameters_ -*Returns* +- _options_ `?Object`: Extra flags to identify the autosave. -Is locked. +# **clearSelectedBlock** -### isPostSavingLocked +_Related_ -Returns whether post saving is locked. +- clearSelectedBlock in core/block-editor store. + +# **createUndoLevel** + +Returns an action object used in signalling that undo history record should +be created. -*Parameters* +_Returns_ - * state: Global application state. +- `Object`: Action object. -*Returns* +# **disablePublishSidebar** -Is locked. +Returns an action object used in signalling that the user has disabled the +publish sidebar. -### isPostLockTakeover +_Returns_ -Returns whether the edition of the post has been taken over. +- `Object`: Action object -*Parameters* +# **editPost** - * state: Global application state. +Returns an action object used in signalling that attributes of the post have +been edited. -*Returns* +_Parameters_ -Is post lock takeover. +- _edits_ `Object`: Post attributes to edit. -### getPostLockUser +_Returns_ -Returns details about the post lock user. +- `Object`: Action object. -*Parameters* +# **enablePublishSidebar** - * state: Global application state. +Returns an action object used in signalling that the user has enabled the +publish sidebar. -*Returns* +_Returns_ -A user object. +- `Object`: Action object -### getActivePostLock +# **enterFormattedText** -Returns the active post lock. +_Related_ -*Parameters* +- enterFormattedText in core/block-editor store. - * state: Global application state. +# **exitFormattedText** -*Returns* +_Related_ -The lock object. +- exitFormattedText in core/block-editor store. -### canUserUseUnfilteredHTML +# **hideInsertionPoint** -Returns whether or not the user has the unfiltered_html capability. +_Related_ -*Parameters* +- hideInsertionPoint in core/block-editor store. - * state: Editor state. +# **insertBlock** -*Returns* +_Related_ -Whether the user can or can't post unfiltered HTML. +- insertBlock in core/block-editor store. -### isPublishSidebarEnabled +# **insertBlocks** -Returns whether the pre-publish panel should be shown -or skipped when the user clicks the "publish" button. +_Related_ -*Parameters* +- insertBlocks in core/block-editor store. - * state: Global application state. +# **insertDefaultBlock** -*Returns* +_Related_ -Whether the pre-publish panel should be shown or not. +- insertDefaultBlock in core/block-editor store. -### getEditorBlocks +# **lockPostSaving** -Return the current block list. +Returns an action object used to signal that post saving is locked. -*Parameters* +_Parameters_ - * state: null +- _lockName_ `string`: The lock name. -*Returns* +_Returns_ -Block list. +- `Object`: Action object -### getEditorSettings +# **mergeBlocks** -Returns the post editor settings. +_Related_ -*Parameters* +- mergeBlocks in core/block-editor store. - * state: Editor state. +# **moveBlocksDown** -*Returns* +_Related_ -The editor settings object. +- moveBlocksDown in core/block-editor store. -## Actions +# **moveBlocksUp** -### setupEditor +_Related_ -Returns an action generator used in signalling that editor has initialized with -the specified post object and editor settings. +- moveBlocksUp in core/block-editor store. -*Parameters* +# **moveBlockToPosition** - * post: Post object. - * edits: Initial edited attributes object. - * template: Block Template. +_Related_ -### resetPost +- moveBlockToPosition in core/block-editor store. -Returns an action object used in signalling that the latest version of the -post has been received, either by initialization or save. +# **multiSelect** + +_Related_ + +- multiSelect in core/block-editor store. + +# **receiveBlocks** + +_Related_ + +- receiveBlocks in core/block-editor store. + +# **redo** + +Returns an action object used in signalling that undo history should +restore last popped state. + +_Returns_ + +- `Object`: Action object. + +# **refreshPost** + +Action generator for handling refreshing the current post. + +# **removeBlock** + +_Related_ + +- removeBlock in core/block-editor store. + +# **removeBlocks** + +_Related_ + +- removeBlocks in core/block-editor store. + +# **replaceBlocks** + +_Related_ -*Parameters* +- replaceBlocks in core/block-editor store. - * post: Post object. +# **resetAutosave** -### resetAutosave (deprecated) +> **Deprecated** since 5.6. Callers should use the `receiveAutosaves( postId, autosave )` selector from the '@wordpress/core-data' package. Returns an action object used in signalling that the latest autosave of the post has been received, by initialization or autosave. -*Deprecated* +_Parameters_ -Deprecated since 5.6. Callers should use the `receiveAutosaves( postId, autosave )` - selector from the '@wordpress/core-data' package. +- _newAutosave_ `Object`: Autosave post object. -*Parameters* +_Returns_ - * newAutosave: Autosave post object. +- `Object`: Action object. -### updatePost +# **resetBlocks** -Returns an action object used in signalling that a patch of updates for the -latest version of the post have been received. +_Related_ + +- resetBlocks in core/block-editor store. + +# **resetEditorBlocks** + +Returns an action object used to signal that the blocks have been updated. + +_Parameters_ + +- _blocks_ `Array`: Block Array. +- _options_ `?Object`: Optional options. + +_Returns_ + +- `Object`: Action object + +# **resetPost** + +Returns an action object used in signalling that the latest version of the +post has been received, either by initialization or save. -*Parameters* +_Parameters_ - * edits: Updated post fields. +- _post_ `Object`: Post object. -### setupEditorState +_Returns_ + +- `Object`: Action object. + +# **savePost** + +Action generator for saving the current post in the editor. + +_Parameters_ + +- _options_ `Object`: + +# **selectBlock** + +_Related_ + +- selectBlock in core/block-editor store. + +# **setTemplateValidity** + +_Related_ + +- setTemplateValidity in core/block-editor store. + +# **setupEditor** + +Returns an action generator used in signalling that editor has initialized with +the specified post object and editor settings. + +_Parameters_ + +- _post_ `Object`: Post object. +- _edits_ `Object`: Initial edited attributes object. +- _template_ `?Array`: Block Template. + +# **setupEditorState** Returns an action object used to setup the editor state when first opening an editor. -*Parameters* +_Parameters_ - * post: Post object. +- _post_ `Object`: Post object. -### editPost +_Returns_ -Returns an action object used in signalling that attributes of the post have -been edited. +- `Object`: Action object. -*Parameters* +# **showInsertionPoint** - * edits: Post attributes to edit. +_Related_ -### savePost +- showInsertionPoint in core/block-editor store. -Action generator for saving the current post in the editor. +# **startMultiSelect** -*Parameters* +_Related_ - * options: null +- startMultiSelect in core/block-editor store. -### refreshPost +# **startTyping** -Action generator for handling refreshing the current post. +_Related_ -### trashPost +- startTyping in core/block-editor store. -Action generator for trashing the current post in the editor. +# **stopMultiSelect** -### autosave +_Related_ -Action generator used in signalling that the post should autosave. +- stopMultiSelect in core/block-editor store. -*Parameters* +# **stopTyping** - * options: Extra flags to identify the autosave. +_Related_ -### redo +- stopTyping in core/block-editor store. -Returns an action object used in signalling that undo history should -restore last popped state. +# **synchronizeTemplate** + +_Related_ + +- synchronizeTemplate in core/block-editor store. -### undo +# **toggleBlockMode** + +_Related_ + +- toggleBlockMode in core/block-editor store. + +# **toggleSelection** + +_Related_ + +- toggleSelection in core/block-editor store. + +# **trashPost** + +Action generator for trashing the current post in the editor. + +# **undo** Returns an action object used in signalling that undo history should pop. -### createUndoLevel +_Returns_ -Returns an action object used in signalling that undo history record should -be created. +- `Object`: Action object. -### updatePostLock +# **unlockPostSaving** -Returns an action object used to lock the editor. +Returns an action object used to signal that post saving is unlocked. -*Parameters* +_Parameters_ - * lock: Details about the post lock status, user, and nonce. +- _lockName_ `string`: The lock name. -### enablePublishSidebar +_Returns_ -Returns an action object used in signalling that the user has enabled the -publish sidebar. +- `Object`: Action object -### disablePublishSidebar +# **updateBlock** -Returns an action object used in signalling that the user has disabled the -publish sidebar. +_Related_ -### lockPostSaving +- updateBlock in core/block-editor store. -Returns an action object used to signal that post saving is locked. +# **updateBlockAttributes** -*Parameters* +_Related_ - * lockName: The lock name. +- updateBlockAttributes in core/block-editor store. -### unlockPostSaving +# **updateBlockListSettings** -Returns an action object used to signal that post saving is unlocked. +_Related_ -*Parameters* +- updateBlockListSettings in core/block-editor store. - * lockName: The lock name. +# **updateEditorSettings** -### resetEditorBlocks +Undocumented declaration. -Returns an action object used to signal that the blocks have been updated. +# **updatePost** + +Returns an action object used in signalling that a patch of updates for the +latest version of the post have been received. + +_Parameters_ + +- _edits_ `Object`: Updated post fields. + +_Returns_ -*Parameters* +- `Object`: Action object. + +# **updatePostLock** + +Returns an action object used to lock the editor. - * blocks: Block Array. - * options: Optional options. +_Parameters_ -### updateEditorSettings +- _lock_ `Object`: Details about the post lock status, user, and nonce. -Returns an action object used in signalling that the post editor settings have been updated. +_Returns_ -*Parameters* +- `Object`: Action object. - * settings: Updated settings \ No newline at end of file + diff --git a/docs/designers-developers/developers/data/data-core-notices.md b/docs/designers-developers/developers/data/data-core-notices.md index 5ae7f1fb00067..bb8d4c0e14081 100644 --- a/docs/designers-developers/developers/data/data-core-notices.md +++ b/docs/designers-developers/developers/data/data-core-notices.md @@ -1,91 +1,130 @@ -# **core/notices**: Notices Data +# Notices Data + +Namespace: `core/notices`. ## Selectors -### getNotices + + +# **getNotices** Returns all notices as an array, optionally for a given context. Defaults to the global context. -*Parameters* +_Parameters_ - * state: Notices state. - * context: Optional grouping context. +- _state_ `Object`: Notices state. +- _context_ `?string`: Optional grouping context. -## Actions +_Returns_ -### createNotice +- `Array`: Array of notices. -Yields action objects used in signalling that a notice is to be created. -*Parameters* - - * status: Notice status. - Defaults to `info`. - * content: Notice message. - * options: Notice options. - * options.context: Context under which to - group notice. - * options.id: Identifier for notice. - Automatically assigned - if not specified. - * options.isDismissible: Whether the notice can - be dismissed by user. - Defaults to `true`. - * options.speak: Whether the notice - content should be - announced to screen - readers. Defaults to - `true`. - * options.actions: User actions to be - presented with notice. - -### createSuccessNotice + -Returns an action object used in signalling that a success notice is to be +## Actions + + + +# **createErrorNotice** + +Returns an action object used in signalling that an error notice is to be created. Refer to `createNotice` for options documentation. -*Parameters* +_Related_ + +- createNotice + +_Parameters_ + +- _content_ `string`: Notice message. +- _options_ `?Object`: Optional notice options. + +_Returns_ - * content: Notice message. - * options: Optional notice options. +- `Object`: Action object. -### createInfoNotice +# **createInfoNotice** Returns an action object used in signalling that an info notice is to be created. Refer to `createNotice` for options documentation. -*Parameters* +_Related_ - * content: Notice message. - * options: Optional notice options. +- createNotice -### createErrorNotice +_Parameters_ -Returns an action object used in signalling that an error notice is to be +- _content_ `string`: Notice message. +- _options_ `?Object`: Optional notice options. + +_Returns_ + +- `Object`: Action object. + +# **createNotice** + +Yields action objects used in signalling that a notice is to be created. + +_Parameters_ + +- _status_ `?string`: Notice status. Defaults to `info`. +- _content_ `string`: Notice message. +- _options_ `?Object`: Notice options. +- _options.context_ `?string`: Context under which to group notice. +- _options.id_ `?string`: Identifier for notice. Automatically assigned if not specified. +- _options.isDismissible_ `?boolean`: Whether the notice can be dismissed by user. Defaults to `true`. +- _options.speak_ `?boolean`: Whether the notice content should be announced to screen readers. Defaults to `true`. +- _options.actions_ `?Array`: User actions to be presented with notice. + +# **createSuccessNotice** + +Returns an action object used in signalling that a success notice is to be created. Refer to `createNotice` for options documentation. -*Parameters* +_Related_ + +- createNotice + +_Parameters_ - * content: Notice message. - * options: Optional notice options. +- _content_ `string`: Notice message. +- _options_ `?Object`: Optional notice options. -### createWarningNotice +_Returns_ + +- `Object`: Action object. + +# **createWarningNotice** Returns an action object used in signalling that a warning notice is to be created. Refer to `createNotice` for options documentation. -*Parameters* +_Related_ + +- createNotice + +_Parameters_ + +- _content_ `string`: Notice message. +- _options_ `?Object`: Optional notice options. - * content: Notice message. - * options: Optional notice options. +_Returns_ -### removeNotice +- `Object`: Action object. + +# **removeNotice** Returns an action object used in signalling that a notice is to be removed. -*Parameters* +_Parameters_ + +- _id_ `string`: Notice unique identifier. +- _context_ `?string`: Optional context (grouping) in which the notice is intended to appear. Defaults to default context. + +_Returns_ + +- `Object`: Action object. - * id: Notice unique identifier. - * context: Optional context (grouping) in which the notice is - intended to appear. Defaults to default context. \ No newline at end of file + diff --git a/docs/designers-developers/developers/data/data-core-nux.md b/docs/designers-developers/developers/data/data-core-nux.md index 51f1219f994a9..e937601ec864b 100644 --- a/docs/designers-developers/developers/data/data-core-nux.md +++ b/docs/designers-developers/developers/data/data-core-nux.md @@ -1,69 +1,100 @@ -# **core/nux**: The NUX (New User Experience) Data +# The NUX (New User Experience) Data + +Namespace: `core/nux`. ## Selectors -### getAssociatedGuide + + +# **areTipsEnabled** + +Returns whether or not tips are globally enabled. + +_Parameters_ + +- _state_ `Object`: Global application state. + +_Returns_ + +- `boolean`: Whether tips are globally enabled. + +# **getAssociatedGuide** Returns an object describing the guide, if any, that the given tip is a part of. -*Parameters* +_Parameters_ + +- _state_ `Object`: Global application state. +- _tipId_ `string`: The tip to query. - * state: Global application state. - * tipId: The tip to query. +_Returns_ -### isTipVisible +- `?NUX.GuideInfo`: Information about the associated guide. + +# **isTipVisible** Determines whether or not the given tip is showing. Tips are hidden if they are disabled, have been dismissed, or are not the current tip in any guide that they have been added to. -*Parameters* +_Parameters_ - * state: Global application state. - * tipId: The tip to query. +- _state_ `Object`: Global application state. +- _tipId_ `string`: The tip to query. -*Returns* +_Returns_ -Whether or not the given tip is showing. +- `boolean`: Whether or not the given tip is showing. -### areTipsEnabled -Returns whether or not tips are globally enabled. + -*Parameters* +## Actions - * state: Global application state. + -*Returns* +# **disableTips** -Whether tips are globally enabled. +Returns an action object that, when dispatched, prevents all tips from +showing again. -## Actions +_Returns_ -### triggerGuide +- `Object`: Action object. -Returns an action object that, when dispatched, presents a guide that takes -the user through a series of tips step by step. +# **dismissTip** -*Parameters* +Returns an action object that, when dispatched, dismisses the given tip. A +dismissed tip will not show again. - * tipIds: Which tips to show in the guide. +_Parameters_ -### dismissTip +- _id_ `string`: The tip to dismiss. -Returns an action object that, when dispatched, dismisses the given tip. A -dismissed tip will not show again. +_Returns_ -*Parameters* +- `Object`: Action object. - * id: The tip to dismiss. +# **enableTips** -### disableTips +Returns an action object that, when dispatched, makes all tips show again. -Returns an action object that, when dispatched, prevents all tips from -showing again. +_Returns_ + +- `Object`: Action object. + +# **triggerGuide** + +Returns an action object that, when dispatched, presents a guide that takes +the user through a series of tips step by step. + +_Parameters_ + +- _tipIds_ `Array`: Which tips to show in the guide. + +_Returns_ -### enableTips +- `Object`: Action object. -Returns an action object that, when dispatched, makes all tips show again. \ No newline at end of file + diff --git a/docs/designers-developers/developers/data/data-core-viewport.md b/docs/designers-developers/developers/data/data-core-viewport.md index c294c7f346850..b8f133834ec59 100644 --- a/docs/designers-developers/developers/data/data-core-viewport.md +++ b/docs/designers-developers/developers/data/data-core-viewport.md @@ -1,25 +1,50 @@ -# **core/viewport**: The Viewport Data +# The Viewport Data + +Namespace: `core/viewport`. ## Selectors -### isViewportMatch + + +# **isViewportMatch** Returns true if the viewport matches the given query, or false otherwise. -*Parameters* +_Usage_ + +```js +isViewportMatch( state, '< huge' ); +isViewPortMatch( state, 'medium' ); +``` + +_Parameters_ + +- _state_ `Object`: Viewport state object. +- _query_ `string`: Query string. Includes operator and breakpoint name, space separated. Operator defaults to >=. + +_Returns_ - * state: Viewport state object. - * query: Query string. Includes operator and breakpoint name, - space separated. Operator defaults to >=. +- `boolean`: Whether viewport matches query. + + + ## Actions -### setIsMatching + + +# **setIsMatching** Returns an action object used in signalling that viewport queries have been updated. Values are specified as an object of breakpoint query keys where value represents whether query matches. -*Parameters* +_Parameters_ + +- _values_ `Object`: Breakpoint query matches. + +_Returns_ + +- `Object`: Action object. - * values: Breakpoint query matches. \ No newline at end of file + diff --git a/docs/designers-developers/developers/data/data-core.md b/docs/designers-developers/developers/data/data-core.md index 57308660d4d63..3f823475fcca1 100644 --- a/docs/designers-developers/developers/data/data-core.md +++ b/docs/designers-developers/developers/data/data-core.md @@ -1,335 +1,385 @@ -# **core**: WordPress Core Data +# WordPress Core Data + +Namespace: `core`. ## Selectors -### isRequestingEmbedPreview + -Returns true if a request is in progress for embed preview data, or false -otherwise. +# **canUser** + +Returns whether the current user can perform the given action on the given +REST resource. + +Calling this may trigger an OPTIONS request to the REST API via the +`canUser()` resolver. + + + +_Parameters_ -*Parameters* +- _state_ `Object`: Data state. +- _action_ `string`: Action to check. One of: 'create', 'read', 'update', 'delete'. +- _resource_ `string`: REST resource to check, e.g. 'media' or 'posts'. +- _id_ `[string]`: Optional ID of the rest resource to check. - * state: Data state. - * url: URL the preview would be for. +_Returns_ -### getAuthors +- `(boolean|undefined)`: Whether or not the user can perform the action, or `undefined` if the OPTIONS request is still being made. + +# **getAuthors** Returns all available authors. -*Parameters* +_Parameters_ + +- _state_ `Object`: Data state. + +_Returns_ + +- `Array`: Authors list. + +# **getAutosave** + +Returns the autosave for the post and author. + +_Parameters_ + +- _state_ `Object`: State tree. +- _postType_ `string`: The type of the parent post. +- _postId_ `number`: The id of the parent post. +- _authorId_ `number`: The id of the author. + +_Returns_ + +- `?Object`: The autosave for the post and author. - * state: Data state. +# **getAutosaves** -*Returns* +Returns the latest autosaves for the post. + +May return multiple autosaves since the backend stores one autosave per +author for each post. + +_Parameters_ + +- _state_ `Object`: State tree. +- _postType_ `string`: The type of the parent post. +- _postId_ `number`: The id of the parent post. -Authors list. +_Returns_ -### getCurrentUser +- `?Array`: An array of autosaves for the post, or undefined if there is none. + +# **getCurrentUser** Returns the current user. -*Parameters* +_Parameters_ - * state: Data state. +- _state_ `Object`: Data state. -*Returns* +_Returns_ -Current user object. +- `Object`: Current user object. -### getUserQueryResults +# **getEmbedPreview** -Returns all the users returned by a query ID. +Returns the embed preview for the given URL. -*Parameters* +_Parameters_ - * state: Data state. - * queryID: Query ID. +- _state_ `Object`: Data state. +- _url_ `string`: Embedded URL. -*Returns* +_Returns_ -Users list. +- `*`: Undefined if the preview has not been fetched, otherwise, the preview fetched from the embed preview API. -### getEntitiesByKind +# **getEntitiesByKind** Returns whether the entities for the give kind are loaded. -*Parameters* +_Parameters_ - * state: Data state. - * kind: Entity kind. +- _state_ `Object`: Data state. +- _kind_ `string`: Entity kind. -*Returns* +_Returns_ -Whether the entities are loaded +- `boolean`: Whether the entities are loaded -### getEntity +# **getEntity** Returns the entity object given its kind and name. -*Parameters* +_Parameters_ - * state: Data state. - * kind: Entity kind. - * name: Entity name. +- _state_ `Object`: Data state. +- _kind_ `string`: Entity kind. +- _name_ `string`: Entity name. -*Returns* +_Returns_ -Entity +- `Object`: Entity -### getEntityRecord +# **getEntityRecord** Returns the Entity's record object by key. -*Parameters* +_Parameters_ - * state: State tree - * kind: Entity kind. - * name: Entity name. - * key: Record's key +- _state_ `Object`: State tree +- _kind_ `string`: Entity kind. +- _name_ `string`: Entity name. +- _key_ `number`: Record's key -*Returns* +_Returns_ -Record. +- `?Object`: Record. -### getEntityRecords +# **getEntityRecords** Returns the Entity's records. -*Parameters* +_Parameters_ - * state: State tree - * kind: Entity kind. - * name: Entity name. - * query: Optional terms query. +- _state_ `Object`: State tree +- _kind_ `string`: Entity kind. +- _name_ `string`: Entity name. +- _query_ `?Object`: Optional terms query. -*Returns* +_Returns_ -Records. +- `Array`: Records. -### getThemeSupports +# **getThemeSupports** Return theme supports data in the index. -*Parameters* +_Parameters_ - * state: Data state. +- _state_ `Object`: Data state. -*Returns* +_Returns_ -Index data. +- `*`: Index data. -### getEmbedPreview +# **getUserQueryResults** -Returns the embed preview for the given URL. +Returns all the users returned by a query ID. -*Parameters* +_Parameters_ - * state: Data state. - * url: Embedded URL. +- _state_ `Object`: Data state. +- _queryID_ `string`: Query ID. -*Returns* +_Returns_ -Undefined if the preview has not been fetched, otherwise, the preview fetched from the embed preview API. +- `Array`: Users list. -### isPreviewEmbedFallback +# **hasFetchedAutosaves** -Determines if the returned preview is an oEmbed link fallback. +Returns true if the REST request for autosaves has completed. -WordPress can be configured to return a simple link to a URL if it is not embeddable. -We need to be able to determine if a URL is embeddable or not, based on what we -get back from the oEmbed preview API. +_Parameters_ -*Parameters* +- _state_ `Object`: State tree. +- _postType_ `string`: The type of the parent post. +- _postId_ `number`: The id of the parent post. - * state: Data state. - * url: Embedded URL. +_Returns_ -*Returns* +- `boolean`: True if the REST request was completed. False otherwise. -Is the preview for the URL an oEmbed link fallback. +# **hasUploadPermissions** -### hasUploadPermissions (deprecated) +> **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. -https://developer.wordpress.org/rest-api/reference/ - -*Deprecated* + -Deprecated since 5.0. Callers should use the more generic `canUser()` selector instead of - `hasUploadPermissions()`, e.g. `canUser( 'create', 'media' )`. +_Parameters_ -*Parameters* +- _state_ `Object`: Data state. - * state: Data state. +_Returns_ -*Returns* +- `boolean`: Whether or not the user can upload media. Defaults to `true` if the OPTIONS request is being made. -Whether or not the user can upload media. Defaults to `true` if the OPTIONS - request is being made. +# **isPreviewEmbedFallback** -### canUser +Determines if the returned preview is an oEmbed link fallback. -Returns whether the current user can perform the given action on the given -REST resource. +WordPress can be configured to return a simple link to a URL if it is not embeddable. +We need to be able to determine if a URL is embeddable or not, based on what we +get back from the oEmbed preview API. -Calling this may trigger an OPTIONS request to the REST API via the -`canUser()` resolver. +_Parameters_ -https://developer.wordpress.org/rest-api/reference/ +- _state_ `Object`: Data state. +- _url_ `string`: Embedded URL. -*Parameters* +_Returns_ - * state: Data state. - * action: Action to check. One of: 'create', 'read', 'update', 'delete'. - * resource: REST resource to check, e.g. 'media' or 'posts'. - * id: Optional ID of the rest resource to check. +- `booleans`: Is the preview for the URL an oEmbed link fallback. -*Returns* +# **isRequestingEmbedPreview** -Whether or not the user can perform the action, - or `undefined` if the OPTIONS request is still being made. +Returns true if a request is in progress for embed preview data, or false +otherwise. -### getAutosaves +_Parameters_ -Returns the latest autosaves for the post. +- _state_ `Object`: Data state. +- _url_ `string`: URL the preview would be for. -May return multiple autosaves since the backend stores one autosave per -author for each post. +_Returns_ -*Parameters* +- `boolean`: Whether a request is in progress for an embed preview. - * state: State tree. - * postType: The type of the parent post. - * postId: The id of the parent post. -*Returns* + -An array of autosaves for the post, or undefined if there is none. +## Actions -### getAutosave + -Returns the autosave for the post and author. +# **addEntities** -*Parameters* +Returns an action object used in adding new entities. - * state: State tree. - * postType: The type of the parent post. - * postId: The id of the parent post. - * authorId: The id of the author. +_Parameters_ -*Returns* +- _entities_ `Array`: Entities received. -The autosave for the post and author. +_Returns_ -### hasFetchedAutosaves +- `Object`: Action object. -Returns true if the REST request for autosaves has completed. +# **receiveAutosaves** -*Parameters* +Returns an action object used in signalling that the autosaves for a +post have been received. - * state: State tree. - * postType: The type of the parent post. - * postId: The id of the parent post. +_Parameters_ -*Returns* +- _postId_ `number`: The id of the post that is parent to the autosave. +- _autosaves_ `(Array|Object)`: An array of autosaves or singular autosave object. -True if the REST request was completed. False otherwise. +_Returns_ -## Actions +- `Object`: Action object. -### receiveUserQuery +# **receiveCurrentUser** -Returns an action object used in signalling that authors have been received. +Returns an action used in signalling that the current user has been received. -*Parameters* +_Parameters_ - * queryID: Query ID. - * users: Users received. +- _currentUser_ `Object`: Current user object. -### receiveCurrentUser +_Returns_ -Returns an action used in signalling that the current user has been received. +- `Object`: Action object. -*Parameters* +# **receiveEmbedPreview** - * currentUser: Current user object. +Returns an action object used in signalling that the preview data for +a given URl has been received. -### addEntities +_Parameters_ -Returns an action object used in adding new entities. +- _url_ `string`: URL to preview the embed for. +- _preview_ `Mixed`: Preview data. -*Parameters* +_Returns_ - * entities: Entities received. +- `Object`: Action object. -### receiveEntityRecords +# **receiveEntityRecords** Returns an action object used in signalling that entity records have been received. -*Parameters* +_Parameters_ + +- _kind_ `string`: Kind of the received entity. +- _name_ `string`: Name of the received entity. +- _records_ `(Array|Object)`: Records received. +- _query_ `?Object`: Query Object. +- _invalidateCache_ `?boolean`: Should invalidate query caches - * kind: Kind of the received entity. - * name: Name of the received entity. - * records: Records received. - * query: Query Object. - * invalidateCache: Should invalidate query caches +_Returns_ -### receiveThemeSupports +- `Object`: Action object. + +# **receiveThemeSupports** Returns an action object used in signalling that the index has been received. -*Parameters* +_Parameters_ - * themeSupports: Theme support for the current theme. +- _themeSupports_ `Object`: Theme support for the current theme. -### receiveEmbedPreview +_Returns_ -Returns an action object used in signalling that the preview data for -a given URl has been received. +- `Object`: Action object. -*Parameters* +# **receiveUploadPermissions** - * url: URL to preview the embed for. - * preview: Preview data. +Returns an action object used in signalling that Upload permissions have been received. -### saveEntityRecord +_Parameters_ -Action triggered to save an entity record. +- _hasUploadPermissions_ `boolean`: Does the user have permission to upload files? -*Parameters* +_Returns_ - * kind: Kind of the received entity. - * name: Name of the received entity. - * record: Record to be saved. +- `Object`: Action object. -### receiveUploadPermissions +# **receiveUserPermission** -Returns an action object used in signalling that Upload permissions have been received. +Returns an action object used in signalling that the current user has +permission to perform an action on a REST resource. -*Parameters* +_Parameters_ - * hasUploadPermissions: Does the user have permission to upload files? +- _key_ `string`: A key that represents the action and REST resource. +- _isAllowed_ `boolean`: Whether or not the user can perform the action. -### receiveUserPermission +_Returns_ -Returns an action object used in signalling that the current user has -permission to perform an action on a REST resource. +- `Object`: Action object. -*Parameters* +# **receiveUserQuery** - * key: A key that represents the action and REST resource. - * isAllowed: Whether or not the user can perform the action. +Returns an action object used in signalling that authors have been received. -### receiveAutosaves +_Parameters_ -Returns an action object used in signalling that the autosaves for a -post have been received. +- _queryID_ `string`: Query ID. +- _users_ `(Array|Object)`: Users received. + +_Returns_ + +- `Object`: Action object. + +# **saveEntityRecord** + +Action triggered to save an entity record. + +_Parameters_ + +- _kind_ `string`: Kind of the received entity. +- _name_ `string`: Name of the received entity. +- _record_ `Object`: Record to be saved. + +_Returns_ -*Parameters* +- `Object`: Updated record. - * postId: The id of the post that is parent to the autosave. - * autosaves: An array of autosaves or singular autosave object. \ No newline at end of file + diff --git a/docs/manifest.json b/docs/manifest.json index 9e3806f91b116..b9f03974dcee0 100644 --- a/docs/manifest.json +++ b/docs/manifest.json @@ -119,6 +119,60 @@ "markdown_source": "https://raw.githubusercontent.com/WordPress/gutenberg/master/docs/designers-developers/developers/data/README.md", "parent": "developers" }, + { + "title": "WordPress Core Data", + "slug": "data-core", + "markdown_source": "https://raw.githubusercontent.com/WordPress/gutenberg/master/docs/designers-developers/developers/data/data-core.md", + "parent": "data" + }, + { + "title": "Annotations", + "slug": "data-core-annotations", + "markdown_source": "https://raw.githubusercontent.com/WordPress/gutenberg/master/docs/designers-developers/developers/data/data-core-annotations.md", + "parent": "data" + }, + { + "title": "Block Types Data", + "slug": "data-core-blocks", + "markdown_source": "https://raw.githubusercontent.com/WordPress/gutenberg/master/docs/designers-developers/developers/data/data-core-blocks.md", + "parent": "data" + }, + { + "title": "The Block Editor’s Data", + "slug": "data-core-block-editor", + "markdown_source": "https://raw.githubusercontent.com/WordPress/gutenberg/master/docs/designers-developers/developers/data/data-core-block-editor.md", + "parent": "data" + }, + { + "title": "The Post Editor’s Data", + "slug": "data-core-editor", + "markdown_source": "https://raw.githubusercontent.com/WordPress/gutenberg/master/docs/designers-developers/developers/data/data-core-editor.md", + "parent": "data" + }, + { + "title": "The Editor’s UI Data", + "slug": "data-core-edit-post", + "markdown_source": "https://raw.githubusercontent.com/WordPress/gutenberg/master/docs/designers-developers/developers/data/data-core-edit-post.md", + "parent": "data" + }, + { + "title": "Notices Data", + "slug": "data-core-notices", + "markdown_source": "https://raw.githubusercontent.com/WordPress/gutenberg/master/docs/designers-developers/developers/data/data-core-notices.md", + "parent": "data" + }, + { + "title": "The NUX (New User Experience) Data", + "slug": "data-core-nux", + "markdown_source": "https://raw.githubusercontent.com/WordPress/gutenberg/master/docs/designers-developers/developers/data/data-core-nux.md", + "parent": "data" + }, + { + "title": "The Viewport Data", + "slug": "data-core-viewport", + "markdown_source": "https://raw.githubusercontent.com/WordPress/gutenberg/master/docs/designers-developers/developers/data/data-core-viewport.md", + "parent": "data" + }, { "title": "Packages", "slug": "packages", @@ -1270,59 +1324,5 @@ "slug": "tree-select", "markdown_source": "https://raw.githubusercontent.com/WordPress/gutenberg/master/packages/components/src/tree-select/README.md", "parent": "components" - }, - { - "title": "WordPress Core Data", - "slug": "data-core", - "markdown_source": "https://raw.githubusercontent.com/WordPress/gutenberg/master/docs/designers-developers/developers/data/data-core.md", - "parent": "data" - }, - { - "title": "Annotations", - "slug": "data-core-annotations", - "markdown_source": "https://raw.githubusercontent.com/WordPress/gutenberg/master/docs/designers-developers/developers/data/data-core-annotations.md", - "parent": "data" - }, - { - "title": "Block Types Data", - "slug": "data-core-blocks", - "markdown_source": "https://raw.githubusercontent.com/WordPress/gutenberg/master/docs/designers-developers/developers/data/data-core-blocks.md", - "parent": "data" - }, - { - "title": "The Block Editor’s Data", - "slug": "data-core-block-editor", - "markdown_source": "https://raw.githubusercontent.com/WordPress/gutenberg/master/docs/designers-developers/developers/data/data-core-block-editor.md", - "parent": "data" - }, - { - "title": "The Post Editor’s Data", - "slug": "data-core-editor", - "markdown_source": "https://raw.githubusercontent.com/WordPress/gutenberg/master/docs/designers-developers/developers/data/data-core-editor.md", - "parent": "data" - }, - { - "title": "The Editor’s UI Data", - "slug": "data-core-edit-post", - "markdown_source": "https://raw.githubusercontent.com/WordPress/gutenberg/master/docs/designers-developers/developers/data/data-core-edit-post.md", - "parent": "data" - }, - { - "title": "Notices Data", - "slug": "data-core-notices", - "markdown_source": "https://raw.githubusercontent.com/WordPress/gutenberg/master/docs/designers-developers/developers/data/data-core-notices.md", - "parent": "data" - }, - { - "title": "The NUX (New User Experience) Data", - "slug": "data-core-nux", - "markdown_source": "https://raw.githubusercontent.com/WordPress/gutenberg/master/docs/designers-developers/developers/data/data-core-nux.md", - "parent": "data" - }, - { - "title": "The Viewport Data", - "slug": "data-core-viewport", - "markdown_source": "https://raw.githubusercontent.com/WordPress/gutenberg/master/docs/designers-developers/developers/data/data-core-viewport.md", - "parent": "data" } ] \ No newline at end of file diff --git a/docs/toc.json b/docs/toc.json index 774796da6a4fb..e8bbe9f0a6419 100644 --- a/docs/toc.json +++ b/docs/toc.json @@ -20,7 +20,17 @@ {"docs/designers-developers/developers/internationalization.md": []}, {"docs/designers-developers/developers/accessibility.md": []}, {"docs/designers-developers/developers/feature-flags.md": []}, - {"docs/designers-developers/developers/data/README.md": "{{data}}"}, + {"docs/designers-developers/developers/data/README.md": [ + {"docs/designers-developers/developers/data/data-core.md": []}, + {"docs/designers-developers/developers/data/data-core-annotations.md": []}, + {"docs/designers-developers/developers/data/data-core-blocks.md": []}, + {"docs/designers-developers/developers/data/data-core-block-editor.md": []}, + {"docs/designers-developers/developers/data/data-core-editor.md": []}, + {"docs/designers-developers/developers/data/data-core-edit-post.md": []}, + {"docs/designers-developers/developers/data/data-core-notices.md": []}, + {"docs/designers-developers/developers/data/data-core-nux.md": []}, + {"docs/designers-developers/developers/data/data-core-viewport.md": []} + ]}, {"docs/designers-developers/developers/packages.md": "{{packages}}"}, {"packages/components/README.md": "{{components}}"}, {"docs/designers-developers/developers/themes/README.md": [ diff --git a/docs/tool/config.js b/docs/tool/config.js index 6dd2341e3d3c8..70ddebf14bcd3 100644 --- a/docs/tool/config.js +++ b/docs/tool/config.js @@ -4,60 +4,8 @@ const glob = require( 'glob' ).sync; const path = require( 'path' ); -const root = path.resolve( __dirname, '../../' ); - module.exports = { componentPaths: glob( 'packages/components/src/*/**/README.md' ), - dataNamespaces: { - core: { - title: 'WordPress Core Data', - // TODO: Figure out a way to generate docs for dynamic actions/selectors - selectors: [ path.resolve( root, 'packages/core-data/src/selectors.js' ) ], - actions: [ path.resolve( root, 'packages/core-data/src/actions.js' ) ], - }, - 'core/annotations': { - title: 'Annotations', - selectors: [ path.resolve( root, 'packages/annotations/src/store/selectors.js' ) ], - actions: [ path.resolve( root, 'packages/annotations/src/store/actions.js' ) ], - }, - 'core/blocks': { - title: 'Block Types Data', - selectors: [ path.resolve( root, 'packages/blocks/src/store/selectors.js' ) ], - actions: [ path.resolve( root, 'packages/blocks/src/store/actions.js' ) ], - }, - 'core/block-editor': { - title: 'The Block Editor’s Data', - selectors: [ path.resolve( root, 'packages/block-editor/src/store/selectors.js' ) ], - actions: [ path.resolve( root, 'packages/block-editor/src/store/actions.js' ) ], - }, - 'core/editor': { - title: 'The Post Editor’s Data', - selectors: [ path.resolve( root, 'packages/editor/src/store/selectors.js' ) ], - actions: [ path.resolve( root, 'packages/editor/src/store/actions.js' ) ], - }, - 'core/edit-post': { - title: 'The Editor’s UI Data', - selectors: [ path.resolve( root, 'packages/edit-post/src/store/selectors.js' ) ], - actions: [ path.resolve( root, 'packages/edit-post/src/store/actions.js' ) ], - }, - 'core/notices': { - title: 'Notices Data', - selectors: [ path.resolve( root, 'packages/notices/src/store/selectors.js' ) ], - actions: [ path.resolve( root, 'packages/notices/src/store/actions.js' ) ], - }, - 'core/nux': { - title: 'The NUX (New User Experience) Data', - selectors: [ path.resolve( root, 'packages/nux/src/store/selectors.js' ) ], - actions: [ path.resolve( root, 'packages/nux/src/store/actions.js' ) ], - }, - 'core/viewport': { - title: 'The Viewport Data', - selectors: [ path.resolve( root, 'packages/viewport/src/store/selectors.js' ) ], - actions: [ path.resolve( root, 'packages/viewport/src/store/actions.js' ) ], - }, - }, - dataDocsOutput: path.resolve( __dirname, '../designers-developers/developers/data' ), - packageFileNames: glob( 'packages/*/package.json' ) .map( ( fileName ) => fileName.split( '/' )[ 1 ] ), diff --git a/docs/tool/generator.js b/docs/tool/generator.js deleted file mode 100644 index f5ee6f584e78f..0000000000000 --- a/docs/tool/generator.js +++ /dev/null @@ -1,100 +0,0 @@ -/** - * Node dependencies - */ -const path = require( 'path' ); -const fs = require( 'fs' ); -const { kebabCase } = require( 'lodash' ); - -/** - * Generates the table of contents' markdown. - * - * @param {Object} parsedNamespaces Parsed Namespace Object - * - * @return {string} Markdown string - */ -function generateTableOfContent( parsedNamespaces ) { - return [ - '# Data Module Reference', - '', - Object.values( parsedNamespaces ).map( ( parsedNamespace ) => { - return ` - [**${ parsedNamespace.name }**: ${ parsedNamespace.title }](/docs/designers-developers/developers/data/data-${ kebabCase( parsedNamespace.name ) }.md)`; - } ).join( '\n' ), - ].join( '\n' ); -} - -/** - * Generates the table of contents' markdown. - * - * @param {Object} parsedFunc Parsed Function - * @param {boolean} generateDocsForReturn Whether to generate docs for the return value. - * - * @return {string} Markdown string - */ -function generateFunctionDocs( parsedFunc, generateDocsForReturn = true ) { - return [ - `### ${ parsedFunc.name }${ parsedFunc.deprecated ? ' (deprecated)' : '' }`, - parsedFunc.description ? [ - '', - parsedFunc.description, - ].join( '\n' ) : null, - parsedFunc.deprecated ? [ - '', - '*Deprecated*', - '', - `Deprecated ${ parsedFunc.deprecated.description }`, - ].join( '\n' ) : null, - parsedFunc.params.length ? [ - '', - '*Parameters*', - '', - parsedFunc.params.map( ( param ) => ( - ` * ${ param.name }: ${ param.description }` - ) ).join( '\n' ), - ].join( '\n' ) : null, - parsedFunc.return && generateDocsForReturn ? [ - '', - '*Returns*', - '', - parsedFunc.return.description, - ].join( '\n' ) : null, - ].filter( ( row ) => row !== null ).join( '\n' ); -} - -/** - * Generates the namespace selectors/actions markdown. - * - * @param {Object} parsedNamespace Parsed Namespace - * - * @return {string} Markdown string - */ -function generateNamespaceDocs( parsedNamespace ) { - return [ - `# **${ parsedNamespace.name }**: ${ parsedNamespace.title }`, - '', - '## Selectors', - '', - ( parsedNamespace.selectors.map( generateFunctionDocs ) ).join( '\n\n' ), - '', - '## Actions', - '', - parsedNamespace.actions.map( - ( action ) => generateFunctionDocs( action, false ) - ).join( '\n\n' ), - ].join( '\n' ); -} - -module.exports = function( parsedNamespaces, rootFolder ) { - const tableOfContent = generateTableOfContent( parsedNamespaces ); - fs.writeFileSync( - path.join( rootFolder, 'README.md' ), - tableOfContent - ); - - Object.values( parsedNamespaces ).forEach( ( parsedNamespace ) => { - const namespaceDocs = generateNamespaceDocs( parsedNamespace ); - fs.writeFileSync( - path.join( rootFolder, 'data-' + kebabCase( parsedNamespace.name ) + '.md' ), - namespaceDocs - ); - } ); -}; diff --git a/docs/tool/index.js b/docs/tool/index.js index c0bb2c1101c7e..5e4244f88437c 100644 --- a/docs/tool/index.js +++ b/docs/tool/index.js @@ -2,24 +2,23 @@ * Node dependencies */ const fs = require( 'fs' ); +const { join } = require( 'path' ); +const { execSync } = require( 'child_process' ); /** * Internal dependencies */ const config = require( './config' ); -const parser = require( './parser' ); -const generator = require( './generator' ); -const { getPackageManifest, getComponentManifest, getDataManifest, getRootManifest } = require( './manifest' ); +const { getPackageManifest, getComponentManifest, getRootManifest } = require( './manifest' ); -const parsedModules = parser( config.dataNamespaces ); -generator( parsedModules, config.dataDocsOutput ); +// Update data files from code +execSync( join( __dirname, 'update-data.js' ) ); const rootManifest = getRootManifest( config.tocFileName ); const packageManifest = getPackageManifest( config.packageFileNames ); const componentManifest = getComponentManifest( config.componentPaths ); -const dataManifest = getDataManifest( parsedModules ); fs.writeFileSync( config.manifestOutput, - JSON.stringify( rootManifest.concat( packageManifest, componentManifest, dataManifest ), undefined, '\t' ) + JSON.stringify( rootManifest.concat( packageManifest, componentManifest ), undefined, '\t' ) ); diff --git a/docs/tool/manifest.js b/docs/tool/manifest.js index f21130e448e11..d6dcfeebc577f 100644 --- a/docs/tool/manifest.js +++ b/docs/tool/manifest.js @@ -1,7 +1,7 @@ /** * Node dependencies */ -const { camelCase, kebabCase, nth, upperFirst } = require( 'lodash' ); +const { camelCase, nth, upperFirst } = require( 'lodash' ); const fs = require( 'fs' ); @@ -45,25 +45,6 @@ function getComponentManifest( componentPaths ) { } ); } -/** - * Generates the data manifest. - * - * @param {Object} parsedNamespaces Parsed Namespace Object - * - * @return {Array} Manifest - */ -function getDataManifest( parsedNamespaces ) { - return Object.values( parsedNamespaces ).map( ( parsedNamespace ) => { - const slug = `data-${ kebabCase( parsedNamespace.name ) }`; - return { - title: parsedNamespace.title, - slug, - markdown_source: `${ baseRepoUrl }/docs/designers-developers/developers/data/${ slug }.md`, - parent: 'data', - }; - } ); -} - function getRootManifest( tocFileName ) { return generateRootManifestFromTOCItems( require( tocFileName ) ); } @@ -106,6 +87,5 @@ function generateRootManifestFromTOCItems( items, parent = null ) { module.exports = { getPackageManifest, getComponentManifest, - getDataManifest, getRootManifest, }; diff --git a/docs/tool/parser.js b/docs/tool/parser.js deleted file mode 100644 index 12ed0e002b261..0000000000000 --- a/docs/tool/parser.js +++ /dev/null @@ -1,201 +0,0 @@ -/** - * Node dependencies - */ -const fs = require( 'fs' ); - -/** - * External dependencies - */ -const { last, size, first, some, overEvery, negate, isEmpty } = require( 'lodash' ); -const espree = require( 'espree' ); -const doctrine = require( 'doctrine' ); - -/** - * Returns true if the given Espree parse result node is a documented named - * export declaration, or false otherwise. - * - * @param {Object} node Node to test. - * - * @return {boolean} Whether node is a documented named export declaration. - */ -function isDocumentedNamedExport( node ) { - return ( - node.type === 'ExportNamedDeclaration' && - size( node.leadingComments ) > 0 - ); -} - -/** - * Returns true if the given exported declaration name is considered stable for - * documentation, or false otherwise. - * - * @see https://github.com/WordPress/gutenberg/blob/master/docs/contributors/coding-guidelines.md#experimental-and-unstable-apis - * - * @param {string} name Name to test. - * - * @return {boolean} Whether the provided name describes a stable API. - */ -const isStableExportName = ( name ) => ! /^__(unstable|experimental)/.test( name ); - -/** - * Returns true if the given export name is eligible to be included in - * generated output, or false otherwise. - * - * @type {boolean} Whether name is eligible for documenting. - */ -const isEligibleExportedName = overEvery( [ - negate( isEmpty ), - isStableExportName, -] ); - -/** - * Returns the assigned name for a given declaration node type, or undefined if - * it cannot be determined. - * - * @param {Object} declaration Declaration node. - * - * @return {?string} Exported declaration name. - */ -function getDeclarationExportedName( declaration ) { - let declarator; - switch ( declaration.type ) { - case 'FunctionDeclaration': - declarator = declaration; - break; - - case 'VariableDeclaration': - declarator = first( declaration.declarations ); - } - - if ( declarator ) { - return declarator.id.name; - } -} - -/** - * Returns true if the given DocBlock contains at least one reference to the - * tag named by the provided title, or false otherwise. - * - * @param {Object} docBlock Parsed DocBlock node. - * @param {string} title Title to search. - * - * @return {boolean} Whether DocBlock contains tag by title. - */ -const hasDocBlockTag = ( docBlock, title ) => some( docBlock.tags, { title } ); - -/** - * Returns true if the given DocBlock contains at least one reference to a - * private tag. - * - * @param {Object} docBlock Parsed DocBlock node. - * - * @return {boolean} Whether DocBlock contains private tag. - */ -const hasPrivateTag = ( docBlock ) => hasDocBlockTag( docBlock, 'private' ); - -/** - * Returns true if the given DocBlock contains at least one reference to a - * param tag. - * - * @param {Object} docBlock Parsed DocBlock node. - * - * @return {boolean} Whether DocBlock contains param tag. - */ -const hasParamTag = ( docBlock ) => hasDocBlockTag( docBlock, 'param' ); - -/** - * Returns true if the give DocBlock contains a description. - * - * @param {Object} docBlock Parsed DocBlock node. - * - * @return {boolean} Whether DocBlock contains a description. - */ -const hasDescription = ( docBlock ) => !! docBlock.description; - -/** - * Maps parse type to specific filtering logic by which to consider for - * inclusion a parsed named export. - * - * @type {Object} - */ -const FILTER_PARSED_DOCBLOCK_BY_TYPE = { - /** - * Selectors filter. Excludes documented exports either marked as private - * or which do not include at least one `@param` DocBlock tag. This is used - * to distinguish between selectors (which at least receive state as an - * argument) and exported constant values. - * - * @param {Object} docBlock DocBlock object to test. - * - * @return {boolean} Whether documented selector should be included. - */ - selectors: overEvery( [ hasParamTag, negate( hasPrivateTag ) ] ), - - /** - * Actions filter. Excludes documented exports marked as private. - * - * @param {Object} docBlock DocBlock object to test. - * - * @return {boolean} Whether documented action should be included. - */ - actions: overEvery( [ hasDescription, negate( hasPrivateTag ) ] ), -}; - -module.exports = function( config ) { - const result = {}; - Object.entries( config ).forEach( ( [ namespace, namespaceConfig ] ) => { - const namespaceResult = { - name: namespace, - title: namespaceConfig.title, - selectors: [], - actions: [], - }; - - [ 'selectors', 'actions' ].forEach( ( type ) => { - namespaceConfig[ type ].forEach( ( file ) => { - const code = fs.readFileSync( file, 'utf8' ); - const parsedCode = espree.parse( code, { - attachComment: true, - // This should ideally match our babel config, but espree doesn't support it. - ecmaVersion: 9, - sourceType: 'module', - } ); - - parsedCode.body.forEach( ( node ) => { - if ( ! isDocumentedNamedExport( node ) ) { - return; - } - - const docBlock = doctrine.parse( - last( node.leadingComments ).value, - { unwrap: true, recoverable: true } - ); - - const filter = FILTER_PARSED_DOCBLOCK_BY_TYPE[ type ]; - if ( typeof filter === 'function' && ! filter( docBlock ) ) { - return; - } - - const name = getDeclarationExportedName( node.declaration ); - if ( ! isEligibleExportedName( name ) ) { - return; - } - - const func = { - name, - description: docBlock.description, - deprecated: docBlock.tags.find( ( tag ) => tag.title === 'deprecated' ), - params: docBlock.tags.filter( ( tag ) => tag.title === 'param' ), - return: docBlock.tags.find( ( tag ) => tag.title === 'return' ), - }; - - namespaceResult[ type ].push( func ); - } ); - } ); - } ); - - result[ namespace ] = namespaceResult; - } ); - - return result; -}; diff --git a/docs/tool/update-data.js b/docs/tool/update-data.js new file mode 100755 index 0000000000000..d689fc173fd4f --- /dev/null +++ b/docs/tool/update-data.js @@ -0,0 +1,50 @@ +#!/usr/bin/env node + +const { join } = require( 'path' ); +const spawnSync = require( 'child_process' ).spawnSync; + +const modules = [ + [ 'core', { + 'Autogenerated actions': 'packages/core-data/src/actions.js', + 'Autogenerated selectors': 'packages/core-data/src/selectors.js', + } ], + 'core/annotations', + 'core/blocks', + 'core/block-editor', + 'core/editor', + 'core/edit-post', + 'core/notices', + 'core/nux', + 'core/viewport', +]; + +modules.forEach( ( entry ) => { + if ( ! Array.isArray( entry ) ) { + entry = [ entry, { + 'Autogenerated actions': `packages/${ entry.replace( 'core/', '' ) }/src/store/actions.js`, + 'Autogenerated selectors': `packages/${ entry.replace( 'core/', '' ) }/src/store/selectors.js`, + } ]; + } + const [ namespace, targets ] = entry; + + Object.entries( targets ).forEach( ( [ token, target ] ) => { + // Note that this needs to be a sync process for each output file that is updated: + // until docgen provides a way to update many tokens at once, we need to make sure + // the output file is updated before starting the second pass for the next token. + const { status, stderr } = spawnSync( + join( __dirname, '..', '..', 'node_modules', '.bin', 'docgen' ), + [ + target, + `--output docs/designers-developers/developers/data/data-${ namespace.replace( '/', '-' ) }.md`, + '--to-token', + `--use-token "${ token }"`, + '--ignore "/unstable|experimental/i"', + ], + { shell: true }, + ); + + if ( status !== 0 ) { + throw stderr.toString(); + } + } ); +} );